add: architecture review — contradictions and issues found
This commit is contained in:
parent
faa2dcd15c
commit
036e5ff481
117
ARCHITECTURE-REVIEW-2026-02-22.md
Normal file
117
ARCHITECTURE-REVIEW-2026-02-22.md
Normal file
@ -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. **Решить открытые вопросы** (лейблы, реакции) или явно пометить как "решим при реализации"
|
||||
Loading…
Reference in New Issue
Block a user