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 Sequence And State Diagrams

• Status: CURRENT SOURCE-RECONCILED DIAGRAM INPUT / OWNER REVIEW REQUIRED
• Process: PROC-YMS-SCALE-TICKET-EXECUTION-MK
• Reconciliation: MK_PHYSICAL_SCALE_RECONCILIATION.md
• Policy: MK_PHYSICAL_SCALE_POLICY_DECISION_MATRIX.md
• Rebuild packet: MK_PHYSICAL_SCALE_CAPABILITY_REBUILD_PACKET.md
• Source baseline: qa@4f6165bc4c53a7d98b0c246392dd9ed5bd75c21c
• Important: current and target diagrams are labeled separately. A target diagram is not current behavior or implementation authorization.

---

1. Process Context

flowchart LR
    Commercial[Commercial Agreement]
    Inbound[Inbound Purchase]
    Outbound[Outbound Sales]
    Scale[Physical Scale]
    Transload[Transload / Receipt]
    Inventory[Inventory Lot]
    Allocation[Inventory Allocation]
    Equipment[Equipment Load]
    Packing[Packing / Documents]
    Delivery[Delivery]

    Commercial --> Inbound
    Commercial --> Outbound
    Inbound --> Scale
    Outbound --> Scale
    Scale -->|Purchase child handoff| Transload
    Transload --> Inventory
    Inventory --> Allocation
    Allocation --> Outbound
    Scale -->|Sales child handoff| Outbound
    Outbound --> Equipment
    Equipment --> Packing
    Packing --> Delivery

Scale is the physical-ticket owner.
It is not the owner of receipt, inventory, allocation, outbound close, packing or delivery.

---

2. Intended Flow / Stage Matrix

flowchart TB
    Start[Select business flow]
    Purchase{Purchase or Doortrade?}
    GrossIn[Entry = Gross]
    TareOut[Exit = Tare]
    TareIn[Entry = Tare]
    GrossOut[Exit = Gross]

    Start --> Purchase
    Purchase -->|Yes| GrossIn --> TareOut
    Purchase -->|No: Sales or Export| TareIn --> GrossOut

Current warning:

The current integrated Check-in writes Gross for every accepted flow.
This conflicts with the current UI matrix for Sales/Export.

---

3. Current Integrated Check-in Transaction

sequenceDiagram
    autonumber
    actor Operator as Scale Operator
    participant UI as Scale Portal JS
    participant API as POST /yms/scale/check-in/execute
    participant Tx as apiRouteRunLegacyWrite
    participant Order as Purchase/Sales Application Helpers
    participant Ticket as Scale Ticket Helper
    participant Link as Transload/Equipment Link
    participant DB as MySQL

    Operator->>UI: Select flow/order and enter item/stage values
    UI->>UI: Validate required fields and item Gross/Tare/Net
    UI->>API: FLOW + ORDER/ITEMS + SCALE_TICKET
    API->>Tx: Begin local transaction
    Tx->>Order: Save/create owner order and items
    Order->>DB: Header/items
    Tx->>Ticket: SCALE_IN
    Ticket->>DB: Ticket entry stage
    Ticket->>Link: Bind to Transload or Equipment Load
    Link->>DB: Link/projection updates
    Tx->>DB: Flush local sync tasks
    Tx->>DB: Commit
    API-->>UI: Order ID + Ticket ID/Number
    UI->>API: Refresh Schedule/tickets
    UI-->>Operator: Success message and refreshed board

Current positive boundary:

Order/items + ticket + direct ticket link
= one local Check-in transaction

Current remaining uncertainty:

client response/refresh
!= durable request idempotency

---

4. Current Check-in Response Loss

sequenceDiagram
    actor Operator
    participant UI
    participant API
    participant DB

    Operator->>UI: Submit Check-in
    UI->>API: /check-in/execute
    API->>DB: Commit order/items/ticket/link
    Note over UI,API: Response delayed or connection lost
    UI-->>Operator: Request timed out; refresh before retry
    Operator->>UI: Refresh
    UI->>API: Schedule + ticket detail
    API->>DB: Read exact order/ticket/link
    alt Existing ticket found
        API-->>UI: Committed result
        UI-->>Operator: Show existing ticket; do not retry
    else Confirmed absent
        API-->>UI: No ticket/link
        UI-->>Operator: Retry may be allowed
    else Mismatch
        API-->>UI: Conflict/unknown
        UI-->>Operator: Stop and escalate
    end

