# Architecture Review — Team Board Дата: 2026-02-23 ## 1. Соответствие PRD ### 4.1 Управление проектами ✅ ХОРОШО - **Архитектура:** Полностью покрывает, модель Project с multi-repo поддержкой - **Код:** Реализовано 100%, все API endpoints работают, UI компоненты созданы - **Расхождения:** Нет ### 4.2 Управление задачами (Kanban) ⚠️ ЧАСТИЧНО - **Архитектура:** Покрывает полностью, модель Task с подзадачами, зависимостями, watchers - **Код:** Базовые CRUD есть, но отсутствуют специальные операции - **Расхождения:** - ❌ `POST /api/v1/tasks/{id}/take` — не реализован (БФФ проксирует, но в трекере нет) - ❌ `POST /api/v1/tasks/{id}/reject` — не реализован - ❌ `POST /api/v1/tasks/{id}/assign` — не реализован - ❌ `POST /api/v1/tasks/{id}/watch` — не реализован - ✅ Базовые CRUD работают ### 4.3 Чат и коммуникация ✅ ХОРОШО - **Архитектура:** Unified Message модель реализована корректно - **Код:** Message с chat_id/task_id работает, WS chat.send функционирует - **Расхождения:** - ⚠️ Голосовые сообщения (voice_url) — поле есть в модели, но API загрузки нет ### 4.4 AI агенты ⚠️ ПРОБЛЕМЫ - **Архитектура:** Модель Member unified, AgentConfig детализирован - **Код:** Модели реализованы, но проблемы с функциональностью - **Расхождения:** - ❌ Agent management UI — полностью отсутствует - ❌ MCP Tools — не реализованы - ❌ Фильтрация WS событий по capabilities — упрощена: humans получают ВСЁ - ❌ REST API token auth для агентов — не работает (только WS auth) ### 4.5 Файлы и вложения ❌ НЕ РЕАЛИЗОВАНО - **Архитектура:** Модель Attachment есть - **Код:** Полностью отсутствует - **Расхождения:** - ❌ `POST /api/v1/messages/{id}/attachments` — не реализован - ❌ `GET /api/v1/attachments/{id}` — не реализован - ❌ Хранение файлов — не реализовано ### 4.6 Аутентификация и авторизация ⚠️ ЧАСТИЧНО - **Архитектура:** JWT + Token auth описаны корректно - **Код:** JWT через BFF работает, agent WS auth работает - **Расхождения:** - ❌ Token auth для REST API агентов — проверка не реализована - ✅ BFF JWT auth работает - ✅ WS token auth для агентов работает ### 4.7 WebSocket и реал-тайм ⚠️ ПРОБЛЕМЫ - **Архитектура:** Подробно описан протокол, фильтрация событий - **Код:** Базовые WS работают, но упрощённая архитектура - **Расхождения:** - ❌ Task события (task.created/updated/assigned) — не транслируются - ⚠️ Упрощённая фильтрация: humans/bridges получают ВСЁ, agents — по подпискам - ✅ auth, heartbeat, chat.send, project.subscribe работают ### 4.8 Steps (этапы задач) ✅ ХОРОШО - **Архитектура:** Корректно описаны как чеклист внутри задачи - **Код:** Полная реализация: модель, API, UI в TaskModal - **Расхождения:** Нет ## 2. Архитектурные проблемы ### 2.1 WebSocket: Один слот на slug — КРИТИЧЕСКАЯ ПРОБЛЕМА **Проблема:** `ConnectionManager.clients: dict[str, ConnectedClient]` — один слот на slug. ```python # manager.py:15 self.clients: dict[str, ConnectedClient] = {} # slug → client ``` **Последствия:** - Множественные вкладки одного пользователя вытесняют друг друга - Агент при переподключении теряет предыдущую сессию - Race conditions при одновременных подключениях **Решение:** `dict[str, list[ConnectedClient]]` или уникальные session_id. ### 2.2 Task Events не транслируются **Проблема:** В коде есть `broadcast_task_event`, но никто её не вызывает. ```python # manager.py:47 async def broadcast_task_event(self, project_id: str, event_type: str, data: dict): ``` **Последствия:** Агенты не получают уведомления о создании/обновлении задач. **Решение:** Интегрировать в REST API endpoints для задач. ### 2.3 REST API авторизация агентов не работает **Проблема:** Токен проверяется только в WebSocket, REST API для агентов полностью открыт. ```python # BFF проксирует агентские операции, но агенты не могут ходить напрямую к Tracker ``` **Последствия:** Агенты не могут делать REST вызовы без BFF. **Решение:** Добавить token auth middleware в Tracker REST API. ### 2.4 BFF on_behalf_of создаёт collision risk **Проблема:** Bridge может зарегистрировать любой `on_behalf_of` slug, даже несуществующий. ```python # handler.py:88-95 if on_behalf_of and member.type == "bridge": # Если пользователь не найден, используется синтетический slug effective_slug = on_behalf_of ``` **Последствия:** Коллизии slug при подключении реального пользователя. **Решение:** Строгая валидация on_behalf_of или префиксы для synthetic slugs. ### 2.5 Упрощённая фильтрация событий **Проблема:** Humans/bridges получают ВСЕ события без фильтрации. ```python # manager.py:36 if client.member_type in ("human", "bridge"): await self.send_to(slug, {"type": "message.new", "data": message}) continue ``` **Последствия:** Лишний трафик, невозможность настроить подписки для людей. **Решение:** Единая логика фильтрации для всех типов участников. ## 3. Расхождения документация ↔ код ### 3.1 TRACKER-PROTOCOL.md vs реальный протокол **Документ описывает:** - task.created/updated/assigned события - Детальную фильтрацию по listen_mode и capabilities - REST API endpoints для task operations **Реальный код:** - Task события не отправляются - Упрощённая фильтрация (humans получают всё) - Task API endpoints отсутствуют ### 3.2 ARCHITECTURE.md vs WS manager **Документ описывает:** - Фильтрацию по capabilities и listen modes - Отдельные подписки для humans **Реальный код:** - Capabilities не используются в фильтрации - Humans получают всё без подписок ### 3.3 CONCEPTS.md vs Agent REST auth **Документ описывает:** - REST API с token авторизацией для агентов - MCP Tools полный набор **Реальный код:** - REST API открыт для всех - MCP Tools отсутствуют ### 3.4 PRD vs отсутствующие features **PRD объявляет реализованными:** - Agent management UI - Attachments API - Task special operations **Реальный код:** - Эти features полностью отсутствуют ## 4. Рекомендации ### P0: Блокеры #### P0.1 Исправить WebSocket collision ```python # manager.py class ConnectionManager: def __init__(self): self.clients: dict[str, list[ConnectedClient]] = {} # slug → clients[] self.sessions: dict[str, ConnectedClient] = {} # session_id → client ``` **Без этого:** Система не работает корректно при multiple connections. #### P0.2 Добавить REST token auth для агентов ```python # tracker/api/middleware.py async def verify_agent_token(request: Request): auth = request.headers.get("Authorization") if auth and auth.startswith("Bearer "): token = auth[7:] # Проверить в БД Member.token ``` **Без этого:** Агенты не могут использовать API напрямую. #### P0.3 Реализовать task events ```python # tracker/api/tasks.py после create/update/delete await broadcast_task_event(task.project_id, "task.created", task_data) ``` **Без этого:** Агенты не видят изменения задач. ### P1: Важно #### P1.1 Реализовать task special operations - `POST /api/v1/tasks/{id}/take` — атомарное взятие задачи - `POST /api/v1/tasks/{id}/reject` — отклонение с причиной - `POST /api/v1/tasks/{id}/assign` — назначение - `POST /api/v1/tasks/{id}/watch` — подписка на задачу **Почему:** Это ключевые операции для работы агентов с задачами. #### P1.2 Создать Agent Management UI - Страница `/agents` с списком агентов - Создание агентов с генерацией токенов - Просмотр статусов и capabilities **Почему:** Без UI управление агентами невозможно. #### P1.3 Унифицировать фильтрацию событий ```python async def should_receive_event(client: ConnectedClient, event_type: str, data: dict) -> bool: # Единая логика для всех типов участников # Проверка подписок, listen_mode, capabilities ``` **Почему:** Текущая архитектура не масштабируется. #### P1.4 Исправить on_behalf_of логику - Валидировать существование пользователя - Использовать префиксы для synthetic slugs: `web-{slug}` - Логировать все proxy подключения **Почему:** Предотвращает коллизии и security issues. ### P2: Хорошо бы #### P2.1 Реализовать Attachments API - `POST /api/v1/messages/{id}/attachments` — загрузка - `GET /api/attachments/{id}` — скачивание - Хранение на диске по storage_path **Почему:** Команды часто работают с файлами. #### P2.2 Добавить MCP Tools для агентов - create_task, take_task, update_task - send_message, list_messages - watch_task, unwatch_task **Почему:** Агентам нужны инструменты для работы. #### P2.3 Улучшить monitoring - Health check endpoints `/health` - Метрики WebSocket connections - Логирование всех WS событий с timestamps **Почему:** Проще дебажить и мониторить продакшен. ## 5. Обновлённая архитектурная диаграмма ### Текущая архитектура (как есть) ``` Web Client ——HTTP/JWT——→ BFF ——HTTP/Token——→ Tracker ↓ ↑ ↑ WS/JWT————————————————┘ │ │ WS/Token Picogent Agent ———————————————————————————————————┘ (REST auth не работает) ConnectionManager: dict[slug → client] ← ПРОБЛЕМА Фильтрация: humans=ALL, agents=subscription ← УПРОЩЕНО Task events: НЕ ОТПРАВЛЯЮТСЯ ← ПРОБЛЕМА ``` ### Целевая архитектура (как должно быть) ``` Web Client ——HTTP/JWT——→ BFF ——HTTP/Token——→ Tracker ↓ ↑ ↑ ↑ WS/JWT————————————————┘ │ │ WS/Token │ │ Picogent Agent ————HTTP/Token—————————————————┘ │ ├————————WS/Token————————————————————────┘ └————————MCP Tools———————┘ ConnectionManager: dict[slug → clients[]] ← ФИКС dict[session_id → client] ← ФИКС Фильтрация: unified для всех типов ← УЛУЧШЕНИЕ Task events: все операции транслируются ← ФИКС Agent REST: token auth работает ← ФИКС ``` ### Компоненты как должны быть | Компонент | Порт | Протоколы | Изменения | |-----------|------|-----------|-----------| | **Tracker** | 8100 | HTTP+WS (token auth) | + Task events, + Agent REST auth | | **BFF** | 8200 | HTTP+WS (JWT auth) | + on_behalf_of validation | | **Web Client** | 3100 | HTTP+WS через BFF | + Agent Management UI | | **Picogent** | — | HTTP+WS к Tracker | + MCP Tools | ### Протоколы взаимодействия - **Web ↔ BFF:** JWT auth, WS proxy с session management - **BFF ↔ Tracker:** Token auth, on_behalf_of для web users - **Agent ↔ Tracker:** Token auth для HTTP и WS, unified - **Events:** Task+Message события через WS с единой фильтрацией --- **Итог:** Архитектура в целом правильная, но много критических недоработок в реализации. Основная проблема — WebSocket connection management и отсутствие task events. После фиксов P0 система будет работать корректно.