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 Inventory Allocation — Sequence, State And Migration Diagrams

• Status: SOURCE-RECONCILED DIAGRAM INPUT / OWNER REVIEW REQUIRED
• Process: PROC-OMS-INVENTORY-TO-OUTBOUND-ALLOCATION-MK
• Rebuild packet: MK_INVENTORY_ALLOCATION_CAPABILITY_REBUILD_PACKET.md
• Reconciliation: MK_INVENTORY_ALLOCATION_RECONCILIATION.md
• Operator Runbook: MK_INVENTORY_ALLOCATION_OPERATOR_RUNBOOK.md
• Purpose: preserve source/target identity, current transaction order, quantity/weight asymmetry, conflict recovery and target migration in editable form

A diagram explains sequence or ownership. It does not override the owning Process, source or accepted policy.

---

1. Receipt To Allocation To Outbound

flowchart LR
    IN[Inbound Purchase]
    REC[Receipt Finalize]
    LOT[Inventory Lot]
    WB[Allocation Workbench]
    ITEM[New Outbound Item]
    ALLOC[Allocation Relation]
    OUT[Existing Outbound Shipment]
    SCALE[Optional Scale]
    PACK[Optional Packing]
    DEL[Optional Delivery]

    IN --> REC --> LOT --> WB
    OUT --> WB
    WB --> ITEM
    WB --> ALLOC
    ITEM --> OUT
    ALLOC --> LOT
    OUT --> SCALE
    OUT --> PACK
    OUT --> DEL

Receipt != Allocation
Allocation != Scale/Packing/Delivery completion

---

2. Current Source And Target Selection

sequenceDiagram
    actor Operator
    participant UI as Allocation Workbench
    participant API as Allocation Query API
    database DB as MySQL

    Operator->>UI: Open Workbench and set source filter
    UI->>API: GET eligible sources
    API->>DB: Read open active lots + source relationships
    DB-->>UI: Lot/source/balance rows
    Operator->>UI: Add source rows to client basket
    UI->>API: GET existing targets
    API->>DB: Read active outbound + equipment/container bridge
    DB-->>UI: Eligible existing targets
    Operator->>UI: Select one target

The client basket is not durable authority.

---

3. Current Full-Lot Basket

flowchart TB
    Source[Source row]
    Qty[REMAIN_QUANTITY]
    Wgt[REMAIN_NET_WEIGHT]
    Key[LOT_ID : SOURCE_ITEM_ID]
    Basket[Client basket row]

    Source --> Qty --> Basket
    Source --> Wgt --> Basket
    Source --> Key --> Basket

Current UI does not present a partial quantity/weight editor.

---

4. Current Apply Transaction

sequenceDiagram
    actor Operator
    participant UI
    participant API as Allocation API
    database DB

    Operator->>UI: Apply once
    UI->>API: Target + all basket rows
    API->>DB: Begin transaction
    API->>DB: Validate target order/equipment bridge
    loop each source row
        API->>DB: Read source lot and remaining weight
        API->>DB: Insert new target T_LOAD_ITEM
        API->>DB: Insert T_LOAD_ALLOCATION
        API->>DB: Conditional decrement REMAIN_NET_WEIGHT
    end
    API->>DB: Synchronize target bridge projections
    alt every row succeeds
        API->>DB: Commit
        API-->>UI: Target + created item IDs
    else any row fails
        API->>DB: Rollback
        API-->>UI: Error
    end

---

5. Basket Rollback

sequenceDiagram
    participant API
    database DB

    API->>DB: Begin transaction
    API->>DB: Row A item/allocation/decrement
    DB-->>API: Success
    API->>DB: Row B item/allocation/decrement
    DB-->>API: Stale balance / failure
    API->>DB: Rollback
    Note over DB: Row A and Row B business writes should both be absent.

If evidence shows otherwise, stop and classify a data conflict rather than assuming partial success.

---

6. Concurrent Source Consumption

