This is an internal working record, not an everyday instruction. It was written while the system was being rebuilt, for whoever maintains it. If you are here to do today's work, use the everyday documents instead: Procedures · Processes · Runbooks · The working day, step by step
MK Physical Scale — Current Four-Flow Matrix — 2026-08-10¶
- Status:
CURRENT SOURCE-RECONCILED FLOW MATRIX / RUNTIME AND PHYSICAL ACCEPTANCE REQUIRED - Task:
CTC-CDOC-003 - Source ref:
master@8981a02f7b2a2fa256a7365d6921f3d7636f1fe2 - Process:
PROC-YMS-SCALE-TICKET-EXECUTION-MK - Effects:
NONE
1. Flow matrix¶
| Flow | Direction | Order owner | Check-in | Check-out | Entry link | Current source notes |
|---|---|---|---|---|---|---|
PURCHASE |
inbound | MK Inbound Purchase | GROSS |
TARE |
T_TRANSLOAD.SCALE_TICKET_ID |
Check-in can aggregate item Gross; Check-out derives Tare aggregate from items; Purchase finalize remains separate |
DOORTRADE |
inbound/local | MK Inbound Purchase | GROSS |
TARE |
T_TRANSLOAD.SCALE_TICKET_ID |
Same stage direction as Purchase; downstream branch/finalize remains separate |
SALES |
outbound/local | MK Outbound Sales | TARE |
GROSS |
T_EQUIPMENT_LOAD.SCALE_TICKET_ID |
Check-in preserves submitted Tare; Check-out derives Gross aggregate from items |
EXPORT |
outbound/ocean | MK Outbound Sales / Booking | TARE |
GROSS |
T_EQUIPMENT_LOAD.SCALE_TICKET_ID |
Check-in preserves submitted Tare; Check-out does not synthesize Gross from commodity items in current server route |
OTHER/Walk-In remains a UI fallback and is not one of the four accepted integrated command flows.
2. End-to-end command matrix¶
| Stage | UI responsibility | API | Transaction owner | Record/state guard | Persisted result | Separate next outcome |
|---|---|---|---|---|---|---|
| Check-in | choose flow/order/context, supply entry reading and items | POST /api/yms/scale/check-in/execute |
one apiRouteRunLegacyWrite() request |
flow valid; items valid; tenant/menu; existing ticket lineage | order/items + entry ticket stage + order-ticket link | none implied |
| Check-out | reopen active ticket/order, supply exit reading and current items | POST /api/yms/scale/check-out/execute |
one apiRouteRunLegacyWrite() request |
exact order-ticket bridge before mutation; valid exit stage | order/items + exit ticket stage | Purchase finalize or later outbound process remains separate |
| Reweigh | correct entry stage before exit | PATCH /api/yms/scale/check-in |
one request | active ticket; stage state; changed values; reason; CAS | same ticket updated + correction event | no physical reversal implied |
| Void/Reversal | retire ticket when allowed | DELETE /api/yms/scale/tickets/{id} |
one request | tenant/active ticket; reason; downstream execution guard | soft-delete/event/link cleanup as allowed | physical movement and downstream effects are not undone |
| Readback | reload stable record and event history | GET /tickets/{id}, GET /tickets/{id}/events |
read-only | tenant + active predicates | authoritative current ticket/event view | classify unknown result before retry |
Legacy routes remain present:
POST /api/yms/scale/check-in
PATCH /api/yms/scale/check-in
POST /api/yms/scale/check-out
Their continued existence is compatibility surface, not permission to bypass the integrated normal path or its order-ticket relationship guard.
3. Stage semantics¶
| Semantic | Persisted/current meaning | Must not be interpreted as |
|---|---|---|
GROSS |
one accepted ticket stage with timestamp + axle weights | automatically “check-in” for every flow |
TARE |
one accepted ticket stage with timestamp + axle weights | automatically “check-out” for every flow |
NET |
order/item/business derived weight, validated as Gross - Tare where applicable |
a third physical Scale stage |
| Check-in | first stage selected by flow policy | truck physically verified solely because DB write exists |
| Check-out | second stage selected by flow policy | receipt/outbound close/packing/delivery complete |
| Reweigh | same-ticket stage correction with lineage | a new unrelated ticket |
| Reversal | system lineage compensation when guarded/authorized | undo of physical movement |
4. Direction matrix¶
PURCHASE inbound : GROSS -> TARE
DOORTRADE inbound : GROSS -> TARE
SALES outbound : TARE -> GROSS
EXPORT outbound : TARE -> GROSS
The current browser schema and current server flow selector agree on this matrix.
5. Weight-source matrix¶
| Flow/stage | Current numeric source | Current concern |
|---|---|---|
| Purchase Check-in Gross | server aggregate of item GROSS_WEIGHT into ticket Gross steering axle |
assumes item Gross is the intended ticket reading; physical provenance not established |
| Doortrade Check-in Gross | same inbound aggregation behavior | same |
| Sales Check-in Tare | submitted SCALE_TICKET Tare payload |
must be physically/operator validated; no accepted device adapter |
| Export Check-in Tare | submitted SCALE_TICKET Tare payload |
same |
| Purchase/Doortrade Check-out Tare | server aggregate of item Tare into ticket Tare steering axle | relationship/readback still requires Runtime evidence |
| Sales Check-out Gross | server aggregate of item Gross into ticket Gross steering axle | downstream close remains separate |
| Export Check-out Gross | submitted ticket Gross remains material; server skips item-derived exit aggregation for Export | exact Product/field policy requires evidence |
6. Unit matrix¶
| Surface | Current source behavior | Status |
|---|---|---|
| Scale live display | lb |
source fact |
| ticket event input/canonical/display UOM | LB |
source fact |
| ticket axle values | integer normalization | source fact |
| order-item UOM | persisted separately on item | source fact |
| KG -> LB or other conversion in Scale ticket path | no accepted conversion found | OPEN / EVIDENCE REQUIRED |
| physical device unit/provenance | no accepted adapter found | OPEN / PHYSICAL EVIDENCE REQUIRED |
Do not infer that an order-item UOM conversion has occurred merely because a Scale ticket is stored in LB.
7. Record and state guard matrix¶
| Guard | Current source result | Failure/recovery |
|---|---|---|
| Tenant | ticket/order/link queries are tenant scoped | reject/not found; do not substitute another tenant record |
| Menu/module | YMS Scale routes require yms.scale and scale-portal |
access evidence still role-specific |
| Flow | integrated commands accept Purchase/Doortrade/Sales/Export | invalid flow rejected before write |
| Commodity/items | at least one item; current validation on IDs/quantity and non-Export weights | fix input; no fabricated commodity |
| Existing ticket | existing linked active ticket can route to same-ticket update | reread lineage before retry |
| Check-out bridge | inbound uses T_TRANSLOAD; outbound uses T_EQUIPMENT_LOAD |
foreign/mismatched ticket rejected before order Save |
| Stage order | second stage requires first stage | reconcile ticket before retry |
| Correction | reason + CAS snapshot | stale concurrent edit fails; reread |
| Reversal | reason + downstream guard | stop when downstream execution exists |
| Soft delete | active-row predicates | deleted ticket not normal active work |
8. Same-ticket versus new-ticket matrix¶
| Situation | Current disposition |
|---|---|
| no active linked ticket for intended order | create new ticket number/ticket and link |
| active existing ticket resolved for order | reuse ticket identity and route to Check-in update |
| identical repeated completed stage | existing result may be returned |
| changed first stage before Check-out | same ticket, reasoned reweigh/correction |
| changed already-completed stage not eligible for correction | reject |
| timeout with unknown result | reread; do not assume either new ticket or no ticket |
| intentionally separate physical movement/business transaction | requires new authoritative business/ticket context; do not fabricate by retry |
9. Response-loss matrix¶
| Observation after timeout | Classification | Action |
|---|---|---|
| no order/ticket/link change | likely not committed | retry only after exact readback |
| order/items + entry ticket + link present | Check-in committed | do not replay; continue from current ticket |
| exit stage present | Check-out committed | do not replay Scale Out; inspect downstream owner status |
| ticket present but order/link mismatch | conflict | stop and escalate/reconcile |
| correction/reversal event present | compensation committed | do not repeat compensation |
| result cannot be classified | UNKNOWN |
no blind retry |
No durable request token was found for Scale integrated commands.
10. Correction/reversal and physical non-implications¶
A successful system correction/reversal can change ticket lineage and links. It does not establish that:
- a truck crossed the physical scale again;
- the original reading was erased from reality;
- a gate movement was reversed;
- inventory/receipt/shipping effects were compensated;
- printed paper was recalled;
- a device was recalibrated.
Every physical correction requires a separately observed physical procedure and policy.
11. Stale validation/smoke references¶
| Historical/current document claim | Current source status |
|---|---|
Check-in all-flow GROSS |
retired as stale |
| Sales/Export first stage conflict remains in source | closed in current source |
/check-out/execute absent |
retired as stale |
smoke expecting /check-out/execute conflicts with source |
retired as stale for current ref |
| current static contract preserves all-flow Gross | retired; current static test expects inbound Gross/outbound Tare |
| old sequential pre-save Check-out is the only normal path | stale for current integrated path |
Static tests describe source structure only. Runtime smoke results from another revision/environment are historical evidence unless the exact current revision/environment is established.
12. Evidence still required¶
The four-flow evidence set must eventually prove, without being run by this task:
Purchase : Gross-in -> Tare-out
Doortrade : Gross-in -> Tare-out
Sales : Tare-in -> Gross-out
Export : Tare-in -> Gross-out
For each flow capture:
- target role and tenant;
- exact order and ticket stable IDs;
- before-state;
- submitted physical reading and unit/provenance;
- API result;
- ticket/detail/event reread;
- order-ticket bridge reread;
- Gross/Tare/Net values;
- board state;
- downstream status separately;
- timeout/retry case;
- correction/reversal case where authorized;
- cleanup/recovery plan in non-Production evidence environments.
Current result is SOURCE-RECONCILED, not Runtime/physical acceptance.
---¶
Source:
docs/processes/MK_PHYSICAL_SCALE_CURRENT_FLOW_MATRIX_2026-08-10.md— ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.