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 Source Reconciliation¶
- Status:
DETAILED SOURCE-RECONCILED PROCESS INPUT / OWNER REVIEW REQUIRED - Process:
PROC-YMS-SCALE-TICKET-EXECUTION-MK - Current contract:
MK_SCALE_TICKET_EXECUTION_WORKFLOW.md - Rebuild packet:
MK_PHYSICAL_SCALE_CAPABILITY_REBUILD_PACKET.md - Source authority:
MK_PHYSICAL_SCALE_SOURCE_AUTHORITY.md - Operating profile:
mk-order - Source baseline:
qa@4f6165bc4c53a7d98b0c246392dd9ed5bd75c21c - Effect boundary: documentation only
1. Reconciliation Result¶
The current Scale capability is no longer accurately described by the 2026-07-17 Process reconstruction in several important areas.
Current improvements confirmed¶
- Check-in now uses one integrated server write transaction for owner order/items, Scale ticket and ticket link.
- first-stage correction uses compare-and-swap and a required reason;
- correction, void and reversal write immutable
T_SCALE_TICKET_EVENTevidence; - Check-out requires the first stage and rejects changed completed-stage replay;
- reversal performs broad downstream-execution checks and rolls back when blocked;
- current physical-ticket print is tenant and active-row scoped;
- the browser timeout is 30 seconds, not 7 seconds;
- zero weight is currently rejected rather than enabled through the old numeric Client branch.
Current risks confirmed¶
- Check-out remains a multi-request composite with partial owner-save and downstream-child outcomes.
- no durable request token protects Check-in/Check-out from response-loss replay.
- YMS and BMS can still mutate the same ticket family through different contracts.
- no accepted physical-device adapter exists.
- empty-yard demo cards are inserted into the operational board.
- ticket-number generation still has concurrency risk.
- completed tickets leave the normal active board.
- most importantly, the current UI flow policy and integrated Check-in write path disagree for Sales/Export.
2. Reconciled Process Boundary¶
Scale owns:
physical-flow selection
+ accepted entry stage
+ accepted exit stage
+ ticket identity
+ stage timestamps/axle snapshots
+ ticket-to-business link
+ correction/void/reversal lineage
+ exact Scale readback
Scale does not own:
Commercial terms
Purchase/Outbound ordinary authoring
Purchase receipt finalize
Inventory Lot creation/correction
Inventory Allocation
Outbound close/status
Packing / Delivery
Billing
browser print as a durable effect
The Scale Portal can guide multiple owners, but the child results remain independent.
3. Reconciled Current Entry And Reads¶
3.1 Operator entry¶
Current normal entry:
Operations > Scale Portal
Current API entry requires:
- authenticated session/request context;
- enabled
yms.scalemodule; scale-portalmenu route for YMS Scale routes.
Exact role and action-level capability policy remains unaccepted.
3.2 Current reads¶
GET /api/yms/scale/schedule
GET /api/yms/scale/tickets
GET /api/yms/scale/tickets/{ticketId}
GET /api/yms/scale/tickets/{ticketId}/events
The schedule combines Purchase/Sales order context and ticket/link projections. The active-ticket read returns active rows with exactly one persisted stage. Exact detail and event timeline are available by known ticket ID.
3.3 Current flow inference¶
Flow can be inferred from:
- exact Order class/direction;
- Booking/container/order type;
- company presence;
- walk-in reference prefix;
- which stage exists.
This inference is compatibility behavior. Target commands carry an accepted typed flow and validate it against the linked record.
4. Reconciled Current Flow Matrix¶
The current UI is designed around:
| Flow | Check-in | Check-out | Related owner |
|---|---|---|---|
| Purchase | Gross | Tare | Inbound Purchase |
| Doortrade | Gross | Tare | Inbound Purchase |
| Sales | Tare | Gross | Outbound Sales |
| Export | Tare | Gross | Outbound Sales / Booking |
| Other/Walk-In fallback | Tare | Gross | Unapproved long-term owner |
The current integrated Check-in does not honor this matrix. It writes Gross for every accepted flow.
SCALE-REC-001 — blocking contradiction¶
Sales/Export UI:
entry = Tare
exit = Gross
Integrated Check-in:
entry write = Gross for all flows
Board/Check-out:
expects the flow-specific entry stage
This is not a documentation-only discrepancy. It is a current source contract contradiction and must be characterized with controlled Runtime evidence before any Scale writer migration or Process approval.
5. Reconciled Current Check-in¶
5.1 Current integrated command¶
POST /api/yms/scale/check-in/execute
Server steps¶
resolve tenant/actor
-> validate flow
-> validate every commodity line
-> validate Gross/Tare/Net arithmetic on item input
-> save or create owner Order and Items
-> create/update ticket entry stage
-> bind ticket to Purchase Transload or Sales Equipment Load
-> flush local sync tasks
-> commit
All steps inside the callback share one apiRouteRunLegacyWrite() DB transaction.
5.2 Current positive behavior¶
- existing Inbound/Outbound item ownership is reused;
- item and ticket validation occur before commit;
- a failure in the integrated callback rolls back the local callback work;
- server returns Order ID, Scale Ticket ID and ticket number;
- client refreshes after result.
5.3 Current limitations¶
- no durable request token;
- no accepted record version/freshness token;
- all-flow Gross stage contradiction;
- ticket number is not request-bound;
- client timeout can occur while server continues;
- exact post-commit ticket/order/link readback is not one explicit response contract;
- action-level role policy is absent;
- walk-in Product scope is unclear.
5.4 Safe current recovery¶
After timeout/error:
- search the exact order/reference/equipment;
- inspect exact ticket/detail;
- inspect Purchase Transload or Sales Equipment Load link;
- compare item and ticket values;
- classify
COMMITTED,ABSENTorCONFLICT; - retry only a proven absent command.
Do not rely only on the Schedule row or toast.
6. Reconciled Current Reweigh¶
Current entry-stage update supports:
same values
-> return existing result
changed values before exit
-> require correction reason
-> compare-and-swap full current stage snapshot
-> update stage
-> append REWEIGH_CORRECTION event
-> return ticket result
changed values after exit
-> reject
This is a strong target parity baseline, but the current API still lacks a durable business request token and separate semantic recovery capability.
The BMS generic PATCH does not enforce the same contract.
7. Reconciled Current Check-out¶
7.1 Current browser orchestration¶
For a linked order, the browser currently performs:
owner header update
-> each owner item update/add, sequentially
-> Scale Out
-> child owner handoff
Sales / Export child¶
Scale Out committed
-> separate Outbound update:
OUT_TIME = browser time
ORDER_STATUS = COMPLETED
Purchase / Doortrade child¶
Scale Out committed
-> exact ticket detail reload
-> user chooses branch
-> separate Purchase finalize transaction
7.2 Current transaction boundaries¶
| Boundary | Current transaction |
|---|---|
| each owner header/item API request | separate transaction |
| Scale Out API request | one ticket/link transaction |
| Outbound close | separate Outbound transaction |
| Purchase finalize | separate Inbound transaction |
| browser output only |
7.3 Current positive Scale Out behavior¶
- exact ticket ID required;
- first stage must exist with positive weight;
- current second stage cannot already contain different values;
- identical completed-stage replay returns existing result;
- stage update uses compare-and-swap;
- Gross/Tare total consistency is checked;
- linked owner ticket pointer is retained.
7.4 Partial-result states¶
owner header saved / item failed / Scale not attempted
owner header/items saved / Scale failed
Scale completed / Outbound close failed
Scale completed / Purchase finalize pending
Scale completed / Purchase finalize failed
Scale result unknown / owner rows committed
The target UI must expose these states explicitly.
7.5 Safe current recovery¶
Resume from the last confirmed boundary:
- owner Save incomplete: owner corrects/resumes; no Scale Out;
- owner Save complete and Scale absent: Scale Out only;
- Scale complete and Outbound close missing: Outbound close only;
- Scale complete and Purchase finalize missing: Purchase finalize only;
- unknown Scale result: exact ticket/link reread first.
8. Reconciled Current Purchase Handoff¶
Scale owns the completed ticket only.
Inbound Purchase owns:
- selected branch;
- item weight distribution/finalization;
- order
IN_TIME/OUT_TIMEticket projection; - Transload state;
- Inventory Lot materialization;
- branch navigation outcome;
- finalize recovery.
Current branch values:
WAREHOUSE_ONLY
DIRECT_OUTBOUND
MIXED
These values currently drive finalize/navigation behavior. They do not by themselves prove allocation or physical downstream completion.
Scale completed
!= Purchase finalized
!= Inventory Lot verified
!= allocated
9. Reconciled Current Outbound Handoff¶
Scale Out completion and Outbound close are separate.
Current browser invokes a later Outbound update to set:
OUT_TIME
ORDER_STATUS = COMPLETED
This update uses browser-generated time and can fail after the Scale ticket is committed.
Target must return independent results:
Scale Ticket: COMPLETED
Outbound Close: COMPLETED / FAILED / UNKNOWN / NOT_APPLICABLE
The operator must not repeat Scale Out to repair the Outbound child.
10. Reconciled Current Void / Reversal¶
YMS deletion is not an ordinary delete.
Current YMS behavior:
- require reason;
- conditionally soft-delete active ticket;
- reread ticket;
- reject when downstream execution exists;
- classify incomplete ticket as Void and completed ticket as Reversal;
- append immutable event;
- detach accepted Transload/Equipment Load ticket links;
- clear active Order ticket-number projections;
- commit or roll back all YMS work.
Current downstream checks include relevant:
- Transload state/timestamps/equipment/warehouse/final metrics;
- Orders linked by ticket number;
- Inventory Lots and Inventory Lot Ledger;
- Equipment Loads and Delivery/Transload use.
Competing BMS path¶
The BMS generic delete path uses a different contract and can detach only part of the relationship/evidence family. It does not provide the same reason/event/downstream guard.
Target policy must select one MK Scale reversal owner and retire or strictly separate the competing writer.
11. Reconciled Current Event Timeline¶
T_SCALE_TICKET_EVENT is append-only evidence for:
REWEIGH_CORRECTION
TICKET_VOID
TICKET_REVERSAL
It stores:
- ticket identity;
- affected stage;
- input/canonical/display units;
- before/after stage time;
- before/after axle values;
- reason;
- actor;
- request ID;
- event timestamp.
The event timeline is authoritative for correction/reversal provenance. It does not currently provide Check-in/Check-out idempotency.
12. Reconciled Current Print¶
Current physical-ticket output:
/frontend/pages/system/BMS/scale-ticket/scaleticket.php?IDS[]=<ticketId>
Current source applies:
- page role access;
- current tenant predicate;
- active-row predicate.
The previous missing-tenant/deleted warning is stale for current qa.
Print remains nondurable:
print rendered
!= printed successfully
!= ticket complete
!= owner process complete
The ORDER_ID Sales Weight Ticket is a separate document projection and must not be confused with physical Scale ticket ownership.
13. Reconciled Current Live Weight / Device Boundary¶
Current source proves only:
UI displays 00000 lb initially
manual entry is supported
It does not prove:
- physical hardware model;
- serial/TCP/HTTP protocol;
- device authentication;
- polling/stream transport;
- stable reading detection;
- reading session/identity;
- reconnect behavior;
- accepted-reading provenance;
- Production device operation.
Device integration remains a future/optional child capability until Product and field evidence establish it.
14. Reconciled State And Non-Implication Matrix¶
| Evidence | Proves | Does not prove |
|---|---|---|
| integrated Check-in response | local request returned ticket/order IDs | client did exact DB/detail readback or downstream completion |
| one accepted entry stage | vehicle/equipment entry stage recorded | Check-out or owner completion |
| two accepted stages | physical ticket completed | Purchase receipt/Outbound close/Packing/Delivery |
| correction event | a reasoned stage correction occurred | underlying owner rows were corrected |
| void/reversal event | YMS ticket lifecycle action occurred | every competing BMS/owner residual was repaired |
| completed ticket absent from open board | expected active-list behavior | ticket deleted or missing |
| physical print rendered | document projection opened | durable print/business acknowledgement |
| Purchase finalize result | Inbound owner committed its child | allocation or Outbound completion |
| Outbound close result | Outbound owner committed close fields | Delivery or Billing complete |
15. Reconciled Stable Errors¶
Use application errors rather than raw current strings:
SCALE_FLOW_INVALID
SCALE_STAGE_DIRECTION_CONFLICT
SCALE_ORDER_STALE
SCALE_ITEM_INVALID
SCALE_TICKET_STALE
SCALE_ENTRY_REQUIRED
SCALE_ENTRY_ALREADY_EXISTS
SCALE_EXIT_ALREADY_EXISTS
SCALE_REWEIGH_REASON_REQUIRED
SCALE_REWEIGH_AFTER_EXIT_FORBIDDEN
SCALE_WEIGHT_NEGATIVE
SCALE_WEIGHT_ZERO_FORBIDDEN
SCALE_TARE_EXCEEDS_GROSS
SCALE_REQUEST_DUPLICATE
SCALE_REQUEST_PAYLOAD_CONFLICT
SCALE_RESULT_UNKNOWN
SCALE_TICKET_NUMBER_CONFLICT
SCALE_DOWNSTREAM_LOCKED
SCALE_LINK_CONFLICT
SCALE_BMS_OWNER_CONFLICT
SCALE_DEVICE_UNAVAILABLE
SCALE_DATA_CONFLICT
Current message compatibility can be mapped at adapters while target UI consumes stable codes.
16. Target Process Shape¶
Identify flow and record
-> load accepted flow policy
-> verify owner snapshot
-> capture/accept entry reading
-> ExecuteScaleCheckIn
-> exact ticket/order/link readback
-> ENTRY_RECORDED
-> optional CorrectScaleEntryStage
-> owner PrepareScaleCheckOut
-> capture/accept exit reading
-> CompleteScaleCheckOut
-> exact completed ticket readback
-> explicit Purchase finalize or Outbound close result
-> downstream owner handoff
Target separates presentation from policy and repositories:
React
-> Next.js adapter
-> TypeScript Scale application/policy
-> typed repositories
-> MySQL first
17. Current Versus Target Disposition¶
| Current behavior | Target disposition |
|---|---|
| integrated local Check-in transaction | preserve, add typed flow, request token, version and exact readback |
| all-flow Gross Check-in | reject; replace with accepted flow policy |
| browser-sequential Check-out owner saves | replace with owner preparation contract or explicit per-child result |
| later Outbound close | preserve separate owner, expose result/recovery |
| later Purchase finalize | preserve separate owner, expose result/recovery |
| stage CAS | preserve as conditional repository write |
| immutable correction/reversal events | preserve and expose timeline |
MAX + 1 ticket number |
replace with request-bound atomic reservation |
| BMS generic writer | retire for MK YMS scope or strictly separate records/callers |
| static live-weight display | retain manual input; add device only through accepted adapter |
| interactive demo rows in empty board | remove from operational mode; explicit demo mode only |
| active-board-only completed visibility | add completed detail/timeline view |
| current physical-ticket print | preserve tenant/active scope as compatibility; later use target read adapter |
18. Owner Review Questions¶
Business and flow¶
- Is the accepted matrix Purchase/Doortrade Gross→Tare and Sales/Export Tare→Gross?
- Is
Other/Walk-Ina supported MK flow or demo/compatibility only? - Can a stage ever legitimately be zero?
- Which fields may be edited at Check-out?
Roles¶
- Which roles may view, Check-in, Check-out, reweigh, reverse, view events and print?
- Does reweigh/reversal require manager approval?
- May BMS users mutate MK YMS tickets?
Device¶
- Is real device integration required in the next migration or deferred?
- Which hardware/protocol/source exists?
- Is manual fallback required and how is it marked?
Recovery¶
- How long may an unknown request remain unresolved?
- Who owns ticket-number collision and link conflicts?
- What downstream states block reversal?
- How are residual conflicts repaired when BMS/YMS history diverges?
Migration¶
- Which tenant/cohort moves first?
- How is one-writer routing controlled and rolled back?
- When can BMS generic writers and PHP callers retire?
19. Verification Disposition¶
Existing source/static evidence supports:
- integrated Check-in transaction composition;
- current YMS stage/event/reversal code;
- current read and print predicates;
- current browser Check-out orchestration;
- existing Purchase-focused local smoke design.
Still required:
all four physical flows
Sales/Export stage contradiction
actual target roles/menu/API/record scope
concurrent/timeout/unknown result
BMS/YMS conflict fixtures
real device or explicit no-device decision
current Wiki content
field/operator acceptance
No Runtime, DB, device or Wiki test was performed in this documentation wave.
---¶
Source:
docs/processes/MK_PHYSICAL_SCALE_RECONCILIATION.md— ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.