Files
0pt/docs/adr/ADR-0002-kanonisk-orderstatus.md
T
admin c3582838aa
CI (SIAX Cloud) / integration (push) Skipped
CI (SIAX Cloud) / sonar (push) Skipped
masterplan-lock / check (push) Successful in 1m3s
CI (SIAX Cloud) / security (push) Successful in 1m4s
Security Scan (SIAX Cloud) / security (push) Successful in 1m7s
CI (SIAX Cloud) / quality (push) Successful in 1m52s
CI (SIAX Cloud) / sonar (pull_request) Skipped
masterplan-lock / check (pull_request) Successful in 6s
CI (SIAX Cloud) / security (pull_request) Successful in 18s
Security Scan (SIAX Cloud) / security (pull_request) Successful in 19s
CI (SIAX Cloud) / quality (pull_request) Successful in 1m20s
CI (SIAX Cloud) / integration (pull_request) Successful in 1m58s
feat(orders): kanonisk statusmaskin + guardad DB-constraint (ADR-0002, C3)
2026-09-29 21:15:35 +02:00

3.3 KiB

ADR-0002 — Kanonisk orderstatus: kodnivå-union + guardad DB-constraint

Status: Accepted Date: 2026-09-29 Owners: 0pt (simon@siax.io) Related requirements: C3 (kanonisera orderstatus), DoD §17 (backup-städ), §33 (migreringsordning), §35 (restore-drill) Related artifacts: lib/order-flow.ts (ORDER_STATUSES, OrderStatus, isKnownOrderStatus, nextOrderStatus), sql/015_order_status_check.sql

Context

orders.status är fri text (sql/001_init.sql line ~92: status text NOT NULL DEFAULT 'draft'). Flödet draft→quoted→in_production→review→accepted→delivered är känt i kod, men DB:n nekar inga andra värden — fri text har redan orsakat minst en missvisande "klar"-visning i ordkön (okänd status renderades som "done/klar" utan att ordern faktiskt levererats).

Prod-harvest ej körbar i session (2026-09-29): ingen DATABASE_URL/POSTGRES_URL för 0pt finns i Infisical (varken default-env eller /0pt-sökvägar — körningen injicerade 246 secrets utan order-DB-URL). Statusfördelningen i prod är därför okänd här; migreringen är guardad och manuell.

Existing implementations

  • lib/order-flow.ts — NEXT_STATUS-flödet, resolveAdvanceAction, buildOrderInboxItem.
  • app/admin/page.tsx + app/api/orders/route.ts konsumerar flödet.
  • tests/order-flow.test.ts behandlar cancelled som terminal read_only-status.

Decision

  1. Kodnivå-union är SSOT: type OrderStatus = de sex flödesstatusarna + cancelled (används i tests som terminal status — därmed med, trots utebliven harvest). ORDER_STATUSES är den utömmande listan; isKnownOrderStatus() klassar fri text fail-closed. NEXT_STATUS/resolveAdvanceAction/ buildOrderInboxItem konsumerar unionen via nextOrderStatus() — okänd status ger alltid read_only / ingen inbox-post, aldrig påhittat nästa steg.
  2. DB guardas — inte typ-migreras: sql/015_order_status_check.sql lägger CHECK (status IN (...)) NOT VALID (fas A, kort lås, nekar vid dirt-data via DO-preflight) och VALIDATE CONSTRAINT i separat session (fas B, SHARE UPDATE EXCLUSIVE + lock_timeout='5s'). KÖRS EJ mot prod i sessionen — Simon kör efter harvest-rapport och backup (pg_dump -t orders före fas A).

Alternativ avvisade

  • Fortsatt fri text — redan orsakat missvisande "klar"; ingen möjlighet att fela tidigt vid skrivning.
  • Omedelbar NOT VALID utan harvest — risk för prod-block: NOT VALID validerar inte befintliga rader, men VALIDATE-fasen (och varje ny UPDATE) krockar med okända statusar; utan känd statusfördelning är fas B en lotteri.
  • Postgres enum-typ — kräver typmigrering av kolumnen (ALTER TYPE-lås, ADD VALUE kan ej ske i transaktion i äldre PG), tyngre drift än en CHECK som kan utökas med en rad kod + en rullande migrering.

Consequences

  • Ny status = en rad i ORDER_STATUSES/NEXT_STATUS + en uppföljningsmigrering som lägger till värdet i CHECK:en (drop+add NOT VALID, validate igen).
  • Rader med okänd status (om harvest hittar sådana) mappas i en EGEN, granskad migrering före fas A — preflighten nekar annars körning (fail-closed).
  • SQL-listan och kodlistan är dubbelbokning; testen i tests/order-flow.test.ts låser att alla ORDER_STATUSES har definierat beteende (nästa steg eller read_only).