team-board/docs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
58388d3021
docs/ARCHITECTURE-REVIEW-2026-02-22.md

7.5 KiB
Raw Blame History

Архитектурный ревью: поиск противоречий и проблем

Дата: 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. Решить открытые вопросы (лейблы, реакции) или явно пометить как "решим при реализации"