At a Glance
Persona: Inventory Controller · Module: spot-check · Workflow stages: create → pending → in_progress → completed (+ void) · Key permissions: create / assign / monitor, flag recount, override variance, submit (fires rollup), void
What this persona does: Owns the spot-check exercise end-to-end — defines sampling, assigns the Counter, reviews variance, and submits to fire the adjustment rollup.
Inventory Controller — the single owner of the spot-check exercise: defines selection criteria (method = random / high_value / manual, size of the sample), schedules and launches the spot check, assigns the Counter, monitors progress, reviews variances, approves or rejects recount requests, and triggers the variance rollup to inventory-adjustment. Authority anchor for SPC_AUTH_001.
The Inventory Controller is the single owner of the spot-check exercise — the only persona who can create spot checks, configure method and size, assign counters, flag recounts, submit, and void. Rows are derived from Section 3 (Primary Actions) of this file; rule citations refer to spot-check/02-business-rules § 4 / § 5.
| Action | pending |
in_progress |
completed |
void |
|---|---|---|---|---|
| Create spot check (random / high_value / manual) | ✅ (SPC_VAL_001–SPC_VAL_003) |
— | — | — |
| Assign counter to spot check | ✅ (SPC_AUTH_001) |
✅ | ❌ | ❌ |
| Monitor progress (lines counted vs total) | ✅ | ✅ (SPC_CALC_004) |
✅ (read-only) | ✅ (read-only) |
| Flag line for recount (variance breach) | — | ✅ (SPC_VAL_006) |
❌ | ❌ |
| Override / accept variance (countersignature) | — | ✅ (SPC_AUTH_001) |
❌ | ❌ |
Submit spot check (in_progress → completed) |
— | ✅ (SPC_AUTH_001; SPC_VAL_004 — all lines counted; SPC_POST_001 rollup fires) |
— | — |
| Void spot check | ✅ (SPC_VAL_008) |
✅ (SPC_VAL_008) |
❌ (SPC_VAL_007 — terminal) |
— |
| Route rollup adjustment for approval | — | — | ✅ — to Approver / Finance via inventory-adjustment | — |
| Edit lines after completion | — | — | ❌ (SPC_VAL_007 — immutable; raise manual adjustment per SPC_POST_004) |
— |
tb_spot_check for an inventory or consignment location.tb_spot_check documents owned by the controller (pending / in_progress).| Action | State precondition | State effect | Notes |
|---|---|---|---|
| Open spot check (random sampling) | Location is inventory- or consignment-type per SPC_VAL_001 |
New tb_spot_check in pending; method = random; system samples size distinct products |
Per SPC_VAL_002–SPC_VAL_003. |
| Open spot check (high-value sampling) | Same | New tb_spot_check in pending; method = high_value; top-size products by value / velocity sampled |
Per SPC_VAL_003. |
| Open spot check (manual selection) | Same | New tb_spot_check in pending; method = manual; controller adds tb_spot_check_detail rows explicitly |
Manual is the event-driven path (suspected discrepancy, incident). |
| Assign counter | Spot check in pending |
Counter location-grant recorded | Per SPC_AUTH_001. |
| Monitor progress | Spot check in in_progress |
(read) lines with actual_qty populated vs total |
No persisted progress counters on tb_spot_check — derived per SPC_CALC_004. |
| Flag line for recount | Variance breaches tolerance per SPC_VAL_006 |
Detail-comment with recount tag | Recount ideally by a different counter to remove bias. |
| Override / accept variance | SPC_VAL_006 flag exists |
Flag cleared; line eligible for rollup | Controller countersignature recorded in detail-comment thread. |
| Submit spot check | All detail lines have actual_qty; no open recount flags |
doc_status = completed; rollup adjustment created |
Per SPC_POST_001–SPC_POST_002. |
| Void spot check | Status is pending or in_progress |
doc_status = void; no rollup |
Per SPC_VAL_008; partial entries preserved. |
|diff_qty| / on_hand_qty exceeds threshold, the controller can (a) trigger recount (different counter), (b) override / accept the variance with countersignature, (c) hold the line pending investigation.TODO: Source the exact UI for sampling method selection, recount flagging, override countersignature, and rollup-trigger button from
../carmen-inventory-frontend/.
| Trigger | Handoff to | Artefact |
|---|---|---|
| Submit spot check | System → inventory-adjustment rollup | tb_spot_check.doc_status = completed; tb_stock_in / tb_stock_out created with info.spotCheckId. |
| Route rollup adjustment for approval | Audit / Config (Approver / Finance) per ADJ_AUTH_* |
Rollup tb_stock_in / tb_stock_out in in_progress. |
| Void | (terminal) | tb_spot_check.doc_status = void. |
../carmen-inventory-frontend/ — Inventory Controller UI screens.../carmen-inventory-frontend-e2e/tests/ — no spot-check spec currently exists.SPC_AUTH_001, SPC_VAL_*, SPC_POST_*), physical-count/03-user-flow-count-lead (full-count counterpart owner path — same persona acting with a wider scope), inventory-adjustment/03-user-flow-inventory-controller (rollup-side flow, same persona acting as adjustment owner).