173 lines
13 KiB
Markdown
173 lines
13 KiB
Markdown
# Phase 0 Research: Clean Repository Enterprise Preparation
|
||
|
||
## Decision 1: Артефакты разделяются на 3 класса политики clean-профиля
|
||
|
||
**Decision**
|
||
Ввести формальную классификацию артефактов при подготовке enterprise clean-поставки:
|
||
|
||
1. **Prohibited Artifacts** — строго запрещены (test/demo/load-test payloads, примеры эксплуатационных данных, временные дампы и нецелевые локальные БД/репозитории).
|
||
2. **Required System Artifacts** — обязательны для работоспособного старта (системная инициализация, базовые конфигурации, служебные миграции, security bootstrap).
|
||
3. **Conditional Artifacts** — допускаются только при соблюдении дополнительных условий (например, шаблоны конфигурации без чувствительных данных).
|
||
|
||
**Rationale**
|
||
Проблема clean-подготовки не решается простым delete-list: есть риск удалить необходимые для запуска системные элементы. Разделение на 3 класса даёт детерминированную и проверяемую модель принятия решений.
|
||
|
||
**Alternatives considered**
|
||
- **Только deny-list**: отклонено, потому что высок риск ложных блокировок системных стартовых сущностей.
|
||
- **Только allow-list**: отклонено как слишком жёсткое для эволюции проекта; высокая операционная стоимость сопровождения без явной пользы на текущем масштабе.
|
||
- **Ручная экспертная проверка без формальной модели**: отклонено из-за невоспроизводимости и человеческого фактора.
|
||
|
||
---
|
||
|
||
## Decision 2: Source Isolation политика — strict internal-only с явным реестром источников
|
||
|
||
**Decision**
|
||
Для enterprise clean-профиля принять строгую модель source isolation:
|
||
|
||
- разрешены только источники из **внутреннего реестра серверов компании**;
|
||
- любые внешние internet endpoints считаются нарушением и блокируют выпуск;
|
||
- отсутствие внешнего интернета трактуется как базовое эксплуатационное условие, а не деградационный режим.
|
||
|
||
**Rationale**
|
||
Требование пользователя и корпоративный контур задают нулевую толерантность к внешним загрузкам. Явный реестр внутренних источников обеспечивает прозрачный аудит и исключает неоднозначную интерпретацию “внутренности” ресурса.
|
||
|
||
**Alternatives considered**
|
||
- **Soft-warning для внешних источников**: отклонено, не соответствует security/compliance профилю.
|
||
- **Частично разрешённые внешние зеркала**: отклонено, усложняет доверенную цепочку и нарушает требование полной изоляции.
|
||
- **Runtime fallback на внешние источники при недоступности внутренних**: отклонено как прямое нарушение корпоративной политики.
|
||
|
||
---
|
||
|
||
## Decision 3: Compliance gate должен быть обязательным и блокирующим перед выпуском
|
||
|
||
**Decision**
|
||
Выпуск enterprise clean-дистрибутива допускается только после обязательной проверки clean/compliance с бинарным результатом:
|
||
|
||
- `COMPLIANT` — выпуск разрешён;
|
||
- `BLOCKED` — выпуск запрещён до устранения нарушений.
|
||
|
||
Проверка должна валидировать одновременно:
|
||
1. data purity (отсутствие запрещённых payloads);
|
||
2. source isolation (только внутренние источники);
|
||
3. целостность manifest релиза.
|
||
|
||
**Rationale**
|
||
Снижение рисков требует enforce-механизма, а не рекомендаций. Блокирующий gate переводит требования из “договорённостей” в гарантируемый процесс релиза.
|
||
|
||
**Alternatives considered**
|
||
- **Проверка только по запросу**: отклонено из-за неполного охвата релизов.
|
||
- **Постфактум аудит после выпуска**: отклонено, потому что не предотвращает инцидент, а фиксирует его постфактум.
|
||
- **Частичный gate только по test-data**: отклонено, так как не покрывает критичный риск внешних источников.
|
||
|
||
---
|
||
|
||
## Decision 4: UX контроля выпуска — интерактивный TUI (`ncurses`/совместимый аналог)
|
||
|
||
**Decision**
|
||
Операционный интерфейс подготовки/проверки фиксируется как единый интерактивный консольный TUI-flow (на `ncurses` или совместимом аналоге), в котором оператор:
|
||
|
||
- выбирает релиз-кандидат;
|
||
- запускает проверку;
|
||
- наблюдает поэтапный прогресс;
|
||
- получает итог и детализацию нарушений;
|
||
- экспортирует отчёт.
|
||
|
||
**Rationale**
|
||
Для изолированных контуров и release-операций TUI обеспечивает воспроизводимый сценарий без зависимости от веб-интерфейса и внешней инфраструктуры.
|
||
|
||
**Alternatives considered**
|
||
- **Только non-interactive CLI**: отклонено для primary UX из-за более слабой наблюдаемости этапов и восстановительных действий.
|
||
- **Веб-панель**: отклонено как нецелевой интерфейс для данной фичи и избыточно для операционного сценария.
|
||
|
||
---
|
||
|
||
## Decision 5: Формат compliance-отчёта должен быть одновременно машинным и операторским
|
||
|
||
**Decision**
|
||
Каждый прогон проверки формирует единый отчёт с двумя представлениями:
|
||
|
||
1. **Structured section** — формализованные поля для автоматической валидации и аудита;
|
||
2. **Operator section** — человекочитаемая сводка нарушений и шагов восстановления.
|
||
|
||
Минимальные поля:
|
||
- report_id;
|
||
- candidate_id;
|
||
- started_at / finished_at;
|
||
- final_status;
|
||
- checks summary (data purity / internal sources / no external endpoints / manifest consistency);
|
||
- violations[] (category, location, severity, remediation);
|
||
- execution metadata (кто запустил, профиль, версия политики).
|
||
|
||
**Rationale**
|
||
Без структурированного представления отчёт трудно автоматизировать; без операторской сводки — трудно использовать в day-to-day эксплуатации.
|
||
|
||
**Alternatives considered**
|
||
- **Только текстовый лог**: отклонено, слабая пригодность для автоматического контроля.
|
||
- **Только machine format**: отклонено, ухудшает скорость ручного triage в релизном окне.
|
||
|
||
---
|
||
|
||
## Decision 6: Интеграция в release workflow — ручной запуск + обязательный CI gate
|
||
|
||
**Decision**
|
||
Использовать двухконтурную интеграцию:
|
||
|
||
1. **Pre-release operator run (TUI)** — подготовка и предварительная валидация релиз-кандидата;
|
||
2. **CI gate** — обязательное повторное подтверждение compliance перед финальным выпуском.
|
||
|
||
Оба прогона должны опираться на одну и ту же policy-модель.
|
||
|
||
**Rationale**
|
||
Это сочетает управляемость оператора и enforce-гарантию pipeline, снижая риск “локально прошло, в релиз не попало”.
|
||
|
||
**Alternatives considered**
|
||
- **Только операторский запуск**: отклонено (нет централизованной enforce-гарантии).
|
||
- **Только CI без операторского шага**: отклонено (хуже диагностика и устранение до релизного окна).
|
||
|
||
---
|
||
|
||
## Decision 7: Вся конфигурация валидации определяется через `.clean-release.yaml` в корне репозитория
|
||
|
||
**Decision**
|
||
Ввести единый конфигурационный файл `.clean-release.yaml` в корне репозитория, определяющий:
|
||
- `profile` и `scan_mode` (repo | build | docker);
|
||
- `prohibited_categories` и `prohibited_paths` — классификация запрещённых артефактов;
|
||
- `allowed_sources` — список допустимых внутренних endpoint'ов (glob-паттерны);
|
||
- `ignore_paths` — исключения из сканирования;
|
||
- `database_cleanup` (tables + preserve) — правила очистки БД от тестовых данных.
|
||
|
||
**Rationale**
|
||
Централизация конфигурации в одном файле обеспечивает прозрачность и версионируемость правил. Владелец проекта явно контролирует политику clean-поставки через декларативный конфиг, что снижает операционные ошибки.
|
||
|
||
**Alternatives considered**
|
||
- Хранение правил в БД: отклонено — усложняет версионирование и аудит policy drift.
|
||
- Отдельные файлы для каждой секции: отклонено — фрагментация ухудшает обзорность и повышает вероятность рассинхронизации.
|
||
- Hardcode в коде: отклонено — нарушает принцип конфигурируемости и делает проект-специфичные правила невозможными.
|
||
|
||
---
|
||
|
||
## Decision 8: Очистка БД от тестовых пользователей и демо-данных — обязательная стадия
|
||
|
||
**Decision**
|
||
Добавить стадию `database_cleanup` в compliance pipeline. Правила очистки задаются в секции `database_cleanup` файла `.clean-release.yaml`:
|
||
- `tables` — список таблиц с SQL-условиями для удаления тестовых записей;
|
||
- `preserve` — whitelist записей, которые MUST быть сохранены (напр. системный admin).
|
||
|
||
**Rationale**
|
||
Одной файловой очистки недостаточно: тестовые пользователи (`test_user`, `sample_analyst`) и демо-дашборды в БД являются таким же нарушением enterprise clean-профиля, как наличие тестовых файлов в дистрибутиве.
|
||
|
||
**Alternatives considered**
|
||
- Только предупреждение без очистки: отклонено — не обеспечивает SC-001 (100% отсутствие тестовых данных).
|
||
- Автоматическая очистка по паттернам имён: отклонено — высокий риск ложных удалений без явного whitelist.
|
||
|
||
---
|
||
|
||
## Open Clarifications Status
|
||
|
||
По итогам Phase 0 + speckit.clarify (2026-03-04) все `NEEDS CLARIFICATION` сняты:
|
||
- Режимы ввода: 3 режима (папка, репозиторий, Docker-образ) — FR-015;
|
||
- Классификация артефактов: `.clean-release.yaml` — FR-016;
|
||
- Определение внутренних источников: `allowed_sources` в конфиге — FR-017;
|
||
- Область сканирования NO_EXTERNAL_ENDPOINTS: все текстовые файлы — FR-018;
|
||
- Очистка БД: секция `database_cleanup` — FR-019;
|
||
- Структура конфига: полная схема зафиксирована — FR-020. |