170 lines
16 KiB
Markdown
170 lines
16 KiB
Markdown
---
|
||
work_item: ORCH-105
|
||
stage: analysis
|
||
author_agent: analyst
|
||
status: ready-for-review
|
||
created_at: 2026-06-12
|
||
model_used: claude-opus-4-8
|
||
---
|
||
|
||
# 01 — BRD (бизнес-требования): ORCH-105 — Подготовка презентации по орку
|
||
|
||
Work Item: **ORCH-105** · Repo: **orchestrator** · Стадия: analysis
|
||
|
||
## 1. Бизнес-контекст и проблема
|
||
|
||
Заказчику нужна **презентация о продукте «Orchestrator» в формате PowerPoint** — чтобы
|
||
показывать платформу стейкхолдерам и потенциальным заказчикам. Дополнительно в презентацию
|
||
надо добавить **слайд про Lite-установку** (через скрипты-установщики) и **слайды-инструкцию
|
||
«как пользоваться орком через Plane»**.
|
||
|
||
**Установленный факт (опора, не изобретать):** канон презентации в репозитории **уже
|
||
существует** — его ввела задача **ORCH-011** (витрина системы `docs/overview/`):
|
||
|
||
- `docs/overview/presentation.md` — **слайдо-источник** (источник истины): 16 слайдов в
|
||
формате `## Слайд N: Заголовок` + 3–6 тезисов + опциональная подпись `> Визуал: …`.
|
||
- `scripts/build_presentation.py` — dev-скрипт сборки **редактируемого `.pptx`** в тёмном
|
||
дизайне (`python-pptx`, ленивый импорт; чистый парсер `parse_slides` — stdlib-only).
|
||
- `tests/test_system_docs.py` — анти-дрейф-контур, который машинно валидирует формат
|
||
слайдов, сквозную нумерацию, обязательные биты нарратива и процедуру сборки.
|
||
|
||
Канон **намеренно** держит инварианты (ORCH-011 D4/D5, NFR-2): сборка идёт **вне рантайма
|
||
платформы** (одноразовый dev-venv), `python-pptx` **не входит** в прод-образ, а **собранный
|
||
`.pptx`-бинарь в git не коммитится** (`build/` в `.gitignore`).
|
||
|
||
**Проблема (дельта ORCH-105):** текущая дека рассказывает про продукт в целом, но **не
|
||
содержит** (а) выделенного слайда о том, как просто развернуть Lite-вариант скриптами, и
|
||
(б) слайдов-инструкции для оператора «как вести задачу через Plane» (запуск, статусы,
|
||
человеческие гейты, авто-лейблы, STOP, наблюдение). Задача — **дополнить существующий
|
||
слайдо-источник** этим содержанием и убедиться, что `.pptx` собирается с новыми слайдами.
|
||
Это **docs-only** доработка контента витрины: код рантайма не меняется.
|
||
|
||
## 2. Объём (scope)
|
||
|
||
### В объёме
|
||
- **Расширить `docs/overview/presentation.md`:**
|
||
- добавить **один выделенный слайд про Lite-установку** (скрипт-ассистированный характер:
|
||
`gen_secrets.py` → секреты, `onboard_project.py` → регистрация проекта, `docker compose
|
||
up`, пошаговый runbook `LITE_SETUP.md` с проверкой каждого шага);
|
||
- добавить **2–3 слайда-инструкцию «как пользоваться орком через Plane»** (запуск задачи,
|
||
статусная модель «индикация ≠ управление», два человеческих гейта — Approved и Confirm
|
||
Deploy, авто-лейблы `autoApprove`/`autoDeploy`/`Bug`, отмена STOP, наблюдение за ходом);
|
||
- при необходимости — лёгкая актуализация продуктового нарратива на текущее состояние.
|
||
- Сохранить **сквозную нумерацию слайдов с 1** (renumber при вставке в середину) и формат
|
||
(заголовок + 3–6 тезисов + опц. `> Визуал:`), а также раздел «Как собрать .pptx».
|
||
- Убедиться, что `scripts/build_presentation.py` собирает валидный `.pptx`, включающий новые
|
||
слайды (скрипт менять **не требуется** — парсер обобщённый; правка только при крайней
|
||
необходимости).
|
||
- **Расширить анти-дрейф** `tests/test_system_docs.py`: зафиксировать присутствие нового
|
||
обязательного контента (Lite-установка, использование через Plane).
|
||
- Обновить `CHANGELOG.md` (запись `docs:`); при необходимости — указатель/маршрут в
|
||
`docs/overview/README.md`.
|
||
|
||
### Вне объёма
|
||
- **Коммит собранного `.pptx`-бинаря в git** — запрещён каноном ORCH-011 D5 (`build/`
|
||
в `.gitignore`); презентация собирается по требованию.
|
||
- Добавление `python-pptx` в `requirements*`/`Dockerfile` (NFR-2; машинно запрещено тестом).
|
||
- Кастомный графический дизайн/брендинг сверх существующего тёмного текстового шаблона
|
||
(визуалы — текстовые подписи `> Визуал: …`, а не растровые картинки).
|
||
- Переписывание дизайна рендера (`build_pptx`), смена темы/шрифтов — если это не строго
|
||
необходимо.
|
||
- Любые изменения рантайма: `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`,
|
||
схема БД — **не трогаются**.
|
||
- Переписывание `business.md` и прочих тех-блоков витрины (описанные способности — тираж и
|
||
работа через трекер — там уже отражены; ORCH-105 добавляет именно **слайды**).
|
||
- Создание отдельного монолитного «lite-инсталлятора» как нового скрипта (его нет; Lite
|
||
ставится комбинацией существующих скриптов и compose — см. §6).
|
||
|
||
## 3. Заинтересованные стороны
|
||
|
||
- **Заказчик / Owner** — постановщик задачи и **приёмщик** презентации; конечный
|
||
пользователь `.pptx` при показе стейкхолдерам.
|
||
- **Потенциальные заказчики / менеджеры** — аудитория презентации (нетехнический и
|
||
полу-технический читатель).
|
||
- **Операторы платформы** — целевые читатели слайдов «как пользоваться через Plane».
|
||
- **Reviewer** — контролирует норматив сопровождения витрины (изменил витрину → согласовано,
|
||
факты не разъехались с golden sources; необновлённый сопутствующий док → finding ≥ P1).
|
||
|
||
## 4. Бизнес-требования (BR)
|
||
|
||
- **BR-1** — Презентация о продукте в формате PowerPoint собирается из слайдо-источника
|
||
витрины и содержит связный рассказ о платформе (существующий нарратив сохранён и при
|
||
необходимости актуализирован).
|
||
- **BR-2** — В презентации есть **выделенный слайд про Lite-установку**, точно отражающий её
|
||
скрипт-ассистированный характер: секреты генерирует `scripts/gen_secrets.py`, проект
|
||
регистрирует `scripts/onboard_project.py` (`plan`/`apply`/`verify`), стек поднимается
|
||
`docker compose`, а маршрут описан пошаговым runbook `LITE_SETUP.md` с проверкой каждого
|
||
шага. Без вымышленных артефактов/скриптов.
|
||
- **BR-3** — В презентации есть **слайды-инструкция «как пользоваться орком через Plane»**,
|
||
покрывающие: запуск задачи (перевод в «To Analyse» — единственная точка входа), статусную
|
||
модель (индикация ≠ управление; управляющих статусов ровно три), **два человеческих гейта**
|
||
(Approved на `analysis`, Confirm Deploy на `deploy`), **авто-лейблы** (`autoApprove`/
|
||
`autoDeploy`/`Bug`), **отмену STOP**, и **наблюдение за ходом** (статусы доски + живая
|
||
карточка в Telegram + комментарии в задаче).
|
||
- **BR-4** — Итоговый `.pptx` собирается документированной командой
|
||
(`scripts/build_presentation.py`) и включает **все** новые слайды; тёмный дизайн и
|
||
корректное отображение кириллицы сохранены.
|
||
- **BR-5** — Содержание презентации **фактологически точно** и согласовано с golden sources
|
||
витрины (`tech-pipeline.md`, `tech-integrations.md`, `LITE_SETUP.md`, паспорт `CLAUDE.md`):
|
||
никаких выдуманных возможностей, имён статусов, лейблов или скриптов.
|
||
- **BR-6** — Сопровождение выполнено в том же PR: `CHANGELOG.md` несёт запись `docs:` по
|
||
ORCH-105; норматив витрины (ORCH-011/079) соблюдён.
|
||
|
||
## 5. Нефункциональные требования (NFR)
|
||
|
||
- **NFR-1 (self-hosting безопасность)** — изменение **docs-only**: `src/**`,
|
||
`STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, схема БД — байт-в-байт не трогаются; `python-pptx`
|
||
**не попадает** в прод-образ; сборка `.pptx` — только вне рантайма (dev-venv).
|
||
- **NFR-2 (анти-дрейф / совместимость формата)** — после правок `presentation.md` остаётся
|
||
валидной для канонического парсера `parse_slides` (сквозная нумерация с 1, ≥1 тезис на
|
||
слайд, непустые заголовки); **весь существующий** `tests/test_system_docs.py` — зелёный.
|
||
- **NFR-3 (бинарь не в git)** — собранный `.pptx` не коммитится; `build/` остаётся в
|
||
`.gitignore`; артефакт сборки — по требованию.
|
||
- **NFR-4 (гигиена)** — в слайдах **нет** боевых хост-литералов (FORBIDDEN-скан) и
|
||
секретоподобных значений (секрет-эвристика); относительные ссылки резолвятся.
|
||
- **NFR-5 (стиль)** — новые слайды держат стиль деки: 3–6 тезисов, опц. подпись
|
||
`> Визуал: …`, тон и терминологию `business.md` (нетехнический язык для продуктовых слайдов;
|
||
оператор-инструкция — простыми шагами).
|
||
|
||
## 6. Допущения и ограничения
|
||
|
||
- **Форма поставки = воспроизводимая сборка.** Deliverable — **расширенный слайдо-источник +
|
||
скрипт сборки**; сам `.pptx` производится по требованию (ORCH-011 D5). Если нетехническому
|
||
стейкхолдеру нужен готовый файл — он **собирается командой и передаётся вне git** (например,
|
||
вложением к задаче Plane); это операционный шаг, не изменение кода. Это сознательное
|
||
следование действующему машинно-проверяемому канону, а не упущение.
|
||
- **«Скрипт-установщик» для Lite** = фактические скрипты-помощники (`gen_secrets.py`,
|
||
`onboard_project.py`) + `docker compose` + verified-runbook `LITE_SETUP.md`. **Отдельного
|
||
монолитного lite-инсталлятора в репозитории нет**; одношаговый bootstrap (`bootstrap_bundle.py`)
|
||
относится к варианту **Bundled**, а не Lite. Заказчик явно просил **Lite** — слайд остаётся
|
||
точным к Lite (при желании можно одной строкой упомянуть Bundled-bootstrap как смежный
|
||
вариант, но фокус слайда — Lite).
|
||
- **Рост деки.** С добавлением ~4 слайдов (1 Lite + 2–3 Plane) дека вырастает до ~19–20
|
||
слайдов. Это выше «ориентира 14–18» из ORCH-011 FR-4, но **проходит жёсткий тест** (`≥ 12`).
|
||
Рост оправдан явным запросом; финальное число и возможное слияние слайдов — на усмотрение
|
||
developer/architect (жёсткое требование — только сквозная нумерация и ≥ 12).
|
||
- **Сборка/проверка `.pptx`** предполагает доступность `python-pptx` в dev-venv (вне рантайма).
|
||
**Автоматический гейт тестов проверяет ИСТОЧНИК** (`presentation.md`: парс/структура/контент),
|
||
а **не отрендеренный бинарь** — рендер проверяется **вручную** в dev-venv (честное
|
||
разграничение; см. 03/04).
|
||
|
||
## 7. Критерии успеха
|
||
|
||
Расширенный слайдо-источник собирается в `.pptx`; слайды Lite-установки и использования через
|
||
Plane присутствуют, точны и согласованы с golden sources; сквозная нумерация и формат
|
||
сохранены; весь `tests/test_system_docs.py` (с новыми проверками) зелёный; `python-pptx` не в
|
||
прод-образе, бинарь не в git; `CHANGELOG`/витрина обновлены. Детальные PASS/FAIL —
|
||
`03-acceptance-criteria.md`.
|
||
|
||
## 8. Риски
|
||
|
||
- **Ошибка перенумерации** при вставке слайдов в середину → падение проверки сквозной
|
||
нумерации (`parse_slides`).
|
||
- **Дрейф фактов**: слайд расходится с реальной возможностью/именем (статус/лейбл/скрипт).
|
||
- **Случайный запрещённый литерал/секрет** в тексте слайда → красный анти-дрейф.
|
||
- **Неточная подача Lite** как монолитного инсталлятора (его нет) → вводящий в заблуждение
|
||
слайд.
|
||
- **Раздувание деки** сверх читаемого объёма.
|
||
|
||
Краткий перечень; детальная проработка и митигации — `10-tech-risks.md` (заполняет архитектор).
|