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
- test scheme exists

## Environment

Use these variables in shell:

export API_URL="http://127.0.0.1:9020"
export API_KEY="admin-local-dev-key"
export SCHEME_ID="82086336d385427f9d56244f9e1dd772"

## 1. Health / system

- GET /healthz -> 200
- GET /api/v1/ping -> 200
- GET /api/v1/db/ping -> 200
- GET /api/v1/manifest -> 200

## 2. 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

## 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

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

Validate:
- pricing bundle contains categories and rules arrays
- effective seat price resolves according to domain priority
- test seat preview explains selectable / has_price state
- pricing write responses are stable and typed
- stale pricing mutation returns `detail.code = stale_draft_version`

## 6. Draft publish preview

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

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

## 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

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