# Feature Specification: Clean Repository Enterprise Preparation

**Feature Branch**: `023-clean-repo-enterprise`  
**Created**: 2026-03-03  
**Status**: Draft  
**Input**: User description: "Я хочу проработать возможность создания чистого репозитория проекта без тестовых данных для последующего разворота в сети моей организации."

## User Scenarios & Testing *(mandatory)*

### User Story 1 - Чистый корпоративный релиз без тестовых данных (Priority: P1)

Как владелец платформы, я хочу получать enterprise-поставку без тестовых и демонстрационных данных, чтобы безопасно разворачивать продукт в сети организации.

**Why this priority**: Это ключевое условие допуска в корпоративный контур и базовое требование к чистоте поставки.

**Independent Test**: Можно сформировать enterprise-дистрибутив и проверить, что запрещённые категории данных отсутствуют, а система запускается в «пустом» рабочем состоянии.

**Acceptance Scenarios**:

1. **Given** собран релиз-кандидат, **When** выполняется подготовка clean-поставки, **Then** итоговый дистрибутив не содержит тестовые и демонстрационные данные.
2. **Given** clean-поставка сформирована, **When** оператор разворачивает её в новом корпоративном окружении, **Then** система стартует без предзагруженных демо-сущностей и доступна для первичной настройки.

---

### User Story 2 - Полностью изолированная поставка без внешнего интернета (Priority: P1)

Как администратор корпоративной инфраструктуры, я хочу, чтобы развёртывание и эксплуатация clean-профиля не требовали внешнего интернета, а все ресурсы загружались только с внутренних серверов компании.

**Why this priority**: Для изолированных контуров это обязательное требование информационной безопасности и комплаенса.

**Independent Test**: Можно отключить внешний интернет для стенда, выполнить установку и запуск, и подтвердить, что все зависимости, артефакты и обновления берутся только из внутренних источников.

**Acceptance Scenarios**:

1. **Given** внешний интернет недоступен, **When** выполняется развертывание clean-профиля, **Then** процесс завершается успешно с использованием только внутренних серверов компании.
2. **Given** в конфигурации указан внешний источник ресурсов, **When** запускается проверка enterprise-compliance, **Then** выпуск блокируется и формируется отчёт о нарушении политики изоляции.
3. **Given** система работает в корпоративной сети, **When** выполняются штатные операции получения ресурсов, **Then** обращения во внешние интернет-источники отсутствуют.

---

### User Story 3 - Обязательная проверка соответствия перед выпуском (Priority: P2)

Как release-менеджер, я хочу иметь обязательный контроль clean/compliance перед выпуском, чтобы исключить случайный выпуск неочищенной или не изолированной поставки.

**Why this priority**: Автоматическая проверка снижает риск человеческой ошибки и обеспечивает повторяемость релизного процесса.

**Independent Test**: Можно подложить запрещённый артефакт или внешний endpoint, запустить проверку и убедиться, что выпуск блокируется с понятным отчётом.

**Acceptance Scenarios**:

1. **Given** в релиз-кандидате найден запрещённый артефакт, **When** запускается проверка соответствия, **Then** проверка завершается неуспешно с детализацией нарушения.
2. **Given** в релиз-кандидате обнаружен внешний источник загрузки ресурсов, **When** запускается проверка соответствия, **Then** проверка завершается неуспешно с указанием внешнего источника и причины блокировки.
3. **Given** релиз-кандидат соответствует правилам clean и изоляции, **When** запускается проверка соответствия, **Then** проверка завершается успешно и фиксируется результат для аудита.

---

### User Story 4 - Прозрачный операционный регламент (Priority: P3)

Как инженер сопровождения, я хочу иметь однозначную документацию по clean-развертыванию в изолированном контуре, чтобы выполнять запуск без дополнительных согласований и устных инструкций.

**Why this priority**: Формализованный регламент уменьшает время ввода в эксплуатацию и число операционных ошибок.

**Independent Test**: Новый инженер по документации выполняет clean-развертывание в изолированном сегменте и проходит проверочный чек-лист без обращения к команде разработки.

**Acceptance Scenarios**:

