From 1bb548ff3b69868830320f7614c82b7e18d373ea Mon Sep 17 00:00:00 2001 From: Markov Date: Mon, 23 Feb 2026 19:43:50 +0100 Subject: [PATCH] docs: Architecture Review --- ARCHITECTURE-REVIEW.md | 301 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 301 insertions(+) create mode 100644 ARCHITECTURE-REVIEW.md diff --git a/ARCHITECTURE-REVIEW.md b/ARCHITECTURE-REVIEW.md new file mode 100644 index 0000000..de44b06 --- /dev/null +++ b/ARCHITECTURE-REVIEW.md @@ -0,0 +1,301 @@ +# 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 система будет работать корректно. \ No newline at end of file