Current source has no durable request token, so exact record readback is required.

---

5. Current Sales/Export Stage Contradiction

sequenceDiagram
    actor Operator
    participant UI as Scale Portal Flow Policy
    participant API as Integrated Check-in API
    participant DB as T_SCALE_TICKET
    participant Board as Active Ticket Board

    Operator->>UI: Select Sales/Export Check-in
    UI->>UI: Display entry meaning as Tare
    UI->>API: EXECUTE_CHECKIN payload
    Note over UI,API: Current payload/server force Gross
    API->>DB: Write GROSS_TIME and Gross weight
    API-->>UI: Ticket success
    UI->>Board: Refresh active board
    Board->>DB: Read ticket
    Board->>Board: Sales/Export expected entry = Tare
    alt Tare absent
        Board-->>Operator: Ticket may be omitted/misclassified
    else Unexpected compatibility path
        Board-->>Operator: Behavior requires exact Runtime evidence
    end

This diagram is a source contradiction, not a claim of a verified Production incident.

---

6. Current Entry Correction / Reweigh

sequenceDiagram
    autonumber
    actor Operator
    participant UI
    participant API as PATCH /yms/scale/check-in
    participant Tx
    participant Ticket
    participant Event as T_SCALE_TICKET_EVENT
    participant DB

    Operator->>UI: Reopen active ticket
    UI->>UI: Compare current versus edited entry values
    alt Values unchanged
        UI->>API: Repeat same stage
        API->>Ticket: Read current stage
        Ticket-->>UI: Existing ticket result
    else Values changed
        UI->>Operator: Require correction reason
        Operator->>UI: Enter reason
        UI->>API: Changed stage + reason
        API->>Tx: Begin
        Tx->>Ticket: Read active snapshot
        Ticket->>DB: Conditional CAS update; exit must be absent
        Ticket->>Event: Append REWEIGH_CORRECTION
        Event->>DB: Before/after/reason/actor/request
        Tx->>DB: Commit
        API-->>UI: Ticket + Event result
    end

---

7. Current Check-out Composite

sequenceDiagram
    autonumber
    actor Operator
    participant UI as Scale Portal JS
    participant OwnerAPI as Inbound/Outbound API
    participant ScaleAPI as POST /yms/scale/check-out
    participant Ticket as Scale Ticket Helper
    participant Child as Purchase Finalize / Outbound Close
    participant DB as MySQL

    Operator->>UI: Edit checkout header/items and exit stage
    loop Header and each item
        UI->>OwnerAPI: PATCH/POST owner row
        OwnerAPI->>DB: Commit one request
        OwnerAPI-->>UI: Result
    end
    UI->>ScaleAPI: Exit stage
    ScaleAPI->>Ticket: Validate entry, stage and totals
    Ticket->>DB: Commit exit stage
    ScaleAPI-->>UI: Completed Scale ticket
    alt Sales/Export
        UI->>Child: Outbound close update
        Child->>DB: Commit or fail separately
        Child-->>UI: Child result
    else Purchase/Doortrade
        UI-->>Operator: Choose branch
        Operator->>UI: Warehouse/Direct/Mixed
        UI->>Child: Purchase finalize
        Child->>DB: Commit or fail separately
        Child-->>UI: Child result
    end

Current partial-result boundaries:

owner row 1 committed / owner row 2 failed
owner rows committed / Scale Out failed
Scale Out committed / Outbound close failed
Scale Out committed / Purchase finalize failed

---

8. Current Check-out Recovery By Last Confirmed Boundary

flowchart TD
    Error[Check-out error or timeout]
    ReadOwner[Read owner header/items]
    ReadTicket[Read exact ticket stages]
    ReadChild[Read Purchase finalize or Outbound close]
    OwnerMissing{Owner changes complete?}
    TicketComplete{Scale exit committed?}
    ChildComplete{Required child committed?}

    Error --> ReadOwner --> ReadTicket --> ReadChild --> OwnerMissing
    OwnerMissing -->|No| ResumeOwner[Resume/correct owner Save only]
    OwnerMissing -->|Yes| TicketComplete
    TicketComplete -->|No| ResumeScale[Submit Scale Out only if confirmed absent]
    TicketComplete -->|Yes| ChildComplete
    ChildComplete -->|No| ResumeChild[Run owner child only]
    ChildComplete -->|Yes| Done[Show full readback]

