Files
crank/_bmad-output/implementation-artifacts/epic-2-context.md
T

82 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Epic 2 Context: Надёжное создание Tools из реальных OpenAPI
<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. -->
## Goal
Дать self-hosted администратору безопасный и воспроизводимый путь от OpenAPI/Swagger к пригодным к публикации Draft Operations: сохранить проверенный immutable snapshot, получить детерминированный preview со всеми findings, явно разрешить ограничения и конфликты, затем атомарно применить выбранный ImportPlan без silent loss, утечки секретов и частичных мутаций. Отдельных UX/design и product brief artifacts в planning-каталоге нет; UX-ограничения ниже собраны из PRD и Epic 2 требований.
## Stories
- Story 2.1: Реализовать безопасное immutable artifact storage
- Story 2.2: Добавить workspace-scoped metadata artifacts
- Story 2.3: Реализовать bounded filesystem reconciliation artifacts
- Story 2.4: Реализовать artifact claim/recovery coordinator
- Story 2.5: Ввести bounded multipart upload и verified OpenAPI preview
- Story 2.6: Завершить OpenAPI upload UX и release evidence
- Story 2.7: Преобразовать OpenAPI в детерминированный NormalizedIR
- Story 2.8: Безопасно разрешать references и schema composition
- Story 2.9: Сохранить полный поддерживаемый HTTP contract
- Story 2.10: Привязать security schemes через безопасный import API
- Story 2.11: Выбирать security mappings в OpenAPI UI
- Story 2.12: Предоставить полный preview и явный partial mode
- Story 2.13: Атомарно применять ImportPlan и обрабатывать re-import
- Story 2.14: Зафиксировать OpenAPI support matrix и regression corpus
- Story 2.15: Добавить OpenAPI-ветку в guided onboarding
## Story numbering migration — 2026-09-13
Номера изменены без изменения scope и порядка зависимостей. Для новых запусков и ссылок использовать только текущую колонку. Старые specs перенаправляют на canonical files. Архивные журналы, commits и worktree paths не переименованы: остановленные loop runs со старой нумерацией не возобновлять против нового спринта. HTTP contract теперь Story 2.9; 2026-09-13 коммит `f8ee7c9bfeaa8a3f73a4850ff3f82b2bc2155fe8` интегрирован в `main` fast-forward, статус спринта согласован с завершённым spec: `done`.
| Historical ID | Current ID | Outcome |
|---|---|---|
| 2.1a | 2.1 | Artifact store |
| 2.1b | 2.2 | Scoped metadata |
| 2.1e / 2.1b2a | 2.3 | Filesystem reconciliation |
| 2.1f / 2.1b2b | 2.4 | Claim recovery |
| 2.1c | 2.5 | Upload / preview API |
| 2.1d | 2.6 | Upload UX / evidence |
| 2.2 | 2.7 | NormalizedIR |
| 2.3 | 2.8 | References / composition |
| 2.4 | 2.9 | HTTP contract |
| 2.5 | 2.10 / 2.11 | Security schemes API / mapping UI |
| 2.6 | 2.12 | Preview / partial mode |
| 2.7 | 2.13 | Apply / re-import |
| 2.8 | 2.14 | Matrix / corpus |
| 2.9 | 2.15 | Guided onboarding |
Первоначальная объединённая Story 2.1 (OpenAPI source, до декомпозиции) соответствует текущим 2.1–2.6, а не только новой Story 2.1. Общие пять AC для 2.3/2.4 наследуются обеими stories; их индивидуальные specs уточняют границы ответственности.
## Requirements & Constraints
- Upload принимает один UTF-8 `.yaml`, `.yml` или `.json` через bounded multipart contract (до 256 KiB). Пустые, oversized, malformed, неподдержанные и не содержащие методов документы отклоняются до создания Draft или другой бизнес-мутации.
- Поддерживаются OpenAPI 3.0/3.1 и Swagger 2.0; сохраняются REST methods (кроме `TRACE`/`CONNECT`), path/query/header/cookie parameters, required/default/enum/nullable/format, JSON/form/multipart bodies и все успешные `2xx` responses, включая `204` и несколько success schemas. XML получает явный unsupported finding.
- Local и разрешённые external references, `allOf`/`oneOf`/`anyOf`, recursion и discriminators либо сохраняются, либо блокируют создание объяснимым finding. External fetch выключен по умолчанию, ограничен operator-controlled allowlist/offline bundle и bounded depth/size/cycle policy.
- Preview не изменяет Operations, versions, Agent bindings или Auth Profiles. Полный Apply возможен только без blocker findings; partial mode требует явного выбора actionable candidates с замкнутыми dependencies. Конфликты ограничены `skip`, `rename` и `new_version`.
- Bearer/basic/api-key schemes связываются только с typed `AuthProfileRef`; OAuth/unknown schemes требуют ручной настройки. Raw credentials не попадают в artifacts, plans, Draft, logs, traces, metrics, diagnostics или exports.
- Apply атомарен, идемпотентен и безопасен при retry/concurrency; bounded redacted report перечисляет outcome каждого candidate (`created`, `versioned`, `renamed`, `skipped`, `rejected`). Silent semantic loss запрещён.
- Versioned normative support matrix и checksummed corpus содержат не менее 50 fixtures OpenAPI 3.0/3.1 и Swagger 2.0; не менее 95% Operations representative corpus становятся actionable Draft. Исправленный import defect закрепляется regression fixture; E2E использует реальный upload → preview → plan → apply путь.
## Technical Decisions
- Канонический pipeline: `ParsedDocument → typed NormalizedIR + complete Findings → immutable ImportPlan → transactional Apply`. Каждый source construct получает stable ID и mapping либо explicit finding; canonical output и plan digest не зависят от времени, map ordering или request IDs.
- `crank-artifacts` хранит bounded immutable bytes под opaque SHA-256 reference через private temp file, fsync, atomic no-clobber publish и directory fsync. PostgreSQL хранит workspace ownership, digest/ref, size, MIME, sensitivity и lifecycle/reference state; verified read повторно проверяет digest и размер.
- Artifact metadata всегда scoped по authoritative workspace. Reconciliation bounded/resumable, использует grace period и reference recheck и безопасно восстанавливается после unlink/quarantine/DB/fsync uncertainty; referenced data не удаляется без подтверждённого reference accounting.
- `crank-import` pure относительно PostgreSQL, artifacts и Operations. Parser получает только verified snapshot; разрешённые external snapshots immutable и входят в plan digest, поэтому изменение remote content требует нового preview и устраняет TOCTOU.
- Применяются hexagonal modular-monolith boundaries и единая migration authority. Apply повторно проверяет source/external digests, importer/support-matrix version, catalog revision, dependencies, auth refs и conflicts перед одной PostgreSQL transaction с conditional predicates/locks.
- Общий `OutboundPolicy` применяется к external references: deny-before-allow после DNS resolution, system proxy и implicit redirects выключены, network/input/output limits bounded. Boundary errors typed/localized и содержат безопасные Request ID/Trace ID.
- Matrix, corpus, preview/plan и apply reports — immutable evidence; release evidence индексируется signed JSON-Schema Evidence Manifest. Документация не обещает больше, чем доказано executable matrix/corpus.
## UX & Interaction Patterns
- Upload flow на RU/EN имеет idle, validating, uploading, parsing/loading, success, cancelled, empty/no-methods, error и recovery states; показывает только bounded metadata, findings, actionable recovery и Request ID/Trace ID.
- Preview показывает methods, paths, names, mappings, schemas, security, conflicts и source locations; для больших результатов использует search/filter/grouping и bounded pagination/virtualized rendering (до 2 000 candidates). Blockers видимы, partial/conflict consequences требуют явного подтверждения.
- Replacement, refresh, navigation, workspace/language change и concurrent requests защищены AbortController и monotonic identity/revision guards. Duplicate Apply click и stale response не создают повторную мутацию и не меняют authoritative selection.
- UI соблюдает keyboard navigation, visible focus, semantic labels, screen-reader status, contrast, non-color meaning и reduced-motion. Guided onboarding переиспользует canonical upload/preview flow, позволяет выбрать Draft для test/publish и не публикует автоматически.
## Cross-Story Dependencies
- Epic 2 начинается после Epic 1 foundation: typed configuration, migration authority, correlation/metrics contracts, Admin authorization/Auth Profiles, Operation lifecycle и shared runtime/outbound policy должны быть доступны.
- Artifact/upload цепочка упорядочена как `2.1 → 2.2 → 2.3 → 2.4 → 2.5 → 2.6`. Normalization и semantic branches питают preview/apply: `2.7 → 2.8 → 2.9 → 2.10 → 2.11 → 2.12 → 2.13`; Story 2.14 квалифицирует весь workflow и фиксирует evidence. 2.10 владеет security semantics/revalidation API, 2.11 использует этот API для mapping UI; обе сохраняют исходный immutable contract.
- Story 2.15 зависит от guided onboarding Epic 1 и готового bounded import workflow, не создаёт отдельный parser и не обходит Auth Profile/ImportPlan. Созданные Drafts используют обычные publication и Agent-binding flows последующих эпиков.