At a Glance
Module: spot-check · Personas: Inventory Controller · Counter · Audit / Config
Workflow lifecycle: Pending → In Progress → Completed (variance rollup to inventory-adjustment) with Void branch
Drill into per-persona views below for action-level detail
This page is the overview entry point for the user-flow set of the spot-check module. Unlike physical-count's three-tier period / document / detail exercise, a spot check is a two-tier ad-hoc check — one tb_spot_check header per (location, time-window) pairing with a method (random / high_value / manual) and size, plus tb_spot_check_detail rows holding per-product on_hand_qty (book snapshot) / actual_qty (counted) / diff_qty (variance). The work moves quickly along this hierarchy: Inventory Controller opens the spot check, the system (or the controller, for method = manual) samples size items, assigns a Counter; the Counter walks the location and enters physical quantities line by line; the Inventory Controller inspects variance, triggers recounts, approves completion; the rollup then writes a variance adjustment to inventory-adjustment which is the path to the inventory ledger.
Section 2 below describes the document lifecycle state machine for tb_spot_check.doc_status (pending → in_progress → completed, plus the void cancel path), independent of who acts. Each per-persona file (linked from Section 3) describes that persona's path through this state space — entry point, available actions, decision branches, handoff that ends their involvement. Section 4 then summarises the cross-persona handoffs that stitch the individual paths together (Inventory Controller → Counter for assignment; Counter → Inventory Controller for completed-sheet sign-off; Inventory Controller → Approver/Finance for variance-adjustment approval via inventory-adjustment).
TODO: Source the canonical UI screens / wizard flows from
../carmen-inventory-frontend/once aspot-checkroute is discoverable; cross-reference E2E specs at../carmen-inventory-frontend-e2e/tests/once added (nospot-checkspec exists as of this writing). No carmen/docs source folder exists for this module.
Document-level state machine (enum_spot_check_status):
enum_spot_check_status)| From state | Action | To state | Allowed for | Pre-conditions |
|---|---|---|---|---|
(none) |
create tb_spot_check for (location, method, size) |
pending |
Inventory Controller | Location is inventory- or consignment-type per SPC_VAL_001; method and size set per SPC_VAL_002. Sample generated per SPC_VAL_003 (random / high_value) or empty for manual. on_hand_qty snapshot captured per line. |
pending |
counter enters first actual_qty |
in_progress |
Counter | Counter has location-grant for the spot check per SPC_AUTH_004. |
in_progress |
edit actual_qty / add detail comments |
in_progress |
Counter (own lines) | Lines within counter's location-grant. |
in_progress |
flag variance line for recount | in_progress |
Inventory Controller | Variance breach per SPC_VAL_006. Triggers recount sub-flow. |
in_progress |
submit (all lines counted) | completed |
Inventory Controller | All detail lines have non-null actual_qty per SPC_VAL_004; all recount flags resolved. Fires variance rollup per SPC_POST_001. |
pending |
cancel before counting starts | void |
Inventory Controller | Allowed per SPC_VAL_008; no rollup triggered. |
in_progress |
cancel mid-count | void |
Inventory Controller | Allowed per SPC_VAL_008; no rollup triggered; partial entries preserved in audit log. |
completed |
view / report / audit | completed |
All personas (per scope) | Terminal. Immutable per SPC_VAL_007. |
void |
view / audit | void |
All personas (per scope) | Terminal alternative. No ledger effect. |
The in_progress → completed transition on tb_spot_check is the rollup event. Per SPC_POST_001 / SPC_POST_002:
diff_qty > 0 group into one or more tb_stock_in documents under reason SPOT_CHECK_OVERAGE (or aliased COUNT_OVERAGE).diff_qty < 0 group into one or more tb_stock_out documents under reason SPOT_CHECK_SHORTAGE (or aliased COUNT_SHORTAGE).diff_qty = 0 produce no rollup row.info.spotCheckId = <tb_spot_check.id> for the back-join.TODO: Document the rollup-document-numbering convention (whether one rollup per spot check, one per reason, or one per line) when frontend logic is confirmed. Confirm reason-code naming.
Each file describes one persona group's path through the lifecycle above. The three groups collapse from the source personas in spot-check § 4:
method, size), schedules and launches spot checks, assigns Counters, monitors progress, reviews variances, approves or rejects recount requests, approves adjustments for posting.| From persona | Trigger | To persona | Handoff artefact |
|---|---|---|---|
| Inventory Controller | Generates spot check + assigns counter | Counter | tb_spot_check in pending; counter location-grant. |
| Counter | Completes assigned lines | Inventory Controller | tb_spot_check_detail lines all have non-null actual_qty. |
| Inventory Controller | Flags variance line for recount | Counter (ideally different from original counter) | Detail-comment with recount-required tag. |
| Inventory Controller | Submits the spot check | System → rollup → inventory-adjustment | tb_spot_check.doc_status = completed; rollup tb_stock_in / tb_stock_out created. |
| Inventory Controller | Routes rollup adjustment for approval | Audit / Config (Approver / Finance via adjustment side) | tb_stock_in / tb_stock_out in in_progress. |
| Approver / Finance (on adjustment side) | Approves rollup adjustment | System → inventory ledger | tb_stock_in / tb_stock_out in completed; tb_inventory_transaction written. |
| Auditor | Reviews completed spot checks + posted adjustments | (read-only — terminal) | Full chain readable: spot-check sheet, recount records, approvals, posted adjustments, journal entries. |
TODO: Diagram these handoffs once Mermaid / sequence-diagram convention is established for the wiki. Cross-link to inventory-adjustment/03-user-flow for the rollup-side flow.
../carmen-inventory-frontend/ — UI flow source.../carmen-inventory-frontend-e2e/tests/ — no spot-check spec currently exists.