ss-tools/specs/023-clean-repo-enterprise/quickstart.md

Quickstart: Enterprise Clean Compliance (TUI)

Purpose

Этот quickstart описывает минимальный операционный путь проверки enterprise clean-поставки в изолированной сети компании:

• без внешнего интернета;
• только с внутренними серверами ресурсов;
• с блокировкой релиза при нарушениях.

Prerequisites

1. Есть релиз-кандидат (candidate_id) для проверки.
2. Активна политика enterprise-clean.
3. Настроен внутренний реестр серверов ресурсов (artifact/git/package mirrors).
4. Внешний интернет для узла проверки недоступен/запрещён согласно корпоративной политике.
5. Доступен TUI-скрипт проверки clean-compliance.

Step 1 — Запуск TUI

cd /home/busya/dev/ss-tools
./backend/.venv/bin/python3 -m backend.src.scripts.clean_release_tui

Ожидаемое состояние интерфейса после старта: READY.

Step 2 — Выбор релиз-кандидата и профиля

В главном экране TUI:

1. Установить Candidate = <candidate_id>.
2. Установить Profile = enterprise-clean.
3. Проверить, что отображается список разрешённых внутренних серверов.

Step 3 — Запуск проверки

Нажать F5 (Run Check).

Ожидаемый порядок стадий:

1. Data Purity
2. Internal Sources Only
3. No External Internet Endpoints
4. Manifest Consistency

Состояние интерфейса: RUNNING.

Step 4A — Успешный результат

Если все стадии PASS:

• итоговый статус: COMPLIANT;
• отображается Report ID;
• доступна выгрузка отчёта (F6 Export Report).

Это означает, что релиз-кандидат допускается к следующему этапу выпуска.

Step 4B — Блокирующий результат

Если хотя бы одна обязательная стадия FAIL:

• итоговый статус: BLOCKED;
• отображается таблица нарушений с полями:
  • категория;
  • локация;
  • remediation.

Типовые причины:

• найдены test/demo/load-test данные;
• найден внешний endpoint;
• нарушена целостность manifest.

Step 5 — Recovery Flow

1. Исправить нарушения по рекомендациям в отчёте.
2. Повторно запустить проверку из того же TUI экрана (F5).
3. Повторять до статуса COMPLIANT.

CI Gate (обязательный)

После операторского прогона TUI та же политика должна быть проверена в CI. Релиз допускается только при COMPLIANT в CI-прогоне.

Acceptance Checklist (Operator)

• Проверка выполнена на профиле enterprise-clean
• Внешние источники не обнаружены
• Проверка завершена статусом COMPLIANT
• Отчёт выгружен и приложен к релизному пакету
• Candidate отмечен как готовый к выпуску

Troubleshooting Matrix

Category	Symptom	Blocking Rule	Remediation
data-purity	В составе кандидата есть test/demo/load-test артефакты	Любой найденный запрещённый артефакт => BLOCKED	Удалить запрещённые артефакты, повторить проверку
external-source	Обнаружен внешний endpoint (не из реестра внутренних хостов)	Любой внешний источник => BLOCKED	Заменить источник на внутренний сервер из allowlist, подтвердить конфиг
operational-risk	Внутренний источник недоступен во время проверки	Недоступность обязательного внутреннего ресурса => BLOCKED	Восстановить доступность внутреннего сервера и перезапустить проверку

Troubleshooting

Сценарий: Internal source unavailable

Симптом:

• этап Internal Sources Only или No External Internet Endpoints завершился с ошибкой доступности.

Действия:

1. Проверить доступность внутреннего сервера ресурсов.
2. Проверить соответствие endpoint реестру разрешённых источников.
3. Перезапустить проверку.

Сценарий: External source detected

Симптом:

• в нарушениях категория external-source.

Действия:

1. Удалить/заменить внешний источник на внутренний сервер из реестра.
2. Подтвердить изменение конфигурации.
3. Перезапустить проверку.

Smoke Validation Record

Дата: 2026-03-03 Среда: backend/.venv, локальный запуск из корня репозитория.

• TUI smoke command:
  • cd backend && .venv/bin/python3 -m src.scripts.clean_release_tui
  • Результат: PASS (exit code 0, состояние READY, панель внутренних источников отображается).
• API contract smoke command:
  • cd backend && .venv/bin/python3 -m pytest tests/api/routes/test_clean_release_api.py -q
  • Результат: PASS (2 passed), shape контрактов /api/clean-release/checks* и /api/clean-release/reports/{id} подтверждён.

Примечание:

• В тестовом прогоне есть существующие проектные предупреждения (Pydantic/FastAPI deprecations), но блокирующих ошибок для feature smoke-проверки не обнаружено.