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 Trade, Cost, Rate And Document Outputs — Sequence And State Diagrams

• Status: SOURCE-RECONCILED DIAGRAM INPUT / NOT RUNTIME-ACCEPTED
• Source baseline: qa@d96498360bb9c3541a1b5f862284596a7ed217b9
• Reconciliation: MK_TRADE_COST_RATE_DOCUMENT_OUTPUTS_RECONCILIATION.md
• Rebuild packet: MK_TRADE_COST_RATE_DOCUMENT_OUTPUTS_CAPABILITY_REBUILD_PACKET.md

Diagrams explain order and ownership. They do not authorize a write, prove current Runtime correctness or replace the owning Process.

---

1. Family Ownership Map

flowchart LR
    Commercial[Commercial / Orders / Booking / Allocation / Scale]
    Trade[Trade Summary Query]
    Export[Export Brokerage Application]
    Cost[Outbound Cost Application]
    Rate[Packing Rate Application]
    Docs[Document Projection Queries]
    File[Optional Future File / Delivery]

    Commercial --> Trade
    Commercial --> Export
    Commercial --> Cost
    Commercial --> Rate
    Commercial --> Docs
    Trade -. read only .-> Commercial
    Export --> Commercial
    Cost --> Commercial
    Rate --> Commercial
    Docs -. read only .-> Commercial
    Docs -. only if separately accepted .-> File

Trade != Export Job != Cost != Rate != Document != File/Delivery

---

2. Current Trade Summary List And Derived Status

sequenceDiagram
    actor Reviewer
    participant Page as Trade/Deal Ledger Page
    participant API as Trade Summary API
    participant Query as Trade Query Helper
    participant DB as MySQL Sources

    Reviewer->>Page: choose date/status/search filters
    Page->>API: GET list
    API->>Query: list(filters, tenant)
    Query->>DB: equipment/order/booking/transaction joins
    DB-->>Query: source rows
    Query->>DB: equipment AP/AR totals
    DB-->>Query: confirmed/closed equipment totals
    Query->>Query: add outbound-order AP
    Query->>Query: derive margin and display status
    Query-->>API: projection rows + paging
    API-->>Page: rows
    Page-->>Reviewer: OPEN/SHIPPED/CLOSED/CLAIMED-filter view
    Note over Reviewer,DB: No business mutation occurs

---

3. Trade Header/Detail Explainability Gap

flowchart TD
    EquipmentAP[Equipment AP]
    EquipmentAR[Equipment AR]
    OutboundAP[Outbound Order AP]
    Header[Header TOTAL_AP / TOTAL_AR / MARGIN]
    Detail[Current Detail Lines]

    EquipmentAP --> Header
    EquipmentAR --> Header
    OutboundAP --> Header
    OutboundAP --> Detail
    EquipmentAP -. incomplete/omitted .-> Detail
    EquipmentAR -. incomplete/omitted .-> Detail

    Header --> Gap{Can reviewer reproduce header?}
    Detail --> Gap
    Gap -->|No| Conflict[UNEXPLAINED / Source Breakdown Required]

Target detail must expose every contributing source class or explicitly mark a projection unexplained.

---

4. Trade Derived State

stateDiagram-v2
    [*] --> SourceRead
    SourceRead --> SourceAmbiguous: multiple/deleted/conflicting links
    SourceRead --> Explained: complete source breakdown
    Explained --> ClosedLabel: AP or AR amount threshold met
    Explained --> ShippedLabel: no amount and ETA/ETD/SWB
    Explained --> OpenLabel: no amount/logistics evidence
    Explained --> ClaimedFilterMatch: negative margin + amount
    SourceAmbiguous --> ManualReconciliation

    note right of ClosedLabel
      Display label only
      Not accounting close
    end note

---

5. Trade CSV

