# Cold-chain operations workbench delivery proposal

## 1. Purpose, users and scope

Operations staff need to act on undelivered overdue orders and trace the underlying evidence. Hub leads need service-stratified metrics. Security staff need dependable session and export controls. Phase one delivers a read-only workbench, metrics API, order timeline and controlled export design. Refunds, dispatch writes, customer notifications and employee rankings are excluded.

R1: filter by hub, service and cohort, prioritizing overdue_open. R2: open complete order evidence with the review cutoff; future events cannot alter a historical metric. R3: exclude cancelled and not-mature orders from the mature denominator. R4: show stratified rates and sample limitations. R5: enforce role, hub and session permissions on the server. R6: provide loading, no-results, errors, freshness and recovery states.

## 2. Information structure and interaction

Start with cutoff, mature count, late count and open overdue count, followed by hub rates and the order queue. Combine the three filters with AND. Keep the result count and displayed orders in sync. Expand an order to show created, picked_up, delivered or cancelled events, including whether an event is later than the cutoff. No matches displays a clear message and a reset action.

The completed reference workbench supports all 216 orders and their full timelines. For production integration, prevent duplicate requests during loading; update the last-success timestamp on completion. On 503, retain the last successful version with a visible error. On session expiry, clear sensitive views and return to corporate login. The reference interaction does not implement a production identity service or export permission system; those are acceptance items below.

## 3. Architecture and data flow

Feed A/B → schema validation and conflict quarantine → immutable canonical event store → order view aggregated at as_of → intranet read-only API → workbench. The orders master supplies route and due_at; visible events determine status. Store dataset_version, ingested_at and source_line for reconciliation and replay. A failed incoming batch must not replace the previous reconciled snapshot.

The corporate identity service issues sessions. The gateway validates sessions and each API checks role plus hub scope. A requested hub is not authorization. Operators access only assigned hubs. Supervisors and batch-scoped service accounts can export within their grants. No application password store is added. Export audit records request_id, user, scope, rows, bytes and dataset_version, without secrets.

## 4. API contract

GET /v1/orders?hub=&service=&cohort=&as_of=&cursor=&limit=50 returns items, next_cursor, total, as_of, dataset_version and updated_at. Limit is 1–100. Use a stable server cursor and the same snapshot for a page sequence to avoid missing or duplicate orders. Invalid filters return 400; a valid empty query returns 200 with an empty items list.

GET /v1/orders/{order_id}/events?as_of= returns ordered events and visible_at_cutoff. Check access before returning content. Missing orders return 404 and forbidden access returns 403. GET /v1/metrics returns mature and late counts, hub/service strata and insufficient-sample states for the same snapshot.

POST /v1/exports requires supervisor or service permission. The body includes scope, as_of, dataset_version and request_key. Accept a job with 202 and job_id, then authorize the completed download against the same scope. Operators receive 403. Deduplicate request_key on the server and audit each export batch.

Errors are 400 for input, 401 for missing/expired session, 403 for permission, 404 for absent resources, 409 for snapshot mismatch, 429 for throttling and 503 for source failure. Include request_id and a safe explanation without credentials.

## 5. Acceptance and traceability

R1: Harbour + express + overdue_open shows one matching order, O0058, and resetting restores 216. R2: every timeline matches the canonical records and future delivery does not alter the historical cohort. R3: 216 = 12 cancelled + 7 not_mature + 107 on_time + 80 delivered_late + 10 overdue_open, with mature 197 and late 90. R4: Southbay express n=4 requires more data and has no standardized hub value; check 5/15-point boundaries. R5: operator export 403, expired session 401 and authorized supervisor export 202; selecting another hub still returns 403 for an operator. R6: test empty results, loading, 503 retained snapshots, 429 retry and successful recovery timestamps.

requirements-traceability.csv links every requirement to an API and a test. Reference UI and algorithm checks verify the learning output. Production permissions, network failures, pagination and load acceptance require the integrated backend; a working static page is not that evidence.

## 6. Effort and milestones

| Workstream | Person-hours | Acceptance gate |
| --- | --- | --- |
| Requirements, metric rules and interaction design | 16 | R1–R6, identity and source contracts agreed |
| Ingestion, aggregation and snapshots | 28 | Reconciliation, replay and future-event tests |
| Frontend and accessibility | 24 | Filters, timelines, empty results and keyboard use |
| API, permissions and export audit | 24 | Session, scope and export checks |
| Identity/gateway integration and release readiness | 16 | Client interfaces, rollback and monitoring |
| Integration, security and user acceptance tests | 24 | All requirements pass and findings are resolved |
| Runbook and handover | 8 | Operations and recovery rehearsal |
| Total | 140 | Dependent on access and approvals |

Plan one engineer at 35 delivery hours per week for four working weeks. Week 1: design 16 + data 19. Week 2: data 9 + frontend 24 + API 2. Week 3: API 22 + integration 13. Week 4: integration 3 + testing 24 + handover 8. Each week totals 35, and the workstreams total 140. Client approval and access waiting time are outside this effort. Delayed security review moves calendar milestones rather than removing tests. Capacity and skills are planning assumptions to confirm, not an agreed production launch or price.

## 7. Operations, support and rollback

Monitor quarantine rates, snapshot age, API errors, access denials and export volumes. Support tickets include hub impact, request_id, data version and reproduction steps. A technical duty owner triages access failures and an operations owner confirms business impact. Support hours, response targets, retention and charges require agreement before launch.

Rollback reads to the last reconciled snapshot while retaining source and quarantine records. Retain access checks even if an API version is reverted. After recovery, recompute the 197/90 controls for the reference snapshot, compare versions and obtain operations sign-off. Rehearse backup and restore before release.

## 8. Dependencies and decisions

The client provides identity protocols, role/hub grants, gateway access, source interfaces and retention requirements. Confirm concurrency, arrival delay, refresh interval, export limits, audit retention and support coverage in week one. Record-based acceptance here does not establish production traffic capacity or an improvement in actual fulfilment outcomes.