team-board/docs
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: обновление архитектуры

Browse Source 
- Tracker-centric модель
- Переименование: backend→tracker, frontend→web-client
- Канбан: Backlog + черновики + статусы
- Зависимости задач
- Файлы в задачах
- Три уровня чатов (лобби, проект, задача)
- Подписка агентов (all/mentions/assigned)
- WebSocket протокол
This commit is contained in:
Markov 2026-02-15 18:00:47 +01:00
parent 4209bc26fd
commit cf2289516e
1 changed files with 298 additions and 255 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

553
IDEAS.md
View File

@ -19,279 +19,319 @@
---
## Архитектура
## Архитектура: Tracker-Centric
### Микросервисы (Python + FastAPI)
### Принцип
| Сервис | Описание |
|--------|----------|
| Gateway | API Gateway, аутентификация |
| Projects | Проекты, Git интеграция |
| Tasks | Задачи, канбан, подзадачи |
| Agents | Управление AI агентами |
| Chat | Чаты проектов |
**Tracker = центральный сервис.** Всё остальное — клиенты.
### Frontend (Next.js)
```
┌─────────────────────────────────────────────────────┐
│ WEB CLIENT │
│ ┌───────────┐ ┌────────────┐ │
│ │ Next.js │ ←→ │ BFF │ (свой бэкенд) │
│ │ фронтенд │ │ Python │ │
│ └───────────┘ │ + Authentik│ │
│ └─────┬──────┘ │
└──────────────────────────┼──────────────────────────┘
│ ws (внутренняя сеть)
┌────────────▼────────────┐
│ TRACKER │
│ (внутренний сервис) │
│ НЕ выставлен наружу │
│ │
│ - проекты │
│ - доски (канбан) │
│ - задачи + подзадачи │
│ - чаты │
│ - события │
│ - БД (PostgreSQL) │
└────────────┬────────────┘
│ ws
┌─────────────────┼─────────────────┐
▼ ▼ ▼
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Агент 1 │ │ Агент 2 │ │ Агент N │
│ (Claude) │ │ (Codex) │ │ (Gemini) │
│ отд. сервис │ │ отд. сервис │ │ отд. сервис │
└──────────────┘ └──────────────┘ └──────────────┘
```
Web UI для управления всем.
### Компоненты
### Database
| Компонент | Описание |
|-----------|----------|
| **Tracker** | Ядро: проекты, задачи, чаты, события. Внутренний, WebSocket сервер |
| **Web Client** | Next.js + BFF (Python). Авторизация через Authentik. Единственное что торчит наружу |
| **Агенты** | Отдельные сервисы. Подключаются к трекеру по WebSocket |
PostgreSQL (существующий на сервере).
### Репозитории
```
team-board/
├── tracker/ — ядро (Python, WebSocket, PostgreSQL)
├── web-client/ — Next.js + BFF
└── docs/ — документация
```
Агенты — отдельные репозитории (шаблон + конкретные).
---
## UI Layout
## Канбан-доска
### Колонки
```
┌────────────────────────────────────────────────────────────────────┐
│ [Logo] Team Board [User Avatar] ▼ │
├──────────────┬─────────────────────────────────────────────────────┤
│ │ Project Alpha [Settings] │
│ PROJECTS │─────────────────────────────────────────────────────│
│ │ 💬 Chat ▼ (сворачиваемый) │
│ ○ Alpha │ ┌──────────────────────────────────────────────┐ │
│ ● Beta │ │ Agent-1: Закоммитил фикс для issue #42 │ │
│ ○ Gamma │ │ Agent-2: Проверил, всё ок │ │
│ │ │ You: Мержите │ │
│ [+ New] │ └──────────────────────────────────────────────┘ │
│ │─────────────────────────────────────────────────────│
│──────────────│ KANBAN │
│ │ │
│ AGENTS │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ │ Backlog │ │ In Prog │ │ Review │ │ Done │ │
│ ● Claude │ ├─────────┤ ├─────────┤ ├─────────┤ ├─────────┤ │
│ ○ Codex │ │ [Task3] │ │ [Task1] │ │ [Task2] │ │ [Task0] │ │
│ ○ Gemini │ │ │ │ └─sub │ │ │ │ │ │
│ │ │ │ │ └─sub │ │ │ │ │ │
│ [+ Add] │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
│ │ │
└──────────────┴─────────────────────────────────────────────────────┘
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ Backlog │ │ TODO │ │ In Prog │ │ Review │ │ Done │
├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤ ├──────────┤
│ [draft] │ │ [ready] │ │ [active] │ │ [review] │ │[complete]│
│ [draft] │ │ [ready] │ │ │ │ │ │[complete]│
│ │ │ │ │ │ │ │ │ │
└──────────┘ └──────────┘ └──────────┘ └──────────┘ └──────────┘
```
### Статусы задач
| Статус | Описание |
|--------|----------|
| `draft` | Черновик. Можно обсуждать, но не выполнять |
| `ready` | Готова к выполнению. Перенос из Backlog → TODO автоматически ставит этот статус |
| `in_progress` | Агент взял в работу |
| `review` | На ревью у другого агента |
| `completed` | Выполнена |
| `blocked` | Заблокирована зависимостью |
### Жизненный цикл задачи
```
1. Человек создаёт задачу → draft (Backlog)
2. Обсуждение в чате проекта
3. Человек перетаскивает в TODO → статус меняется на ready
4. Агент берёт задачу → in_progress
5. Агент завершает → review
6. Ревьюер проверяет → completed / возврат в in_progress
```
---
## Задачи
### Структура задачи
```yaml
Задача:
id: uuid
проект: project_id
название: "Реализовать API авторизации"
описание: "Markdown текст с деталями"
статус: draft | ready | in_progress | review | completed | blocked
# Назначение
назначен: agent_id (или null)
# Вложенные файлы
файлы:
- name: "schema.sql"
type: "text/sql"
content: "..."
- name: "mockup.png"
type: "image/png"
url: "/files/task-123/mockup.png"
# Подзадачи (неограниченная вложенность)
подзадачи:
- название: "Написать модели"
назначен: agent-coder
статус: completed
- название: "Code review"
назначен: agent-reviewer
статус: in_progress
# Зависимости
зависит_от: [task_id_1, task_id_2]
блокирует: [task_id_3]
# Мета
приоритет: low | medium | high | critical
теги: ["api", "auth"]
создано: timestamp
обновлено: timestamp
```
### Зависимости задач
```
Task A ──depends_on──→ Task B
│
└─ Task A НЕ может быть взята пока Task B не completed
Пример:
"Написать тесты" зависит от "Написать код"
"Деплой" зависит от "Тесты пройдены"
```
**Правила:**
- Задача со статусом `blocked` не может быть взята агентом
- Когда зависимость завершена → автоматически разблокировать
- Циклические зависимости запрещены (валидация при создании)
- В UI: визуальная связь между задачами (стрелки)
### Приложенные файлы
- К задаче можно прикрепить файлы (код, изображения, документы)
- Агент может добавлять файлы к задаче (результаты работы)
- Файлы хранятся на диске, метаданные в БД
- Превью для изображений и кода в UI
---
## Чаты
### Три уровня
#### 1. Лобби (общий чат)
Отдельная сущность, не привязан к проекту:
- Обсуждение идей с агентами
- Аналитика, brainstorm
- Агент может создавать файлы, заметки
- Место для обсуждения до создания проекта
#### 2. Чат проекта
У каждого проекта свой чат:
- Обсуждение задач
- Системные уведомления (задача создана, завершена, etc.)
- Агенты видят только чаты своих проектов
#### 3. Комментарии задачи
Внутри каждой задачи:
- Обсуждение деталей
- Код ревью
- Результаты подзадач
---
## Агенты
### Типы провайдеров (адаптеры)
| Провайдер | Описание |
|-----------|----------|
| `anthropic` | Claude API (Opus, Sonnet) |
| `openai` | GPT, Codex |
| `google` | Gemini |
| `openclaw` | Через OpenClaw Gateway (с инструментами) |
| `cli` | Claude Code CLI (без API токенов) |
### Настройки агента
```yaml
Агент:
имя: "Кодер"
slug: "coder"
провайдер: anthropic
модель: claude-sonnet-4-20250514
api_key: "sk-..." # зашифрован
системный_промпт: "Ты — backend разработчик..."
подписка:
режим: mentions # all | mentions | assigned
проекты: ["*"] # или конкретные
ограничения:
макс_параллельных: 2
таймаут: 600 # секунд
```
### Подписка на события
| Режим | Агент получает |
|-------|---------------|
| `all` | Все сообщения в подписанных проектах |
| `mentions` | Только когда @упомянут |
| `assigned` | Назначенные задачи + mentions |
---
## WebSocket протокол
### Трекер → Клиент
```
task.created — задача создана
task.updated — задача обновлена
task.ready — задача готова к выполнению (перенесена из Backlog)
task.assigned — задача назначена агенту
task.blocked — задача заблокирована зависимостью
task.unblocked — зависимость выполнена, задача разблокирована
chat.message — новое сообщение в чате
agent.status — статус агента изменился
file.attached — файл прикреплён к задаче
```
### Клиент → Трекер
```
task.take — агент берёт задачу
task.complete — агент завершил задачу
task.comment — комментарий к задаче
task.attach — прикрепить файл
chat.send — отправить сообщение в чат
agent.register — регистрация агента
agent.heartbeat — пульс
```
---
## Workflow: от идеи до деплоя
### Фаза 1: Инициация проекта
### Фаза 1: Идея → Проект
**Точки входа:**
- Через главного агента (Марков) в Telegram
- Через Web UI — кнопка "New Project"
- Через любого агента
1. Человек открывает Лобби
2. Обсуждает идею с агентом-аналитиком
3. Создаёт проект
4. Агент формирует BRIEF.md, REQUIREMENTS.md
**Результат:** Создаётся черновик проекта, открывается Discovery Chat.
### Фаза 2: Декомпозиция → Задачи
---
1. На основе требований создаются задачи (черновики в Backlog)
2. Расставляются зависимости
3. Прикрепляются файлы (макеты, схемы)
4. Обсуждение в чате проекта
5. Готовые задачи переносятся в TODO
### Фаза 2: Discovery (Обсуждение)
### Фаза 3: Выполнение
**Участники:** Человек + Lead Agent
1. Задача в TODO → агент берёт → In Progress
2. Агент работает, коммитит, прикрепляет файлы
3. Создаёт подзадачу "Ревью" → другому агенту
4. Итерации до готовности
5. Задача → Done
**Цель:** Превратить размытую идею в чёткое ТЗ
### Фаза 4: Ревью и деплой
**Что делает Lead Agent:**
1. Задаёт уточняющие вопросы
2. Предлагает варианты реализации
3. Указывает на риски
4. Формирует структуру
**Артефакты:**
- `BRIEF.md` — краткое описание проекта
- `REQUIREMENTS.md` — функциональные требования
- `ARCHITECTURE.md` — техническое решение
**Выход из фазы:** Человек подтверждает "Да, делаем так"
---
### Фаза 3: Planning (Декомпозиция)
**Кто делает:** Lead Agent (или человек вручную)
**Процесс:**
```
REQUIREMENTS.md → Декомпозиция → Epic → Tasks → Subtasks
```
**Пример:**
```
Epic: "Модуль авторизации"
├── Task: "Модель пользователя"
│ ├── Subtask: "Схема БД"
│ ├── Subtask: "SQLAlchemy модель"
│ └── Subtask: "Миграция"
├── Task: "API эндпоинты"
│ ├── Subtask: "POST /auth/register"
│ ├── Subtask: "POST /auth/login"
│ └── Subtask: "Tests"
└── Task: "Интеграция с frontend"
```
---
### Фаза 4: Execution (Разработка)
**Как агенты берут задачи:**
| Модель | Описание |
|--------|----------|
| **Pull** | Агент сам выбирает задачу по специализации |
| **Push** | Lead Agent назначает задачи |
| **Гибрид** | Критичные — назначаются, остальные — свободный выбор |
**Процесс работы агента:**
1. Взял задачу → "In Progress"
2. Читает контекст (Brief, Requirements, связанные задачи)
3. Работает (код, тесты, документация)
4. Коммитит в feature branch
5. Создаёт подзадачу "Review" → другому агенту
6. Ревью и итерации
7. Merge в main
---
### Фаза 5: Review & QA
**Принцип:** Никакой код не идёт в main без ревью.
**Кто ревьюит:**
- Другой агент (не автор)
- Специальный "Reviewer" агент
- Человек (для критичного)
**Автоматизация:**
- CI/CD запускает тесты
- Линтеры
- Security checks
**Escalation:** 3 итерации ревью без согласия → эскалация к Lead/Human.
---
### Фаза 6: Deploy
1. Integration тесты
2. Staging deploy
3. Human approval (опционально)
4. Production deploy
---
## Задачи и подзадачи
**Ключевой принцип:** Подзадачи внутри задачи — контекст НЕ теряется.
```
Task: "Реализовать API авторизации"
├── Subtask: "Написать модели" → Agent-1 ✓
├── Subtask: "Code review" → Agent-2 ✓
├── Subtask: "Написать тесты" → Agent-1 (in progress)
└── Subtask: "Final review" → Agent-2 (waiting)
```
Когда агент работает над подзадачей — видит всё дерево + историю.
---
## Роли агентов
| Роль | Обязанности |
|------|-------------|
| **Lead/Analyst** | Discovery, Planning, Coordination |
| **Developer** | Код, тесты |
| **Reviewer** | Code review, QA |
| **DevOps** | CI/CD, Deploy |
| **Documenter** | Документация |
---
## Типы агентов
| Тип | Описание |
|-----|----------|
| **OpenClaw** | Полноценный агент с инструментами |
| **Claude API** | Прямой вызов API |
| **Claude Code CLI** | Через CLI (без траты API токенов) |
| **Codex** | OpenAI |
| **Gemini** | Google |
| **Custom** | Любой через API |
---
## Проблема: CLI Integration
**Задача:** Использовать Claude Code CLI (авторизован через Max подписку) без траты API токенов.
**Варианты решения:**
### 1. Headless Mode (если поддерживается)
```bash
claude --message "prompt" --output result.txt
```
### 2. PTY Automation
```python
import pexpect
child = pexpect.spawn('claude')
child.sendline('Write a function...')
response = child.before
```
### 3. Session Bridge
```
Team Board → Agent Service → PTY Bridge → Claude CLI в tmux
```
### 4. MCP Integration
Если CLI поддерживает Model Context Protocol.
### 5. Гибридный подход
- Простые задачи → API (дёшево)
- Кодинг → CLI
- Роутинг по типу задачи
**Требуется исследование:** Проверить возможности `claude` CLI.
---
## Прозрачность
**Всё видно в Web UI:**
- Статус задач
- Кто над чем работает
- Коммиты
- Переписка в задачах
- Метрики
**Уведомления:**
- Задача застряла
- Нужно решение человека
- Deploy готов
---
## Настройки проекта
```yaml
Project:
name: "My Project"
git_enabled: true # default: true
git_url: "https://..."
lead_agent_id: "markov" # можно переназначить
agents: ["claude", "codex"]
```
1. Автоматические проверки (CI/CD)
2. Ревью агентом или человеком
3. Деплой
---
## Инфраструктура (уже есть)
- **PostgreSQL** — БД
- **Thoth** — STT/TTS сервис
- **Authentik** — SSO
- **Nginx + certbot** — домены
- **Gitea** — Git хостинг
- **OpenClaw (Марков)** — главный агент
| Сервис | Описание |
|--------|----------|
| PostgreSQL | База данных |
| Thoth | STT/TTS (голос↔текст) |
| Authentik | SSO для веб-интерфейса |
| Nginx + certbot | Домены и SSL |
| Gitea | Git хостинг |
| OpenClaw (Марков) | Главный агент с инструментами |
| Redis | Очереди и pub/sub |
---
@ -299,22 +339,25 @@ Project:
1. Как интегрировать CLI-агентов (Claude Code, Cline)?
2. Workspace для агентов — общий или изолированный?
3. Реалтайм прогресс работы агента?
4. Лимиты: макс агентов, макс задач?
5. Биллинг/учёт использования API?
3. Прогресс работы агента в реалтайме?
4. Биллинг/учёт использования API?
5. Шаблоны агентов — как быстро создать нового?
---
## Приоритеты реализации
1. [ ] Базовый UI: проекты, доска
2. [ ] Tasks Service: CRUD, подзадачи
3. [ ] Agents Service: регистрация
4. [ ] Chat Service
5. [ ] Git интеграция
6. [ ] CLI Bridge для Claude Code
7. [ ] Подключение реальных агентов
1. [ ] Tracker: базовый WebSocket сервер
2. [ ] Tracker: проекты, задачи, подзадачи
3. [ ] Tracker: зависимости задач
4. [ ] Tracker: чаты (лобби + проект)
5. [ ] Tracker: файлы в задачах
6. [ ] Web Client: авторизация (Authentik)
7. [ ] Web Client: канбан-доска
8. [ ] Web Client: чат
9. [ ] Шаблон агента
10. [ ] Подключение первого агента (OpenClaw)
---
*Документ для обсуждения. Финальная архитектура — отдельно.*
*Документ для обсуждения и аналитики. Обновляется по мере развития идей.*