104 lines
8.6 KiB
Markdown
104 lines
8.6 KiB
Markdown
# 02 — ТЗ: выделенный статус «Confirm Deploy» как триггер прод-деплоя
|
||
|
||
Work Item: **ORCH-059** · Repo: `orchestrator` · Stage: analysis
|
||
|
||
> ТЗ описывает **что** должно измениться и **поведенческий контракт**. Конкретный
|
||
> дизайн (сигнатуры, способ проброса признака «confirm-deploy» из webhook в
|
||
> `stage_engine`, sentinel-обработка) — за архитектором (ADR per-work-item).
|
||
> Точки касания ниже заданы бизнес-запросом Owner и текущей реализацией ORCH-036.
|
||
|
||
## 1. Задействованные модули `src/`
|
||
|
||
| Модуль | Роль в задаче |
|
||
|--------|---------------|
|
||
| `src/plane_sync.py` | Резолвер состояний Plane. Добавить логический ключ `confirm_deploy` ↔ имя статуса «Confirm Deploy»; обеспечить безопасный доступ при отсутствии статуса (fallback/неполный конфиг). |
|
||
| `src/webhooks/plane.py` | `handle_issue_updated` — маршрутизация нового статуса; `handle_verdict` — отделить «подтверждение деплоя» от обычного approve; снять триггер Фазы B со статуса `Approved` на `deploy`. |
|
||
| `src/stage_engine.py` | Блок Фазы B (`current_stage == "deploy" and finished_agent is None`) должен срабатывать ТОЛЬКО по сигналу confirm-deploy, не по обычному Approved. Обновить CTA-текст Фазы A (`_handle_self_deploy_phase_a`). |
|
||
| `src/config.py` | (опционально, на усмотрение архитектора) флаг/имя статуса, если потребуется конфигурируемость. По умолчанию — не требуется. |
|
||
|
||
## 2. Поведенческий контракт (требования)
|
||
|
||
### TRZ-1. Регистрация статуса «Confirm Deploy»
|
||
Резолвер состояний (`get_project_states`) обязан возвращать UUID статуса
|
||
«Confirm Deploy» под логическим ключом `confirm_deploy` для проекта ORCH.
|
||
Маппинг имени `"Confirm Deploy" → "confirm_deploy"` добавляется в
|
||
`_PLANE_NAME_TO_KEY`. Для проектов/сред, где статус отсутствует (enduro,
|
||
fallback `_DEFAULT_STATES`, недоступный API), ключ может отсутствовать —
|
||
обращение к нему должно быть **fail-closed**: «нет статуса → ветка confirm-deploy
|
||
не активируется», без `KeyError`/исключения.
|
||
|
||
### TRZ-2. Триггер прод-деплоя по «Confirm Deploy»
|
||
Когда задача находится на стадии `deploy` и issue переводится в статус
|
||
`Confirm Deploy`, система обязана инициировать **Фазу B** прод-деплоя
|
||
(эквивалент текущего `_handle_self_deploy_phase_b`: idempotency-guard `initiated`,
|
||
`self_deploy.initiate_deploy`, постановка `deploy-finalizer`, комментарии/Telegram).
|
||
Поведение, идемпотентность и Фаза C — **без изменений** относительно ORCH-036;
|
||
меняется только **что именно является триггером**.
|
||
|
||
### TRZ-3. `Approved` больше не запускает прод-деплой
|
||
Перевод задачи стадии `deploy` в статус `Approved` **не должен** инициировать
|
||
Фазу B. Он не должен также вызывать ложный откат (БАГ-8) или ложный advance
|
||
по `check_deploy_status` (вердикта ещё нет). Допустимое поведение — **no-op с
|
||
логированием** (issue остаётся на `deploy`/approval-pending). Конкретный способ
|
||
(игнор на уровне webhook-роутинга или на уровне `stage_engine`) — за архитектором.
|
||
|
||
### TRZ-4. Сохранность гейта `Approved` на остальных стадиях
|
||
Статус `Approved` обязан продолжать работать как человеческий гейт:
|
||
- `analysis` → `architecture` (`check_analysis_approved`, approved-via-status);
|
||
- любой иной человеческий approve-advance, существующий сегодня.
|
||
Регрессия `handle_verdict(approved=True)` для НЕ-`deploy` стадий недопустима.
|
||
|
||
### TRZ-5. CTA Фазы A
|
||
Текст запроса approve в `_handle_self_deploy_phase_a` (Plane-комментарий + Telegram)
|
||
обязан инструктировать оператора переводить задачу в статус **`Confirm Deploy`**
|
||
(а не `Approved`) для запуска прод-деплоя.
|
||
|
||
### TRZ-6. Условность (как ORCH-35/36)
|
||
Ветка confirm-deploy реальна только для self-hosting
|
||
(`self_deploy.self_deploy_applies(repo)` → `orchestrator`). Для прочих репо —
|
||
прежнее поведение (синхронный деплой агентом), статус `Confirm Deploy` не
|
||
требуется и не влияет.
|
||
|
||
## 3. Изменения API
|
||
Изменений HTTP-эндпоинтов **нет**. Канал — существующий `POST /webhook/plane`
|
||
(событие `work_item.updated`). Внешнее изменение: в проекте ORCH появляется
|
||
дополнительный статус доски «Confirm Deploy» (Plane-конфигурация, не код-API).
|
||
|
||
## 4. Изменения схемы БД
|
||
**Нет.** `STAGE_TRANSITIONS`, реестр `QG_CHECKS`, таблицы `tasks`/`jobs`/
|
||
`agent_runs`/`events` — без изменений. Статусы — на стороне Plane; restart-safe
|
||
состояние деплоя — существующие sentinel-файлы ORCH-036 (без миграций).
|
||
|
||
## 5. Требования к новым QG checks
|
||
**Нет.** Новый Quality Gate не вводится. `check_deploy_status` /
|
||
`_parse_deploy_status` и контракт exit-кодов хука (0/1/2) — без изменений.
|
||
|
||
## 6. Конфигурация среды (предусловие эксплуатации)
|
||
- В проекте ORCH в Plane создаётся статус доски **«Confirm Deploy»** (точное имя,
|
||
чувствительно к регистру — должно совпасть с ключом `_PLANE_NAME_TO_KEY`).
|
||
- Размещение статуса на доске — рядом со стадией deploy/approval-pending
|
||
(рекомендация эксплуатации, не код).
|
||
- Кэш состояний (`get_project_states` / `reload_project_states`): после создания
|
||
статуса может потребоваться сброс кэша или рестарт по штатной стадии deploy.
|
||
|
||
## 7. Артефакты, создаваемые/обновляемые по pipeline
|
||
- `docs/work-items/ORCH-059/06-adr/ADR-001-confirm-deploy-status.md` — решение
|
||
(как отличается триггер; где разрезается перегрузка `Approved`; fail-closed
|
||
при отсутствии статуса) — **ведёт архитектор**.
|
||
- `CLAUDE.md` — упоминание выделенного статуса approve прод-деплоя (раздел
|
||
self-hosting / артефакты).
|
||
- `docs/architecture/README.md` — секция ORCH-036: уточнить, что Фаза B
|
||
триггерится статусом `Confirm Deploy`, а не `Approved`.
|
||
- `CHANGELOG.md` — запись ORCH-059.
|
||
- `12-review.md`, `13-test-report.md`, `14-deploy-log.md`, `15-staging-log.md` —
|
||
штатно по стадиям конвейера.
|
||
|
||
## 8. Совместимость и инварианты
|
||
- Не меняются: `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_deploy_status`,
|
||
БАГ-8 (FAILED → откат на development), merge-gate, exit-коды хука, Фазы A/C,
|
||
схема БД, post-deploy (ORCH-021).
|
||
- Self-hosting safety: правка НЕ требует внепланового рестарта прод-контейнера;
|
||
выкат — через штатный deploy-staging (8501) → deploy.
|
||
- Never-crash: отсутствие статуса `Confirm Deploy` в резолвере не приводит к
|
||
исключению в webhook-пути.
|