1. **Given** инженер использует только утверждённую документацию, **When** он выполняет clean-развертывание в изолированной сети, **Then** запуск проходит успешно.
2. **Given** инженер проверяет допустимые источники ресурсов, **When** он сверяется с документацией, **Then** он однозначно определяет, что разрешены только внутренние серверы компании.

---

### Edge Cases

- Что происходит, если обязательные системные стартовые данные ошибочно помечены как тестовые и исключены из clean-поставки?
- Как обрабатывается случай, когда релиз-кандидат одновременно содержит и разрешённые, и запрещённые источники ресурсов?
- Что происходит, если внутренний сервер ресурсов временно недоступен во время развёртывания в изолированном контуре?
- Как система реагирует, если в конфигурации присутствует косвенная ссылка на внешний интернет-источник (например, зеркальный URL вне корпоративного домена)?
- Что происходит при повторной подготовке clean-дистрибутива для уже очищенного релиз-кандидата?

## Requirements *(mandatory)*

### Functional Requirements

- **FR-001**: Система MUST поддерживать отдельный enterprise clean-профиль поставки для развёртывания без тестовых и демонстрационных данных.
- **FR-002**: Enterprise clean-профиль MUST явно определять запрещённые категории содержимого и применять эти правила при формировании поставки.
- **FR-003**: Процесс формирования clean-дистрибутива MUST исключать запрещённые категории из итогового артефакта, сохраняя минимально необходимый набор для работоспособного запуска.
- **FR-004**: Система MUST обеспечивать режим эксплуатации без зависимости от внешнего интернета для enterprise clean-профиля.
- **FR-005**: Все ресурсы, необходимые для установки, запуска, сопровождения и обновления enterprise clean-профиля, MUST загружаться только с внутренних серверов компании.
- **FR-006**: Система MUST обнаруживать и блокировать внешние интернет-источники ресурсов в релиз-кандидате и операционной конфигурации enterprise clean-профиля.
- **FR-007**: Перед выпуском enterprise clean-дистрибутива MUST выполняться обязательная проверка clean/compliance.
- **FR-008**: Проверка clean/compliance MUST завершаться неуспешно при обнаружении хотя бы одного запрещённого артефакта данных или хотя бы одного внешнего интернет-источника.
- **FR-009**: При неуспешной проверке система MUST формировать отчёт с категорией нарушения, расположением, уровнем критичности и рекомендацией по устранению.
- **FR-010**: При успешной проверке система MUST формировать подтверждение прохождения проверки с идентификатором релиз-кандидата и временем проверки.
- **FR-011**: Процесс clean-подготовки MUST быть воспроизводимым: одинаковое входное состояние должно приводить к одинаковому составу поставки и одинаковому результату проверки.
- **FR-012**: Документация MUST включать отдельный регламент изолированного развертывания, включая требования к внутренним серверам ресурсов и действия при недоступности внутренних источников.
- **FR-013**: Документация MUST чётко разделять сценарии development и enterprise clean, чтобы исключить случайное использование внешних интернет-ресурсов в enterprise-контуре.
- **FR-014**: Система MUST вести аудитный журнал этапов подготовки, проверки и выпуска clean-поставки, включая результаты контроля изоляции от внешнего интернета.
- **FR-015**: Валидатор MUST поддерживать три режима ввода артефактов: (A) указанная папка сборки (CLI-аргумент), (B) рекурсивное сканирование файлов текущего репозитория, (C) Docker-образ или архив поставки (.tar.gz). Режим указывается при запуске.
- **FR-016**: Классификация артефактов (включения/исключения, запрещённые категории) MUST определяться через внешний конфигурационный файл `.clean-release.yaml` в корне репозитория, явно задаваемый владельцем проекта.
- **FR-017**: Допустимые внутренние источники ресурсов MUST определяться в секции `allowed_sources` файла `.clean-release.yaml` с glob-паттернами. Любой endpoint, не подпадающий под указанные паттерны, является нарушением политики изоляции.
- **FR-018**: Стадия `NO_EXTERNAL_ENDPOINTS` MUST сканировать все текстовые файлы (включая код, конфиги, скрипты) на наличие URL/хостов и сверять каждый найденный endpoint с `allowed_sources`.
- **FR-019**: Процесс clean-подготовки MUST включать стадию очистки БД от тестовых пользователей и демо-данных. Правила очистки (таблицы, условия, исключения) задаются в секции `database_cleanup` файла `.clean-release.yaml`.
- **FR-020**: Структура `.clean-release.yaml` MUST включать секции: `profile`, `scan_mode`, `prohibited_categories`, `prohibited_paths`, `allowed_sources`, `ignore_paths`, `database_cleanup` (с подсекциями `tables` и `preserve`).

