# 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`).