docs/PLANNING.md

# Planning — Team Board
Дата: 2026-02-23

## Принципы
- Каждый эпик = самодостаточный блок, можно релизить независимо
- Порядок = зависимости + приоритет из Architecture Review
- Никаких параллельных эпиков — строго последовательно
- Каждая story имеет чёткие критерии приёмки

## Эпик 1: WebSocket Foundation — Исправить критические баги
Цель: Устранить P0 блокеры из Architecture Review — WS collision и отсутствие task events
Зависимости: нет

### Story 1.1: Исправить WebSocket connection collision
**Как** системный разработчик **я хочу** чтобы множественные подключения одного пользователя не вытесняли друг друга **чтобы** система работала корректно при multiple tabs/reconnect

**Критерии приёмки:**
- [ ] `ConnectionManager.clients` изменён с `dict[str, ConnectedClient]` на `dict[str, list[ConnectedClient]]`
- [ ] Добавлен `sessions: dict[str, ConnectedClient]` с уникальными session_id
- [ ] При подключении создаётся уникальный session_id
- [ ] При отключении удаляется только конкретная сессия
- [ ] Broadcast отправляется всем сессиям пользователя

**Компоненты:** Tracker  
**Оценка:** M

### Story 1.2: Добавить broadcast task events
**Как** агент **я хочу** получать уведомления о создании/изменении задач **чтобы** реагировать на новую работу в проекте

**Критерии приёмки:**
- [ ] `POST /api/v1/tasks` вызывает `broadcast_task_event("task.created")`
- [ ] `PATCH /api/v1/tasks/{id}` вызывает `broadcast_task_event("task.updated")`
- [ ] `DELETE /api/v1/tasks/{id}` вызывает `broadcast_task_event("task.deleted")`
- [ ] События содержат полную информацию о задаче
- [ ] WebSocket клиент получает события в формате `{"type": "task.created", "data": task}`

**Компоненты:** Tracker  
**Оценка:** M

### Story 1.3: Добавить REST token auth для агентов
**Как** агент **я хочу** аутентифицироваться через токен в REST API **чтобы** делать запросы напрямую к Tracker

**Критерии приёмки:**
- [ ] Middleware `verify_agent_token()` проверяет заголовок `Authorization: Bearer tb-xxxxx`
- [ ] Токен валидируется по таблице Member.token
- [ ] Защищены все эндпоинты кроме `/docs`, `/health`, `/ws`
- [ ] При неверном токене возвращается 401
- [ ] BFF продолжает работать (проксирует с токеном)

**Компоненты:** Tracker  
**Оценка:** S

## Эпик 2: Task Operations — Агентские операции с задачами
Цель: Реализовать специальные операции для агентов из PRD
Зависимости: Эпик 1

### Story 2.1: Реализовать take task API
**Как** агент **я хочу** атомарно взять задачу в работу **чтобы** не было race condition с другими агентами

**Критерии приёмки:**
- [ ] `POST /api/v1/tasks/{id}/take` endpoint создан
- [ ] Проверяется что задача в статусе backlog или todo
- [ ] Атомарно устанавливается assignee_slug = текущий агент и status = in_progress
- [ ] При конфликте возвращается 409 Conflict
- [ ] Broadcast task.updated события после успешного взятия
- [ ] BFF проксирует операцию

**Компоненты:** Tracker / BFF  
**Оценка:** M

### Story 2.2: Реализовать reject task API
**Как** агент **я хочу** отклонить назначенную мне задачу **чтобы** вернуть её в backlog с объяснением

**Критерии приёмки:**
- [ ] `POST /api/v1/tasks/{id}/reject` с body `{"reason": "string"}`
- [ ] Проверяется что assignee_slug = текущий агент
- [ ] Устанавливается assignee_slug = null, status = backlog
- [ ] Добавляется комментарий-сообщение "Задача отклонена: {reason}"
- [ ] Broadcast task.updated события
- [ ] BFF проксирует операцию

**Компоненты:** Tracker / BFF  
**Оценка:** M

### Story 2.3: Реализовать assign task API
**Как** участник **я хочу** назначить задачу другому участнику **чтобы** делегировать работу