### Key Entities *(include if feature involves data)*

- **Release Candidate**: Набор артефактов, из которого формируется enterprise clean-поставка; содержит идентификатор, версию, временные метки и состав.
- **Clean Profile Policy**: Правила классификации содержимого и источников ресурсов на разрешённые/запрещённые для enterprise clean-профиля.
- **Resource Source Registry**: Формализованный перечень разрешённых внутренних серверов компании для загрузки всех ресурсов.
- **Compliance Check Report**: Результат проверки соответствия с итоговым статусом, списком нарушений, ссылкой на релиз-кандидат и метаданными аудита.
- **Distribution Manifest**: Зафиксированный состав итогового дистрибутива для контроля полноты, воспроизводимости и дальнейшего аудита.
- **Isolated Deployment Runbook**: Документированная операционная последовательность для развертывания и восстановления в изолированном контуре.
- **Clean Release Config** (`.clean-release.yaml`): Единый конфигурационный файл в корне репозитория, определяющий правила классификации артефактов, допустимые источники, правила очистки БД и режим сканирования.

## Success Criteria *(mandatory)*

### Measurable Outcomes

- **SC-001**: В 100% выпущенных enterprise clean-релизов отсутствуют тестовые и демонстрационные данные в итоговой поставке.
- **SC-002**: В 100% выпущенных enterprise clean-релизов отсутствуют обращения к внешним интернет-источникам ресурсов в процессе установки и запуска.
- **SC-003**: Не менее 95% запусков обязательной проверки соответствия завершаются автоматическим результатом и отчётом без ручного вмешательства.
- **SC-004**: Время подтверждения готовности clean-поставки по утверждённому процессу не превышает 15 минут для стандартного релиз-кандидата.
- **SC-005**: Не менее 90% новых инженеров сопровождения выполняют изолированное clean-развертывание по документации с первой попытки.
- **SC-006**: Количество инцидентов, связанных с попаданием тестовых данных или использованием внешнего интернета в enterprise-контуре, равно нулю в течение первого отчётного квартала после внедрения.

## Assumptions

- Корпоративный контур развёртывания является изолированным и должен работать без доступа к внешнему интернету.
- В организации существуют внутренние серверы для размещения всех необходимых ресурсов поставки и эксплуатации.
- Для продукта допустимо формальное разделение профилей на development и enterprise clean в рамках единого релизного процесса.
- Базовая первичная инициализация системы без демо-данных остаётся обязательной и должна сохраняться в clean-поставке.
- Роли владельца релиза и инженера сопровождения назначены и несут ответственность за прохождение проверок и соблюдение регламента.

## Clarifications

### Session 2026-03-04

- Q: Что именно сканирует валидатор — папку сборки, файлы репозитория, Docker-образ или JSON-манифест? → A: Поддерживаются три режима: (A) папка сборки через CLI-аргумент, (B) рекурсивное сканирование файлов репозитория, (C) Docker-образ или архив поставки.
- Q: Как определяются запрещённые категории артефактов — по паттернам пути, расширению, содержимому или конфигу? → A: Через внешний конфигурационный файл `.clean-release.yaml` в корне репозитория, где владелец явно перечисляет включения и исключения.
- Q: Что считается «внутренним источником» — точное совпадение хоста, доменные суффиксы или конфиг? → A: Определяется в `.clean-release.yaml` — секция `allowed_sources` с glob-паттернами.
- Q: Что сканирует стадия NO_EXTERNAL_ENDPOINTS — конфиги, код или зависимости? → A: Все текстовые файлы, включая код (.py, .js, .svelte) — поиск URL/хостов и сверка с allowed_sources.
- Q: Какова структура `.clean-release.yaml` и включает ли очистку БД? → A: Подтверждена полная структура с секциями `profile`, `scan_mode`, `prohibited_categories`, `prohibited_paths`, `allowed_sources`, `ignore_paths`, `database_cleanup` (tables + preserve).