POC 4 Step 1: order workflow data layer + state machine

[Dev-Ray-Hunt]

What this builds

Step 1 of POC 4 (per pocs/poc4_order_workflow/NEXT.md): the pure data layer and state machine. No DST files, no network, runs fully in the cloud.

Files added under pocs/poc4_order_workflow/src/

Module	Purpose
schema.py	SQL DDL for all 7 tables, annotated for PostgreSQL migration
database.py	SQLite connection factory with FK enforcement + WAL mode
models.py	Dataclasses for all entities (Customer, Approver, Logo, ColorUp, Order, OrderLineItem, StatusHistory)
state_machine.py	13-state enum + explicit transition map + transition() / bulk_transition() + audit log writer
crud.py	CRUD for all entities; JSON encode/decode helpers
match_key.py	find_approved_color_up(), cascade_approval(), resolve_logo_for_line_item()
production.py	get_production_batches() + production_approve() (the production gate)
dst_stub.py	parse_dst() + open_color_up_editor() stub interface; both raise DSTNotAvailableError

Schema highlights

• orders has no status column — status lives on order_line_items.status per spec decision 1.
• Match key = (logo_id, style_number, color_code) exact — UNIQUE constraint on color_ups(logo_id, style_number, color_code, version).
• status_history is append-only; every transition() call writes an entry with actor, team_proxy flag, and timestamp.
• DST parse fields on logos are all nullable — populated only when POC 1 integration is wired locally.
• Written migration-ready for PostgreSQL (type-mapping comments inline in schema.py).

State machine (13 states)

New → Awaiting Logo ─┬─(exact match)──────────────────────────► Pending Production Approval
                     └─(no match)──► Color-Up In Progress ─► Internal Review ─► Needs Approver
                                                                                      │
                                                                               Sent for Approval
                                                                              ╱       │        ╲
                                                                        Approved  Phone Call  Revision In Progress
                                                                            │                      │
                                                              Pending Production Approval ◄──────── (loops back via
                                                                            │                       Color-Up In Progress)
                                                                     Production Ready
                                                                            │
                                                                       In Production → Complete

Approval cascade

cascade_approval(db, colorup_id, actor):

1. Marks the color-up Approved.
2. Finds all line items referencing it in Sent for Approval or Phone Call.
3. Advances each through Approved → Pending Production Approval and logs both transitions.
4. Returns the list of advanced line item IDs.

Does not cross customers (each color-up FK-chains to one logo → one customer). Needs Approver line items are deliberately excluded — they were never sent to the customer.

Production batch query

Groups Production Ready line items with Approved color-ups by (customer_id, logo_id, placement, thread_sequence_canonical). Thread sequences are normalised with sort_keys=True so key-insertion-order differences don't create phantom splits.

Review fixes applied

Two issues found in review and fixed on this branch:

1. Cascade bug — Needs Approver was previously in the cascade set, but the state machine forbids Needs Approver → Approved, so cascading such an item raised InvalidTransitionError mid-loop. It is now excluded; a regression test covers it.
2. Production-approval gate — added the Pending Production Approval state. Cleared items (customer-approved and exact-match repeats alike) now stop at the gate and require production_approve() to reach Production Ready; nothing skips straight to runnable.

Test results

67 passed

Tests cover: all state transitions + invalid-transition guards (incl. the now-mandatory production gate), full happy-path / revision / phone-call workflows, CRUD round-trips, FK enforcement, match-key exact-match semantics, approval cascade (incl. the Needs-Approver exclusion), the production gate, production batch grouping, and the DST stub contract.

What is stubbed / skipped and why

Feature	Status	Reason
DST parse (POC 1)	Stubbed — DSTNotAvailableError	DSTs are local-only; cloud sandbox has none
Color-up editor (POC 3)	Stubbed — DSTNotAvailableError	POC 3 is local-only
FastAPI web layer	Not started	Step 2 scope
CSV/paste mass-import	Not started	Step 2 scope
Email / reminders	Not started	Step 5 scope
Trim-sheet render	Not started	Step 6 scope

Stubbed/skipped DST work is expected, not a failure (per brief and CLOUD_AGENTS.md).

Known follow-up

The production gate is currently one-directional (Pending Production Approval → Production Ready). No production-rejection path yet — that transition is deferred until the rejection behaviour is decided.

Branch

Created from claude/poc4-foundation (which carries the spec). Target: main. Do not merge.