sequenceDiagram
    actor Reviewer
    participant UI as Trade UI
    participant Browser
    participant DB as Source DB

    Reviewer->>UI: reconcile visible projection
    UI->>DB: read current source
    DB-->>UI: projection + fingerprint
    Reviewer->>UI: Export CSV
    UI->>Browser: create/download Blob
    Browser-->>Reviewer: local CSV
    Note over UI,DB: no server file, DB write, approval or provider result

---

6. Current Export Brokerage Create

sequenceDiagram
    actor Operator
    participant UI as Export Brokerage UI
    participant API as Export Brokerage API
    participant App as Current Orchestrator
    participant DB as MySQL

    Operator->>UI: review proposal and select Booking
    UI->>API: POST create child set
    API->>App: validate tenant/config/input
    App->>DB: begin transaction
    App->>DB: create Purchase/items/Transload/Lot
    App->>DB: create/reuse Booking relation
    App->>DB: create Outbound/items/Equipment
    App->>DB: create Allocations and compatibility markers
    alt every child succeeds
        App->>DB: commit
        API-->>UI: child IDs/result
        UI-->>Operator: Created + links
    else any exception
        App->>DB: rollback
        API-->>UI: error
    end

Transaction success does not eliminate response-loss risk because no durable request result exists.

---

7. Export Create Response Lost

sequenceDiagram
    actor Operator
    participant UI
    participant API
    participant DB

    Operator->>UI: Create once
    UI->>API: request without durable token
    API->>DB: commit complete child set
    API--xUI: response lost
    UI-->>Operator: timeout/unknown
    Note over Operator,DB: Blind retry can create another child set
    Operator->>UI: search exact reference/container/Booking
    UI->>DB: read Purchase/Booking/Outbound/Equipment/Lot/Allocation
    DB-->>UI: committed/absent/partial evidence
    UI-->>Operator: recovery decision

Target uses jobId + requestToken + inputFingerprint and returns the prior result on duplicate.

---

8. Current Export Brokerage Cancel

sequenceDiagram
    actor Operator
    participant API
    participant App as Export Orchestrator
    participant DB

    Operator->>API: cancel with inbound/outbound IDs
    API->>App: validate reference/children/allocations
    App->>DB: begin transaction
    App->>DB: inspect Scale/equipment/transload/ledger/downstream blockers
    alt progressed or ambiguous
        App->>DB: rollback
        API-->>Operator: CANCEL_BLOCKED
    else safe generated child set
        App->>DB: remove allocations
        App->>DB: remove generated Outbound/equipment children
        App->>DB: remove generated Inbound/lot children
        App->>DB: release marked generated Booking/equipment where safe
        App->>DB: commit
        API-->>Operator: deleted/preserved child result
    end

---

9. Target Export Brokerage Job

sequenceDiagram
    actor Operator
    participant React
    participant Next as Next.js Adapter
    participant App as TypeScript Export App
    participant JobRepo
    participant Child as Child Owner Commands

    Operator->>React: Create
    React->>Next: requestToken + reviewed input
    Next->>App: CreateExportBrokerageJob
    App->>JobRepo: claim token / create manifest
    alt duplicate same payload
        JobRepo-->>App: prior result
        App-->>Next: prior manifest
    else new request
        App->>Child: create explicit child results
        Child-->>App: per-child readbacks
        App->>JobRepo: save manifest/result
        App-->>Next: CREATED/PARTIAL/UNKNOWN manifest
    end
    Next-->>React: exact child dispositions

---

10. Current Outbound Cost Save

sequenceDiagram
    actor Operator
    participant UI as Outbound Cost UI
    participant API
    participant Helper as Cost Helper
    participant DB

    Operator->>UI: edit visible cost
    UI->>API: POST order cost, optional transaction ID
    API->>Helper: save
    Helper->>DB: assert Outbound order
    Helper->>DB: find explicit or latest AP
    Helper->>Helper: reject immutable state
    Helper->>DB: insert/update header
    Helper->>DB: soft-delete prior lines
    Helper->>DB: insert submitted nonzero lines
    DB-->>Helper: commit
    Helper-->>UI: transaction result
    Note over UI,DB: sibling AP/files/Trade effect require separate reread

