docs/PRD.md

# 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 и текущего состояния кода. Приоритет у реального состояния системы над планами в документах.**