Skip to content

System Behavior Specification — Sequences and States

0. Document Control And Scenario Unit

Item Baseline
Document ID / type SPEC-BEH / Sequence and State Specification
Repetition unit the normal, alternate and failure flow of one user goal or one command/event
Participants the actor, UI/API, the work owner, the DB, an external provider and the trust boundary
State business state, technical processing state and external state are separated
Time timeout, retry, backoff and expiry are fixed numerically only when there is a basis
Diagrams Mermaid is an explanatory model, not an execution trace or operational evidence

The inventory reservation, outbox and payment examples in the supplied package are a format reference only, not the actual CTC design. Write the per-area scenarios after confirming the existing owner and the real messages and transitions.

1. Scope And Notation

It defines the cross-area connections of the whole system, the normal and exception order per command, and the independent state and transition conditions. It links the work requirements of SRS to the processing of SDD and the messages of Interfaces. The shared diagram below is a logical sequence explaining a responsibility boundary, not an execution trace of a specific API.

2. Common Command Processing Sequence

sequenceDiagram
    actor User as Work user
    participant Web as Screen and HTTP
    participant Owner as Work owner
    participant DB as DB adapter
    User->>Web: Work command and the identifier of the record read
    Web->>Owner: Authenticated context and input
    Owner->>Owner: Authority, preconditions and input validation
    Owner->>DB: Per-command change and transaction contract
    DB-->>Owner: Save result or a classified error
    Owner-->>Web: The result and what recovery needs
    Web-->>User: Confirmed result / error / result unconfirmed

A lost response is not the same as a confirmed failure. The follow-up sequence for a duplicate resend, a version conflict or a partial success is written separately in the command in question. Where there is an external effect, the position before and after the DB commit and the records that survive a failure are stated.

3. Per-Area Sequence And State Contents

Area Normal sequence covers Independent state and exception detail covers
Administration, access and settings login, authority decisions, settings application session, settings revision, application failure
Master data create, edit, work reference change during reference, deactivation, duplication
Trade contract, item, price and the execution link commercial state and the actual fulfilment state
Inbound and outbound execution order, finalisation, follow-up result plan, actual, partial success, correction
Field work and Transload plan, assignment, work result field and office path, completion, correction
Weighing measurement, ticket, evidence consumption completion, correction, void and preservation of the original
Inventory and warehouse inbound, placement, allocation, loading, reversal remaining quantity, ledger, location, allocation state
Transport and Booking reservation, copy, document lookup, transport booking state, schedule, independent flags
Equipment and yard assignment, gate in and out, movement, return equipment state and the booking and inventory state
Documents and output source lookup, preview, output, dispatch render success, save and dispatch results
Billing and settlement source aggregation, finalisation, correction distinguishing billing, settlement and payment state

The actual enum and transition table of each row is partially written or unwritten. A shared Completed state or a shared state machine is not created just because the area names are similar.

4. Existing Area Detail

The Booking processing, state and recovery of the transportation area keeps the existing normal save, conflict, copy and output sequences and the state differences per source. Receipt processing in the inbound and inventory area covers separating finalisation from placement, recovering the same identifier, and correction, reversal and follow-up consumption. Neither document is promoted to a whole-system state specification.

4.1 Source-Confirmed State And Independence

Owning record Confirmed current state or flags State that must be separated
Commercial Agreement DRAFT, OPEN, PARTIAL, FULFILLED, CANCELLED execution, receipt, inventory and settlement completion
Transload and Planner T_TRANSLOAD.STATUS, JOB_STATUS, timestamps, assignment and result fields plan save, assignment acceptance, start, field completion, Office confirmation, inventory reconcile, provider result
Scale Ticket and Event the accepted ticket and optional correction, void and reversal evidence Receipt, Inventory, Delivery and Settlement state
Inventory Lot OPEN, PARTIAL, HOLD, CLOSED and the quantity and weight balance Placement, Allocation, Cost Layer and the source terminal state
Delivery SCHEDULED, DISPATCHED, DELIVERED, TROUBLE Yard placement, Container return, provider notification
Yard Queue QUEUED, SCHEDULED, CLAIMED, COMPLETED, CANCELLED the planned or assigned spot and the real T_YARD_LOCATION occupancy
Equipment Load and Container load and terminal compatibility state and the return facts Booking, Shipment, Delivery and Settlement completion
Booking the native detail has no independent status, and the reference uses Active/Closed and SI/BL/AR date projections document submission, Packing, Billing readiness and execution order state
Document PREVIEW / RENDER_ONLY issued, persisted, emailed, printed, financially posted

The current state values are source evidence, not a target transition table. In particular, accepting the listed status of a Commercial PATCH does not prove an automatic transition rule.

4.2 Cross-Area Normal And Partial Result Sequences

sequenceDiagram
    participant C as Commercial/Fulfillment
    participant O as Operations/Scale
    participant I as Inventory
    participant T as Transportation/Equipment
    participant D as Documents/Settlement
    C->>O: explicit execution/source reference
    O-->>C: committed operation evidence
    O->>I: accepted receipt/weight input
    I-->>O: Lot/Ledger/Placement readback
    I->>T: allocated outbound source relation
    T-->>I: delivery/equipment result (independent)
    C->>D: commercial source projection
    I->>D: inventory/fulfillment source projection
    T->>D: booking/transport source projection
    D-->>C: preview or settlement source result