Do not restart from the top after a partial result.

---

9. Current Purchase Finalize Handoff

sequenceDiagram
    actor ScaleOp as Scale Operator
    participant ScaleUI
    participant ScaleAPI
    participant InboundAPI as Inbound Purchase Finalize
    participant Items as Purchase Items
    participant Transload
    participant Lot as Inventory Lot
    participant DB

    ScaleOp->>ScaleUI: Submit Tare Check-out
    ScaleUI->>ScaleAPI: Scale Out
    ScaleAPI->>DB: Commit completed ticket
    ScaleAPI-->>ScaleUI: Scale complete
    ScaleUI-->>ScaleOp: Choose Warehouse/Direct/Mixed
    ScaleOp->>ScaleUI: Select branch
    ScaleUI->>InboundAPI: Finalize Purchase from completed ticket
    InboundAPI->>Items: Distribute accepted weights / status
    InboundAPI->>Transload: Update receipt state/link
    InboundAPI->>Lot: Materialize/reconcile lots
    InboundAPI->>DB: Commit or rollback child transaction
    InboundAPI-->>ScaleUI: Purchase child result

completed ticket remains committed if Purchase finalize fails

---

10. Current Outbound Close Handoff

sequenceDiagram
    actor ScaleOp
    participant ScaleUI
    participant ScaleAPI
    participant OutboundAPI
    participant DB

    ScaleOp->>ScaleUI: Submit Gross Check-out
    ScaleUI->>ScaleAPI: Scale Out
    ScaleAPI->>DB: Commit completed ticket
    ScaleAPI-->>ScaleUI: Scale complete
    ScaleUI->>OutboundAPI: Set OUT_TIME and COMPLETED
    alt Outbound close succeeds
        OutboundAPI->>DB: Commit owner state
        OutboundAPI-->>ScaleUI: Completed
    else Outbound close fails
        OutboundAPI-->>ScaleUI: Failed
        ScaleUI-->>ScaleOp: Scale complete / Outbound close failed
    end

The target UI must not report a single undifferentiated success when the child fails.

---

11. Current Ticket State Machine

stateDiagram-v2
    [*] --> NotStarted
    NotStarted --> EntryRecorded: Accepted entry stage
    EntryRecorded --> EntryRecorded: Identical repeat
    EntryRecorded --> EntryRecorded: Reasoned reweigh + event
    EntryRecorded --> Completed: Accepted exit stage
    NotStarted --> Voided: Reasoned void, no downstream blocker
    EntryRecorded --> Voided: Reasoned void, no downstream blocker
    Completed --> Reversed: Reasoned reversal, no downstream blocker
    EntryRecorded --> Conflict: stage/flow/link mismatch
    Completed --> Conflict: competing writer or child mismatch
    Conflict --> EntryRecorded: controlled reconciliation
    Conflict --> Completed: controlled reconciliation

The entry/exit stage cannot be derived correctly without an accepted flow policy.

---

12. Current Reversal

sequenceDiagram
    autonumber
    actor Recovery as Recovery Manager
    participant UI
    participant API as DELETE /yms/scale/tickets/{id}
    participant Tx
    participant Ticket
    participant Blockers as Downstream Owners
    participant Event
    participant Links as Transload/Equipment/Order Links
    participant DB

    Recovery->>UI: Select Void/Reversal and reason
    UI->>API: Ticket ID + reason
    API->>Tx: Begin
    Tx->>Ticket: Conditional active soft-delete claim
    Ticket->>Blockers: Check Transload, Inventory, Equipment, Delivery, Order
    alt Blocked
        Blockers-->>Tx: Downstream execution found
        Tx->>DB: Rollback claim
        API-->>UI: SCALE_DOWNSTREAM_LOCKED
    else Allowed
        Ticket->>Event: Append VOID or REVERSAL event
        Event->>DB: Evidence
        Ticket->>Links: Detach ticket pointers / clear projection
        Links->>DB: Update links
        Tx->>DB: Commit
        API-->>UI: Event and residual readback
    end

