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,54 @@
# Блок 5. Интеграции: Plane, Gitea, LLM, Telegram
> Обзорный уровень; детали API, эндпоинтов и вебхуков — в
> [инженерном справочнике](../architecture/README.md) и [internals](../architecture/internals.md).
## Plane — управление задачами
- **Вход конвейера:** перевод задачи в статус «To Analyse» — единственная точка запуска
пайплайна. Вебхуки Plane (HMAC-подписанные) доставляют изменения задач.
- **Статусы = индикация, не управление** ([блок 2](tech-pipeline.md)): платформа сама
выставляет статусы доски, чтобы человек видел осмысленную картину; управляют конвейером
только машина стадий и три управляющих статуса (запуск, человеческие гейты, STOP).
- **Лейблы** — декларативные переключатели на задаче: `autoApprove` / `autoDeploy` (снятие
человеческих гейтов), `Bug` (багфикс-маршрут). Источник истины — Plane API: ошибка чтения
лейблов трактуется как «лейбла нет» (fail-safe — никогда не «авто» по ошибке).
- Платформа пишет в задачу комментарии о ходе работ (под ботами ролей) с кликабельными
ссылками на ветку/PR.
## Gitea — git, PR, CI
- **Каждая задача = одна ветка = один PR.** Ветка срезается от свежего `main`, работа идёт в
изолированном worktree, слияние — только после всех гейтов.
- **Слияние строго через PR-merge API** — платформенный инвариант: прямой push или
force-push в `main` запрещён всем акторам, включая агентов и сам движок.
- **Merge-актор устойчив к икотам:** транзиентные ошибки Gitea (таймаут, «try again later»)
ретраятся с backoff; необратимые — честный отказ без ложных повторов. Ветка, уже целиком
попавшая в `main`, распознаётся и не порождает мусорных PR.
- **CI (Gitea Actions)** гонит полный тест-сьют на каждый push ветки; зелёный CI — гейт
выхода из разработки (`check_ci_green`).
- Вебхуки Gitea (push, PR, статус CI) — второй источник событий конвейера.
## LLM — Claude CLI
- Агенты запускаются через **Claude CLI**: launcher собирает команду с промптом роли,
`--model` и эффортом, резолвленными **только из конфига** (таблица — в
[блоке агентов](tech-agents.md)); имя модели валидируется перед запуском.
- Запуск — в worktree ветки задачи: агент видит код своей задачи и ничего лишнего.
- Каждый запуск пишет в учёт стоимость и токены ([блок 7](tech-observability.md)).
## Telegram — живой трекер и алерты
- **Одна задача = одна живая карточка**: стадия, статус, модель/эффорт агента, стоимость,
честные метрики времени. Карточка обновляется «переездом вниз» чата (старая удаляется,
свежая приходит тихо); леджер карточек зачищает осиротевшие дубли.
- **Алерты** (упавший гейт, ожидание человека, инциденты) приходят отдельными сообщениями
с пингом.
- **Sidecar-watchdog шлёт в собственный канал** со своим ботом: наблюдатель за платформой
не зависит от её Telegram-стека.
---
*Развёртывание интеграций с нуля — [LITE_SETUP](../deployment/LITE_SETUP.md) /
[BUNDLED_SETUP](../deployment/BUNDLED_SETUP.md); безопасность стыков —
[блок 6](tech-quality-security.md).*