docs/IMPLEMENTATION-PLAN.md

Team Board — План реализации

Дата: 2026-02-22 Метод: BMAD Planning

Текущее состояние

Tracker (Python/FastAPI)

• Модели: Project, Task, Agent, Chat, ChatMessage, Label, TaskDependency, TaskFile
• API: CRUD для tasks, projects, agents, chats, labels
• WS: базовый handler (auth, chat.subscribe, chat.send, chat.message broadcast)
• БД: PostgreSQL, Alembic миграции (3 штуки)

Web Client (Next.js)

• Страницы: login, projects list, project board
• Компоненты: KanbanBoard, TaskModal, ChatPanel, Sidebar, CreateProjectModal, AuthGuard
• API client, WS client

Что НЕ соответствует архитектуре v0.4

• Модель Agent отдельная (надо: Member + AgentConfig)
• ChatMessage привязана к Chat, нет task_id/parent_id (надо: Unified Message)
• Нет Steps модели
• Нет watchers на Task
• Нет Attachment модели (отдельные TaskFile)
• Project.git_repo = string (надо: repo_urls = array)
• Task статусы не совпадают (draft/ready/completed vs backlog/todo/done)
• WS handler не фильтрует по listen_mode
• Нет project.subscribe
• Нет heartbeat

---

Эпики

Epic 1: Новые модели БД

Приоритет: MUST (всё остальное зависит от этого)

Очистить БД, создать модели с нуля по ARCHITECTURE.md v0.4.

Stories:

E1-S1: Member + AgentConfig Заменить User + Agent на единую модель Member.

Member: id, name, slug, type(human|agent), role(owner|member|observer|bridge),
  auth_method, password_hash?, token?, status, avatar_url
AgentConfig: member_id(FK), capabilities[], chat_listen, task_listen,
  prompt, model

Acceptance: модели созданы, init_db создаёт владельца (admin)

E1-S2: Unified Message + Attachment Заменить Chat + ChatMessage на Message + Attachment.

Message: id, content, author_type, author_slug,
  chat_id?(lobby/project), task_id?, parent_id?(thread),
  mentions[], voice_url?, created_at
Attachment: id, message_id(FK), filename, mime_type, size, storage_path

Chat таблица остаётся (lobby, project chats), но Message может быть без chat_id (task comment). Acceptance: Message работает и для чата, и для комментариев

E1-S3: Task обновление

- status: backlog|todo|in_progress|in_review|done
- type: task|bug|epic|story
- labels: string[] (ARRAY, вместо отдельной таблицы TaskLabel)
- watchers: string[] (ARRAY of slugs)
- depends_on: UUID[] (ARRAY, вместо TaskDependency таблицы)
- assignee_slug: string (вместо assigned_agent_id FK)
- reviewer_slug: string?
- Убрать: requires_pr, pr_url (пока не нужны)

Acceptance: Task соответствует ARCHITECTURE.md

E1-S4: Step модель

Step: id, task_id(FK), title, done(bool), position(int)

Acceptance: Steps CRUD работает

E1-S5: Project обновление

- repo_urls: string[] (ARRAY, вместо git_repo)
- Убрать: key_prefix, task_counter (номера задач генерить иначе)

Acceptance: Project соответствует ARCHITECTURE.md

E1-S6: Очистка и init

• Удалить Alembic миграции
• DROP ALL + CREATE ALL при первом запуске
• Seed: создать admin (owner), lobby chat Acceptance: чистый старт, docker compose down -v && up работает

---

Epic 2: REST API (MCP-ready)

Приоритет: MUST

Обновить API эндпоинты для всех MCP tools.

Stories:

E2-S1: Auth API

• POST /api/v1/auth/login — логин → JWT
• POST /api/v1/auth/register — регистрация (disabled by default)
• Token validation middleware Acceptance: JWT auth работает

E2-S2: Tasks API

• GET /api/v1/tasks — list (фильтры: project_id, status, assignee, labels)
• GET /api/v1/tasks/{id} — get
• POST /api/v1/tasks — create
• PATCH /api/v1/tasks/{id} — update
• DELETE /api/v1/tasks/{id} — delete
• POST /api/v1/tasks/{id}/take — take (атомарно)
• POST /api/v1/tasks/{id}/reject — reject с причиной
• POST /api/v1/tasks/{id}/assign — assign
• POST /api/v1/tasks/{id}/watch — watch
• DELETE /api/v1/tasks/{id}/watch — unwatch Acceptance: все эндпоинты работают, take атомарный

E2-S3: Steps API