Each call is a separate owner command. On a mid-way failure, do not assume an already committed owner result is cancelled. For example, a Placement failure after a Receipt commit resumes only the Placement instead of recreating the same Receipt. When Pull-Out closing and Yard queue completion are split, read the closing evidence and the queue state separately.

4.3 Per-Area Recovery Order

Area Authority to read first when the result is unconfirmed Simple retries that are forbidden
Commercial the exact Agreement header, lines and source links a create replay without checking the number and lines
Operations the T_TRANSLOAD, planner, equipment and load, time and effect evidence repeating the physical work or the whole completion
Scale the exact ticket and event, then the linked consumer re-running the ticket correction and the Receipt together
Receipt the lot, ledger, placement and source lineage regenerating everything under a new receipt identity
Allocation the target line, the allocation relation and the source balances a blind apply because enough balance appeared to be present
Delivery, Yard and Equipment the Delivery, the queue and location, the equipment and load, and the return evidence, per owner repeating a movement or a return physical action because of a single screen error
Document and provider the source revision, the render result, the file metadata and object, and the attempt and result treating a preview success as a dispatch success, or repeating a source mutation

4.4 Field Work Area — Transload Sequence And State

sequenceDiagram
    participant U as Planner·Loader·Office
    participant W as Transload Web Route
    participant O as Operations Owner
    participant R as DB Owners
    participant X as External Effect
    U->>W: plan/assign/check-in/dock/start/complete/undo
    W->>O: tenant, actor, UUID and the dedicated command
    O->>R: lock + guard + owning writes
    R-->>O: commit + authoritative reread
    O-->>W: the operation result and the independent effect state
    O->>X: event/provider attempt
    X-->>O: delivered or failed
    W-->>U: the DB result and the provider result shown separately
STATE/SEQ ID Start condition and transition Independent facts to check alongside
TRN-STATE-01 Plan Preview or Apply → the planner becomes SCHEDULED, or the active plan is updated do not assume the appointment, the assignment or the work start has changed
TRN-STATE-02 Check-in or Staging → Dock-in → DOCKED check the Yard queue and location, the warehouse placement and the planner sync separately
TRN-STATE-03 DOCKED → START_TRANSLOADING or START_UNLOADING the claimed equipment or load, or the active warehouse placement, the planner STARTED, the staff job event
TRN-STATE-04 work in progress → COMPLETE_TRANSLOADING the final equipment, the 5 photos, the bale result, the seal, the quantity, the terminal Transload and equipment, and the planner, time, placement and Yard close
TRN-STATE-05 work in progress → COMPLETE_UNLOADING or COMPLETE_UNLOADING_SPARE the active warehouse location, the purchase lot materialisation, the Inventory placement, and the planner, time and Transload result
TRN-STATE-06 an allowed step → UNDO ARRIVED→SCHEDULED, DOCKED→ARRIVED, work in progress→DOCKED, UNLOADED→DOCKED, and the compensation stated per step
TRN-STATE-07 SCHEDULED, PRE_PLANNED or ARRIVED → NO_SHOW close the non-dock plan, cancel the inbound queue, the remark, and clear the terminal inventory and placement and the Transload placement
TRN-SEQ-01 DB commit → authoritative re-read → provider attempt a provider failure is not a physical operation failure, and only the resend is a separate recovery

The work state is not one T_TRANSLOAD.STATUS but is spread across the planner JOB_STATUS, the timestamps, the assignment and result, the equipment and load, the warehouse and Yard, staff time, and files and effects. Therefore planner saved ≠ assignment accepted ≠ work started ≠ field complete ≠ Office confirmed ≠ inventory reconciled ≠ provider delivered is used as an invariant of the state specification. returnToAutoPlanned is a choice of Undo and is not decided automatically from a numeric Client value.

4.5 Weighing Area — Scale Sequence And State

sequenceDiagram
    participant U as Scale Operator
    participant W as Scale Portal·Route
    participant S as Scale Owner
    participant D as Scale DB Adapter
    participant C as Downstream Consumer
    U->>W: Create (first stage) or Record (second stage)
    W->>S: tenant, actor, Ticket/Order UUID, the 5 axes
    S->>D: lock/snapshot guard + write
    D-->>S: commit + exact Ticket/event reread
    S-->>W: stage/evidence result
    C->>S: request for the exact Ticket evidence
    S->>D: Ticket shared lock
    D-->>S: gross/tare evidence
    S-->>C: a VALID net, or a blocker
