svg-backend/backend/docs/smoke-regression.md

Smoke regression checklist

This file is the backend manual regression baseline for svg-service.

Preconditions

• docker compose stack is up
• backend responds on port 9020
• valid admin API key is available
• stable SVG fixture exists in repository, e.g. sample-contract.svg

Environment

Use these variables in shell:

export API_URL="http://127.0.0.1:9020" export API_KEY="admin-local-dev-key" export FIXTURE_SVG_PATH="/home/adminko/svg-service/sample-contract.svg"

Main scripts

Primary operator regressions:

• backend/scripts/smoke_core.sh
• backend/scripts/smoke_pricing_publish.sh
• backend/scripts/smoke_regression.sh
• backend/scripts/editor_mutation_regression.sh

The scripts are expected to fail fast on any contract break or unexpected 5xx.

smoke_regression.sh is now an orchestration wrapper:

• first runs smoke_core.sh
• then runs smoke_pricing_publish.sh
• returns non-zero if either scenario fails

Scenario split

Core smoke on clean DB

Use:

• backend/scripts/smoke_core.sh

This scenario is designed for a fully clean database.

It uploads a fresh SVG fixture, resolves the created scheme_id, validates current/draft read models, validates empty pricing state, and then runs editor_mutation_regression.sh on the same fresh scheme.

Important:

• it does not require pre-existing scheme_id
• it does not require pricing categories or price rules
• it does not require publish snapshot or published baseline
• empty pricing on a fresh upload is a valid state, not a failure

Pricing/publish smoke with fixture setup

Use:

• backend/scripts/smoke_pricing_publish.sh

This scenario also uploads a fresh SVG fixture, then prepares its own pricing fixture before validating pricing and publish flow.

Important:

• it creates its own pricing category
• it creates its own pricing rule
• it intentionally checks both a priced seat and an unpriced seat on the same fresh scheme
• it does not rely on historical pricing IDs, rules, or old schemes

1. Health / system

• GET /healthz -> 200 (smoke uses a bounded retry/wait loop and fails explicitly if the API never becomes ready)
• GET /api/v1/ping -> 200
• GET /api/v1/db/ping -> 200
• GET /api/v1/manifest -> 200

2. Core smoke coverage

smoke_core.sh checks:

• GET /healthz -> 200
• GET /api/v1/ping -> 200
• GET /api/v1/db/ping -> 200
• GET /api/v1/manifest -> 200
• POST /api/v1/schemes/upload -> 200
• GET /api/v1/schemes -> 200 and resolves the fresh scheme_id
• GET /api/v1/schemes/{scheme_id} -> 200
• GET /api/v1/schemes/{scheme_id}/versions -> 200
• GET /api/v1/schemes/{scheme_id}/current -> 200
• GET /api/v1/schemes/{scheme_id}/editor/context -> 200
• POST /api/v1/schemes/{scheme_id}/draft/ensure -> 200
• GET /api/v1/schemes/{scheme_id}/draft/summary -> 200
• 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 draft entities by record id -> 200
• stale expected_scheme_version_id conflict -> 409 with typed stale_draft_version
• GET current sectors/groups/seats -> 200
• GET current SVG display meta -> 200
• GET pricing bundle -> 200 with empty categories/rules
• GET pricing coverage -> 200 with zero priced seats
• GET pricing explain/{seat_id} -> 200 with no_price_rule
• GET pricing rules diagnostics -> 200 with empty state
• GET audit -> 200
• backend/scripts/editor_mutation_regression.sh on the same fresh scheme

Validate:

• fresh upload is readable immediately through current/draft/editor endpoints
• empty pricing is accepted as normal state for a newly uploaded scheme
• no endpoint in core smoke returns 500

3. Pricing/publish smoke coverage

smoke_pricing_publish.sh checks:

• POST /api/v1/schemes/upload -> 200
• GET current / POST draft ensure on the fresh scheme -> 200
• POST pricing category -> 200
• POST price rule -> 200
• GET pricing bundle -> 200 with created fixture data
• GET pricing coverage -> 200 with both priced and unpriced seats present
• GET pricing explain/{priced_seat_id} -> 200 with matched rule
• GET pricing explain/{unpriced_seat_id} -> 200 with no_price_rule
• GET current/seats/{priced_seat_id}/price -> 200
• GET test/seats/{priced_seat_id} -> 200
• GET test/seats/{unpriced_seat_id} -> 200
• POST draft/pricing/snapshot -> 200
• GET draft/publish-readiness -> 200
• GET draft/publish-preview?refresh=true -> 200
• GET draft/publish-preview -> 200
• POST publish -> 200
• GET scheme detail/current after publish -> 200 and published state
• GET audit -> 200 and contains scheme.published

Validate:

• fixture setup is fully self-contained
• priced-seat checks happen only after explicit pricing fixture creation
• publish flow is validated on a fresh scheme, not on historical DB data

4. Legacy endpoint families

The sections below remain the API baseline by area, but regression execution is now split between clean-DB core smoke and pricing/publish smoke.

5. Scheme registry

• GET /api/v1/schemes -> 200
• GET /api/v1/schemes/{scheme_id} -> 200
• 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

6. Editor entry flow

