2026-02-23 19:25:06 +01:00

19 KiB

Raw Blame History

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)

Task events через WS — task.created/updated/assigned с фильтрацией
Listen mode фильтрация — chat_listen и task_listen работают корректно
Humans подписки — убрать "получают всё", добавить project.subscribe

Phase 2: Agent Management UI (SHOULD)

Agent management страница — создание агентов с генерацией токенов
Agent мониторинг — список агентов со статусами и capabilities
Token display — показать токен один раз при создании агента

Phase 3: MCP Tools для агентов (SHOULD)

Basic MCP Tools — create_task, take_task, update_task, send_message
REST Token auth — token проверка для REST API агентов
Picogent интеграция — подключить реального агента к системе

Phase 4: Files & Attachments (COULD)

Upload/download API — POST /messages/{id}/attachments, GET /attachments/{id}
File storage — сохранение на диск по storage_path
File preview UI — превью изображений и кода в сообщениях

Nice to Have (будущие итерации)

Telegram Bridge для дублирования чатов
Advanced dashboard с метриками проектов
OAuth/Authentik интеграция для мультипользователей
Git workflow интеграция с Merge Requests
Session compaction для длинных агентских сессий

Документ создан на основе полного анализа 24+ файлов документации Team Board и текущего состояния кода. Приоритет у реального состояния системы над планами в документах.

19 KiB Raw Blame History Unescape Escape