docs(overview): витрина системы docs/overview/ — бизнес+тех, 3 аудитории, презентация (ORCH-011)

Единая точка входа в документацию платформы (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>
This commit is contained in:
2026-06-11 09:24:01 +03:00
committed by orchestrator-deployer
parent c455931ae7
commit 6d798c01ef
20 changed files with 1528 additions and 6 deletions

View File

@@ -0,0 +1,70 @@
# Блок 4. Структура объектов: каноническая модель
> Источник истины — фактическая схема SQLite в `src/db.py` и реестр проектов в
> `src/projects.py`; подробное описание таблиц — [internals, «Database Schema»](../architecture/internals.md).
## Каноническая модель
```
Project ──1:N──► Work-Item / Task ──1:N──► Job ──1:N──► Agent-run
│ │
│ └── артефакты задачи (docs/work-items/<ID>/)
└── Plane-проект ↔ git-репозиторий ↔ префикс задач
```
### Project — проект в реестре
Связка «Plane-проект ↔ git-репозиторий ↔ префикс задач» (например, `ORCH-`). Реестр живёт в
конфиге (`src/projects.py`): один инстанс платформы обслуживает несколько проектов; по
префиксу задачи платформа находит репозиторий и настройки.
### Work-Item / Task — задача конвейера
Строка таблицы `tasks`: текущая **стадия** (`stage`), **маршрут** (`track`: полный или
багфикс), рабочая **ветка**, счётчики откатов, отметки отмены. Натуральные ключи — ID задачи
в Plane и человекочитаемый номер (`ORCH-NNN`). На каждой стадии задача накапливает
**артефакты** — номерные документы в `docs/work-items/<ID>/` (от бизнес-запроса до
deploy-лога; манифест — [PIPELINE_DOCS](../_standards/PIPELINE_DOCS.md)).
### Job — единица работы в очереди
Строка таблицы `jobs`: что запустить (агент какой стадии), для какой задачи, в каком статусе
(`queued``running` → терминал). Очередь даёт: **атомарный захват** (два worker'а не возьмут
один job), **зависимости** между job'ами, **ретраи** с экспоненциальным backoff и breaker
после исчерпания бюджета, ограничение параллелизма.
### Agent-run — один запуск агента
Строка таблицы `agent_runs`: какой агент, какой моделью и эффортом, сколько длился, сколько
стоил (токены/доллары). Из этих строк складывается честная стоимость задачи в живой карточке
и аналитика по ролям.
### События вебхуков и дедуп
Входящие события Plane/Gitea фиксируются с ключом дедупликации: повторная доставка того же
события (ретраи источника, сетевые икоты) не порождает повторной работы.
## Вспомогательные таблицы
| Таблица | Зачем |
|---------|-------|
| `repo_freeze` | durable-заморозка репозитория после деградации прода (serial gate) |
| `coverage_baseline` | базовая линия покрытия тестами; растёт только вверх (ratchet) |
| `tracker_messages` | леджер всех Telegram-карточек задачи (зачистка сирот) |
| `lessons` | машинный журнал уроков — структурированные отклонения конвейера |
Все изменения схемы — аддитивные и идемпотентные (`CREATE TABLE IF NOT EXISTS`, ensure-column
при старте): обновление платформы не требует ручных миграций.
## Словарь терминов
| Термин | Значение |
|--------|----------|
| **Стадия** | Позиция задачи в конвейере; карта стадий — `STAGE_TRANSITIONS` ([блок 2](tech-pipeline.md)) |
| **Гейт (exit-гейт)** | Машинная проверка выхода со стадии; реестр — `QG_CHECKS` |
| **Под-гейт** | Проверка-врезка внутри перехода (не стадия); см. деплойное ребро в [блоке 2](tech-pipeline.md) |
| **Job** | Единица работы в очереди; задача порождает job'ы по мере продвижения |
| **Worktree** | Изолированная рабочая копия репозитория для ветки задачи |
| **Lease (merge-lease)** | Эксклюзивная блокировка «кто сейчас мержит этот репозиторий» — сериализация слияний |
| **Track (маршрут)** | Вариант пути задачи: полный цикл или багфикс с пропуском проектирования |
| **Freeze** | Заморозка очереди репозитория после инцидента до ручного разбора |
---
*Как объекты двигаются по конвейеру — [блок 2](tech-pipeline.md); кто их создаёт —
[агенты](tech-agents.md); как за ними наблюдать — [блок 7](tech-observability.md).*