# 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

```bash
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-проверки не обнаружено.