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.tskonsumerar flödet.tests/order-flow.test.tsbehandlarcancelledsom terminal read_only-status.
Decision
- 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 vianextOrderStatus()— okänd status ger alltid read_only / ingen inbox-post, aldrig påhittat nästa steg. - DB guardas — inte typ-migreras:
sql/015_order_status_check.sqlläggerCHECK (status IN (...)) NOT VALID(fas A, kort lås, nekar vid dirt-data via DO-preflight) ochVALIDATE CONSTRAINTi 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 ordersfö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.tslåser att allaORDER_STATUSEShar definierat beteende (nästa steg eller read_only).