greebo/svg-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(backend): add editor context, draft flow bootstrap, and draft summary endpoints

Browse Source 
add backend endpoints for editor context and draft summaries

ensure draft flow bootstrap for editor-driven workflows
improve draft-aware initialization and summary reads for clients
This commit is contained in:
greebo
2026-03-19 21:47:38 +03:00
parent a266f56ddd
commit 4c15f4c201
6 changed files with 390 additions and 265 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
backend/docs/api-map.md
View File

@@ -47,6 +47,7 @@
- GET /api/v1/schemes/{scheme_id}/pricing/coverage
- GET /api/v1/schemes/{scheme_id}/pricing/unpriced-seats
- GET /api/v1/schemes/{scheme_id}/pricing/explain/{seat_id}
- GET /api/v1/schemes/{scheme_id}/pricing/rules/diagnostics
## app/api/routes/test_mode.py
- GET /api/v1/schemes/{scheme_id}/test/seats/{seat_id}
@@ -62,9 +63,12 @@
- POST /api/v1/schemes/{scheme_id}/draft/remap/apply
## app/api/routes/editor.py
- GET /api/v1/schemes/{scheme_id}/editor/context
- POST /api/v1/schemes/{scheme_id}/draft/ensure
- GET /api/v1/schemes/{scheme_id}/draft/summary
- GET /api/v1/schemes/{scheme_id}/draft/structure
- GET /api/v1/schemes/{scheme_id}/draft/compare-preview
- GET /api/v1/schemes/{scheme_id}/draft/validation
- GET /api/v1/schemes/{scheme_id}/draft/compare-preview
- GET /api/v1/schemes/{scheme_id}/draft/seats/records/{seat_record_id}
- GET /api/v1/schemes/{scheme_id}/draft/sectors/records/{sector_record_id}
- GET /api/v1/schemes/{scheme_id}/draft/groups/records/{group_record_id}
@@ -90,3 +94,4 @@
- This file is an operational route index, not a generated OpenAPI export.
- Update this map in the same change set when adding, removing, renaming, or moving routes.
- Query guards such as expected_current_scheme_version_id / expected_scheme_version_id are part of the operational contract for optimistic concurrency on mutable flows.
- Draft/editor routes may legally return 409 draft_not_editable when current version is already published and no editable draft exists yet.

143
backend/docs/smoke-regression.md
View File