STATE/SEQ ID Input and state Result and independent facts
SCL-STATE-01 Order plus the first GROSS or TARE → FIRST_STAGE the ticket, source link and first stage are stored; Receipt, Transload and Delivery stay incomplete
SCL-STATE-02 FIRST_STAGE plus the opposite stage → a COMPLETE or VALID candidate both timestamps and the 5 axes are preserved and the gross, tare and net evidence is re-evaluated
SCL-STATE-03 a repeat of the same stage and the same weights IDEMPOTENT; no new event and no duplicate physical action
SCL-STATE-04 the same stage with different weights and a reason, before completion a REWEIGH_CORRECTION event and an updated ticket snapshot
SCL-STATE-05 a normal Record stage at COMPLETE SCALE_COMPLETE is blocked; an explicit editor correction or policy path is required
SCL-STATE-06 FIRST_STAGE plus Reverse TICKET_VOID; the ticket is soft-deleted, the event is recorded and the allowed link is released
SCL-STATE-07 COMPLETE plus Reverse TICKET_REVERSAL; when downstream execution exists, SCALE_REVERSAL_BLOCKED
SCL-SEQ-01 a lost response or a conflict re-read in the order exact Ticket → correction or reversal event → consumer owner, and resume only the missing command

The evidence verdict is not the single transition INCOMPLETE → VALID. Invalid or non-finite values, gross<tare and a zero net are each a blocked state, and none of them hides the original stage. The ticket lifecycle and the Receipt, Inventory, Transload, Equipment, Delivery and Settlement lifecycles are independent. When there is no correction event schema, the lineage state is SCHEMA_NOT_APPLIED and is not mistaken for having no history.

4.6 Inventory And Warehouse Area — Inventory Sequence And State

sequenceDiagram
    participant U as Inventory User
    participant I as Inventory Owner
    participant R as Receipt/Lot Writer
    participant P as Placement Owner
    participant A as Allocation Owner
    U->>I: Finalize Receipt(source/evidence/location)
    I->>R: validate + commit Lot/Ledger
    R-->>I: authoritative Lot
    I->>P: establish Placement
    P-->>I: placed or failed
    U->>A: Apply/Reverse Allocation
    A->>R: conditional balance + ledger/relation
    A-->>U: Lot/target/container readback
STATE/SEQ ID Step Independent result and recovery
INV-STATE-01 the source is validated → the Receipt is finalised the lot identity, the ledger and the received and remaining values are created; Placement can be a separate result
INV-STATE-02 the Receipt is committed → the Placement is active or failed on failure, resume only the placement under the same lot and placement identity
INV-STATE-03 an OPEN or PARTIAL lot → Apply Allocation the relation and target item are created and the remaining net weight decreases conditionally; a partial application is allowed
INV-STATE-04 an active Allocation → Reverse the relation tombstone and ledger, a re-aggregation and re-read of the lot balance, target item, order and Container
INV-STATE-05 remaining balance, hold or correction → OPEN, PARTIAL, HOLD or CLOSED the current status is a projection, and the quantity and weight and terminal reopen policy are open
INV-STATE-06 a Receipt correction or reversal the source lineage, the placement, the allocation and the downstream guard, then an exact lot read-back
INV-SEQ-01 a lost response or a partial commit read in the order lot → Placement → Ledger → Allocation → target and container, and resume only the missing owner

An Allocation Apply has no durable request token, so a blind replay with enough remaining quantity can create a duplicate target item and relation. A reversal likewise does not cancel the Receipt, Container, Packing and Billing as one cascade, and reads each owner's state.

5. State Transition Specification Format

It records the state-owning record, the current state, the input command or event, the actor and authority, the guard, the record written, the next state, the independent flags, the forbidden transitions, the state after a failure, the reversal or correction, and the test ID. Where the C1 Legacy, C2 reference and product state values differ, each is mapped and an undetermined mapping is left open.

5.1 Per-Client State Application

The internal Driver, Yard and Transload steps of C1 Legacy and the external carrier and Office-centred flow of the C2 reference are different current bases. Even when the common requirement outcome is the same, the input actor and the intermediate states are described with a profile or policy. One side's state value is not copied to the other Client. A persisted fact of an old record, such as requiresContainerReturn, is not recomputed from a later profile change.

6. Exceptions And Verification Linkage

It writes the sequence for the normal, duplicate, concurrent edit, lost response, follow-up effect failure, partial reversal and permission denial cases in the areas that need them. A case that was not run is linked as NOT_RUN in the test specification. An arrow in the document and a successful execution and recovery in the real environment are separate things.

7. Sequence And State Detail Card

Field Authoring criteria
SEQ/STATE ID and purpose the related REQ, SDD and IF, and the start and end states
Participants and responsibility the owner of the call, response, save and external effect, and the trust boundary
Preconditions and guards the role, tenant, input, version and current state, and the forbidden conditions
Message steps the order, the operation, the payload and result, and the transaction and commit points
Alternates and failures validation, denial, timeout, conflict, unknown and partial result
Duplicates and concurrency the idempotency identity, lock or CAS, the order, and the single winner and re-read
Asynchrony and compensation delivery, retry, reconciliation and manual recovery where an event, outbox or inbox really exists
Observation and tests trace and audit correlation, the test case, failure injection and real evidence

8. Diagrams And Change Review

Source: new-system/docs/specifications/BEHAVIOR.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged. A user instruction quoted inside the text is kept in its original language.