From 036e5ff481cf218c8a871392daf069f249e7d4c8 Mon Sep 17 00:00:00 2001 From: Markov Date: Sun, 22 Feb 2026 14:59:08 +0100 Subject: [PATCH] =?UTF-8?q?add:=20architecture=20review=20=E2=80=94=20cont?= =?UTF-8?q?radictions=20and=20issues=20found?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ARCHITECTURE-REVIEW-2026-02-22.md | 117 ++++++++++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 ARCHITECTURE-REVIEW-2026-02-22.md diff --git a/ARCHITECTURE-REVIEW-2026-02-22.md b/ARCHITECTURE-REVIEW-2026-02-22.md new file mode 100644 index 0000000..5a5c87e --- /dev/null +++ b/ARCHITECTURE-REVIEW-2026-02-22.md @@ -0,0 +1,117 @@ +# Архитектурный ревью: поиск противоречий и проблем +Дата: 2026-02-22 +Автор: Winston (Архитектор, BMAD) + +Проанализированы все документы: ARCHITECTURE.md, 10 брейнштормов, WS-PROTOCOL, MCP-TOOLS. + +--- + +## 🔴 Критические противоречия + +### 1. Redis Streams: решено или нет? +- **BRAINSTORM-MICROSERVICES**: Redis Streams = "КЛЮЧЕВОЕ решение", принят, расписан reconnect через XREAD +- **Разговор 22.02**: Хозяин сказал "не уверен что нужен Redis Streams, оставляй на обсуждение" +- **ARCHITECTURE.md**: Redis "пока не используется", но в "Идеях" — Redis Streams для event bus +- **BRAINSTORM-WS-V2**: Redis Streams не упоминается вообще + +**Проблема:** Документы противоречат друг другу. В одном Redis Streams принят, в другом под вопросом. + +**Решение:** Убрать Redis Streams из принятых решений. Оставить как идею на будущее. Сейчас: WS для online агентов + REST для получения пропущенного при reconnect (GET /tasks?assignee=me). Проще, меньше компонентов. + +### 2. Unified Message vs ChatMessage + TaskComment +- **BRAINSTORM-UI**: решено — Message = одна сущность (chat_id? / task_id?) +- **BRAINSTORM-CHATS**: модель `ChatMessage` с `chat_id` (не task_id) +- **BRAINSTORM-TASKS**: модель `TaskComment` — отдельная сущность +- **ARCHITECTURE.md**: `ChatMessage` и комментарии описаны отдельно + +**Проблема:** Старые документы описывают две сущности, новое решение — одну. ARCHITECTURE.md не обновлён. + +**Решение:** Обновить ARCHITECTURE.md. Одна таблица `Message` с полями chat_id? и task_id?. + +### 3. Файловое хранилище: три версии +- **ARCHITECTURE.md**: "Файловое хранилище — Per-project директории, Upload/download через REST API" +- **BRAINSTORM-AGENTS**: "File storage — всегда, docs, картинки, видео, attachments" +- **Разговор 22.02**: "Отдельного файлового сервиса нет, файлы = вложения к сообщениям/задачам" + +**Проблема:** ARCHITECTURE.md описывает отдельный файловый сервис, а решение — просто attachments. + +**Решение:** Обновить. Файлы = attachments в Message. Документация проекта = ссылка в описании (repo_urls / description). Per-project директории на диске для хранения attachment'ов — деталь реализации. + +--- + +## 🟡 Нестыковки (не критические) + +### 4. WS-PROTOCOL.md vs BRAINSTORM-WS-V2 +Два документа описывают WS протокол с разными решениями: +- **WS-PROTOCOL.md** (старый): task.take, task.complete, task.comment через WS (мутации!) +- **BRAINSTORM-WS-V2** (новый): мутации только через REST + +**Решение:** WS-PROTOCOL.md устарел. Либо обновить, либо пометить deprecated и ссылаться на WS-V2. + +### 5. Agent model: Member vs Agent +- **ARCHITECTURE.md**: Unified Member model (human + agent = одна модель) +- **WS-PROTOCOL.md**: отдельная модель `Agent` с полями connection_type, callback_url и т.д. +- **BRAINSTORM-AGENTS**: "Агент = чёрный ящик", отдельная сущность + +**Проблема:** Не ясно — Member или Agent? Если Member, то connection_type, callback_url, prompt, capabilities — это поля Member? + +**Решение:** Member — базовая модель. Для type=agent дополнительные поля (capabilities, listen_mode, prompt, model). Можно JSON-поле `agent_config` или отдельная таблица `AgentConfig` с FK на Member. + +### 6. Listen modes: один или два? +- **BRAINSTORM-PROJECTS**: `listen: all | mentions` — один режим +- **BRAINSTORM-WS-V2**: `chat_listen` + `task_listen` — два раздельных + +**Решение:** Два раздельных (WS-V2 — более новое решение). + +### 7. HTTP Callback transport +- **WS-PROTOCOL.md**: описан HTTP Callback как альтернативный транспорт +- **Нигде больше не упоминается** + +**Решение:** Убрать из MVP. Если агент offline — он при reconnect запросит текущее состояние через REST. + +### 8. chat.send: через WS или REST? +- **BRAINSTORM-PROTOCOL**: "WS = real-time + чат" +- **BRAINSTORM-MCP-TOOLS**: `send_message` в списке MCP tools (= REST) +- **BRAINSTORM-WS-V2**: `chat.send` в списке клиент→сервер WS событий + +**Проблема:** Чат отправляется и через WS, и через REST? + +**Решение:** Оба варианта валидны. WS для агентов (уже подключены, real-time). REST (MCP tool) — тоже работает (для MCP-клиентов без WS). Tracker обрабатывает одинаково. + +### 9. Watchers: новая фича, нигде кроме WS-V2 +- **BRAINSTORM-WS-V2**: watchers[] на задаче +- **BRAINSTORM-TASKS**: не упоминается +- **ARCHITECTURE.md**: не упоминается + +**Решение:** Добавить watchers в модель задачи при обновлении ARCHITECTURE.md. + +--- + +## 🟢 Открытые вопросы (не противоречия, а незакрытое) + +### 10. Лейблы: глобальные или per-project? +Упоминается в BRAINSTORM-PROJECTS как TBD. Не решено. + +### 11. Реакции в чатах +Упоминается в BRAINSTORM-CHATS как TBD. Не решено. + +### 12. Multi-instance агентов +Упоминается в BRAINSTORM-MISC. Как различать: slug = роль, instance_id? + +### 13. Rollback файлов в хранилище +Упоминается в BRAINSTORM-MISC. Версионирование attachments? + +### 14. Устаревшие документы +- `WS-PROTOCOL.md` — устарел (заменён BRAINSTORM-WS-V2 + BRAINSTORM-PROTOCOL) +- `AGENTS-INTEGRATION.md` — не проверен на актуальность +- `RESEARCH.md` — исследование, может быть неактуально +- `IDEAS.md` — первоначальные идеи, многое уже решено иначе + +--- + +## Рекомендации + +1. **Обновить ARCHITECTURE.md v0.4** — единый источник правды, включить все решения из брейнштормов +2. **Пометить устаревшие документы** — WS-PROTOCOL.md, AGENTS-INTEGRATION.md +3. **Решить Redis Streams** — убрать из принятых, оставить как идею +4. **Решить открытые вопросы** (лейблы, реакции) или явно пометить как "решим при реализации"