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** |
| A9 | Progress + live status on traveler cover + op cards (`X of Y done` driven by `unitsCompleted`, status pill matching the UI) — reprints reflect reality | **done** |
| A10 | Operator `/op` dashboard lists **resumable** ops (`status = "partial"` with no current claim) so any operator can pick up where the last shift left off (landed as B1) | **done** |
| A11 | Part + Assembly duplication — clone into the same parent with a new code. Operations get fresh QR tokens and reset to pending; file attachments are re-referenced (content-addressed) | **done** |
| A12 | QC history view on the part detail page — cross-operation log of every QCRecord (pass/fail, operator, notes, measurements) | **done** |
| A13 | Admin TimeLog correction — per-op "Logs" modal lets admins edit startedAt / endedAt / unitsProcessed / note on a stale entry (or delete it outright). Audited as `correct_timelog` / `delete_timelog` | **done** |
| A14 | Bulk project travelers PDF — one megafile for every part in a project (or just the ones with outstanding ops). Prefixed with a project-level summary sheet | **done** |

### Planned

| Step | What | Notes |
| ---- | ---- | ----- |
| ~~B1~~ | ~~Operator `/op` dashboard lists **resumable** ops~~ | Landed as A10 — second section on `/op` with amber border, shows `unitsCompleted / total · remaining`, tap to scan |
| ~~B2~~ | ~~Progress column on traveler cover + op cards~~ | Landed as A9 — cover sublines + op-card "Progress" meta row + live status pill on both |
| ~~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.