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:
54
docs/overview/tech-integrations.md
Normal file
54
docs/overview/tech-integrations.md
Normal 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).*
|
||||
Reference in New Issue
Block a user