151 lines
13 KiB
Markdown
151 lines
13 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
|
||
---
|
||
|
||
# 02 — ТЗ (TRZ): ORCH-105 — Подготовка презентации по орку
|
||
|
||
Work Item: **ORCH-105** · Repo: **orchestrator** · Стадия: analysis
|
||
|
||
> ТЗ описывает **конкретные изменения к реализации**, выведенные из BRD и фактического кода.
|
||
> Архитектурное обоснование/решения — задача архитектора (06-adr).
|
||
|
||
## 1. Сводка изменения
|
||
|
||
**Docs-only** доработка контента витрины. Расширяем существующий слайдо-источник
|
||
`docs/overview/presentation.md` (канон ORCH-011) тремя смысловыми блоками: (1) выделенный
|
||
слайд про **Lite-установку** скриптами; (2) 2–3 слайда-инструкция **«как пользоваться орком
|
||
через Plane»**; (3) при необходимости — точечная актуализация нарратива. Сохраняем формат и
|
||
сквозную нумерацию слайдов, раздел сборки `.pptx` и тёмный дизайн. Дополняем анти-дрейф
|
||
`tests/test_system_docs.py`, чтобы новый обязательный контент был зафиксирован машинно.
|
||
Скрипт сборки `scripts/build_presentation.py` менять **не требуется** (парсер обобщённый).
|
||
Рантайм (`src/**`, стадии, гейты, БД) — **не затрагивается**.
|
||
|
||
## 2. Задействованные модули / пути
|
||
|
||
| Путь | Действие |
|
||
|------|----------|
|
||
| `docs/overview/presentation.md` | **изменить** — добавить слайд Lite + 2–3 слайда Plane-usage; перенумеровать сквозно; сохранить раздел «Как собрать .pptx»; опц. актуализировать нарратив |
|
||
| `tests/test_system_docs.py` | **изменить** — добавить assert'ы присутствия нового обязательного контента (Lite-установка, использование через Plane); существующие проверки сохранить зелёными |
|
||
| `CHANGELOG.md` | **изменить** — запись `docs:` по ORCH-105 |
|
||
| `docs/overview/README.md` | **опц.** — указатель/строка маршрута (если уместно); не обязателен |
|
||
| `scripts/build_presentation.py` | **НЕ изменять** — `parse_slides` обобщён; правка только при крайней необходимости (тогда сохранить ленивый импорт `pptx` и stdlib-only top-level) |
|
||
| `build/orchestrator-overview.pptx` | **НЕ коммитить** — артефакт сборки (`build/` в `.gitignore`, ORCH-011 D5) |
|
||
| `requirements*.txt`, `Dockerfile` | **НЕ изменять** — `python-pptx` не добавлять (NFR-2) |
|
||
|
||
## 3. Функциональные требования
|
||
|
||
### FR-1 — Слайд про Lite-установку (BR-2)
|
||
Добавить **один** слайд (формат `## Слайд N: <Заголовок>` + 3–6 тезисов + опц. `> Визуал:`),
|
||
точно отражающий Lite-маршрут по `docs/deployment/LITE_SETUP.md`:
|
||
- Lite = **два контейнера платформы** (`orchestrator` + `orchestrator-watchdog`) на
|
||
инфраструктуре заказчика; свои Plane / Gitea / Telegram / LLM подключаются (не входят в Lite).
|
||
- Разворачивается **без правки кода — только конфиг** (принцип 10-common, ORCH-101).
|
||
- Скрипты-помощники: `scripts/gen_secrets.py` (свежие секреты), `scripts/onboard_project.py`
|
||
(`plan`/`apply`/`verify` — регистрация проекта заказчика); подъём — `docker compose up -d`.
|
||
- Маршрут — **пошаговый runbook** `LITE_SETUP.md` с **проверкой каждого шага** (PASS/FAIL).
|
||
- **Рекомендуемое размещение:** сразу после текущего слайда «Тираж платформы» (обзор Lite/
|
||
Bundled) — как его углубление. Точная позиция — на усмотрение developer (требование жёсткое
|
||
только к сквозной нумерации).
|
||
- **Точность (BR-5):** не называть Lite «одним монолитным инсталлятором»; одношаговый
|
||
bootstrap — это Bundled (`bootstrap_bundle.py`), упоминание опционально и как **смежный**
|
||
вариант.
|
||
|
||
### FR-2 — Слайды «как пользоваться орком через Plane» (BR-3)
|
||
Добавить **2–3** слайда оператор-инструкции, опираясь на `docs/overview/tech-pipeline.md`
|
||
(человеческие гейты, STOP, статусная модель) и `tech-integrations.md` (Plane). Покрыть:
|
||
- **Запуск:** перевод задачи в статус **«To Analyse»** — единственная точка входа в конвейер.
|
||
- **Статусная модель:** статусы Plane — **индикация, не управление**; платформа сама их
|
||
выставляет; управляющих статусов ровно три (запуск, человеческие гейты, STOP).
|
||
- **Два человеческих гейта:** **Approved** на `analysis` (одобрить постановку) и **Confirm
|
||
Deploy** на `deploy` (подтвердить прод-выкладку — отдельный статус, чтобы привычный approve
|
||
не выкатывал прод случайным кликом).
|
||
- **Авто-лейблы:** `autoApprove` / `autoDeploy` (снимают человеческие гейты, пакетный
|
||
авто-режим — но **ни одна техническая проверка не пропускается**); `Bug` (багфикс-маршрут).
|
||
- **Отмена:** статус **STOP** — безопасная отмена с уборкой (ветка/worktree), `cancelled`;
|
||
STOP не трогает `main`/прод-контейнер.
|
||
- **Наблюдение за ходом:** платформа двигает статусы доски (Backlog → … → Done) + **живая
|
||
карточка в Telegram** (стадия, стоимость, время, кликабельный номер задачи) + комментарии в
|
||
задаче со ссылками на ветку/PR.
|
||
- **Рекомендуемое размещение:** связным кластером после слайда «Человек в контуре» (он вводит
|
||
«два решения человека») и/или рядом со «Сценарии использования». Точная позиция — на
|
||
усмотрение developer.
|
||
|
||
### FR-3 — Формат и сквозная нумерация (NFR-2)
|
||
- Слайды нумеруются **сквозно с 1** без пропусков (вставка в середину ⇒ перенумеровать все
|
||
последующие). Это машинно-проверяемо: `tests/test_system_docs.py::
|
||
test_presentation_source_parses_with_canonical_parser` требует
|
||
`[s.number] == list(range(1, N+1))`.
|
||
- Каждый новый слайд: **непустой заголовок** + **3–6 тезисов** (минимум — ≥1, требует тест) +
|
||
опц. одна строка `> Визуал: …`.
|
||
- Раздел **«Как собрать .pptx»** сохранён (несёт `build_presentation.py` и маркеры «Проверка:»
|
||
— требует `test_presentation_carries_reproducible_build_procedure`).
|
||
- Служебные `##`-заголовки (например, «Как собрать .pptx») не являются слайдами и завершают
|
||
предыдущий слайд (контракт `parse_slides`) — не вставлять контент слайдов после них.
|
||
|
||
### FR-4 — Сборка `.pptx` с новыми слайдами (BR-4)
|
||
Команда из канона (вне рантайма, dev-venv):
|
||
```bash
|
||
python3 -m venv .venv-pptx && .venv-pptx/bin/pip install python-pptx
|
||
.venv-pptx/bin/python scripts/build_presentation.py
|
||
```
|
||
Ожидаемо: печать `Собрано слайдов: N → build/orchestrator-overview.pptx`, где `N` =
|
||
фактическому числу слайдов источника (включая новые). Открытие `.pptx`: тёмная тема, светлый
|
||
текст, акцентные заголовки, корректная кириллица, новые слайды присутствуют и редактируемы.
|
||
**Это ручная проверка** (см. §6 — `python-pptx` нет в гейте тестов).
|
||
|
||
### FR-5 — Анти-дрейф нового контента (NFR-2, BR-5)
|
||
Расширить `tests/test_system_docs.py`, зафиксировав присутствие нового обязательного нарратива
|
||
в `presentation.md`:
|
||
- маркер **использования через Plane** (например, наличие подстроки уровня `plane` + признака
|
||
оператор-инструкции, по образцу `test_presentation_covers_mandatory_narrative_bits`);
|
||
- маркер **Lite-установки** (например, `lite` / `установк`).
|
||
Точные подстроки выбирает developer; цель — чтобы случайное удаление новых слайдов рвало CI.
|
||
Все **существующие** проверки модуля остаются зелёными без послаблений.
|
||
|
||
### FR-6 — Сопровождение (BR-6)
|
||
- `CHANGELOG.md`: запись `docs:` по ORCH-105 (презентация дополнена слайдами Lite-установки и
|
||
использования через Plane).
|
||
- Витрина: при изменении `presentation.md` норматив сопровождения ORCH-011/079 соблюдён;
|
||
reviewer сверяет факты с golden sources.
|
||
|
||
## 4. Изменения API
|
||
|
||
**Нет.** Эндпоинты (`/queue`, `/metrics`, вебхуки и пр.) не затрагиваются.
|
||
|
||
## 5. Изменения схемы БД
|
||
|
||
**Нет.** Таблицы/миграции/индексы не вводятся и не меняются.
|
||
|
||
## 6. Требования к новым/изменённым QG checks
|
||
|
||
**Нет нового гейта.** Презентация — артефакт витрины; новый Quality Gate не регистрируется
|
||
(`QG_CHECKS` / `STAGE_TRANSITIONS` / `check_*` — байт-в-байт прежние). Контроль выполняется
|
||
**существующими** механизмами:
|
||
- `tests/test_system_docs.py` исполняется обычным тест-сьютом → попадает под `check_ci_green`
|
||
(выход из `development`) и `check_tests_passed` (стадия `testing`).
|
||
- **Важное разграничение (честность гейта):** автоматический гейт проверяет **источник**
|
||
(`presentation.md`: парс, нумерация, обязательные биты, процедура сборки) и инвариант
|
||
«`python-pptx` не в прод-образе». **Сам рендер `.pptx`** в гейте **не выполняется** —
|
||
`python-pptx` отсутствует в прод/тест-образе по канону (ORCH-011 NFR-2), сборка — вне
|
||
рантайма в dev-venv (ручная проверка FR-4 / 04-test-plan TC-07).
|
||
|
||
## 7. Совместимость / регресс
|
||
|
||
- **Docs-only, нулевой рантайм-риск:** `src/**`, `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`,
|
||
схема БД — байт-в-байт не тронуты; kill-switch не нужен (нет рантайм-поведения).
|
||
- **Self-hosting безопасно:** `python-pptx` не входит в прод-образ; сборка — вне рантайма;
|
||
собранный бинарь не коммитится (`build/` в `.gitignore`).
|
||
- **Анти-дрейф сохранён:** `presentation.md` остаётся валидной для `parse_slides`; раздел
|
||
сборки и обязательные биты — на месте; новые проверки только **добавляют** покрытие.
|
||
- **Воспроизводимая сборка:** канон ORCH-011 (источник → скрипт → `.pptx` по требованию) не
|
||
форкается; один парсер (`parse_slides`) — один источник истины о формате.
|
||
- **Обратимость:** изменение полностью обратимо (revert правок `presentation.md` /
|
||
`test_system_docs.py` / `CHANGELOG.md`).
|
||
- **Регресс-поверхность:** полный `pytest tests/ -q` остаётся зелёным (нет правок кода
|
||
рантайма).
|