---

13. Competing BMS Writer

flowchart LR
    YMS[YMS Scale commands]
    BMS[BMS generic ticket PATCH/DELETE]
    Ticket[(T_SCALE_TICKET)]
    Event[(T_SCALE_TICKET_EVENT)]
    Transload[(T_TRANSLOAD)]
    Equipment[(T_EQUIPMENT_LOAD)]

    YMS -->|stage CAS + reason/event + broad blocker guard| Ticket
    YMS --> Event
    YMS --> Transload
    YMS --> Equipment

    BMS -->|generic field update/delete| Ticket
    BMS -->|different sync behavior| Transload
    BMS -. no equivalent YMS event/guard .-> Event

Target state:

one MK physical-ticket writer

---

14. Current Physical Print

sequenceDiagram
    actor Operator
    participant UI
    participant Print as Physical Ticket PHP
    participant DB
    participant Browser

    Operator->>UI: Print verified ticket
    UI->>Print: IDS[]=ticketId
    Print->>Print: Page role check
    Print->>DB: Current tenant + active ticket query
    DB-->>Print: Ticket projection
    Print-->>Browser: HTML
    Browser-->>Operator: Print dialog

browser output
!= durable print acknowledgement

---

15. Current Live Weight Boundary

flowchart LR
    Static[Initial 00000 lb]
    Manual[Manual operator input]
    Unknown[Unconfirmed external caller]
    Business[Scale command]

    Static -. display only .-> Manual
    Unknown -. no accepted device contract .-> Static
    Manual --> Business

No accepted current Device → Reading → Stage provenance path is established.

---

Target Diagrams

16. Target Device-Neutral Reading Path

sequenceDiagram
    actor Operator
    participant Device
    participant Adapter as Device Adapter
    participant Session as Device Session/Reading Channel
    participant UI as React Scale Workspace
    participant App as Scale Application

    Device->>Adapter: Raw reading
    Adapter->>Session: Normalized reading envelope
    Session-->>UI: Value + stability + age + reading ID
    Operator->>UI: Accept reading or choose manual fallback
    UI->>App: Stage input + accepted reading ID/source
    App-->>UI: Committed stage readback

The Device Adapter never writes business tables directly.

---

17. Target Check-in

sequenceDiagram
    autonumber
    actor Operator
    participant React
    participant Next as Next.js Adapter
    participant App as ScaleCheckInApplication
    participant Policy as ScaleFlowPolicy
    participant Request as ScaleRequestRepository
    participant Order as Owner Application Adapter
    participant Ticket as ScaleTicketRepository
    participant Link as Link Repository
    participant DB as MySQL

    Operator->>React: Select flow/record and accepted entry reading
    React->>Next: ExecuteScaleCheckIn DTO
    Next->>App: Authenticated command context
    App->>Policy: Resolve entry/exit policy
    Policy-->>App: Accepted entry stage
    App->>Request: Claim request token
    App->>Order: Save/create owner record through typed contract
    App->>Ticket: Insert entry stage with conditional identity
    App->>Link: Create typed link
    App->>DB: Commit one transaction
    App->>Ticket: Exact ticket readback
    App->>Order: Exact owner readback
    App-->>Next: Stable Check-in result
    Next-->>React: Ticket/order/link result
    React-->>Operator: ENTRY_RECORDED with next action

---

18. Target Check-out Composite

sequenceDiagram
    actor Operator
    participant React
    participant Owner as Inbound/Outbound Application
    participant Scale as ScaleCheckOutApplication
    participant Child as Purchase Finalize / Outbound Close

    Operator->>React: Edit allowed owner values and exit stage
    React->>Owner: PrepareScaleCheckOut
    Owner-->>React: Atomic owner snapshot + version
    React->>Scale: CompleteScaleCheckOut
    Scale-->>React: Scale COMPLETED + exact ticket readback
    alt Purchase/Doortrade
        React->>Child: FinalizePurchaseReceiptFromScale
        Child-->>React: Child disposition
    else Sales/Export
        React->>Child: CloseOutboundFromScale
        Child-->>React: Child disposition
    end
    React-->>Operator: Independent Scale and child results

---