• GET /api/v1/tasks/{id}/steps
• POST /api/v1/tasks/{id}/steps
• PATCH /api/v1/tasks/{task_id}/steps/{step_id}
• DELETE /api/v1/tasks/{task_id}/steps/{step_id} Acceptance: CRUD steps

E2-S4: Messages API (unified)

• GET /api/v1/messages — list (фильтры: chat_id, task_id, parent_id, limit/offset)
• POST /api/v1/messages — send (chat_id или task_id)
• POST /api/v1/messages/{id}/reply — thread reply Acceptance: работает для чатов и комментариев задач

E2-S5: Files API

• POST /api/v1/messages/{id}/attachments — upload
• GET /api/v1/attachments/{id} — download
• GET /api/v1/attachments — list (фильтры: task_id, chat_id) Acceptance: upload/download работает

E2-S6: Projects API

• Обновить существующий API под новые поля (repo_urls) Acceptance: CRUD проектов работает

E2-S7: Members API

• GET /api/v1/members — list (фильтр: project_id)
• GET /api/v1/members/{slug} — get
• POST /api/v1/members — create (agent с токеном)
• PATCH /api/v1/members/{slug} — update
• PATCH /api/v1/members/me/status — update own status Acceptance: CRUD members, генерация токенов для агентов

---

Epic 3: WebSocket Protocol v2

Приоритет: MUST

Stories:

E3-S1: Auth + Heartbeat

• auth → token validation → auth.ok с контекстом (проекты, online members)
• heartbeat → обновление status, last_seen_at
• Timeout 90s → status=offline, уведомление Acceptance: агент подключается и держит сессию

E3-S2: Project Subscribe

• project.subscribe / project.unsubscribe
• Подписка = получение chat + task events для этого проекта Acceptance: подписка/отписка работает

E3-S3: Event Filtering

• message.new — фильтрация по chat_listen + ownership
• task.created/updated/assigned — фильтрация по task_listen + assignee/reviewer/watchers Acceptance: агент с mentions получает только своё, агент с all — всё

E3-S4: chat.send через WS

• Отправка сообщения через WS (помимо REST)
• Broadcast по подписчикам с фильтрацией Acceptance: чат работает в реальном времени

---

Epic 4: Web Client обновление

Приоритет: SHOULD

Stories:

E4-S1: TaskModal — комментарии

• Лента сообщений (Message с task_id) внизу модалки
• Input для нового комментария
• Значки авторов: 👤/🤖/⚙️ Acceptance: комментарии к задаче работают

E4-S2: TaskModal — Steps

• Чеклист между описанием и комментариями
• Добавление/завершение/удаление steps
• Live-обновление через WS Acceptance: steps отображаются и обновляются

E4-S3: TaskModal — watchers

• Кнопка "👁 Наблюдать" / "Отписаться"
• Список watchers в сайдбаре модалки Acceptance: подписка/отписка работает

E4-S4: Agent Management

• Страница /agents — список агентов со статусами
• Создание агента (name, slug, capabilities) → генерация токена
• Отображение токена (один раз при создании) Acceptance: можно создать агента и получить токен

E4-S5: Обновление моделей в клиенте

• api.ts: обновить типы (Member вместо Agent, Message вместо ChatMessage)
• ws.ts: обновить события (message.new, project.subscribe, heartbeat)
• ChatPanel: использовать Unified Message Acceptance: клиент работает с новым API

---

Epic 5: Picogent интеграция

Приоритет: COULD (после Epic 1-3)

Stories:

E5-S1: MCP Tools Provider

• Обёртка над Tracker REST API
• Все 21+ tools из BRAINSTORM-MCP-TOOLS Acceptance: агент может вызывать tools

E5-S2: Router v2

• WS event → текст → единственная сессия
• Фильтрация по listen_mode на стороне picogent (дополнительно к серверной) Acceptance: агент получает события как текст

E5-S3: Single Session

• Одна сессия на агента (не per-task)
• session.resume при reconnect Acceptance: контекст сохраняется между задачами

---

Порядок выполнения

Phase 1: Backend Foundation
  E1 (модели) → E2 (API) → E3 (WS v2)

Phase 2: Frontend
  E4-S5 (типы) → E4-S1 (комменты) → E4-S2 (steps) → E4-S4 (agents)

Phase 3: Agent
  E5-S1 (MCP) → E5-S2 (router) → E5-S3 (session)

Оценка объёма

Epic	Stories	Сложность	~Часы
E1: Модели	6	Средняя	4-6
E2: REST API	7	Средняя	8-12
E3: WS v2	4	Высокая	6-8
E4: Web Client	5	Средняя	8-10
E5: Picogent	3	Высокая	10-14
Итого	25		36-50