183 lines
12 KiB
Markdown
183 lines
12 KiB
Markdown
# Implementation Plan: Clean Repository Enterprise Preparation
|
||
|
||
**Branch**: `023-clean-repo-enterprise` | **Date**: 2026-03-03 | **Spec**: [`spec.md`](./spec.md)
|
||
**Input**: Feature specification from [`/specs/023-clean-repo-enterprise/spec.md`](./spec.md)
|
||
|
||
## Summary
|
||
|
||
Подготовить enterprise clean-профиль поставки, который:
|
||
1) исключает тестовые/демо-данные из дистрибутива,
|
||
2) блокирует любые внешние интернет-источники ресурсов,
|
||
3) допускает загрузку ресурсов только с внутренних серверов компании,
|
||
4) предоставляет обязательную проверку compliance и аудитный отчёт перед выпуском.
|
||
|
||
Ключевой UX фиксируется как интерактивный TUI сценарий на основе [`ux_reference.md`](./ux_reference.md): оператор в одном консольном интерфейсе запускает проверку, видит прогресс по этапам, нарушения и итоговый статус (`COMPLIANT`/`BLOCKED`).
|
||
|
||
## Technical Context
|
||
|
||
**Language/Version**: Python 3.9+ (backend scripts/services), Shell (release tooling)
|
||
**Primary Dependencies**: FastAPI stack (existing backend), ConfigManager, TaskManager, файловые утилиты, internal artifact registries
|
||
**Storage**: PostgreSQL (конфигурации/метаданные), filesystem (артефакты дистрибутива, отчёты проверки)
|
||
**Testing**: pytest (backend), contract checks для release compliance, smoke checks для TUI flow
|
||
**Target Platform**: Linux server в изолированной корпоративной сети
|
||
**Project Type**: web-service + operational CLI/TUI tooling
|
||
**Performance Goals**:
|
||
- стандартный запуск проверки clean/compliance ≤ 15 минут на типовой релиз-кандидат;
|
||
- формирование человекочитаемого отчёта сразу после завершения проверки.
|
||
**Constraints**:
|
||
- Полный запрет на внешние интернет-загрузки в enterprise clean-профиле;
|
||
- все ресурсы только с внутренних серверов компании;
|
||
- выпуск блокируется при любом нарушении data purity или source isolation.
|
||
**Scale/Scope**:
|
||
- 1 enterprise release flow;
|
||
- 1 TUI сценарий подготовки/проверки;
|
||
- 3–6 новых/обновлённых модулей проверки и отчётности;
|
||
- документация и контракты в пределах feature-папки.
|
||
|
||
## Constitution Check
|
||
|
||
*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
|
||
|
||
- **I. Semantic Protocol Compliance**: PASS
|
||
План предусматривает формальные контракты в [`contracts/modules.md`](./contracts/modules.md) с `[DEF]`/`@TAG` и закрывающими якорями.
|
||
- **II. Modular Plugin Architecture**: PASS
|
||
Логика будет интегрирована через существующие сервисы/плагины и централизованную конфигурацию через `ConfigManager`; hardcode-источники запрещаются политикой clean-profile.
|
||
- **III. Unified Frontend Experience**: PASS (N/A for web UI changes)
|
||
Для фичи primary UX — TUI (`ncurses`-совместимый). Изменений веб-компонентов, нарушающих правила `requestApi/fetchApi`, не планируется.
|
||
- **IV. Security & RBAC**: PASS
|
||
Проверка соответствия и выпускные действия остаются под существующей auth/RBAC моделью и аудитом.
|
||
- **V. Independent Testability**: PASS
|
||
В спецификации определены независимые пользовательские сценарии с отдельной проверяемостью.
|
||
- **VI. Asynchronous Execution**: PASS
|
||
Длительная проверка может быть оформлена как task-flow с отчётом; блокировок API на долгих операциях не планируется.
|
||
|
||
**Gate Result (pre-research)**: PASS
|
||
|
||
## Project Structure
|
||
|
||
### Documentation (this feature)
|
||
|
||
```text
|
||
specs/023-clean-repo-enterprise/
|
||
├── plan.md
|
||
├── research.md
|
||
├── data-model.md
|
||
├── quickstart.md
|
||
├── contracts/
|
||
│ ├── modules.md
|
||
│ └── api.yaml
|
||
└── tasks.md
|
||
```
|
||
|
||
### Source Code (repository root)
|
||
|
||
```text
|
||
backend/
|
||
├── src/
|
||
│ ├── api/
|
||
│ ├── core/
|
||
│ ├── services/
|
||
│ └── scripts/
|
||
└── tests/
|
||
|
||
frontend/
|
||
└── src/ # Без изменений в рамках этой фичи (primary UX = TUI script)
|
||
```
|
||
|
||
**Structure Decision**: Выбрана структура web application с упором на backend + operational TUI tooling; изменения фронтенда не требуются для MVP enterprise clean-подготовки.
|
||
|
||
## Phase 0 — Outline & Research Plan
|
||
|
||
Цель: снять неопределённости и принять архитектурные решения до контрактов.
|
||
|
||
Исследовательские направления:
|
||
1. Политика классификации артефактов (что считать test/demo/load data и как исключать без повреждения system-init).
|
||
2. Политика source isolation (детекция и запрет внешних internet endpoints, allowlist внутренних серверов).
|
||
3. Формат compliance-отчёта для релизного аудита (минимальный обязательный набор полей).
|
||
4. Паттерн интеграции TUI-проверки в существующий release workflow (ручной запуск + CI gate).
|
||
|
||
Выход Phase 0: заполненный [`research.md`](./research.md) без `NEEDS CLARIFICATION`.
|
||
|
||
## Phase 1 — Design & Contracts Plan
|
||
|
||
Цель: спроектировать сущности, контракты и API/интерфейсы для реализации.
|
||
|
||
1. Проверка соответствия UX из [`ux_reference.md`](./ux_reference.md):
|
||
- состояния `READY/RUNNING/COMPLIANT/BLOCKED` должны быть отражены в контракте TUI-модуля (`@UX_STATE`);
|
||
- ошибки `Data Purity`, `External Source`, `Internal Source Unavailable` должны иметь контракт восстановления.
|
||
2. Модель данных:
|
||
- ReleaseCandidate, CleanProfilePolicy, ResourceSourceRegistry, ComplianceCheckReport, DistributionManifest.
|
||
3. Семантические контракты:
|
||
- модуль orchestration проверки;
|
||
- модуль policy engine;
|
||
- модуль source isolation validator;
|
||
- модуль report generator;
|
||
- TUI module (CRITICAL UX-contract).
|
||
4. API/контракты:
|
||
- схема запуска проверки и получения результата;
|
||
- контракт структуры violation entries.
|
||
5. Quickstart:
|
||
- изолированный запуск в корпоративной сети без внешнего интернета.
|
||
|
||
Выход Phase 1:
|
||
- [`data-model.md`](./data-model.md)
|
||
- [`contracts/modules.md`](./contracts/modules.md)
|
||
- [`contracts/api.yaml`](./contracts/api.yaml)
|
||
- [`quickstart.md`](./quickstart.md)
|
||
|
||
## Phase 2 — Task Planning Approach
|
||
|
||
На этапе `/speckit.tasks` задачи будут разбиты на независимые user-story инкременты:
|
||
|
||
- US1 (P1): формирование clean-дистрибутива без test/demo-data.
|
||
- US2 (P1): source isolation и internal-only resource policy.
|
||
- US3 (P2): release compliance gate + отчётность.
|
||
- US4 (P3): операционный runbook + onboarding сценарий.
|
||
|
||
Для каждой истории будут определены:
|
||
- независимый тест;
|
||
- набор backend задач;
|
||
- проверка контракта;
|
||
- критерии готовности.
|
||
|
||
## Post-Design Constitution Re-Check
|
||
|
||
Проверка после подготовки артефактов Phase 1 ([`research.md`](./research.md), [`data-model.md`](./data-model.md), [`contracts/modules.md`](./contracts/modules.md), [`contracts/api.yaml`](./contracts/api.yaml), [`quickstart.md`](./quickstart.md)):
|
||
|
||
- **I. Semantic Protocol Compliance**: PASS
|
||
Контракты оформлены через `[DEF:...:Module]` и закрывающие `[/DEF:...:Module]` в [`contracts/modules.md`](./contracts/modules.md).
|
||
- **II. Modular Plugin Architecture**: PASS
|
||
Дизайн опирается на существующие модульные сервисы и централизованную конфигурацию, без hardcode-конфигураций clean-политики.
|
||
- **III. Unified Frontend Experience**: PASS (N/A for web UI changes)
|
||
Целевой UX реализуется как TUI (`ncurses`-совместимый), что согласовано со [`ux_reference.md`](./ux_reference.md).
|
||
- **IV. Security & RBAC**: PASS
|
||
Введён блокирующий compliance-gate при внешних источниках и запрещённых данных, отчётность предусмотрена для аудита.
|
||
- **V. Independent Testability**: PASS
|
||
Зафиксированы независимые сценарии проверки clean/compliance и recovery flow в [`quickstart.md`](./quickstart.md).
|
||
- **VI. Asynchronous Execution**: PASS
|
||
Длительная проверка проектируется как orchestrated run с поэтапным статусом и финальным отчётом, без требований к блокирующим long-running API вызовам.
|
||
|
||
**Gate Result (post-design)**: PASS
|
||
|
||
**Operational Note (resolved)**: конфликт numeric prefix `020` устранён governance-решением: enterprise clean feature закреплён под уникальным префиксом `023` (ветка и feature-directory: `023-clean-repo-enterprise`). Проверка prereqs и speckit-поток выполняются с `FEATURE_DIR=specs/023-clean-repo-enterprise` без неоднозначности с [`specs/020-task-reports-design`](../020-task-reports-design).
|
||
|
||
## Implementation Traceability & Final Notes
|
||
|
||
- Статус реализации: Phase 1–7 завершены (T001–T043).
|
||
- Ключевые подтверждения polish-фазы:
|
||
- T039: smoke TUI сценария зафиксирован в [`quickstart.md`](./quickstart.md).
|
||
- T040: контрактная проверка API подтверждена тестом [`backend/tests/api/routes/test_clean_release_api.py`](../../backend/tests/api/routes/test_clean_release_api.py).
|
||
- T041: создан чеклист evidence package [`checklists/release-readiness.md`](./checklists/release-readiness.md).
|
||
- T042: governance conflict по префиксу закрыт и задокументирован.
|
||
- T043: добавлена итоговая traceability-нотация в текущем плане.
|
||
|
||
Итог: feature готова к финальному релизному циклу с обязательным CI gate (`COMPLIANT` only) и операционной доказательной базой для аудита.
|
||
|
||
## Complexity Tracking
|
||
|
||
> Fill ONLY if Constitution Check has violations that must be justified
|
||
|
||
| Violation | Why Needed | Simpler Alternative Rejected Because |
|
||
|-----------|------------|-------------------------------------|
|
||
| None at planning stage | N/A | N/A |
|