claude-bot
6d798c01ef
Единая точка входа в документацию платформы (ADR-001 D1–D9): - docs/overview/ — 10 файлов: индекс (маршруты «Я заказчик / Я менеджер / Я разработчик» + норматив «изменил функциональность → обнови витрину в том же PR»), business.md (без жаргона, 6 сценариев), 7 тех-блоков (link-first), presentation.md (16 слайдов + процедура сборки «команда + Проверка:»). - scripts/build_presentation.py — генератор .pptx в тёмном дизайне (python-pptx; чистый stdlib-парсер parse_slides + ленивый import pptx; бинарь не коммитится, build/ в .gitignore; зависимость НЕ в прод-образе — машинный гард TC-09). - tests/test_system_docs.py — структурный анти-дрейф: derive-сверки стадий/ гейтов/агентов импортом STAGE_TRANSITIONS/QG_CHECKS/glob промптов/config, валидность ссылок, FORBIDDEN-скан + секрет-эвристика, слайды каноническим парсером, NFR-2, указатели. - reviewer.md — ось обзорных доков ORCH-079 расширена на витрину (D7; канон 52d байт-в-байт, только текст внутри секций) + анти-регресс ассерт в test_agent_prompts_canon.py. - Указатели: README.md, CLAUDE.md (правила №2/№6, «Структура»), PRODUCT_VISION.md (врезка-ссылка), CHANGELOG.md. Рантайм байт-в-байт: src/**, docker-compose.yml, Dockerfile, requirements* — ноль изменений (docs+tests+dev-скрипт, паттерн ORCH-102/103). pytest: 1873 passed. Refs: ORCH-011 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
64 lines
5.7 KiB
Markdown
64 lines
5.7 KiB
Markdown
# Блок 1. Архитектура: компоненты и связи
|
||
|
||
> Обзорный уровень. Полная таблица компонентов с деталями и историей решений — в
|
||
> [инженерном справочнике](../architecture/README.md) («Компоненты») и
|
||
> [internals](../architecture/internals.md); здесь — цельная картина, как части складываются
|
||
> в конвейер.
|
||
|
||
## Поток одной задачи
|
||
|
||
```
|
||
Plane (трекер) Gitea (git/CI)
|
||
│ вебхук │ вебхук
|
||
▼ ▼
|
||
┌────────────────────────────────────────┐
|
||
│ FastAPI-приём (HMAC-подпись, дедуп) │
|
||
└───────────────────┬────────────────────┘
|
||
▼
|
||
вебхук → очередь (jobs) → агент (Claude CLI в worktree) → гейт (QG) → переход стадии
|
||
▲ │
|
||
└────────── следующая стадия / откат ◄─────────┘
|
||
```
|
||
|
||
Каждое продвижение задачи — один и тот же цикл: событие принято → в очередь поставлен job →
|
||
worker запустил агента стадии → результат проверен гейтом качества → state machine перевела
|
||
задачу на следующую стадию (или откатила назад).
|
||
|
||
## Компоненты
|
||
|
||
| Компонент | Роль |
|
||
|-----------|------|
|
||
| **Webhook-приёмники** (`src/webhooks/`) | Принимают события Plane (статусы задач) и Gitea (push, PR, CI). Проверяют HMAC-подпись, дедуплицируют повторные доставки. |
|
||
| **Очередь задач** (`jobs` + worker) | Собственная очередь на SQLite: атомарный захват job'а, ретраи с backoff, зависимости между job'ами, ограничение параллелизма. |
|
||
| **State machine** (`src/stages.py`) | Карта стадий `STAGE_TRANSITIONS`: для каждой стадии — следующая, агент и гейт выхода. Единственный источник истины о конвейере. |
|
||
| **Stage engine** (`src/stage_engine.py`) | Исполняет переходы: диспетчеризация гейтов, откаты, под-гейты деплойного ребра, синхронизация статусов с Plane. |
|
||
| **Agent launcher** (`src/agents/launcher.py`) | Запускает Claude CLI агента в изолированном git worktree ветки задачи, следит за процессом (watchdog), авто-продвигает стадию по завершении. |
|
||
| **Реестр гейтов** (`src/qg/checks.py`) | `QG_CHECKS` — машинные проверки выхода со стадий; вердикты читаются только из YAML-frontmatter артефактов. |
|
||
| **Plane-sync** (`src/plane_sync.py`) | Индикация статусов в Plane (слой «показать человеку», никогда не управление конвейером). |
|
||
| **Notifications** (`src/notifications.py`) | Живая Telegram-карточка задачи и алерты. |
|
||
|
||
## Фоновые демоны (самовосстановление)
|
||
|
||
Поднимаются в lifespan FastAPI-приложения (`src/main.py`) и работают рядом с конвейером:
|
||
|
||
- **reconciler** — находит расхождения «БД говорит одно, реальность другое» (зависшие стадии,
|
||
потерянные ветки) и возвращает задачи в консистентное состояние;
|
||
- **job-reaper** — возвращает в очередь job'ы, чей исполнитель умер (упавший процесс, рестарт);
|
||
- **disk-watchdog** — следит за местом на диске, чистит устаревшие worktree;
|
||
- **build-cache-pruner** — прибирает докер-кэш сборок.
|
||
|
||
Отдельно от приложения живёт **sidecar-watchdog** — независимый контейнер-наблюдатель: следит
|
||
за самим оркестратором снаружи (health, метрики) и шлёт алерты в собственный Telegram-канал.
|
||
Наблюдатель сознательно отделён от наблюдаемого: падение оркестратора не валит сторожа.
|
||
|
||
## Изоляция работы агентов
|
||
|
||
Каждая задача живёт в собственной git-ветке (`feature/<ID>-slug`) и собственном **worktree** —
|
||
изолированной рабочей копии репозитория. Агенты разных задач не видят незакоммиченную работу
|
||
друг друга; слияние в `main` происходит только через PR в Gitea после всех гейтов.
|
||
|
||
---
|
||
|
||
*Подробнее: [компоненты и API](../architecture/README.md) · [внутренности и схема БД](../architecture/internals.md) ·
|
||
следующий блок — [конвейер и стадии](tech-pipeline.md).*
|