busya/ss-tools
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
19898b157018352bce08e5d89c3ffb01c25d2106
ss-tools/specs/023-clean-repo-enterprise/plan.md

11 KiB
Raw Blame History

Implementation Plan: Clean Repository Enterprise Preparation

Branch: 023-clean-repo-enterprise | Date: 2026-03-03 | Spec: spec.md
Input: Feature specification from /specs/023-clean-repo-enterprise/spec.md

Summary

Подготовить enterprise clean-профиль поставки, который:

  1. исключает тестовые/демо-данные из дистрибутива,
  2. блокирует любые внешние интернет-источники ресурсов,
  3. допускает загрузку ресурсов только с внутренних серверов компании,
  4. предоставляет обязательную проверку compliance и аудитный отчёт перед выпуском.

Ключевой UX фиксируется как интерактивный TUI сценарий на основе 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 с [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)

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)

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 без NEEDS CLARIFICATION.

Phase 1 — Design & Contracts Plan

Цель: спроектировать сущности, контракты и API/интерфейсы для реализации.

  1. Проверка соответствия UX из 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:

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, data-model.md, contracts/modules.md, contracts/api.yaml, quickstart.md):

  • I. Semantic Protocol Compliance: PASS Контракты оформлены через [DEF:...:Module] и закрывающие [/DEF:...:Module] в 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.
  • IV. Security & RBAC: PASS Введён блокирующий compliance-gate при внешних источниках и запрещённых данных, отчётность предусмотрена для аудита.
  • V. Independent Testability: PASS Зафиксированы независимые сценарии проверки clean/compliance и recovery flow в quickstart.md.
  • VI. Asynchronous Execution: PASS Длительная проверка проектируется как orchestrated run с поэтапным статусом и финальным отчётом, без требований к блокирующим long-running API вызовам.

Gate Result (post-design): PASS

Operational Note: в tooling обнаружено предупреждение о конфликте numeric prefix 020 между specs/023-clean-repo-enterprise и specs/020-task-reports-design. Это не блокирует текущий план-файл, но требует governance-решения для устранения неоднозначности при запуске стандартных speckit-скриптов.

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