97 lines
5.9 KiB
Markdown
97 lines
5.9 KiB
Markdown
# 07 — Требования к инфраструктуре
|
||
|
||
**Work Item:** ORCH-066
|
||
**Автор:** Architect
|
||
**Дата:** 2026-06-07
|
||
|
||
> ORCH-066 не меняет топологию (контейнеры/порты/сеть — без изменений, см.
|
||
> `docs/operations/INFRA.md`). Единственное инфра-действие — создание новых
|
||
> Plane-статусов в проекте **ORCH** руками оператора через Plane API. Это
|
||
> **предусловие эксплуатации**, не часть кодового PR.
|
||
|
||
---
|
||
|
||
## 1. Что нужно сделать оператору (ДО эксплуатации новой модели)
|
||
|
||
Создать в Plane-проекте **ORCH** следующие статусы (states) с точными именами —
|
||
резолвер сопоставляет их по `name` (`_PLANE_NAME_TO_KEY`):
|
||
|
||
| Plane name (точно) | Логический ключ | Группа Plane (рекомендуемая) | Назначение |
|
||
|--------------------|-----------------|------------------------------|------------|
|
||
| `To Analyse` | `to_analyse` | unstarted / started | Человеческий вход: старт конвейера + resume аналитика из Needs Input. |
|
||
| `Analysis` | `analysis` | started | Индикация стадии анализа. |
|
||
| `Code-Review` | `code_review` | started | Индикация стадии review. |
|
||
| `Awaiting Deploy` | `awaiting_deploy` | started | Phase A: ожидание ручного approve на прод-деплой. |
|
||
| `Deploying` | `deploying` | started | Phase B: идёт прод-деплой. |
|
||
| `Monitoring after Deploy` | `monitoring` | started | Phase C / окно пост-деплой наблюдения. |
|
||
|
||
`Confirm Deploy` (ORCH-059) и базовые статусы (`Backlog`, `Todo`, `In Progress`,
|
||
`Architecture`, `Development`, `Review`, `Testing`, `Approved`, `Rejected`, `Done`,
|
||
`Cancelled`, `Needs Input`, `In Review`, `Blocked`) уже существуют — **не трогать**.
|
||
|
||
> ⚠️ **Точность имён критична.** Резолв идёт по строковому `name`. Опечатка/иной регистр
|
||
> → статус не сопоставится → ключ деградирует на собственный базовый UUID проекта
|
||
> (alias-fallback, ADR §2.2): индикация откатится к старому статусу, но конвейер
|
||
> продолжит работать. Дефис в `Code-Review` — обязателен.
|
||
|
||
---
|
||
|
||
## 2. Plane API — как создать статус
|
||
|
||
Эндпоинт (как в `src/plane_sync.py`, `PLANE_BASE = {plane_api_url}/api/v1`):
|
||
|
||
```
|
||
POST {PLANE_BASE}/workspaces/{WORKSPACE}/projects/{ORCH_PROJECT_ID}/states/
|
||
Headers: X-API-Key: <PLANE_API_TOKEN> (или соответствующий бот-токен с правами)
|
||
Body (JSON):
|
||
{ "name": "To Analyse", "group": "started", "color": "#3f76ff" }
|
||
```
|
||
|
||
Повторить для каждого имени из таблицы §1. `group` влияет только на колонку доски;
|
||
оркестратор `group` не читает (резолв строго по `name`). `color` — на вкус оператора.
|
||
|
||
Проверка после создания:
|
||
|
||
```
|
||
GET {PLANE_BASE}/workspaces/{WORKSPACE}/projects/{ORCH_PROJECT_ID}/states/
|
||
```
|
||
В ответе должны присутствовать все 6 имён.
|
||
|
||
---
|
||
|
||
## 3. Сброс кэша статусов (важно)
|
||
|
||
`get_project_states` кэширует резолв per-process (`_STATES_CACHE`). После создания
|
||
статусов оркестратор подхватит их **только** после сброса кэша:
|
||
|
||
- штатно — `plane_sync.reload_project_states(project_id)` (или рестарт процесса);
|
||
- на **staging** (8501) — безопасный рестарт песочницы;
|
||
- на **прод** (8500) — **НЕ рестартить контейнер ради этого** в рамках задачи
|
||
(self-hosting: общий контейнер всех проектов). Кэш заполняется при первом обращении к
|
||
проекту; если статусы созданы ДО первого PATCH в цикле новой версии — отдельный сброс не
|
||
нужен. Если созданы позже — дождаться штатного цикла обновления/деплоя орка.
|
||
|
||
---
|
||
|
||
## 4. Порядок раската (рекомендация)
|
||
|
||
1. Слить кодовый PR ORCH-066 через `deploy-staging` (8501).
|
||
2. Создать 6 статусов в проекте ORCH (§1–§2).
|
||
3. Сбросить кэш / поднять staging, прогнать sandbox-задачу — убедиться, что доска
|
||
показывает `Analysis` / `Code-Review` / `Awaiting Deploy` / `Deploying` /
|
||
`Monitoring after Deploy` / `Done` на соответствующих этапах.
|
||
4. Прод-деплой орка штатным self-deploy (Phase A → approve → Phase B/C).
|
||
|
||
**До шага 2** система работает строго как до ORCH-066 (alias-fallback) — раскат
|
||
безопасно обратим: не создавать/удалить статусы = откат индикации к старой модели,
|
||
без изменения кода.
|
||
|
||
---
|
||
|
||
## 5. Что НЕ требуется
|
||
|
||
- Никаких изменений docker-compose, портов, сети, томов, `.env`/`.env.staging`.
|
||
- Никаких миграций БД (`tasks` не хранит Plane-статус).
|
||
- Никаких изменений в проекте **enduro-trails** — там новые статусы не создаются;
|
||
alias-fallback держит прежнюю индикацию (`In Progress`/`Review`/`Done`).
|