docs/BUILD-PLAN.md

# Build Plan

The roadmap agreed at project kickoff. Each step is committed separately so the app can be deployed and used at any point in the sequence.

| # | Step | Status |
| - | ---- | ------ |
| 1 | Repo scaffold, Dockerfile, Prisma schema, auth (admin email/password, operator PIN, 12h session) | **done** |
| 2 | Admin CRUD: Machines, Operation Templates, Projects → Assemblies → Parts, file uploads | **done** |
| 3 | Operation authoring (template or ad-hoc) + QR token generation | **done** |
| 4 | Operator scan flow: claim → start → units/notes → QC prompt → close | **done** |
| 5 | PDF generation: per-operation card + per-part cover sheet | **done** |
| 6 | Fasteners + PO (PDF + lifecycle: draft → sent → partial → received) | **done** |
| 7 | Admin dashboard (WIP, overdue, plan-vs-actual hours by machine/operator) + audit log viewer | **done** |
| 8 | In-browser STEP viewer + server-side thumbnails | **done** |
| 9 | QC records (inline checkboxes + dedicated QC op type + fail-handling workflow) | **done** |
| 10 | OpenAPI docs at `/api/docs`, nightly SQLite backup script | planned |

## Post-kickoff additions

Items that came out of floor-testing, not in the original roadmap.

### Landed

| Step | What | Status |
| ---- | ---- | ------ |
| A1 | File attachments on Assembly (STEP / drawing / cut) — shared across all parts in the assembly | **done** |
| A2 | Quick-link files on operator scan card (drawing + cut tap-targets; STEP rendered inline instead of downloaded) | **done** |
| A3 | Total quantity to produce (`assembly.qty × part.qty`) shown on scan card, traveler cover, op cards | **done** |
| A4 | Part + assembly drawing PDFs inlined into the traveler output (cover → assembly drawing → part drawing → op cards) | **done** |
| A5 | Partial-completion state (`partial` status + cumulative `unitsCompleted` counter); `claim` accepts pending OR partial; `release` → partial when units>0 | **done** |
| A6 | 3D STEP viewer embedded on operator scan card + admin assembly page (shared `StepViewerPanel`, load-on-tap) | **done** |
| A7 | "Done" button auto-detects partial: if typed units < remaining, step ends `partial` and releases claim instead of locking `completed` | **done** |
| A8 | QC fail workflow: `kind="qc"` dedicated inspection steps + `qc_failed` status blocks reclaim until admin hits qc-reset (landed together with Step 9) | **done** |

### Planned

| Step | What | Notes |
| ---- | ---- | ----- |
| B1 | Operator `/op` dashboard lists **resumable** ops (`status = "partial"` with no current claim) | Needed because A5+A7 mean partial ops become unclaimed — they currently only re-surface when someone physically re-scans the card |
| B2 | Progress column on traveler cover + op cards (`X of Y done`) driven by `unitsCompleted` | Makes paper reflect reality when a traveler is re-printed mid-run |
| ~~B3~~ | ~~QC fail workflow on close~~ | Landed as A8 alongside Step 9 — `qc_failed` locks the step; admin `qc-reset` rolls it back to `pending`/`partial` based on `unitsCompleted` |

Hours-by-machine / plan-vs-actual reporting is already scoped in Step 7. Fresh-testing findings are tracked ad-hoc.

## Locked design decisions

- **Hierarchy:** Project → Assembly → Part → Operation.
- **QR granularity:** one QR per Operation; each step prints its own card.
- **Claim model:** an Operation locks to one operator on Start; other scans of an in-progress operation show a read-only view noting who holds it. `partial` ops are unclaimed and resumable by any operator.
- **Operators can hold multiple operations at once** (across different parts).
- **Purchase orders:** PDF generation + lifecycle states (`draft → sent → partial → received → cancelled`).
- **No offline mode.** The app assumes the shop LAN is up.
- **Language:** English only in the UI.
- **Persistence:** SQLite in a single mounted `/data` volume; migrations via Prisma.
- **Integrations:** none for now; REST API is versioned (`/api/v1/*`) and fully documented for future use.