feat(orders): kanonisk statusmaskin + guardad DB-constraint (ADR-0002, C3)
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
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
This commit is contained in:
@@ -0,0 +1,61 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user