82 lines
11 KiB
Markdown
82 lines
11 KiB
Markdown
# 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 последующих эпиков.
|