@@ -31,148 +31,91 @@ export SCHEME_ID="82086336d385427f9d56244f9e1dd772"
- GET /api/v1/schemes/{scheme_id}/current -> 200
- GET /api/v1/schemes/{scheme_id}/versions -> 200
Validate:
- scheme_id is stable
- current version exists
- version list contains current version
- status and counts are consistent
## 3. Structure read model
- GET /api/v1/schemes/{scheme_id}/current/sectors -> 200
- GET /api/v1/schemes/{scheme_id}/current/groups -> 200
- GET /api/v1/schemes/{scheme_id}/current/seats -> 200
Validate:
- total counts are non-negative
- known sample scheme returns expected object lists
- seats contain seat_id / sector_id / group_id contract where applicable
## 4. SVG / display pipeline
- GET /api/v1/schemes/{scheme_id}/current/svg -> 200
- GET /api/v1/schemes/{scheme_id}/current/svg/display -> 200
- GET /api/v1/schemes/{scheme_id}/current/svg/display/meta -> 200
- GET /api/v1/schemes/{scheme_id}/current/svg/display?mode=optimized -> 200 or explicit controlled failure
- GET /api/v1/schemes/{scheme_id}/current/svg/display/meta?mode=optimized -> 200 or explicit controlled failure
Validate:
- response content type for svg endpoints is image/svg+xml
- meta returns scheme_id, scheme_version_id, view_box, width, height
- no 500 on passthrough mode
- unsupported mode returns 422
## 5. Pricing read model
## 5. Pricing read model / diagnostics
- GET /api/v1/schemes/{scheme_id}/pricing -> 200
- GET /api/v1/schemes/{scheme_id}/current/seats/{seat_id}/price -> 200 for priced seat
- GET /api/v1/schemes/{scheme_id}/test/seats/{seat_id} -> 200 for priced and unpriced seat
- GET /api/v1/schemes/{scheme_id}/pricing/coverage -> 200
- GET /api/v1/schemes/{scheme_id}/pricing/unpriced-seats -> 200
- GET /api/v1/schemes/{scheme_id}/pricing/explain/{seat_id} -> 200
- GET /api/v1/schemes/{scheme_id}/pricing/rules/diagnostics -> 200
- GET /api/v1/schemes/{scheme_id}/current/seats/{seat_id}/price -> 200 for priced seat
- GET /api/v1/schemes/{scheme_id}/test/seats/{seat_id} -> 200 for priced and unpriced seat
## 6. Editor entry workflow
- GET /api/v1/schemes/{scheme_id}/editor/context -> 200 always
- if context.needs_new_draft=true -> POST /api/v1/schemes/{scheme_id}/draft/ensure -> 200
- after ensure -> GET /api/v1/schemes/{scheme_id}/editor/context -> 200 and editable=true
Validate:
- pricing bundle contains categories and rules arrays
- effective seat price resolves according to domain priority
- test seat preview explains selectable / has_price state
- coverage endpoint is internally consistent
- explain endpoint returns matched_rule for priced seat and null for unpriced seat
- published current version does not break editor bootstrap
- ensure returns created_new_draft=true when current was published
- ensure returns created_new_draft=false when current was already draft
## 6. Draft editor read/write guards
## 7. Draft editor read model
- GET /api/v1/schemes/{scheme_id}/draft/structure -> 200
- GET /api/v1/schemes/{scheme_id}/draft/validation -> 200
- GET /api/v1/schemes/{scheme_id}/draft/compare-preview -> 200
- GET /api/v1/schemes/{scheme_id}/draft/summary -> 200 when current version is draft
- GET /api/v1/schemes/{scheme_id}/draft/structure -> 200 when current version is draft
- GET /api/v1/schemes/{scheme_id}/draft/validation -> 200 when current version is draft
- GET /api/v1/schemes/{scheme_id}/draft/compare-preview -> 200 when current version is draft
- GET /api/v1/schemes/{scheme_id}/draft/seats/records/{seat_record_id} -> 200
- GET /api/v1/schemes/{scheme_id}/draft/sectors/records/{sector_record_id} -> 200
- GET /api/v1/schemes/{scheme_id}/draft/groups/records/{group_record_id} -> 200
- PATCH /api/v1/schemes/{scheme_id}/draft/seats/records/{seat_record_id} with unknown sector_id -> 422
- POST /api/v1/schemes/{scheme_id}/draft/seats/bulk with unknown group_id -> 422
- POST /api/v1/schemes/{scheme_id}/draft/remap/preview with unknown target group -> 422
- POST /api/v1/schemes/{scheme_id}/draft/sectors duplicate sector_id -> 422
- POST /api/v1/schemes/{scheme_id}/draft/groups duplicate group_id -> 422
Validate:
- stale expected_scheme_version_id returns 409 on guarded draft endpoints
- duplicate/reference failures return typed detail payloads
- successful read endpoints stay stable after failed mutations
## 8. Draft mutations
## 7. Draft publish preview / readiness
- POST /api/v1/schemes/{scheme_id}/draft/sectors -> 200 or typed 422 conflict
- POST /api/v1/schemes/{scheme_id}/draft/groups -> 200 or typed 422 conflict
- PATCH /api/v1/schemes/{scheme_id}/draft/seats/records/{seat_record_id} -> 200 or typed 422 validation error
- POST /api/v1/schemes/{scheme_id}/draft/seats/bulk -> 200 or typed 422 validation error
- PATCH /api/v1/schemes/{scheme_id}/draft/sectors/records/{sector_record_id} -> 200
- PATCH /api/v1/schemes/{scheme_id}/draft/groups/records/{group_record_id} -> 200
- POST /api/v1/schemes/{scheme_id}/draft/repair-references -> 200
- POST /api/v1/schemes/{scheme_id}/draft/remap/preview -> 200 or typed 422 validation error
- POST /api/v1/schemes/{scheme_id}/draft/remap/apply -> 200 or typed 422 validation error
## 9. Publish preview / readiness
- GET /api/v1/schemes/{scheme_id}/publish/validation -> 200
- GET /api/v1/schemes/{scheme_id}/draft/publish-readiness -> 200 when current version is draft
- POST /api/v1/schemes/{scheme_id}/draft/pricing/snapshot -> 200 when scheme is in draft
- GET /api/v1/schemes/{scheme_id}/draft/publish-preview?refresh=true -> 200
- GET /api/v1/schemes/{scheme_id}/draft/publish-preview -> 200
- GET /api/v1/schemes/{scheme_id}/draft/publish-preview?refresh=true&baseline_scheme_version_id={published_version_id} -> 200
- GET /api/v1/schemes/{scheme_id}/draft/publish-readiness -> 200
- GET /api/v1/schemes/{scheme_id}/draft/publish-readiness?expected_scheme_version_id={current_version_id} -> 200
- GET /api/v1/schemes/{scheme_id}/draft/publish-readiness?expected_scheme_version_id=deadbeef... -> 409
Validate:
- refresh and cached read both succeed
- preview summary contains is_publishable / has_structure_changes / has_artifacts / snapshot_available
- pricing_coverage is internally consistent
- baseline override returns override strategy when explicit baseline is provided
- preview retention does not grow unbounded for same version+variant
- readiness returns validation_summary, pricing_coverage, snapshot, readiness flags
## 10. Publish lifecycle
## 8. Publish / version lifecycle
- POST /api/v1/schemes/{scheme_id}/publish -> 200 when draft is ready
- POST /api/v1/schemes/{scheme_id}/publish with stale expected_scheme_version_id -> 409
- POST /api/v1/schemes/{scheme_id}/unpublish -> 200
- POST /api/v1/schemes/{scheme_id}/rollback -> 200
- POST /api/v1/schemes/{scheme_id}/versions?expected_current_scheme_version_id=deadbeef... -> 409
- POST /api/v1/schemes/{scheme_id}/publish?expected_scheme_version_id=deadbeef... -> 409
- POST /api/v1/schemes/{scheme_id}/publish?expected_scheme_version_id={current_version_id} -> 200 when environment is ready
Validate:
- stale protection returns typed 409 payload
- successful publish returns scheme_id, scheme_version_id, status, current_version_number, published_at, pricing_snapshot, validation_summary
- after publish, current scheme status is published
- audit contains scheme.published event for the same scheme_version_id
## 9. Admin / ops
## 11. Admin / ops
- GET /api/v1/admin/schemes/{scheme_id}/current/artifacts -> 200
- GET /api/v1/admin/schemes/{scheme_id}/current/validation -> 200
- GET /api/v1/admin/artifacts/publish-preview/audit -> 200
- POST /api/v1/admin/artifacts/publish-preview/cleanup?dry_run=true -> 200
Optional:
- POST /api/v1/admin/schemes/{scheme_id}/current/display/regenerate?mode=passthrough -> 200
- POST /api/v1/admin/display/backfill?mode=passthrough&limit=10&only_missing=true -> 200
Validate:
- audit endpoint does not report orphan files or missing files for DB rows in normal state
- validation report is readable and deterministic
- admin routes do not produce 500 for healthy scheme state
## 10. Audit trail
## 12. Audit trail
- GET /api/v1/schemes/{scheme_id}/audit -> 200
Validate:
- recent publish preview / pricing / version events are present when corresponding operations were run
- audit total is non-negative
- event payloads stay JSON-serializable
## 13. Fail criteria
## 11. Fail criteria
Regression is considered failed if any of the following happen:
- health or db ping fails
Regression is considered failed if:
- any stable read endpoint returns 500
- passthrough display endpoint fails on known-good sample
- publish preview refresh or cached read returns 500
- pricing bundle contract changes unexpectedly
- admin audit/cleanup endpoints fail on healthy environment
- artifact retention grows without bound for repeated preview refresh on same variant
- publish readiness says ready but guarded publish fails for non-stale reasons
## 12. Operator note
Run this checklist after:
- schema changes
- pricing schema/repository refactors
- artifact lifecycle changes
- display pipeline changes
- route reorganization
- startup/import/config changes
- publish lifecycle changes
- published current version cannot be converted to draft through ensure flow
- draft editor summary/read endpoints return inconsistent data
- publish-state mutation guard is bypassed