Software Detailed Design (SDD)¶
0. Document Control And The Detailed Design Boundary¶
| Item | Baseline |
|---|---|
| Document ID / type | SPEC-SDD / Software Detailed Design |
| Upper contract | the SRS requirements and the SAD boundary are made concrete at the implementation unit |
| Repetition unit | the module, component, command and query, function and transaction |
| Excluded | the approval of a requirement itself, the physical DB dictionary, an external contract original, and screen-only detail |
| Currency | the implementation symbol and revision and the source-confirmed, target and TBD state are stated |
| Meaning of complete | authoring the detail card, implementing, testing, and the real acceptance are judged separately |
No fictitious class, algorithm or state is created, and the current source owner is linked first. A shared design is not duplicated into one area, and when there is an exception the difference and the basis are recorded.
1. Purpose And The Detailed Design Unit¶
It makes the module responsibilities of SAD concrete as real commands, queries, processing, transactions and error recovery. This document owns the system-wide shared design and the per-area detailed design contents. An existing contract next to the code is linked as a detail section and is not copied. The basis is the Module Registry and the real existing documents below, and it does not mean every README is a completed SDD.
2. Shared Processing Design¶
The responsibility is separated in this order: the screen and HTTP input → the authenticated execution context → the input, authority and source relationship validation → the owning module command and query → the DB adapter → the result or error. A public input and an internal compatibility identifier are not mixed. The UI does not create and confirm a save result by itself.
The transaction boundary is recorded per command. A duplicate request, a version conflict, a lost response and a partial success are not merged into the same failure. When the result is unconfirmed, the query and retry method follows the contract of that command. It is not assumed that every command has the same idempotency key or the same retry count.
3. Per-Area Detailed Design Sections¶
| Area | What is made detailed in this section | Existing basis and current document state |
|---|---|---|
| Administration, access and settings | the authentication and authority decision, and the settings application, revision and recovery | Policy contract; the full SDD organisation is incomplete |
| Master data | the query and change responsibility, and the effect of a change during a reference | Master data; the full SDD organisation is incomplete |
| Trade | the order, item and price snapshot and the execution link | Commercial; the full SDD organisation is incomplete |
| Inbound and outbound | the execution order, source, quantity and result processing | Fulfillment; the full SDD organisation is incomplete |
| Field work and Transload | the assignment, the work result, the correction and the source relationship | §5 detail written; the real role and DB acceptance is NOT_RUN |
| Weighing | the ticket creation, correction, void and evidence consumption | §6 detail written; the device, role and DB acceptance is NOT_RUN |
| Inventory and warehouse | the lot, ledger, placement, allocation, reversal and concurrency | §7 and Receipt detailed design written; the real full C2 acceptance is NOT_RUN |
| Transport and Booking | the reservation and transport commands and the output source query | Booking detailed design partially written; the other transportation detail is unwritten |
| Equipment and yard | the equipment assignment, location, return and photo link | Equipment lifecycle; the full SDD organisation is incomplete |
| Documents and output | the source projection, overlay, render and output | Documents; the full SDD organisation is incomplete |
| Billing and settlement | the source and unit price calculation, finalisation and follow-up change | Settlement; the full SDD organisation is incomplete |
4. Transportation Area — Booking Detail Linkage¶
The normal save, conflict, unconfirmed result, copy and Packing processing of Booking are owned by the existing Booking design for that section. The body is not copied again into this system SDD. The HTTP data shape is Interfaces, the meaning of a field such as the company or the weight is Data, and a real observation is distinguished from Tests.
4.1 Current Implementation Detail Entry Points¶
| Area | The public and assembly boundary | The save and query boundary | The confirmed processing rules and the incomplete parts |
|---|---|---|---|
| Administration, access and settings | workspaceSession.ts, identity-access, policy and platform-administration |
platform-administration DB adapter | the session user, tenant and role are re-read; the typed context is applied only on a selected path |
| Master data | the master-data public contract and the shared options | company/commodity/master adapters | the same tenant reference check is confirmed only in some commands; removing the generic mutation is incomplete |
| Trade | commercial/src/public.ts, semanticTradeRoutes.ts and the bootstrap tradeData.ts |
commercial-write.ts, commercial-read.ts |
a header and lines transaction, with a type, line and delete restriction when an execution exists; the state transition is undetermined |
| Inbound and outbound | the fulfillment public command, semanticTradeRoutes.ts and useFulfillmentWorkspace |
fulfillment-write.ts |
the policy decision of create and an explicit source; a normal Save does not call Receipt or Allocation |
| Field work | operations transload.ts, semanticTransloadRoutes.ts |
the writers that transload-read.ts delegates to |
the completion writer is a lock, commit and read-back; a proof failure can be WRITE_RESULT_UNKNOWN |
| Weighing | the scale public.ts and the bootstrap tradeData.ts |
trade-public.ts→scale-evidence.ts→writer |
the ticket save is separated from the correction and reversal and the Receipt mutation |
| Inventory and warehouse | the inventory public commands and the fulfillment receipt action | the trade/inventory-write.ts family |
the Receipt, Lot, Placement and Allocation writers are separated, and the unknown read-back rule is partly implemented |
| Transport and Booking | the transportation public contract and the semantic Booking routes | company-booking/legacy transportation adapters | the native UUID, tenant and CAS, clone and Packing contract refers to the existing Booking SDD |
| Equipment and yard | the equipment-lifecycle public and fleet contract | yard/equipment DB adapters | the equipment identity and mirror are separated from the Yard occupancy and queue; the whole correction owner is incomplete |
| Documents and output | the documents src/public.ts |
owning module read projection | the return is PREVIEW or RENDER_ONLY; there is no issue, save or send mutation |
| Billing and settlement | the settlement src/public.ts and tradeData.ts |
settlement-projection.ts |
a source line calculation and a difference read model; there is no posting or payment |
The file names follow the current product root. The entry point table is a map for finding code, not a completed algorithm description of each area. When the detailed design changes, the trace goes from the real caller to the DB and provider boundary.
5. Field Work Area — Transload Detailed Design¶
| SDD ID | The command family and the current owner | The processing, transaction and read-back | The open item and the forbidden interpretation |
|---|---|---|---|
| TRN-SDD-01 | Plan Preview and Apply — semanticTransloadRoutes.ts → operations → planner writer |
the tenant target and the Reload, Unload, Transload, Other and Domestic types are validated and up to 10 deduplicated Forklift Operators are stored; an active SCHEDULED or STARTED plan is updated, and otherwise a SCHEDULED plan is created and then re-read | saving a plan is not interpreted as an assignment acceptance or a work start |
| TRN-SDD-02 | Assignment Submit — the Transload route, public and DB owner | the UUID loader is resolved and the queue order is stored, and AUTO_PLANNED or STAGING moves to DOCKED; an unassign releases the assignment and the plan applied value, and then re-reads | the target canonical of SPECIAL_INSTRUCTION, COMMODITY_NAME and FINAL_DRAFT and the ASSIGNMENT_DATA JSON is unresolved |
| TRN-SDD-03 | Check-in, Staging and Dock — the dedicated Transload command | Dock-in confirms a dock-eligible Yard, closes the active warehouse placement, syncs the planner and commits DOCKED; Cancel is only allowed before the start and releases the occupancy to return to AUTO_PLANNED; After Clear creates a dedicated queue | the Yard queue and the real Yard and warehouse occupancy are not merged into the same fact |
| TRN-SDD-04 | Start Transloading and Unloading — the start writer | the current state is locked, and Transload claims the available loading equipment while Unload claims the active warehouse placement; the planner STARTED and the staff job event are recorded and the authoritative Transload is returned | on an equipment or placement claim failure it is not shown as a completed start |
| TRN-SDD-05 | Complete Transloading — the completion writer | the final equipment, 5 TRANSLOAD photos, the bale result, the seal and the quantity are validated, and the terminal transload and equipment, the planner and staff time, and the placement and Yard close are fixed in a transaction and then re-read |
a DB completion is not expanded into an Office confirmation, a provider success or a settlement completion |
| TRN-SDD-06 | Complete Unloading and Space Review — the completion writer and the Inventory owner | it requires an active warehouse location, materialises the purchase lot and then hands over to the Inventory placement; an overflow is judged as a separate Complete + Space Review result |
when the Lot and Placement follow-up result is unclear, the whole completion is not blindly replayed |
| TRN-SDD-07 | Undo and No Show — the dedicated correction writer | Undo compensates the planner, the time and the per-step equipment, placement and Yard within the range ARRIVED→SCHEDULED, DOCKED→ARRIVED, work in progress→DOCKED and UNLOADED→DOCKED; No Show clears the plan, the queue and the terminal inventory and placement in an allowed state and then re-reads | it is not a cascade rollback of every child effect, and returnToAutoPlanned is a chosen command |
| TRN-SDD-08 | Spare, Leftover, Domestic, Scale and Document — each dedicated command | the input, the state and the follow-up owner are each validated, and the exact record and effect are read after the commit | they are not merged into a generic update adapter, and a provider failure is not changed into a physical work failure |
Every mutation is based on the order DB lock and guard → owning writes → commit → authoritative re-read → attempt the external effect. When whether it committed is unclear, T_TRANSLOAD, the planner, the equipment and load, the warehouse and Yard, the staff time, and the file and event are read from the relevant owner, and only the unconfirmed step is resumed. This design records the current source boundary, and the real C1 and C2 role, DB and provider acceptance keeps the NOT_RUN state of Tests.
6. Weighing Area — Scale Detailed Design¶
| SDD ID | The command and owner | The processing, transaction and read-back | The failure and open item |
|---|---|---|---|
| SCL-SDD-01 | Create Ticket — the Scale public → the evidence adapter → the writer | the UUID, the tenant and the Fulfillment Order direction and commodity are validated, and the first GROSS or TARE axle readings, the ticket number and the source order link are stored in a transaction, and then the exact summary is re-read | the same UUID with the same intent recovers, and a different intent is an IDEMPOTENCY_CONFLICT |
| SCL-SDD-02 | Link Bridge — the create transaction | inbound links only the empty Scale link of the most recent target T_TRANSLOAD and outbound links only that of T_EQUIPMENT_LOAD, and updates T_LOAD.TICKET_NUMBER |
a link is not a consuming work completion or a transfer of ownership |
| SCL-SDD-03 | Record Stage — the stage writer | the current ticket snapshot is read, the same stage and value is IDEMPOTENT, a missing first stage is blocked, and a correction before completion requires a reason; a CAS update, the correction event and a re-read follow | a completed ticket blocks a normal reweigh; on gross<tare the transaction rolls back |
| SCL-SDD-04 | Evaluate Evidence — weight-evidence.ts |
the 5-axis totals of the two stages are used to compute INCOMPLETE, INVALID, GROSS_BELOW_TARE, ZERO_NET and VALID with the net and readyForReceipt | the calculation is not a Receipt completion command and there is no quantity conversion |
| SCL-SDD-05 | Editor Create and Update — the editor writer | the direct ticket fields, up to 3 bad bales and the signature are stored; an update requires an expectedUpdatedAt CAS, a weight and time change remark, a downstream reversible guard, and a before and after event |
the real role and device provenance acceptance of the direct edit path is NOT_RUN |
| SCL-SDD-06 | Void and Reversal — the reverse writer | the expected lifecycle and reason, the snapshot and the downstream guard are validated; FIRST_STAGE is TICKET_VOID and COMPLETE is TICKET_REVERSAL, and after the soft-delete, event and link release the exact reversal is read back |
when a finalised consumer exists it is SCALE_REVERSAL_BLOCKED; a consuming ledger is not reversed automatically |
| SCL-SDD-07 | Receipt Evidence Lock — the Scale evidence adapter | the exact ticket is read with a shared lock, and only when it is VALID is the Inventory owner callback run inside the same transaction boundary | this does not mean Scale becomes the Lot writer, and the schema readiness and the Receipt result are judged by the Inventory owner |
| SCL-SDD-08 | Unknown and Conflict Recovery | the ticket UUID, the stage snapshot, the event reason and request, and the linked consumer are re-read per owner | a blind replay of the whole create, stage or reversal, or of a downstream physical action, is forbidden |
The current event writer records the before and after axle weights, the stage time, the reason, the actor, the request ID and the LB input, canonical and display values. This is a fact of the current adapter, not an approved multi-UOM conversion design. The precision and rounding and the device and offline capture stay unresolved.
7. Inbound And Inventory Area — Inventory Detailed Design¶
The existing Receipt design states that the inbound finalisation and the location placement are separate transactions. Therefore a placement failure does not mean an inbound rollback, and the recovery is designed to keep the identifier of an already created receipt. This case is not applied wholesale to every area, and the commit and follow-up effect boundary of each command is written. An existing model test result is distinguished from a real C2 execution result.
| SDD ID | The command and transaction | The authoritative result | The recovery and open item |
|---|---|---|---|
| INV-SDD-01 | Finalize Receipt: the source and item, remaining, policy, evidence and placement UUID are validated, then the Lot and Ledger are committed | exact Lot identity, received/remaining quantity·weight, lineage·receipt version | it is separated from a normal order save; a duplicate source guard |
| INV-SDD-02 | Place Lot: after the Receipt commit a separate Placement owner can run | a read-back of the active placement and location of the same Lot UUID | on failure a new Receipt or Lot is not created and only the placement is resumed |
| INV-SDD-03 | Correct and Reverse Receipt | the lot UUID, version, lineage and the follow-up allocation and placement are validated, and the ledger and correction evidence are preserved | all inventory is not treated as zero or closed from the source terminal state alone |
| INV-SDD-04 | Apply Allocation | the target execution and equipment and the active Lot and balance are validated → the target item → the allocation relation → a conditional decrease of the remaining net weight → a workbench re-read | a partial application is allowed; there is no immediate quantity deduction; the durable request token is undetermined |
| INV-SDD-05 | Reverse Allocation | the Allocation UUID, the target item and the follow-up equipment and execution guard are applied, and after the Lot balance, ledger, target and container are re-aggregated it is re-read | it is separate from a Receipt reversal; when the response is lost the same intent is recovered with a reversal marker |
| INV-SDD-06 | Direct Container Loading | the selected Container, time and allocation payload in the trade-inventory profile are processed as an owner command | it is not replaced by a Brokerage unlink or a normal Outbound line delete |
| INV-SDD-07 | Balance, Status and Placement reconciliation | the Lot, the active placement, the ledger, the allocation relation and the target and container are compared per owner | the quantity, weight and UOM, the OPEN, PARTIAL, HOLD and CLOSED, and the reopen policy are unresolved |
| INV-SDD-08 | Cost, Document and Billing boundary | the rate snapshot and the Packing, Invoice, Billing and Settlement source are connected as a read projection | the Inventory Cost Layer and landed cost are unimplemented; a reversal does not automatically cancel a document or a billing |
7.1 Core Transaction And Recovery Design¶
| Command family | The transaction and commit boundary | The unconfirmed result and correction handling |
|---|---|---|
| Commercial create and update | the header and lines are written in the same transaction and the authoritative detail is returned | the same request identity and the whole detail are compared; when an execution exists the line and type changes are restricted |
| Fulfillment create and update | the owner transaction of the execution order and the lines | the source relationship and the policy are re-verified; Receipt and Allocation are separate commands |
| Transload complete | a scoped record lock, the completion mutation and the commit, then the owning record and effects are re-queried | the commit and the provider and event results are separated; Undo compensates only the named children |
| Scale accept, correct and void | a separate transaction of the Scale ticket and event owner | the ticket and event are re-queried first, and the consuming work is reconciled separately |
| Receipt and Placement | the Receipt, Lot and ledger commit and the chosen location placement can be a separate transaction | the Lot, Placement and ledger are re-queried and only the missing step is resumed with the same receipt identity |
| Allocation apply | the target and source validation, the target line and relation, and a conditional decrease of the remaining weight | the target line, allocation and source balance are re-queried together; a blind replay is forbidden |
| Booking save and clone | a tenant-scoped Booking transaction, and an update uses a ROW_VERSION CAS |
the exact Booking read-back and the clone receipt relationship are confirmed; the detail is the existing SDD |
| Document render | a read-only projection and an in-memory render | a render failure is not changed into a source save failure or a provider failure |
7.2 Per-Client Detailed Design Application¶
C1 describes the compatible behaviour based on the real call, table and state of the Legacy adapter, and C2 compares the reference and mkmetal with the native implementation. A difference is shown as a policy, input or source relationship, and no separate module or writer is created for a customer name. The current C1 internal transportation and Yard detail and the C2 external carrier candidate are not merged into the same state machine.
8. Authoring Items Of Each Detail Section¶
Each area section repeats the card below per command, query or independent component.
| Field | Authoring criteria |
|---|---|
| Design ID and requirement ID | a bidirectional link between SRS, BR and AC and the implementation symbol |
| Responsibility, caller and dependency | the public contract, the real caller, and the allowed and forbidden dependency |
| Input, output and validation | the type, the required and default, the boundary, the return and error, and the sensitivity |
| Processing order and algorithm | the steps, the branches, the calculation and rounding, and the state change |
| Transaction and concurrency | the read and write set, the lock or CAS, the commit, and the idempotency and duplicate handling |
| Failure and recovery | the validation, conflict, unknown and partial result and the authoritative read-back |
| Security and observation | the tenant and action validation, the audit, log and metric, and the exclusion of secret information |
| Test and change impact | the unit, integration and runtime test case, the evidence, and the affected document and consumer |
9. Implementation Handover And Design Review¶
The detailed design review checks a missing upper requirement, a duplicated owner, an incomplete effect outside a transaction, a concealed error, and a broken previous Client contract. On a change it records the affected API, field, state, screen, test and operational procedure, and it does not declare a design or acceptance complete from the existence of code alone.
It is written in this order: the responsibility and non-responsibility → the caller and the public contract → the input, output and precondition → the algorithm and branches → the read and write record and the writer → the transaction and concurrency → the error, duplicate, lost response and recovery → the follow-up impact → the test and RTM. The per-Client basis and the difference from the current implementation are stated. A list of code files does not replace the detailed design.¶
Source:
new-system/docs/specifications/SDD.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.