Odoo-Modules/fusion_plating/docs/superpowers/specs/2026-06-03-box-tracking-sticker-redesign-design.md

# Box-Level Tracking + Job Sticker Redesign — Design Spec

Date: 2026-06-03
Status: Approved (brainstormed with client), implementation in progress.

## Summary

Two coupled deliverables:

1. **Job sticker redesign** (thermal-label-friendly, 6×4 in / 152×102 mm):
   - **Internal Job Sticker → Layout A** (stacked: identity band + full-width
     instructions), printed **one per job**.
   - **External Job Sticker → Layout B** (left identity rail + tall instructions
     column), printed **one per box**, carrying the **box identity** (BOX n/N)
     and a **per-box QR**. Shows the **factory logo** (`env.company.logo`).
2. **Box-level tracking**: a new `fp.box` registry, one record per received box,
   auto-created at receiving, with a status workflow and per-box scannable QR.

## Decisions (locked with client)

| Q | Decision |
|---|---|
| Label size | Keep 6×4 in (152×102 mm). |
| Redesign goals | Readability/scan-speed + thermal print quality (no grey fills — solid-black bands + knockout white text; thick rules; bold sans). |
| Masking on label | **MASK badge** (on/off flag) when `sale.order.line.x_fc_masking_enabled` is true. No detail text. |
| Baking on label | **BAKE block** showing `sale.order.line.x_fc_bake_instructions` text, only when present. Also a BAKE flag for at-a-glance. |
| Notes source | Internal = `x_fc_internal_description`; External = SO line `name` (customer-facing). |
| Long notes | Notes-dominant zone, **length-tiered font shrink** to keep to **one label**, clip with "…see traveller" only in the extreme. |
| Factory logo | On **External only** (header), from `env.company.logo` → `logo_web` → company partner image. Internal stays clean. Thermal caveat: prefer a mono/high-contrast logo. |
| Box tracking depth | **Box registry** — per-box record, status, scannable QR. (Not box-contents.) |
| Internal copies | **One per job.** |
| External copies | **One per box.** |
| Box QR | **Per-box** — encodes `/fp/box/<id>`. |

## Label layouts (approved mockups)

Both labels: outer 0.9 mm border, `overflow:hidden` single-page guard, dynamic
blocks render only when their field has content.

**Layout A (Internal, per job):** full-width stacked rows —
`[logo | WO# band + INTERNAL tag | QR]` → `Part# + MASK/BAKE flags` →
one-line field strip `Customer · PO · Qty · Due · Thk` → `BAKE` block →
`NOTES` (full width, `x_fc_internal_description`, length-tiered, bottom padding).

**Layout B (External, per box):** absolute two-column —
- Left rail (50 mm): `logo` → black band `WORK ORDER <wo> | BOX n / N` →
  `MASK/BAKE` flags → per-box QR → `Part#` → `Customer` → `PO/Qty` → `Due/Thk`.
- Right column: `BAKE` block → `NOTES` (customer description, length-tiered).
- Full-height divider (rail `border-right`). CUSTOMER copy.

Reference mockups (Chrome-rendered, true 6×4):
`~/Downloads/fusion_sticker_concepts/Sticker-A-Internal-LongNotes.*`,
`Sticker-B-External.*`. Final proof renders through entech wkhtmltopdf.

## `fp.box` model (fusion_plating_receiving)

| Field | Type | Notes |
|---|---|---|
| `name` | Char | Sequence, e.g. `BOX/<wo-or-recv>/01`. |
| `box_number` | Integer | n (1..N). |
| `box_count` | Integer | N (related/snapshot of receiving `box_count_in`). |
| `receiving_id` | M2O `fp.receiving` | Origin. ondelete cascade. |
| `sale_order_id` | M2O `sale.order` | Related from receiving. |
| `job_id` | M2O `fp.job` | Resolved (single-job SO = that job; multi-job = first/SO-level, see edge cases). |
| `partner_id` | M2O `res.partner` | Related (customer). |
| `state` | Selection | `received → racked → in_process → packed → shipped` (+ `lost`/`cancelled`). |
| `qr` | Binary/compute | Encodes `<base_url>/fp/box/<id>`. |
| `location_note` | Char | Optional free text "where is it now". |
| `scan_event_ids` | (phase 2) | Per-scan log — deferred. |

Constraints: `(receiving_id, box_number)` unique. Append-only-ish; state advances.

## Auto-create at receiving

When `fp.receiving.box_count_in = N` is set and the receiving is confirmed
(state hook — reuse the existing box-count chatter point at
`fp_receiving.py:~1191`), create/sync N `fp.box` rows (1..N), linked to the
receiving + resolved job. **Idempotent**: changing N adds/removes trailing rows
(never renumbers existing tracked boxes). Manager can regenerate.

## Scanning

- Controller route `/fp/box/<int:box_id>` → resolves the box, shows its job /
  status, allows advancing state (received→…→shipped). Tie into the existing
  shopfloor scan wedge (`request.env.user` attribution — no `tablet_tech_id`).
- **Reconciliation**: helper flags a receiving/job whose boxes haven't all
  reached `shipped` (so none are lost — matches the "ship back in the same
  boxes" Sub-8 rule).

## Label binding

- **External job sticker** (`fusion_plating_jobs.report_fp_job_sticker_template`):
  iterate the job's `fp.box` records → **one label per box** (Layout B), each
  with its `box_number/box_count` + per-box QR (`/fp/box/<id>`). Replaces the
  current `range(box_count_in)` loop in `report_fp_wo_sticker_inner`. When a job
  has no `fp.box` rows yet, fall back to a single label (BOX 1/1).
- **Internal job sticker** (`report_fp_job_sticker_internal_template`): **one per
  job** (Layout A), job QR (`/fp/job/<id>`), no box loop.
- Shared inner keeps the 100-label hard safety cap (defense-in-depth from the
  WO-30072 OOM fix).

## UI

- Boxes list + kanban (group by `state`) under **Operations**; form with state
  buttons + scan QR.
- Smart buttons: box count on `fp.receiving` and `fp.job` forms.

## Module placement

- Model + auto-create + views/menu/ACL → `fusion_plating_receiving`.
- Scan controller → `fusion_plating_receiving` (or shopfloor).
- Label templates → `fusion_plating_jobs` (job stickers) + shared inner in
  `fusion_plating_reports`.

## Edge cases / open

- **Multi-job SO** (one SO line → multiple jobs via serial/thickness grouping):
  boxes are physical (per shipment/receiving). MVP links a box to the SO's
  primary job; the external sticker prints the SO's boxes. Revisit if a real
  multi-job-per-box case appears.
- **Box ↔ part for multi-part SO**: out of MVP (registry, not contents).
- Per-box qty/contents = future "registry + contents" upgrade.

## Deploy / verify

entech (LXC 111 / pve-worker5), `-u fusion_plating_receiving fusion_plating_jobs
fusion_plating_reports` with the revert-on-failure guard. Verify: render both
stickers for a real job through wkhtmltopdf; confirm auto-create on a test
receiving; scan a box id.