docs: PRD v1.0
This commit is contained in:
parent
83bf602f15
commit
537fcfe09a
322
PRD.md
Normal file
322
PRD.md
Normal file
@ -0,0 +1,322 @@
|
||||
# Product Requirements Document — Team Board
|
||||
|
||||
**Версия:** 1.0
|
||||
**Дата:** 2026-02-23
|
||||
**Автор:** Mary (BMAD Method)
|
||||
|
||||
---
|
||||
|
||||
## 1. Видение продукта
|
||||
|
||||
Team Board — платформа для совместной работы людей и AI-агентов над проектами. Канбан-доска, чат, файлы — где агенты являются полноценными участниками команды: берут задачи, общаются, создают подзадачи, ревьюят код. Человек — участник процесса, а не наблюдатель. Всё происходит на человеческом языке в прозрачном чате, в отличие от MetaGPT и Claude Flow где агенты работают вместо людей.
|
||||
|
||||
---
|
||||
|
||||
## 2. Целевая аудитория
|
||||
|
||||
- **Разработчики** — управление проектами с AI-помощью
|
||||
- **Product Manager** — координация команды из людей и агентов
|
||||
- **Solo разработчики** — масштабирование через AI-агентов
|
||||
- **Команды** — прозрачная работа с AI как с коллегами
|
||||
|
||||
---
|
||||
|
||||
## 3. Ключевые концепции
|
||||
|
||||
### Member (Участники)
|
||||
Единая модель для людей и агентов. Различие только в `type` ("human" | "agent") и методе авторизации (password/JWT vs token).
|
||||
|
||||
### Project (Проекты)
|
||||
Контейнер для задач с канбан-доской, чатом и настройками. Поддержка multi-repo через `repo_urls[]`.
|
||||
|
||||
### Task (Задачи)
|
||||
Основная единица работы со статусами backlog → todo → in_progress → in_review → done. Поддержка подзадач, зависимостей, наблюдателей.
|
||||
|
||||
### Step (Этапы)
|
||||
Чеклист внутри задачи для отображения прогресса агента. В отличие от подзадач, этапы не попадают на канбан-доску.
|
||||
|
||||
### Message (Сообщения)
|
||||
Unified модель для чат-сообщений И комментариев к задачам. Одно поле `chat_id` или `task_id` определяет контекст.
|
||||
|
||||
### Chat (Чаты)
|
||||
Два типа: lobby (глобальный чат) и project (чат проекта). Комментарии к задачам через Message с `task_id`.
|
||||
|
||||
### Agent (AI-агенты)
|
||||
Независимые приложения, подключающиеся по WebSocket. Настраиваются через AgentConfig с capabilities, listen modes, промптами.
|
||||
|
||||
---
|
||||
|
||||
## 4. Функциональные требования
|
||||
|
||||
### 4.1 Управление проектами
|
||||
|
||||
| ID | Описание | Статус |
|
||||
|----|----------|--------|
|
||||
| P001 | `GET /api/v1/projects` — список проектов | ✅ реализовано |
|
||||
| P002 | `POST /api/v1/projects` — создание проекта с name, slug, description, repo_urls[] | ✅ реализовано |
|
||||
| P003 | `PATCH /api/v1/projects/{slug}` — обновление проекта | ✅ реализовано |
|
||||
| P004 | `DELETE /api/v1/projects/{slug}` — удаление проекта | ✅ реализовано |
|
||||
| P005 | Поддержка multi-repo проектов через repo_urls[] | ✅ реализовано |
|
||||
| P006 | Статусы проектов: active, archived | ✅ реализовано |
|
||||
| P007 | CreateProjectModal в веб-интерфейсе | ✅ реализовано |
|
||||
|
||||
### 4.2 Управление задачами (Kanban)
|
||||
|
||||
| ID | Описание | Статус |
|
||||
|----|----------|--------|
|
||||
| T001 | `GET /api/v1/tasks` с фильтрами project_id, status, assignee, labels | ✅ реализовано |
|
||||
| T002 | `POST /api/v1/tasks` — создание задачи с автогенерацией номера (TE-1, TE-2...) | ✅ реализовано |
|
||||
| T003 | `PATCH /api/v1/tasks/{id}` — обновление полей задачи | ✅ реализовано |
|
||||
| T004 | `DELETE /api/v1/tasks/{id}` — удаление задачи | ✅ реализовано |
|
||||
| T005 | Статусы: backlog, todo, in_progress, in_review, done с свободными переходами | ✅ реализовано |
|
||||
| T006 | Приоритеты: critical, high, medium, low | ✅ реализовано |
|
||||
| T007 | Лейблы как string[] (coding, backend, urgent...) | ✅ реализовано |
|
||||
| T008 | Подзадачи через parent_id (полноценные задачи на канбане) | ✅ реализовано |
|
||||
| T009 | Зависимости через depends_on UUID[] | ✅ реализовано |
|
||||
| T010 | Назначение assignee_slug, reviewer_slug | ✅ реализовано |
|
||||
| T011 | Watchers как string[] (наблюдатели задачи) | ✅ реализовано |
|
||||
| T012 | KanbanBoard с drag & drop и mobile tabs | ✅ реализовано |
|
||||
| T013 | TaskModal с редактированием title, description, status, priority, assignee | ✅ реализовано |
|
||||
| T014 | CreateTaskModal с выбором типа, приоритета, назначения | ✅ реализовано |
|
||||
| T015 | `POST /api/v1/tasks/{id}/take` — атомарное взятие задачи агентом | ❌ не реализовано |
|
||||
| T016 | `POST /api/v1/tasks/{id}/reject` — отклонение задачи с причиной | ❌ не реализовано |
|
||||
| T017 | `POST /api/v1/tasks/{id}/assign` — назначение задачи | ❌ не реализовано |
|
||||
| T018 | `POST /api/v1/tasks/{id}/watch` — подписка на задачу | ❌ не реализовано |
|
||||
|
||||
### 4.3 Чат и коммуникация
|
||||
|
||||
| ID | Описание | Статус |
|
||||
|----|----------|--------|
|
||||
| C001 | `GET /api/v1/messages` с фильтрами chat_id, task_id, limit, offset | ✅ реализовано |
|
||||
| C002 | `POST /api/v1/messages` — отправка в чат или комментарий к задаче | ✅ реализовано |
|
||||
| C003 | Unified Message модель для чат-сообщений И комментариев задач | ✅ реализовано |
|
||||
| C004 | Упоминания через mentions[] с автодополнением @slug | ✅ реализовано |
|
||||
| C005 | Поддержка threads через parent_id (только в чатах) | ✅ реализовано |
|
||||
| C006 | Значки авторов в UI: 👤 human, 🤖 agent, ⚙️ system | ✅ реализовано |
|
||||
| C007 | ChatPanel для lobby чата | ✅ реализовано |
|
||||
| C008 | Комментарии к задачам в TaskModal | ✅ реализовано |
|
||||
| C009 | Голосовые сообщения через voice_url | 🔨 частично |
|
||||
| C010 | WebSocket chat.send для real-time отправки | ✅ реализовано |
|
||||
|
||||
### 4.4 AI агенты
|
||||
|
||||
| ID | Описание | Статус |
|
||||
|----|----------|--------|
|
||||
| A001 | `GET /api/v1/members` — список участников (люди + агенты) | ✅ реализовано |
|
||||
| A002 | `POST /api/v1/members` — создание агента с токеном | ✅ реализовано |
|
||||
| A003 | Unified Member модель с type ("human" | "agent") | ✅ реализовано |
|
||||
| A004 | AgentConfig с capabilities[], chat_listen, task_listen, prompt, model | ✅ реализовано |
|
||||
| A005 | Listen modes: "all" | "mentions" для chat и task событий раздельно | ✅ реализовано |
|
||||
| A006 | WebSocket auth через token для агентов | ✅ реализовано |
|
||||
| A007 | Heartbeat каждые 30 секунд, timeout 90 секунд → offline | ✅ реализовано |
|
||||
| A008 | Статусы: online, offline, busy с broadcast уведомлениями | ✅ реализовано |
|
||||
| A009 | Picogent агент готов к подключению (agent.json конфиг) | ✅ реализовано |
|
||||
| A010 | Agent management UI — создание, настройка токенов | ❌ не реализовано |
|
||||
| A011 | MCP Tools для агентов (create_task, take_task, send_message...) | ❌ не реализовано |
|
||||
| A012 | Фильтрация WS событий по capabilities и listen modes | ❌ не реализовано |
|
||||
|
||||
### 4.5 Файлы и вложения
|
||||
|
||||
| ID | Описание | Статус |
|
||||
|----|----------|--------|
|
||||
| F001 | Attachment модель связанная с Message | ✅ реализовано |
|
||||
| F002 | `POST /api/v1/messages/{id}/attachments` — загрузка файлов | ❌ не реализовано |
|
||||
| F003 | `GET /api/v1/attachments/{id}` — скачивание файлов | ❌ не реализовано |
|
||||
| F004 | Хранение файлов на диске по storage_path | ❌ не реализовано |
|
||||
| F005 | Превью файлов в UI (изображения, код) | ❌ не реализовано |
|
||||
|
||||
### 4.6 Аутентификация и авторизация
|
||||
|
||||
| ID | Описание | Статус |
|
||||
|----|----------|--------|
|
||||
| AU001 | JWT аутентификация для людей (login/password) | ✅ реализовано |
|
||||
| AU002 | Token аутентификация для агентов | ✅ реализовано |
|
||||
| AU003 | BFF с JWT авторизацией на порту 8200 | ✅ реализовано |
|
||||
| AU004 | Роли: owner, member, observer, bridge | ✅ реализовано |
|
||||
| AU005 | AuthGuard компонент для защиты страниц | ✅ реализовано |
|
||||
| AU006 | Login страница с формой входа | ✅ реализовано |
|
||||
| AU007 | Token auth для REST API агентов | ❌ не реализовано |
|
||||
|
||||
### 4.7 WebSocket и реал-тайм
|
||||
|
||||
| ID | Описание | Статус |
|
||||
|----|----------|--------|
|
||||
| WS001 | WebSocket эндпоинт `/ws` с auth handshake | ✅ реализовано |
|
||||
| WS002 | Сообщения: auth, heartbeat, chat.send, project.subscribe, ack | ✅ реализовано |
|
||||
| WS003 | События: auth.ok/error, message.new, agent.status | ✅ реализовано |
|
||||
| WS004 | BFF WebSocket прокси с on_behalf_of для browser пользователей | ✅ реализовано |
|
||||
| WS005 | Очередь сообщений до auth.ok на клиенте | ✅ реализовано |
|
||||
| WS006 | Project subscriptions для получения событий проекта | ✅ реализовано |
|
||||
| WS007 | Task события: task.created, task.updated, task.assigned | ❌ не реализовано |
|
||||
| WS008 | Фильтрация событий по listen_mode и capabilities | ❌ не реализовано |
|
||||
|
||||
### 4.8 Steps (этапы задач)
|
||||
|
||||
| ID | Описание | Статус |
|
||||
|----|----------|--------|
|
||||
| S001 | Step модель связанная с Task | ✅ реализовано |
|
||||
| S002 | `GET /api/v1/tasks/{id}/steps` — список этапов | ✅ реализовано |
|
||||
| S003 | `POST /api/v1/tasks/{id}/steps` — создание этапа | ✅ реализовано |
|
||||
| S004 | `PATCH /api/v1/tasks/{tid}/steps/{sid}` — обновление (title, done) | ✅ реализовано |
|
||||
| S005 | `DELETE /api/v1/tasks/{tid}/steps/{sid}` — удаление этапа | ✅ реализовано |
|
||||
| S006 | Steps UI в TaskModal с чекбоксами и прогрессом | ✅ реализовано |
|
||||
|
||||
---
|
||||
|
||||
## 5. Нефункциональные требования
|
||||
|
||||
### Производительность
|
||||
- WebSocket подключения: до 100 одновременных агентов
|
||||
- REST API: до 1000 RPS
|
||||
- База данных: PostgreSQL с connection pooling
|
||||
- Время отклика API: <200ms для CRUD операций
|
||||
|
||||
### Безопасность
|
||||
- JWT токены с истечением 30 дней
|
||||
- Agent токены формата `tb-{32 random chars}`
|
||||
- Все пароли хешируются bcrypt
|
||||
- HTTPS обязателен в продакшене
|
||||
- CORS настроен для фронтенда
|
||||
|
||||
### Масштабируемость
|
||||
- Архитектура готова к горизонтальному масштабированию
|
||||
- Статичные файлы и аттачменты на диске (возможно S3 в будущем)
|
||||
- Redis для кеширования и очередей (зарезервировано)
|
||||
- WebSocket connections можно балансировать
|
||||
|
||||
### Надёжность
|
||||
- Агенты переподключаются при обрыве WebSocket
|
||||
- Heartbeat мониторинг с автоматическим offline
|
||||
- База данных с автоматическими backups (планируется)
|
||||
- Graceful shutdown всех сервисов
|
||||
|
||||
---
|
||||
|
||||
## 6. Архитектура (высокоуровневая)
|
||||
|
||||
### Компоненты
|
||||
|
||||
```
|
||||
Web Client (Next.js, порт 3100)
|
||||
↓ HTTPS
|
||||
BFF (Python/FastAPI, порт 8200)
|
||||
↓ HTTP + WebSocket
|
||||
Tracker (Python/FastAPI, порт 8100)
|
||||
↓ SQL
|
||||
PostgreSQL (порт 5433)
|
||||
|
||||
Agents (Picogent) → WebSocket → Tracker
|
||||
```
|
||||
|
||||
### Принципы
|
||||
- **Tracker-Centric:** Tracker — внутренний сервис, единая точка правды
|
||||
- **BFF для веба:** Только веб-клиент ходит через BFF, агенты — напрямую
|
||||
- **WebSocket для событий:** Реал-тайм уведомления и чат
|
||||
- **REST для мутаций:** Все изменения данных через REST API
|
||||
- **Unified модели:** Member = human | agent, Message = chat | task comments
|
||||
|
||||
### Деплой
|
||||
- **Tracker:** Docker Compose с PostgreSQL
|
||||
- **BFF + Web Client:** systemd сервисы на хосте
|
||||
- **Agents:** systemd unit на агента (один процесс = один агент)
|
||||
- **Nginx:** SSL termination, статичные файлы, проксирование
|
||||
|
||||
---
|
||||
|
||||
## 7. Текущий статус
|
||||
|
||||
### Что работает сейчас (✅)
|
||||
|
||||
**Backend (Tracker v0.2.0):**
|
||||
- Все модели данных созданы и соответствуют архитектуре
|
||||
- Полный REST API CRUD для всех сущностей
|
||||
- WebSocket с базовой функциональностью (auth, heartbeat, chat.send)
|
||||
- JWT и token аутентификация
|
||||
- БД инициализация с admin пользователем
|
||||
|
||||
**Frontend (Web Client v0.2.0):**
|
||||
- KanbanBoard с drag & drop и mobile tabs
|
||||
- TaskModal с steps, комментариями, редактированием
|
||||
- ChatPanel для lobby чата
|
||||
- CreateTaskModal, CreateProjectModal
|
||||
- BFF прокси с JWT авторизацией
|
||||
- AuthGuard и Login страница
|
||||
|
||||
**Infrastructure:**
|
||||
- Docker Compose для разработки (Tracker + PostgreSQL + Redis)
|
||||
- systemd сервисы для продакшена (BFF, Web Client)
|
||||
- Nginx конфигурация с SSL
|
||||
- Домены: dev.team.uix.su (активный), team.uix.su (placeholder)
|
||||
|
||||
**Agent System:**
|
||||
- Picogent готов к подключению с agent.json конфигом
|
||||
- WebSocket подключение и аутентификация работают
|
||||
- Heartbeat и статус мониторинг
|
||||
|
||||
### Что не работает (❌)
|
||||
|
||||
**WebSocket события:**
|
||||
- Task events (task.created, task.updated, task.assigned) не транслируются
|
||||
- Фильтрация событий по listen_mode и capabilities не реализована
|
||||
- Humans и bridges пока получают ВСЕ события (упрощённо)
|
||||
|
||||
**Agent операции:**
|
||||
- MCP Tools для агентов отсутствуют
|
||||
- take_task, reject_task, assign_task API не реализованы
|
||||
- Agent management UI не создан
|
||||
|
||||
**Файлы:**
|
||||
- Upload/download API для attachments не реализован
|
||||
- Превью файлов в UI отсутствует
|
||||
|
||||
**REST API для агентов:**
|
||||
- Token авторизация работает только для WebSocket, не для REST
|
||||
|
||||
### Известные баги
|
||||
|
||||
**WebSocket (исправлено сегодня):**
|
||||
- ✅ connect() не вызывался — исправлено
|
||||
- ✅ subscribeProject() не вызывался — исправлено
|
||||
- ✅ send() дропал сообщения до auth.ok — исправлено очередью
|
||||
|
||||
**BFF WebSocket proxy:**
|
||||
- ✅ Добавлен on_behalf_of чтобы browser-пользователь регистрировался по своему slug
|
||||
|
||||
**Архитектура WS упрощена:**
|
||||
- ✅ Humans/bridges получают ВСЕ события без подписок, фильтрация на клиенте
|
||||
- ✅ Agents получают по подпискам project.subscribe
|
||||
|
||||
---
|
||||
|
||||
## 8. Приоритеты следующей итерации
|
||||
|
||||
### Phase 1: Завершить WebSocket v2 (MUST)
|
||||
1. **Task events через WS** — task.created/updated/assigned с фильтрацией
|
||||
2. **Listen mode фильтрация** — chat_listen и task_listen работают корректно
|
||||
3. **Humans подписки** — убрать "получают всё", добавить project.subscribe
|
||||
|
||||
### Phase 2: Agent Management UI (SHOULD)
|
||||
1. **Agent management страница** — создание агентов с генерацией токенов
|
||||
2. **Agent мониторинг** — список агентов со статусами и capabilities
|
||||
3. **Token display** — показать токен один раз при создании агента
|
||||
|
||||
### Phase 3: MCP Tools для агентов (SHOULD)
|
||||
1. **Basic MCP Tools** — create_task, take_task, update_task, send_message
|
||||
2. **REST Token auth** — token проверка для REST API агентов
|
||||
3. **Picogent интеграция** — подключить реального агента к системе
|
||||
|
||||
### Phase 4: Files & Attachments (COULD)
|
||||
1. **Upload/download API** — POST /messages/{id}/attachments, GET /attachments/{id}
|
||||
2. **File storage** — сохранение на диск по storage_path
|
||||
3. **File preview UI** — превью изображений и кода в сообщениях
|
||||
|
||||
### Nice to Have (будущие итерации)
|
||||
- Telegram Bridge для дублирования чатов
|
||||
- Advanced dashboard с метриками проектов
|
||||
- OAuth/Authentik интеграция для мультипользователей
|
||||
- Git workflow интеграция с Merge Requests
|
||||
- Session compaction для длинных агентских сессий
|
||||
|
||||
---
|
||||
|
||||
**Документ создан на основе полного анализа 24+ файлов документации Team Board и текущего состояния кода. Приоритет у реального состояния системы над планами в документах.**
|
||||
Loading…
Reference in New Issue
Block a user