sequenceDiagram
    actor A as Operator A
    actor B as Operator B
    participant App
    database DB

    A->>App: Apply Lot 45 weight 20,000
    B->>App: Apply Lot 45 weight 20,000
    App->>DB: Request A conditional decrement
    DB-->>App: A succeeds
    App->>DB: Request B conditional decrement
    DB-->>App: B affected rows = 0
    App-->>A: Committed result
    App-->>B: ALLOCATION_STALE_BALANCE
    B->>App: Refresh source and allocation history

Conditional weight protection does not replace request idempotency, quantity/UOM policy or duplicate relation checks.

---

7. Quantity And Weight Asymmetry

flowchart LR
    Before[Lot before]
    Alloc[Allocation quantity + weight]
    Item[Target item quantity + weight]
    Weight[REMAIN_NET_WEIGHT decremented]
    Qty[REMAIN_QUANTITY unchanged immediately]
    Later[Later lot reconciliation may recalculate]

    Before --> Alloc
    Alloc --> Item
    Alloc --> Weight
    Alloc --> Qty
    Weight --> Later
    Qty --> Later

This asymmetry requires an explicit UOM/authority decision before migration.

---

8. Apply Response Lost

sequenceDiagram
    actor Operator
    participant UI
    participant API
    database DB

    Operator->>UI: Apply basket
    UI->>API: Submit without durable request token
    API->>DB: Commit target items, allocations and balances
    DB-->>API: Success
    API--xUI: Response lost
    Operator->>UI: Refresh, do not Apply again
    UI->>API: Query target items + allocations + source lots
    API->>DB: Reread exact identities
    alt committed result found
        DB-->>UI: Existing committed result
    else absent
        DB-->>UI: Retry may be allowed
    else conflict/ambiguous
        DB-->>UI: Stop and manual review
    end

---

9. Duplicate Request Target Model

sequenceDiagram
    actor Operator
    participant App as Allocation Application
    database DB

    Operator->>App: Apply request token R1
    App->>DB: Check R1
    DB-->>App: Not found
    App->>DB: Commit R1 + allocation result
    App-->>Operator: Result
    Operator->>App: Replay R1 after timeout
    App->>DB: Check R1 + payload fingerprint
    DB-->>App: Existing result
    App-->>Operator: Same target item/allocation IDs; no new consumption

---

10. Outbound Item Update Divergence

flowchart TB
    Allocation[Active allocation]
    Source[Source lot balance]
    Item[Allocated target item]
    Edit[Ordinary Outbound item update]
    Divergence[Allocation / source / target disagreement]
    Correct[Allocation-aware correction command]

    Allocation --> Item
    Allocation --> Source
    Edit --> Item
    Item --> Divergence
    Source --> Divergence
    Allocation --> Divergence
    Divergence --> Correct

Ordinary Outbound Save must not become the target correction owner.

---

11. Inbound Source Correction After Allocation

sequenceDiagram
    actor Receiving
    participant Inbound
    participant Allocation
    database DB

    Receiving->>Inbound: Correct received quantity/weight
    Inbound->>DB: Read source item/transload/lot
    Inbound->>Allocation: Query active allocations and downstream locks
    Allocation-->>Inbound: Allocated quantity/weight + relations
    alt accepted corrected source remains >= allocated values
        Inbound->>DB: Conditional correction + lot reconciliation
        DB-->>Receiving: Exact source/lot/allocation readback
    else conflict
        Inbound-->>Receiving: Block and require allocation/inventory recovery
    end

---

12. Booking Compatibility Conflict

sequenceDiagram
    actor BookingOperator
    participant Booking
    database DB
    participant AllocationOwner as Allocation Owner

    BookingOperator->>Booking: Save Booking
    Booking->>DB: Commit Booking-owned fields
    Booking->>DB: Current compatibility changes order/item/lot/allocation
    alt compatibility complete
        DB-->>BookingOperator: Booking result, child reread still required
    else partial/hidden failure
        DB-->>BookingOperator: Booking may appear saved
        BookingOperator->>AllocationOwner: Reconcile exact child IDs
        AllocationOwner->>DB: Read allocation and source balances
        AllocationOwner-->>BookingOperator: committed / missing / conflict
    end

Target Booking Save must not own this hidden mutation.

