130 lines
8.0 KiB
Markdown
130 lines
8.0 KiB
Markdown
---
|
||
work_item: ORCH-062
|
||
stage: analysis
|
||
author_agent: analyst
|
||
status: ready-for-review
|
||
created_at: 2026-06-09
|
||
model_used: claude-opus-4-8
|
||
---
|
||
|
||
# 03 — Критерии приёмки (Acceptance Criteria): ORCH-062 — авто-prune docker build cache на mva154
|
||
|
||
Work Item: **ORCH-062** · Repo: **orchestrator** · Стадия: analysis
|
||
|
||
Формат: каждый критерий имеет **PASS** (что должно быть истинно для приёмки) и **FAIL** (что
|
||
считается провалом). Reviewer/tester проверяют их буквально по файлам репозитория и поведению.
|
||
|
||
> Критерии сформулированы инвариантно к выбору механизма (heartbeat-демон A / `daemon.json` B /
|
||
> cron C). Где критерий специфичен пути A (код), это помечено; при выборе B/C его проверяет
|
||
> эквивалент на хосте, задокументированный в `07-infra-requirements.md` / INFRA.md.
|
||
|
||
---
|
||
|
||
## AC-1 — Авто-уборка build cache выполняется без оператора
|
||
|
||
**Условие:** build cache очищается автоматически и периодически (BR-1/FR-1).
|
||
- **PASS:** существует автоматический механизм (демон-тик пути A / BuildKit GC пути B / cron пути C),
|
||
который без ручного вмешательства запускает уборку build cache с настроенным периодом; механизм
|
||
описан в `06-adr` и INFRA.md.
|
||
- **FAIL:** уборка возможна только ручным запуском оператором; либо механизм не описан/не внедрён.
|
||
|
||
---
|
||
|
||
## AC-2 — Удерживается тёплый недавний кэш
|
||
|
||
**Условие:** очистка по умолчанию удаляет старый кэш, сохраняя свежий (BR-2/FR-2).
|
||
- **PASS:** команда/политика по умолчанию несёт возрастной фильтр (ориентир `until=24h`) или порог
|
||
объёма (`builder.gc.defaultKeepStorage`); `-a/--all` (если используется) применяется только в
|
||
паре с фильтром удержания. Параметр удержания конфигурируем.
|
||
- **FAIL:** дефолт безусловно сносит весь build cache (например, `docker builder prune -af` без
|
||
возрастного фильтра/порога), убивая тёплый кэш каждой сборки.
|
||
|
||
---
|
||
|
||
## AC-3 — Self-hosting безопасность: только build cache, без рестарта прода
|
||
|
||
**Условие:** операция затрагивает только build cache и не нарушает работу контейнеров (BR-3/FR-3).
|
||
- **PASS:** используется строго `docker builder prune` (BuildKit GC); в коде/процедуре **нет**
|
||
`docker image prune`, `docker system prune`, остановки/рестарта контейнеров или прод-деплоя;
|
||
обслуживание `enduro-trails` и прод-контейнер `orchestrator` не затрагиваются.
|
||
- **FAIL:** найдено любое удаление образов запущенных сервисов / `system prune` / любая
|
||
остановка/рестарт прод-контейнера в рамках уборки.
|
||
|
||
---
|
||
|
||
## AC-4 — never-raise: уборка не роняет конвейер
|
||
|
||
**Условие:** ошибки уборки изолированы (NFR-1/FR-6).
|
||
- **PASS:** сбой docker-команды, ненулевой rc, таймаут или недоступность docker.sock логируются и
|
||
проглатываются; фоновый цикл/процедура продолжает работу; конвейер не падает. (Путь A:
|
||
per-tick/per-команда `try/except`, как `disk_watchdog._run`/`tick`.)
|
||
- **FAIL:** ошибка уборки всплывает в процесс/останавливает фоновый цикл/влияет на обработку очереди.
|
||
|
||
---
|
||
|
||
## AC-5 — kill-switch отключает фичу в исходное состояние
|
||
|
||
**Условие:** обратимость одним флагом (BR-5/FR-5/NFR-3).
|
||
- **PASS:** при выключенном `*_enabled` демон не стартует (путь A) / процедура неактивна; поведение
|
||
системы 1:1 как до задачи; (путь A) `GET /queue` показывает `enabled=false`. Флаг задокументирован
|
||
в `.env.example` и INFRA.md.
|
||
- **FAIL:** фича работает при выключенном флаге, либо kill-switch отсутствует/не документирован.
|
||
|
||
---
|
||
|
||
## AC-6 — Конфигурируемость с безопасными дефолтами
|
||
|
||
**Условие:** период/политика удержания настраиваемы, невалид деградирует на дефолт (BR-6/FR-5).
|
||
- **PASS:** период (`*_interval_s`) и политика удержания (возраст/объём) читаются из env с
|
||
безопасными дефолтами; невалидное значение → лог-warning + дефолт (как валидаторы
|
||
`disk_monitor_*` в `src/config.py`).
|
||
- **FAIL:** параметры захардкожены без возможности конфигурации, либо невалидное значение роняет
|
||
старт/процедуру.
|
||
|
||
---
|
||
|
||
## AC-7 — Наблюдаемость состояния авто-prune
|
||
|
||
**Условие:** оператор видит состояние уборки (BR-4/FR-4).
|
||
- **PASS:** (путь A) `GET /queue` содержит read-only блок авто-prune (`enabled`, `interval_s`,
|
||
`retention`, `last_run_ts`, best-effort результат последней уборки); `status()` never-raise.
|
||
(Путь B/C) способ наблюдения (`docker system df`) описан в INFRA.md.
|
||
- **FAIL:** состояние авто-prune нигде не наблюдаемо.
|
||
|
||
---
|
||
|
||
## AC-8 — Изоляция от Quality Gate и схемы БД
|
||
|
||
**Условие:** конвейер и гейты не затронуты (NFR-2/FR §5,§6).
|
||
- **PASS:** `STAGE_TRANSITIONS`, `QG_CHECKS`, `check_*`, `_parse_*`, `src/stage_engine.py` и схема
|
||
БД (`src/db.py`) — без изменений; новый модуль (путь A) — leaf без зависимостей на конвейер.
|
||
- **FAIL:** изменён любой элемент реестра гейтов / переходов стадий / схемы БД, либо введена новая
|
||
миграция ради учёта уборки.
|
||
|
||
---
|
||
|
||
## AC-9 — Документация и регресс
|
||
|
||
**Условие:** golden source обновлён, полный регресс зелёный (NFR-6).
|
||
- **PASS:** `docs/operations/INFRA.md` обновлён (секция авто-prune + env-карта; снята формулировка
|
||
ORCH-063 «освобождение build cache — ручная операция»); `.env.example` несёт новые ключи;
|
||
`CHANGELOG.md` имеет запись Unreleased; `06-adr/ADR-001-*.md` и `07-infra-requirements.md`
|
||
заполнены; `pytest tests/ -q` зелёный.
|
||
- **FAIL:** функционал изменён, но INFRA.md/.env.example/CHANGELOG/ADR не обновлены; либо регресс
|
||
`tests/` красный.
|
||
|
||
---
|
||
|
||
## Сводная матрица AC ↔ FR/BR
|
||
| AC | Покрывает |
|
||
|----|-----------|
|
||
| AC-1 | BR-1 / FR-1 |
|
||
| AC-2 | BR-2 / FR-2 |
|
||
| AC-3 | BR-3 / FR-3 / NFR-2 |
|
||
| AC-4 | NFR-1 / FR-6 |
|
||
| AC-5 | BR-5 / FR-5 / NFR-3 |
|
||
| AC-6 | BR-6 / FR-5 |
|
||
| AC-7 | BR-4 / FR-4 |
|
||
| AC-8 | NFR-2 / FR-5 / FR-6 (TRZ §5,§6) |
|
||
| AC-9 | NFR-6 |
|