19. Target Unknown-Result Decision

flowchart TD
    Unknown[Command result unknown]
    Token[Read request token]
    Ticket[Read ticket/detail/events]
    Link[Read order/transload/equipment link]
    State{Classification}

    Unknown --> Token --> Ticket --> Link --> State
    State -->|Committed| Existing[Return existing result]
    State -->|Confirmed absent| Retry[Allow retry with same token]
    State -->|Conflict| Review[Manual reconciliation]
    State -->|Still unknown| Stop[Stop; no replay]

---

20. Target One-Writer Cutover

sequenceDiagram
    participant PHP as Current PHP/YMS Writer
    participant TS as TypeScript Scale Writer
    participant Router as Cohort Router
    participant DB
    participant Monitor

    Note over PHP,TS: Read-shadow and scenario parity first
    Router->>TS: Selected cohort write
    TS->>DB: One authoritative command
    PHP->>DB: Read-only for selected cohort
    Monitor->>DB: Compare ticket/link/event/readback
    alt Gate passes
        Router->>TS: Expand cohort
    else Critical mismatch
        Router->>PHP: Return new requests to prior writer
        TS->>DB: Stop new writes; preserve committed evidence
        Monitor->>DB: Reconcile in-flight request tokens
    end

No dual write.

---

21. Target Component Map

flowchart TB
    React[React Scale Workspace]
    Next[Next.js Server / Route Adapters]
    Query[Scale Query Application]
    CheckIn[Scale Check-in Application]
    CheckOut[Scale Check-out Application]
    Correct[Scale Correction Application]
    Reverse[Scale Reversal Application]
    Policy[Flow / Weight / Recovery Policy]
    TicketRepo[Scale Ticket Repository]
    EventRepo[Ticket Event Repository]
    RequestRepo[Request Repository]
    OwnerAdapters[Inbound / Outbound Link Adapters]
    DB[(MySQL)]
    Device[Optional Device Adapter]

    React --> Next
    Next --> Query
    Next --> CheckIn
    Next --> CheckOut
    Next --> Correct
    Next --> Reverse
    CheckIn --> Policy
    CheckOut --> Policy
    Correct --> Policy
    Reverse --> Policy
    Query --> TicketRepo
    CheckIn --> TicketRepo
    CheckOut --> TicketRepo
    Correct --> TicketRepo
    Reverse --> TicketRepo
    Correct --> EventRepo
    Reverse --> EventRepo
    CheckIn --> RequestRepo
    CheckOut --> RequestRepo
    CheckIn --> OwnerAdapters
    CheckOut --> OwnerAdapters
    TicketRepo --> DB
    EventRepo --> DB
    RequestRepo --> DB
    OwnerAdapters --> DB
    Device -. normalized readings .-> React

---

22. Target Migration Waves

flowchart LR
    W0[W0 Characterize]
    W1[W1 Flow Policy + Defect Repair]
    W2[W2 TypeScript Reads]
    W3[W3 React Read-only]
    W4[W4 Check-in Writer]
    W5[W5 Check-out Writer]
    W6[W6 Child Dispositions]
    W7[W7 Reweigh/Reversal]
    W8[W8 Optional Device]
    W9[W9 BMS Writer Retirement]
    W10[W10 Stabilize/Wiki]
    W11[W11 PHP Caller-zero]
    W12[W12 PostgreSQL]

    W0 --> W1 --> W2 --> W3 --> W4 --> W5 --> W6 --> W7 --> W8 --> W9 --> W10 --> W11 --> W12

Device Wave can be deferred without blocking manual-entry migration when Product accepts that scope.

---

23. Diagram Maintenance Triggers

Update these diagrams when any of the following changes:

• flow/stage policy;
• Check-in/Check-out transaction boundary;
• owner pre-save/finalize/close behavior;
• ticket/link/event authority;
• BMS writer scope;
• request idempotency/version;
• device adapter/session/reading contract;
• correction/reversal blocker policy;
• current/future page/API route;
• one-writer/rollback/caller-zero.

Repository Mermaid source is editable documentation. Wiki publication may require reviewed SVG/PNG plus adjacent plain text.

---

Source: docs/processes/MK_PHYSICAL_SCALE_SEQUENCE_DIAGRAMS.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.