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