---

11. Outbound Cost Ownership Ambiguity

flowchart TD
    Order[Outbound Order]
    AP1[AP Transaction A]
    AP2[AP Transaction B]
    AP3[AP Transaction C]
    UI[Current UI chooses one/latest]
    Decision{Typed Outbound Cost owner known?}

    Order --> AP1
    Order --> AP2
    Order --> AP3
    AP1 --> UI
    AP2 --> UI
    AP3 --> UI
    UI --> Decision
    Decision -->|No| Stop[STOP / ACCOUNTING OWNER REQUIRED]
    Decision -->|Yes| Write[Exact transaction command]

---

12. Target Cost Conditional Update

sequenceDiagram
    actor Operator
    participant React
    participant Next
    participant App as Outbound Cost App
    participant Repo

    Operator->>React: save exact typed cost
    React->>Next: transaction ID + expected version + full intent
    Next->>App: UpdateOutboundCost
    App->>Repo: conditional header/line transaction
    alt stale/immutable/owner mismatch
        Repo-->>App: conflict
        App-->>React: typed error + current readback
    else success
        Repo-->>App: exact header/lines/siblings
        App-->>React: SAVED
    end

---

13. Current Packing Rate Autosave

sequenceDiagram
    actor Operator
    participant UI as Packing Invoice UI
    participant API as Rate PATCH
    participant DB
    participant Print as Browser Print

    Operator->>UI: edit Rate and blur
    UI->>API: item IDs + float rate
    API->>DB: update each eligible ID
    DB-->>API: updated count
    API-->>UI: success count
    par operator action
        Operator->>Print: Print
    and unresolved source
        UI-->>UI: local row may appear clean/pending
    end
    Note over UI,DB: invalid intended IDs may be silently skipped

---

14. Target Packing Rate Result

sequenceDiagram
    actor Operator
    participant React
    participant App as Rate Correction App
    participant Repo

    Operator->>React: Save intended rate set
    React->>App: requestToken + expected prior rates
    App->>Repo: conditional update all or explicit per-item
    Repo-->>App: per-item dispositions
    App-->>React: UPDATED/STALE/DENIED/NOT_FOUND
    React->>App: exact reread
    App-->>React: persisted rates
    React-->>Operator: print ready only after accepted readback

---

15. Current Packing Document Projection

flowchart TD
    Booking[Booking]
    Sales[Outbound Sales Items]
    EL[Equipment Loads]
    EC[Equipment Commodity]
    Helper[Packing List Helper]
    Full{Every selected container has equipment commodity coverage?}
    EquipmentRows[Use equipment commodity rows]
    Fallback[Use Outbound item fallback for whole output]
    Template[Fixed/current template values]
    Browser[Render / transient edit / print]

    Booking --> Helper
    Sales --> Helper
    EL --> Helper
    EC --> Helper
    Helper --> Full
    Full -->|Yes| EquipmentRows
    Full -->|No| Fallback
    EquipmentRows --> Template
    Fallback --> Template
    Template --> Browser

No durable file, email, approval or Booking-flag effect occurs.

---

16. Purchase Local Invoice Projection

sequenceDiagram
    actor Reviewer
    participant Page as Local Invoice Page
    participant Helper as Report Helper
    participant DB
    participant Print as Browser Print

    Reviewer->>Page: open exact Purchase ORDER_ID
    Page->>Helper: purchase_local_invoice
    Helper->>DB: active Purchase/order items/company
    DB-->>Helper: current source
    Helper->>Helper: UOM formulas + fee - credit
    Helper-->>Page: current projection
    Page-->>Reviewer: render
    Reviewer->>Print: print/cancel
    Note over Page,DB: no invoice record/file/acknowledgement

---

17. Booking Confirmation Projection