**Критерии приёмки:**
- [ ] `POST /api/v1/tasks/{id}/assign` с body `{"assignee_slug": "string"}`
- [ ] Проверяется существование assignee в проекте
- [ ] Устанавливается assignee_slug и status = todo (если был backlog)
- [ ] Broadcast task.updated события
- [ ] BFF проксирует операцию

**Компоненты:** Tracker / BFF  
**Оценка:** S

### Story 2.4: Реализовать watch/unwatch task API
**Как** участник **я хочу** подписываться на уведомления по задаче **чтобы** отслеживать её прогресс

**Критерии приёмки:**
- [ ] `POST /api/v1/tasks/{id}/watch` добавляет текущий slug в watchers[]
- [ ] `DELETE /api/v1/tasks/{id}/watch` удаляет slug из watchers[]
- [ ] Дубликаты в watchers игнорируются
- [ ] Broadcast task.updated события при изменении watchers
- [ ] BFF проксирует операции

**Компоненты:** Tracker / BFF  
**Оценка:** S

## Эпик 3: WebSocket Events — Правильная фильтрация событий
Цель: Унифицировать фильтрацию событий для всех типов участников
Зависимости: Эпик 2

### Story 3.1: Реализовать project.subscribe для humans
**Как** пользователь веб-клиента **я хочу** подписываться только на события нужных проектов **чтобы** не получать лишний трафик

**Критерии приёмки:**
- [ ] Humans/bridges могут отправлять `project.subscribe` сообщения
- [ ] `connection.subscribed_projects` хранит список подписок
- [ ] По умолчанию подписок нет (не "получать всё")
- [ ] События фильтруются по подпискам для всех типов участников
- [ ] Web Client автоматически подписывается на текущий проект

**Компоненты:** Tracker / Web  
**Оценка:** M

### Story 3.2: Унифицировать фильтрацию по listen_mode
**Как** агент с chat_listen="mentions" **я хочу** получать только сообщения где меня упоминают **чтобы** снизить шум в канале

**Критерии приёмки:**
- [ ] Функция `should_receive_event(client, event_type, data)` для всех типов
- [ ] chat_listen="mentions" → только сообщения с mentions[] содержащими агента
- [ ] chat_listen="all" → все сообщения в подписанных проектах
- [ ] task_listen="mentions" → только задачи где агент assignee/reviewer/watcher
- [ ] task_listen="all" → все task события в подписанных проектах
- [ ] Humans используют ту же логику с listen_mode="all" по умолчанию

**Компоненты:** Tracker  
**Оценка:** M

### Story 3.3: Исправить on_behalf_of validation
**Как** BFF **я хочу** валидировать on_behalf_of пользователей **чтобы** предотвратить коллизии slug

**Критерии приёмки:**
- [ ] При on_behalf_of проверяется существование Member с таким slug
- [ ] Несуществующие users получают префикс `web-{slug}`
- [ ] Все proxy подключения логируются с уровнем INFO
- [ ] Bridge не может перехватить slug существующего агента
- [ ] Добавлены unit тесты для collision cases

**Компоненты:** BFF  
**Оценка:** S

## Эпик 4: Agent Management — UI для управления агентами
Цель: Создать интерфейс для создания и мониторинга агентов
Зависимости: Эпик 3

### Story 4.1: Страница Agent Management
**Как** администратор **я хочу** видеть список всех агентов с их статусами **чтобы** мониторить работу системы

**Критерии приёмки:**
- [ ] Страница `/agents` доступна в навигации
- [ ] Таблица агентов с колонками: name, slug, status, capabilities, last_seen_at
- [ ] Статусы показаны цветами: 🟢 online, 🔴 offline, 🟡 busy
- [ ] Обновление статусов через WebSocket в реальном времени
- [ ] Кнопка "Create Agent" ведёт на форму создания

**Компоненты:** Web  
**Оценка:** M

### Story 4.2: Форма создания агента
**Как** администратор **я хочу** создать нового агента и получить его токен **чтобы** подключить к системе

