feat(backend): add publish readiness contract and pricing diagnostics
add backend readiness contract for publish prechecks add pricing diagnostics to explain publish-blocking conditions make publish decisions more explicit and easier to debug for clients
This commit is contained in:
greebo
@@ -56,6 +56,7 @@
|
||||
|
||||
## app/api/routes/publish.py
|
||||
- POST /api/v1/schemes/{scheme_id}/draft/pricing/snapshot
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/publish-readiness
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/publish-preview
|
||||
- POST /api/v1/schemes/{scheme_id}/draft/remap/preview
|
||||
- POST /api/v1/schemes/{scheme_id}/draft/remap/apply
|
||||
@@ -63,10 +64,6 @@
|
||||
## app/api/routes/editor.py
|
||||
- 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/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}
|
||||
- POST /api/v1/schemes/{scheme_id}/draft/sectors
|
||||
- POST /api/v1/schemes/{scheme_id}/draft/groups
|
||||
- DELETE /api/v1/schemes/{scheme_id}/draft/sectors/records/{sector_record_id}
|
||||
@@ -76,6 +73,10 @@
|
||||
- PATCH /api/v1/schemes/{scheme_id}/draft/sectors/records/{sector_record_id}
|
||||
- PATCH /api/v1/schemes/{scheme_id}/draft/groups/records/{group_record_id}
|
||||
- POST /api/v1/schemes/{scheme_id}/draft/repair-references
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/validation
|
||||
- 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}
|
||||
|
||||
## app/api/routes/admin.py
|
||||
- GET /api/v1/admin/schemes/{scheme_id}/current/artifacts
|
||||
@@ -89,6 +90,3 @@
|
||||
- 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.
|
||||
|
||||
## app/api/routes/publish.py
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/publish-readiness
|
||||
|
||||
@@ -31,67 +31,35 @@ 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 / write contract
|
||||
## 5. Pricing read model
|
||||
|
||||
- GET /api/v1/schemes/{scheme_id}/pricing -> 200
|
||||
- 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}/current/seats/{seat_id}/price -> 200 for priced seat
|
||||
- GET /api/v1/schemes/{scheme_id}/test/seats/{seat_id} -> 200 for known seat
|
||||
- POST /api/v1/schemes/{scheme_id}/pricing/categories?expected_scheme_version_id={draft_version_id} -> 200 for valid draft
|
||||
- POST /api/v1/schemes/{scheme_id}/pricing/categories?expected_scheme_version_id=deadbeef... -> 409 for stale draft
|
||||
- GET /api/v1/schemes/{scheme_id}/test/seats/{seat_id} -> 200 for known priced and unpriced seats
|
||||
|
||||
Validate:
|
||||
- pricing bundle contains categories and rules arrays
|
||||
- effective seat price resolves according to domain priority
|
||||
- test seat preview explains selectable / has_price state and returns reason_code / reason_message
|
||||
- pricing write responses are stable and typed
|
||||
- stale pricing mutation returns `detail.code = stale_draft_version`
|
||||
## 6. Draft publish / readiness
|
||||
|
||||
## 6. Draft publish preview
|
||||
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/validation -> 200
|
||||
- GET /api/v1/schemes/{scheme_id}/publish/validation -> 200
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/publish-readiness -> 200
|
||||
- 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
|
||||
|
||||
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
|
||||
- POST /api/v1/schemes/{scheme_id}/publish?expected_scheme_version_id=deadbeef... -> 409 typed stale conflict
|
||||
|
||||
## 7. Admin / ops
|
||||
|
||||
@@ -100,25 +68,7 @@ Validate:
|
||||
- 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
|
||||
|
||||
## 8. 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
|
||||
|
||||
## 9. Fail criteria
|
||||
## 8. Fail criteria
|
||||
|
||||
Regression is considered failed if any of the following happen:
|
||||
|
||||
@@ -126,56 +76,6 @@ Regression is considered failed if any of the following happen:
|
||||
- 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
|
||||
- pricing write contract regresses or stops returning typed payloads
|
||||
- stale draft guard stops returning 409 on pricing mutations
|
||||
- admin audit/cleanup endpoints fail on healthy environment
|
||||
- artifact retention grows without bound for repeated preview refresh on same variant
|
||||
|
||||
## 10. Operator note
|
||||
|
||||
Run this checklist after:
|
||||
- schema changes
|
||||
- pricing schema/repository refactors
|
||||
- artifact lifecycle changes
|
||||
- display pipeline changes
|
||||
- route reorganization
|
||||
- startup/import/config changes
|
||||
|
||||
|
||||
## 3.1. Draft editor read model
|
||||
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/structure -> 200 when current version is draft
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/seats/records/{seat_record_id} -> 200 for known seat record
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/sectors/records/{sector_record_id} -> 200 for known sector record
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/groups/records/{group_record_id} -> 200 for known group record
|
||||
|
||||
Validate:
|
||||
- returned record belongs to current draft scheme_version_id
|
||||
- single-entity endpoints match items visible in draft structure
|
||||
- missing draft record returns 404, not 500
|
||||
|
||||
|
||||
Additional draft read-side stale checks:
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/structure?expected_scheme_version_id={current_version_id} -> 200
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/compare-preview?expected_scheme_version_id={current_version_id} -> 200
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/seats/records/{seat_record_id}?expected_scheme_version_id={current_version_id} -> 200
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/sectors/records/{sector_record_id}?expected_scheme_version_id={current_version_id} -> 200
|
||||
- GET /api/v1/schemes/{scheme_id}/draft/groups/records/{group_record_id}?expected_scheme_version_id={current_version_id} -> 200
|
||||
- same endpoints with stale expected_scheme_version_id -> 409
|
||||
|
||||
|
||||
## 11. Typed error contract
|
||||
|
||||
Validate representative failures return JSON detail objects with:
|
||||
- code
|
||||
- message
|
||||
|
||||
Recommended checks:
|
||||
- stale_draft_version -> 409
|
||||
- stale_current_version -> 409
|
||||
- duplicate_sector_id / duplicate_group_id -> 422
|
||||
- unknown_sector_id / unknown_group_id -> 422
|
||||
- invalid_amount -> 422
|
||||
- publish_validation_failed -> 409
|
||||
|
||||
- readiness endpoint contract breaks unexpectedly
|
||||
- pricing diagnostics endpoints fail on healthy environment
|
||||
- publish stale guard is not typed and deterministic
|
||||
|
||||
Reference in New Issue
Block a user