• GET /api/v1/schemes/{scheme_id}/editor/context -> 200
• POST /api/v1/schemes/{scheme_id}/draft/ensure -> 200

Validate:

• editor context returns current_scheme_version_id
• editor context distinguishes draft vs published state correctly
• ensure endpoint is idempotent on current draft
• ensure endpoint creates a new draft from published current when needed
• returned scheme_version_id is reusable as expected_scheme_version_id

7. Draft read model

Using current draft version id from draft/ensure:

• GET /api/v1/schemes/{scheme_id}/draft/summary?expected_scheme_version_id={draft_version_id} -> 200
• GET /api/v1/schemes/{scheme_id}/draft/structure?expected_scheme_version_id={draft_version_id} -> 200
• GET /api/v1/schemes/{scheme_id}/draft/validation?expected_scheme_version_id={draft_version_id} -> 200
• GET /api/v1/schemes/{scheme_id}/draft/compare-preview?expected_scheme_version_id={draft_version_id} -> 200

Validate:

• summary returns total_seats / total_sectors / total_groups
• summary returns validation_summary / structure_diff_summary / publish_readiness
• structure returns lists for seats / sectors / groups
• validation is deterministic
• compare preview returns stable diff structure
• stale expected_scheme_version_id returns typed 409 conflict

8. Draft entity reads

• 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

Validate:

• record endpoints return exact draft entities
• unknown record id returns 404
• stale expected_scheme_version_id returns typed 409 conflict

9. 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

10. 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

11. 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}/pricing/rules/diagnostics -> 200
• GET /api/v1/schemes/{scheme_id}/current/seats/{seat_id}/price -> 200 only after pricing fixture exists
• GET /api/v1/schemes/{scheme_id}/test/seats/{seat_id} -> 200 for known seat

Validate:

• fresh clean upload is allowed to have categories=[] and rules=[]
• fresh clean upload is allowed to have zero priced seats and no_price_rule explanations
• priced seat checks belong to pricing/publish smoke after fixture setup
• diagnostics returns stable empty state with zero rules on clean upload
• diagnostics returns matched seat visibility after fixture setup
• priced test seat amount is serialized as string when pricing exists

12. Draft mutation regression

Use:

• backend/scripts/editor_mutation_regression.sh

This script checks:

• create sector
• create group
• patch seat
• bulk seat update
• patch sector
• patch group
• duplicate entity validation paths
• stale draft conflict
• remap preview validation path
• repair references
• delete created sector/group
• post-mutation read-model consistency

Validate:

• created entities are returned by API
• patched draft records are actually changed
• bulk update changes persisted fields
• duplicate ids return 422
• stale expected_scheme_version_id returns typed 409
• remap preview without filters returns typed 422
• post-mutation summary / validation / compare-preview remain readable and deterministic

13. Draft publish preview

• 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

14. Publish readiness and publish flow

For current draft version:

• GET /api/v1/schemes/{scheme_id}/draft/publish-readiness -> 200
• POST /api/v1/schemes/{scheme_id}/publish?expected_scheme_version_id={draft_version_id} -> 200 or 409

Validate:

• readiness explicitly shows snapshot_available and pricing gate state
• publish with stale expected version returns typed 409
• publish without draft state returns typed 409
• publish success updates current status to published
• audit trail contains scheme.published event

15. 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
• GET /api/v1/admin/schemes/{scheme_id}/pricing/categories/cleanup-preview -> 200
• POST /api/v1/admin/schemes/{scheme_id}/pricing/categories/cleanup with dry_run=true -> 200

Validate:

• artifact audit does not report orphan files or missing files for DB rows in normal state
• validation report is readable and deterministic
• pricing cleanup preview returns matched candidates and safe_to_delete_count
• pricing cleanup dry-run returns deleted_count=0
• idempotent cleanup is valid in both states: matched_total=0 with would_delete_count=0, or matched_total>0 with would_delete_count>0
• smoke does not require cleanup dry-run to always find something to delete
• admin routes do not produce 500 for healthy scheme state

16. Audit trail

• GET /api/v1/schemes/{scheme_id}/audit -> 200

Validate:

• recent publish preview / pricing / version / publish events are present when corresponding operations were run
• audit total is non-negative
• event payloads stay JSON-serializable

17. Fail criteria

Regression is considered failed if any of the following happen:

• health or db ping fails
• any stable read endpoint returns 500
• passthrough display endpoint fails on known-good sample
• publish preview refresh or cached read returns 500
• publish readiness returns 500
• editor context or draft ensure returns 500
• draft summary / structure / validation / compare-preview returns 500
• editor mutation regression returns non-zero exit code
• clean upload empty pricing state is treated as a failure
• pricing bundle or diagnostics contract changes unexpectedly
• admin audit/cleanup endpoints fail on healthy environment
• pricing cleanup dry-run mutates data
• artifact retention grows without bound for repeated preview refresh on same variant

18. Operator note

Run this checklist after:

• schema changes
• pricing schema/repository refactors
• artifact lifecycle changes
• display pipeline changes
• route reorganization
• startup/import/config changes
• draft lifecycle changes
• publish readiness changes
• admin cleanup changes
• editor mutation changes