**Критерии приёмки:**
- [ ] Форма с полями: name, slug, capabilities (чекбоксы), chat_listen, task_listen, model
- [ ] Slug валидируется на уникальность
- [ ] При создании генерируется токен формата `tb-{32 random chars}`
- [ ] Токен показывается один раз с предупреждением "Сохраните токен"
- [ ] После создания редирект на `/agents` со списком
- [ ] Токен копируется в clipboard кнопкой

**Компоненты:** Web / BFF / Tracker  
**Оценка:** M

### Story 4.3: Agent configuration UI
**Как** администратор **я хочу** редактировать настройки агента **чтобы** корректировать его поведение

**Критерии приёмки:**
- [ ] В таблице агентов кнопка "Edit" открывает модальное окно
- [ ] Поля: name, capabilities, chat_listen, task_listen, model, prompt
- [ ] Slug не редактируется (readonly)
- [ ] Кнопка "Regenerate Token" с подтверждением
- [ ] Изменения сохраняются через PATCH API
- [ ] Обновление конфигурации применяется без перезапуска агента

**Компоненты:** Web / BFF / Tracker  
**Оценка:** M

## Эпик 5: Task Steps UI — Интеграция steps в интерфейс
Цель: Показывать прогресс задач через steps UI
Зависимости: Эпик 4

### Story 5.1: Steps в TaskModal
**Как** пользователь **я хочу** видеть этапы задачи в виде чеклиста **чтобы** отслеживать прогресс выполнения

**Критерии приёмки:**
- [ ] Секция Steps между описанием и комментариями в TaskModal
- [ ] Список шагов с чекбоксами и заголовками
- [ ] Прогресс-бар "3 из 7 выполнено" вверху секции
- [ ] Чекбоксы интерактивны — клик отмечает/снимает выполнение
- [ ] Обновления сохраняются через PATCH API
- [ ] Live обновления через WebSocket

**Компоненты:** Web  
**Оценка:** M

### Story 5.2: Управление steps в TaskModal
**Как** исполнитель задачи **я хочу** добавлять и удалять этапы **чтобы** планировать свою работу

**Критерии приёмки:**
- [ ] Кнопка "+ Add Step" в секции Steps
- [ ] Инлайн добавление шага с автосохранением
- [ ] Кнопка удаления у каждого шага (только для незавершённых)
- [ ] Drag & drop для изменения порядка шагов
- [ ] Завершённые шаги визуально отличаются (зачёркнутый текст)

**Компоненты:** Web  
**Оценка:** S

## Эпик 6: Files & Attachments — Загрузка файлов
Цель: Реализовать upload/download файлов в сообщениях
Зависимости: Эпик 5

### Story 6.1: Upload API для attachments
**Как** пользователь **я хочу** прикреплять файлы к сообщениям **чтобы** делиться документами с командой

**Критерии приёмки:**
- [ ] `POST /api/v1/messages/{id}/attachments` принимает multipart/form-data
- [ ] Файлы сохраняются в `/var/lib/team-board/attachments/{message_id}/`
- [ ] Создаётся Attachment запись в БД с metadata
- [ ] Поддерживаются файлы до 10MB
- [ ] Валидация MIME типов (изображения, документы, код)
- [ ] BFF проксирует загрузку с авторизацией

**Компоненты:** Tracker / BFF  
**Оценка:** M

### Story 6.2: Download API для attachments
**Как** пользователь **я хочу** скачивать прикреплённые файлы **чтобы** просматривать их локально

**Критерии приёмки:**
- [ ] `GET /api/v1/attachments/{id}` отдаёт файл с правильными заголовками
- [ ] Content-Type, Content-Length, Content-Disposition установлены
- [ ] Проверка доступа — пользователь должен иметь доступ к сообщению
- [ ] Обслуживание статичных файлов через FastAPI
- [ ] BFF проксирует скачивание с авторизацией

**Компоненты:** Tracker / BFF  
**Оценка:** S

### Story 6.3: File preview в UI
**Как** пользователь **я хочу** видеть превью файлов в чате **чтобы** не скачивать их для просмотра

