131 lines
6.4 KiB
Markdown
131 lines
6.4 KiB
Markdown
# 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-проверки не обнаружено. |