116 lines
8.7 KiB
Markdown
116 lines
8.7 KiB
Markdown
# 01 — BRD: Approve прод-деплоя через выделенный статус «Confirm Deploy»
|
||
|
||
Work Item: **ORCH-059**
|
||
Repo: `orchestrator`
|
||
Stage: analysis
|
||
Тип: enhancement / risk-reduction (self-hosting)
|
||
|
||
## 1. Контекст и проблема
|
||
|
||
В ORCH-036 («исполняемый самодеплой стадии `deploy`») прод-деплой self-hosting
|
||
инстанса (контейнер `orchestrator`, порт 8500) запускается **Фазой B**: человек
|
||
переводит issue в Plane-статус **`Approved`**, webhook
|
||
`work_item.updated` → `handle_issue_updated` → `handle_verdict(approved=True)`
|
||
→ `_try_advance_stage` → `advance_stage(finished_agent=None)`, и в
|
||
`stage_engine.advance_stage` срабатывает блок
|
||
`current_stage == "deploy" and finished_agent is None` →
|
||
`_handle_self_deploy_phase_b` → detached host-деплой прода.
|
||
|
||
**Перегрузка статуса.** Тот же самый Plane-статус `Approved` (UUID
|
||
`a519a341-…`) используется как **человеческий гейт одобрения BRD** на ранней
|
||
стадии `analysis` (`check_analysis_approved`: analysis → architecture) и в общем
|
||
verdict-роутинге `handle_verdict`. Один и тот же визуальный «Approved» на доске
|
||
означает две принципиально разные вещи:
|
||
|
||
- на `analysis` — «BRD/ТЗ/AC приняты, продолжай конвейер» (дёшево, обратимо);
|
||
- на `deploy` — «**ВЫКАТИ В ПРОД** инструмент, который прямо сейчас обслуживает
|
||
все проекты из одного инстанса с общей БД» (дорого, групповой риск, см.
|
||
раздел Self-hosting в `CLAUDE.md`).
|
||
|
||
### Последствия (Pain)
|
||
- **Двусмысленность семантики.** Один статус — два смысла; оператор не видит из
|
||
названия, что клик на `deploy` запускает реальный прод-рестарт.
|
||
- **Риск случайного клика.** Привычный жест «Approved» (которым оператор
|
||
штатно одобряет BRD десятки раз) на стадии `deploy` молча триггерит
|
||
прод-деплой. Цена ошибки — незапланированный рестарт прод-инстанса,
|
||
встающий конвейер всех проектов.
|
||
- **Несоответствие ожиданиям ORCH-036.** В scope ORCH-36 заявлялась Telegram
|
||
inline-кнопка подтверждения; в коде её **нет** — developer реализовал approve
|
||
исключительно через Plane-статус. Отдельного «осознанного» жеста подтверждения
|
||
деплоя в системе сейчас не существует.
|
||
|
||
## 2. Решение Owner
|
||
|
||
Ввести **отдельный Plane-статус `Confirm Deploy`** в проекте ORCH, который
|
||
триггерит **ТОЛЬКО** Фазу B self-deploy на стадии `deploy`. Статус `Approved`
|
||
перестаёт запускать прод-деплой и сохраняет единственный смысл — человеческое
|
||
одобрение на гейтах конвейера (прежде всего BRD на `analysis`).
|
||
|
||
Минимальная правка: `handle_verdict` в `src/webhooks/plane.py` + регистрация
|
||
нового состояния в проекте ORCH (Plane + резолвер состояний).
|
||
|
||
## 3. Бизнес-цели
|
||
- **BG-1.** Убрать двусмысленность: жест «запустить прод-деплой» отделён от жеста
|
||
«одобрить артефакт».
|
||
- **BG-2.** Снизить риск случайного прод-деплоя: запуск прода требует явного,
|
||
редко используемого статуса `Confirm Deploy`, а не привычного `Approved`.
|
||
- **BG-3.** Не сломать работающий self-hosting конвейер при доработке самого
|
||
инструмента (нулевая регрессия `analysis`-гейта и не-self репозиториев).
|
||
|
||
## 4. Объём (Scope)
|
||
|
||
### В объёме
|
||
- Новый логический статус `confirm_deploy` («Confirm Deploy») в резолвере
|
||
состояний Plane (`src/plane_sync.py`).
|
||
- Маршрутизация нового статуса в `src/webhooks/plane.py`
|
||
(`handle_issue_updated` / `handle_verdict`) на путь Фазы B прод-деплоя.
|
||
- Прекращение триггера Фазы B по статусу `Approved` на стадии `deploy`.
|
||
- Обновление текста CTA Фазы A (Plane-комментарий + Telegram в
|
||
`stage_engine._handle_self_deploy_phase_a`): инструктировать оператора
|
||
переводить задачу в `Confirm Deploy`, а не в `Approved`.
|
||
- Конфигурация Plane: создание статуса «Confirm Deploy» в проекте ORCH
|
||
(предусловие эксплуатации — фиксируется в TRZ/AC как требование среды).
|
||
- Обновление документации (`CLAUDE.md`, `docs/architecture/README.md` секция
|
||
ORCH-036, `CHANGELOG.md`) и ADR per-work-item.
|
||
|
||
### Вне объёма
|
||
- Telegram inline-кнопки подтверждения деплоя (отдельная задача; здесь не
|
||
реализуем — управление по-прежнему статусом Plane).
|
||
- Полностью автоматический approve деплоя (ORCH-54).
|
||
- Изменение Фаз A/C, exit-кодов хука, merge-gate, `check_deploy_status`,
|
||
схемы БД, реестров `STAGE_TRANSITIONS` / `QG_CHECKS`.
|
||
- Поведение прод-деплоя для не-self репозиториев (остаётся прежним).
|
||
- Post-deploy наблюдение (ORCH-021) — не затрагивается.
|
||
|
||
## 5. Заинтересованные стороны
|
||
- **Owner/оператор** — переводит задачи по статусам; главный выгодоприобретатель
|
||
снижения риска.
|
||
- **Self-hosting конвейер** — все проекты на общем инстансе; косвенно зависят от
|
||
безопасности прод-деплоя орка.
|
||
|
||
## 6. Допущения
|
||
- A-1. Plane позволяет добавить кастомный статус «Confirm Deploy» в проект ORCH;
|
||
его UUID резолвится через `get_project_states` (API `/states/`).
|
||
- A-2. Статус `Confirm Deploy` нужен только проекту ORCH (self-hosting). Прочие
|
||
проекты прод-деплой через Plane-approve не используют
|
||
(`self_deploy_applies` → только `orchestrator`).
|
||
- A-3. Оператор переводит задачу в `Confirm Deploy` только когда она реально
|
||
находится на стадии `deploy` (approval-pending после Фазы A).
|
||
|
||
## 7. Риски (детально — 10-tech-risks.md, ведёт архитектор)
|
||
- R-1. Новый логический ключ `confirm_deploy` отсутствует в fallback
|
||
`_DEFAULT_STATES` и в проектах без этого статуса → обращение к ключу должно
|
||
быть безопасным (fail-closed: нет статуса → нет деплоя, не падение).
|
||
- R-2. Регрессия: `Approved` на `deploy` после правки не должен НИ
|
||
запускать деплой, НИ вызывать ложный откат/advance.
|
||
- R-3. Самоправка прода: правка не должна потребовать ручного рестарта прод-
|
||
контейнера вне штатной стадии deploy-staging → deploy.
|
||
|
||
## 8. Definition of Done (бизнес-уровень)
|
||
- Перевод задачи стадии `deploy` в `Confirm Deploy` запускает прод-деплой
|
||
(Фаза B) ровно так же, как раньше делал `Approved`.
|
||
- Перевод задачи стадии `deploy` в `Approved` прод-деплой НЕ запускает.
|
||
- `Approved` на `analysis` (и прочих человеческих гейтах) работает без изменений.
|
||
- CTA Фазы A просит `Confirm Deploy`.
|
||
- Документация и ADR обновлены в том же PR.
|