auto-sync: 2026-06-04 23:30:01

tasks/orchestrator/DESIGN_STAGING_ENV.md

@@ -0,0 +1,70 @@
+# Дизайн: тестовая (staging) среда для orchestrator
+
+**Статус:** дизайн на согласовании · **Связь:** ORCH-30 (методика test-сред), ORCH-7 (self-hosting), ORCH-21 (auto-rollback)
+**Дата:** 2026-06-04 · **Автор:** Стрим (по решениям Славы)
+
+## Решения Славы (04.06, зафиксировано)
+1. **Постоянный** staging-контейнер (не эфемерный). ✅
+2. **Полная изоляция БД** задач staging от прод-очереди. ✅
+3. **Вариант b** — staging работает «как настоящий» в песочнице: отдельный тестовый проект Plane + отдельный тестовый репо Gitea. ✅
+4. Промоут staging→prod: «**смотри на принцип автономно и надёжно**» → решение Стрим (см. §4). ✅
+5. Smoke обязателен И больше: **реальные прогоны**, **изменение статусов и комменты в Plane**, **проверка доступов**, **интеграционное тестирование**. ✅
+6. **Агенты на staging — гибрид C** (04.06): по умолчанию ЗАГЛУШКИ агентов (быстро/дёшево/детерминированно — гейт проверяет что ОРК не сломан, а не качество LLM), + отдельный прогон `full-real` (по флагу, реже) с настоящим Claude CLI через `claude-cli-proxy`. Plane/Gitea на staging — настоящие (песочница), заглушка только на «мозге агента». ✅
+7. **Промоут: ручной approve ОСТАЁТСЯ на старте** (`DEPLOY_REQUIRE_MANUAL_APPROVE=true`) — хук тормозит после зелёного staging и ждёт «go» Славы. Полный авто включим позже, когда наберём доверие. ✅
+
+## §1. Где живёт staging
+- Контейнер `orchestrator-staging`, порт **8501** (прод — 8500), из того же compose-файла (новый service или профиль `staging`).
+- Живёт 24/7. Образ — `orchestrator:candidate` (кандидат на промоут).
+
+## §2. Изоляция БД
+- Отдельный volume / отдельный файл sqlite (`orchestrator_staging.db`), НЕ боевая очередь `jobs`/`tasks`.
+- Пустая на старте + seed-фикстуры тестовых задач. Staging НИКОГДА не пишет в прод-БД.
+- Отдельный `.env.staging` со своими токенами/путями.
+
+## §3. Песочница интеграций (вариант b)
+- **Plane:** отдельный тестовый проект — рабочее имя `ORCH-SANDBOX` (свой project_id, добавить в реестр `src/projects.py` как известный проект staging-инстанса). Staging-орк реально меняет статусы и пишет комменты — но в песочном проекте, не в боевом ORCH.
+- **Gitea:** отдельный репо `orchestrator-sandbox` (или `enduro-sandbox` как цель для тестовых веток). Staging-орк реально создаёт ветки/PR там, не засоряя боевые репозитории.
+- **Боты/токены:** staging использует те же агент-роли, но с явной пометкой и, по возможности, отдельными токенами, чтобы по логам отличать staging-активность от прод.
+- ⚠️ Webhook'и: staging-Plane-проект шлёт события на staging-эндпоинт (8501), прод — на 8500. Реестр проектов фильтрует по project_id (механизм уже есть из ORCH-6).
+
+## §4. Промоут staging→prod — РЕШЕНИЕ СТРИМ (принцип «автономно и надёжно»)
+
+**Ключевой принцип: деплоем орка управляет ВНЕШНИЙ хост-хук, а НЕ сам контейнер орка.**
+Причина: орк деплоит сам себя. Если контейнер сам себе делает `docker compose up -d` нового образа — он убивает свой процесс на середине деплоя и не может довести/откатить. Поэтому исполнитель деплоя — скрипт на хосте (как `enduro-deploy-hook.sh`, который уже умеет rollback через PREV_IMG). Орк может только ИНИЦИИРОВАТЬ (положить сигнал/тег), исполняет и контролирует — хост.
+
+**Поток (полностью автономный, с гейтами и авто-откатом):**
+1. Код прошёл review → merge в main.
+2. Хост-хук собирает образ → тег `orchestrator:candidate`.
+3. Хост-хук поднимает/обновляет `orchestrator-staging` (8501) на candidate (изолированная БД + песочница Plane/Gitea).
+4. **Гейт staging** (всё должно пройти, иначе СТОП, прод не трогаем):
+   - health `/health` отвечает; `/queue` живой; webhook-приём отвечает;
+   - **проверка доступов**: staging реально достучался до Plane (песочный проект) и Gitea (sandbox-репо) своими токенами;
+   - **интеграционный прогон end-to-end**: создать тестовую задачу в ORCH-SANDBOX → staging-орк создаёт ветку в sandbox-репо, **меняет статусы и пишет комменты в Plane** (проверяем по факту через Plane API), доходит до ожидаемой стадии.
+5. Staging зелёный → **промоут build-once**: тот же образ перетегируется `orchestrator:latest`.
+6. Хост-хук сохраняет PREV_IMG прода → `docker compose up -d orchestrator` (8500).
+7. **Health-check прода после рестарта** (с хоста, retry N раз, timeout).
+8. **Если прод-health не поднялся → авто-rollback** на PREV_IMG (механизм уже есть в enduro-хуке) + алерт.
+9. Уведомление о результате (Plane-коммент в боевую задачу + телеграм Славе).
+
+**Почему «автономно И надёжно»:** всё происходит само (автономно), но прод меняется только после зелёного staging-гейта, а любой сбой прода ловится health-check'ом и откатывается на предыдущий образ внешним механизмом (надёжно). Орк физически не может необратимо убить сам себя — рубильник снаружи контейнера.
+
+**Опция ручного стопа:** на старте — флаг `DEPLOY_REQUIRE_MANUAL_APPROVE=true` (хук останавливается после зелёного staging и ждёт явного «go» от Славы). Когда доверие к автоматике наберётся — выключаем, идёт полный авто. Так автономность вводится постепенно, без риска на ранней стадии.
+
+## §5. Что гоняем (по требованию Славы — не только smoke)
+- **Smoke:** health, /queue, webhook-приём живы.
+- **Проверка доступов:** Plane токены (песочный проект), Gitea токены (sandbox-репо) — реальные вызовы, не моки.
+- **Интеграционное тестирование end-to-end:** задача в ORCH-SANDBOX → ветка в sandbox-репо + смена статусов + комменты в Plane (верификация через Plane/Gitea API, что они реально проставлены).
+- **Реальные прогоны:** не моки — staging работает как прод, но в песочнице.
+
+## Этапы реализации (предлагаемая разбивка на задачи Plane)
+- **Этап 1 — Staging-инфра:** service `orchestrator-staging` (8501) в compose, изолированная БД/volume, `.env.staging`, поднятие/health.
+- **Этап 2 — Песочница интеграций:** тестовый Plane-проект ORCH-SANDBOX + Gitea-репо orchestrator-sandbox, токены/доступы, регистрация в `src/projects.py`, маршрутизация webhook'ов на 8501.
+- **Этап 3 — Тест-сьют staging:** скрипт smoke + проверка доступов + интеграционный end-to-end прогон (создание задачи → ветка → статусы → комменты, с верификацией).
+- **Этап 4 — Хост-деплой-хук с промоутом и откатом:** `orchestrator-deploy-hook.sh` (по образцу enduro): build candidate → staging up → гейт §4 → promote → health → auto-rollback. Флаг ручного approve. (Пересекается с ORCH-21.)
+- **Этап 5 — Встройка в конвейер/методику:** стадия `deploy-staging` ПЕРЕД `deploy-prod`, тестер привязан к staging-эндпоинту, обновить методику.
+
+## Открытые мелочи (уточнить по ходу, не блокеры)
+- Имя песочных проекта/репо (ORCH-SANDBOX / orchestrator-sandbox — ок?).
+- Отдельные ли токены ботов для staging или те же с пометкой.
+- N retry и timeout health-check прода (предлагаю 10 попыток × 6 сек = 60с).
+- Ресурсы хоста под постоянный staging-контейнер (лёгкий, но 24/7).