**Критерии приёмки:**
- [ ] Изображения показываются как thumbnail в сообщении
- [ ] Клик на thumbnail открывает полноразмерное изображение
- [ ] Документы показываются как ссылки с иконками типов файлов
- [ ] Код файлы (.js, .py, .md) показываются с syntax highlighting
- [ ] Кнопка скачивания у каждого attachment

**Компоненты:** Web  
**Оценка:** M

## Эпик 7: MCP Tools — Инструменты для агентов  
Цель: Создать MCP Tools для взаимодействия агентов с системой
Зависимости: Эпик 6

### Story 7.1: Базовые Task Tools
**Как** агент **я хочу** создавать и управлять задачами через MCP **чтобы** автоматизировать workflow

**Критерии приёмки:**
- [ ] `create_task(title, description, project_slug, priority?, labels?)` → task_id
- [ ] `take_task(task_id)` → success/error
- [ ] `update_task(task_id, fields)` → updated task
- [ ] `complete_task(task_id)` → устанавливает status=done
- [ ] `list_tasks(project_slug?, status?, assignee?)` → task list
- [ ] Все tools используют существующий REST API с токен авторизацией

**Компоненты:** Picogent  
**Оценка:** M

### Story 7.2: Communication Tools  
**Как** агент **я хочу** отправлять сообщения и читать чат **чтобы** участвовать в обсуждениях

**Критерии приёмки:**
- [ ] `send_message(content, chat_id?, task_id?, mentions?)` → message_id
- [ ] `list_messages(chat_id?, task_id?, limit?)` → message list
- [ ] `add_task_comment(task_id, content)` → comment message
- [ ] `mention_user(slug, message)` → автодобавление в mentions[]
- [ ] Все сообщения получают правильный author_slug агента

**Компоненты:** Picogent  
**Оценка:** S

### Story 7.3: Project & Member Tools
**Как** агент **я хочу** получать информацию о проектах и участниках **чтобы** понимать контекст работы

**Критерии приёмки:**
- [ ] `list_projects()` → project list с основными полями
- [ ] `get_project(slug)` → детальная информация о проекте
- [ ] `list_members(project_slug?)` → список участников
- [ ] `get_member(slug)` → информация об участнике
- [ ] `watch_task(task_id)` / `unwatch_task(task_id)` → управление подписками

**Компоненты:** Picogent  
**Оценка:** S

## Эпик 8: Advanced Features — Дополнительные возможности
Цель: Реализовать отложенные features для полноценной работы
Зависимости: Эпик 7

### Story 8.1: Telegram Bridge Foundation
**Как** пользователь **я хочу** получать уведомления в Telegram **чтобы** не пропускать важные события проекта

**Критерии приёмки:**
- [ ] Bridge агент подключается как member типа "bridge"
- [ ] Принимает все события проектов (listen_mode="all")
- [ ] Фильтрует важные события: task.assigned на меня, mentions в чате
- [ ] Отправляет уведомления в личный чат Telegram
- [ ] Конфигурация через переменные окружения

**Компоненты:** Picogent (отдельный bridge agent)  
**Оценка:** L

### Story 8.2: Voice Messages Support
**Как** пользователь **я хочу** отправлять голосовые сообщения **чтобы** быстро комментировать задачи

**Критерии приёмки:**
- [ ] Web Client записывает аудио через MediaRecorder API
- [ ] Upload аудио как attachment с типом audio/*
- [ ] Message.voice_url ссылается на attachment
- [ ] Аудио плеер в UI для воспроизведения
- [ ] Агенты могут транскрибировать voice_url через STT

**Компоненты:** Web / Tracker / Picogent  
**Оценка:** L

### Story 8.3: Advanced Task Dependencies
**Как** PM **я хочу** видеть граф зависимостей задач **чтобы** планировать последовательность работ

**Критерии приёмки:**
- [ ] UI для добавления зависимостей в TaskModal (autocomplete других задач)
- [ ] Валидация циклических зависимостей на бэкенде
- [ ] Визуализация зависимостей в виде граф-диаграммы
- [ ] Блокировка взятия задач с незавершёнными зависимостями
- [ ] Автоматическое уведомление при разблокировке задачи

**Компоненты:** Web / Tracker  
**Оценка:** L