---

13. Target Preview And Apply

sequenceDiagram
    actor Operator
    participant React as React Workspace
    participant Next as Next.js Adapter
    participant App as TypeScript Allocation Application
    database DB

    Operator->>React: Select sources and target
    React->>Next: Request preview
    Next->>App: Typed query
    App->>DB: Read source/target/current allocations
    DB-->>App: Fresh rows
    App-->>React: Normalized preview + fingerprint
    Operator->>React: Confirm once
    React->>Next: Apply token + fingerprint + rows
    Next->>App: AllocateInventoryBasket
    App->>DB: Validate token/freshness and begin transaction
    App->>DB: Conditional source consumption + target item/allocation writes
    App->>DB: Commit
    App->>DB: Exact reread
    App-->>React: IDs + before/after balances

---

14. Allocation Relation State

stateDiagram-v2
    [*] --> ACTIVE
    ACTIVE --> CORRECTED: approved correction
    ACTIVE --> REVERSED: approved reversal
    ACTIVE --> CONFLICT: data mismatch detected
    CORRECTED --> REVERSED: later approved reversal
    CONFLICT --> ACTIVE: reconciliation proves active result
    CONFLICT --> CORRECTED: accepted correction
    CONFLICT --> REVERSED: accepted compensation

Current soft-delete compatibility does not automatically define these target semantics.

---

15. Reversal Target

sequenceDiagram
    actor Manager
    participant App as Allocation Application
    participant Downstream as Scale/Packing/Delivery Queries
    database DB

    Manager->>App: Reverse allocation with reason
    App->>DB: Read original allocation, target item and source lot
    App->>Downstream: Read blockers
    alt downstream lock exists
        App-->>Manager: ALLOCATION_DOWNSTREAM_LOCKED
    else eligible
        App->>DB: Begin transaction
        App->>DB: Create reversal evidence
        App->>DB: Restore source balance conditionally
        App->>DB: Mark target item disposition
        App->>DB: Commit and reread
        App-->>Manager: Original + reversal + restored balance
    end

---

16. Target Component Boundary

flowchart TB
    UI[React Allocation Workspace]
    SC[Next.js Server Components]
    RH[Next.js Route Handlers]
    APP[TypeScript Allocation Application]
    POL[Eligibility / UOM / Balance Policy]
    REPO[Repositories]
    DB[(MySQL)]

    UI --> SC
    UI --> RH
    SC --> APP
    RH --> APP
    APP --> POL
    APP --> REPO
    REPO --> DB

No worker is required for the local core transaction.

---

17. One-Writer Migration

sequenceDiagram
    participant Selector as Cohort Selector
    participant PHP as PHP Allocation Writer
    participant TS as TypeScript Allocation Writer
    database DB

    Selector->>PHP: Legacy cohort
    Selector->>TS: Migration cohort
    Note over PHP,TS: One writer per request/cohort.
    PHP->>DB: Current Apply
    TS->>DB: Idempotent AllocateInventoryBasket
    alt rollback
        Selector->>PHP: Route new requests back to PHP
        Selector--xTS: Disable new TypeScript writes
        Note over DB: Preserve all committed rows and reconcile in-flight tokens.
    end

---

18. Migration Wave

flowchart LR
    W0[W0 Characterize]
    W1[W1 Typed reads]
    W2[W2 React read-only]
    W3[W3 Shadow preview]
    W4[W4 One-writer Apply]
    W5[W5 Idempotency/reconciliation]
    W6[W6 Correction/reversal]
    W7[W7 Stabilize]
    W8[W8 PHP caller-zero]
    W9[W9 PostgreSQL later]

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

---

19. Diagram Maintenance Triggers

Update these diagrams when any of the following changes:

• source lot eligibility;
• target readiness;
• full/partial behavior;
• target item model;
• quantity/weight/UOM policy;
• basket atomicity;
• idempotency/freshness;
• correction/reversal;
• Inbound/Outbound/Booking interaction;
• target React/Next.js/TypeScript boundary;
• one-writer/rollback/caller-zero;
• PostgreSQL representation.

---

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