sequenceDiagram
    actor Reviewer
    participant Page as Role-protected Confirmation Page
    participant Helper
    participant DB

    Reviewer->>Page: BOOKING_ID
    Page->>Page: role + feature gate
    Page->>Helper: booking_confirmation
    Helper->>DB: Booking/companies/optional Sales ref
    DB-->>Helper: current source
    Helper->>Helper: template + current date + source precedence
    Helper-->>Page: projection
    Page-->>Reviewer: browser render/print
    Note over Reviewer,DB: no Booking approval/confirmation transition

---

18. Sales Weight Ticket Projection Versus Physical Scale

flowchart LR
    Sales[Sales Order + Items + Equipment]
    Output[Sales Weight Ticket ORDER_ID Projection]
    Physical[Physical T_SCALE_TICKET]
    Print[Browser Print]

    Sales --> Output --> Print
    Physical -. not required by current output .-> Output
    Output -. does not prove .-> Physical

---

19. Common Unknown-Result Recovery

flowchart TD
    Action[Action attempted]
    Unknown[Response / print result unknown]
    Class{Action class}
    Read[Read projection]
    Write[DB command]
    Print[Browser print]

    Action --> Unknown --> Class
    Class -->|Read/export| Read
    Class -->|Export/Cost/Rate write| Write
    Class -->|Print| Print
    Read --> R1[Requery source + fingerprint]
    Write --> R2[Reread exact owner records + request/job identity]
    Print --> R3[Human custody decision; no DB rollback]
    R1 --> Resume[Resume only from confirmed boundary]
    R2 --> Resume
    R3 --> Resume

---

20. Target Component Architecture

flowchart TB
    subgraph React_UI
        TradeUI[Trade Reconciliation]
        ExportUI[Export Brokerage]
        CostUI[Outbound Cost]
        RateUI[Packing Rate]
        DocUI[Document Preview]
    end

    subgraph Next_Adapters
        TradeRoute[Trade Query Adapter]
        ExportRoute[Export Command Adapter]
        CostRoute[Cost Command Adapter]
        RateRoute[Rate Command Adapter]
        DocRoute[Document Query Adapter]
    end

    subgraph TypeScript_Core
        TradeApp[Trade Projection Query]
        ExportApp[Export Brokerage Application]
        CostApp[Outbound Cost Application]
        RateApp[Rate Correction Application]
        DocApp[Document Projection Queries]
    end

    Repo[Typed MySQL Repositories]
    Worker[Optional Accepted File/Delivery Worker]

    TradeUI --> TradeRoute --> TradeApp --> Repo
    ExportUI --> ExportRoute --> ExportApp --> Repo
    CostUI --> CostRoute --> CostApp --> Repo
    RateUI --> RateRoute --> RateApp --> Repo
    DocUI --> DocRoute --> DocApp --> Repo
    ExportApp -. async effect only if accepted .-> Worker
    DocApp -. durable file/delivery only if accepted .-> Worker

---

21. Migration Sequence

sequenceDiagram
    participant Legacy as PHP Runtime
    participant TS as TypeScript Read/Command
    participant React as React + Next.js
    participant DB as MySQL
    participant Obs as Parity / Observation

    Legacy->>DB: current authoritative calls
    TS->>DB: read shadow
    TS-->>Obs: source/formula parity
    React->>TS: read-only Trade/Documents
    React-->>Obs: role/UI parity
    Note over Legacy,TS: select one mutable capability/cohort
    React->>TS: Cost or Rate command
    TS->>DB: one authoritative write
    TS-->>Obs: exact readback/rollback evidence
    Legacy-->>Obs: legacy caller count
    Obs-->>Legacy: retire only after caller-zero

---

22. Diagram Update Triggers

Update this catalog when any accepted change modifies:

• Trade source classes/status/date/deleted-row behavior;
• Export child set, markers, transaction or cancel compensation;
• Cost target identity/update/delete;
• rate batch/validation/readback;
• document source/fallback/template/access;
• browser print or durable file/delivery scope;
• target component boundary;
• one-writer/rollback/caller-zero.

Every published Wiki diagram must also include adjacent plain text and renderer/mobile/accessibility verification.

---

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