System Interface Specification¶
0. Document Control And Linkage Scope¶
| Item | Baseline |
|---|---|
| Document ID / type | SPEC-IF / Interface Specification |
| Targets | HTTP API, internal public contract, event and message, webhook, file and batch, provider and device |
| Ownership | the provider and consumer, the direction, the work owner and the trust boundary are stated |
| Version | contract, schema and version are separated from compatibility and deprecation |
| Security | authentication, authorisation, tenant, sensitive data and transport protection are recorded |
| Evidence | mock, contract, real-integration and operational results are judged separately |
The endpoint, payload and error examples in the template are not real contracts. Only values confirmed in the current route, symbol or schema, or in an approved external contract, are used.
1. Scope And Boundary¶
It separates the contracts of the user screen and the HTTP API, module command, query and event, and files, documents, AI, devices and external providers. It defines the input, response, authority, error, retry and effect for each boundary of SAD. A list of APIs alone, or a list of Booking endpoints, is not treated as the whole linkage specification.
2. Common Interface Contract¶
The public identifier is a UUID. The tenant and the authority are verified with the authenticated server context and the target record, and are not replaced by a value from the Client input. Queries and commands, and DB saves and external effects, are separated. Error states, response envelopes, idempotency and version follow the contract of each actual interface, and the same specification is not arbitrarily applied to every boundary.
The HTTP address and the source location are also separated. The implementation of /api/bookings is inside the product at apps/web/app/api/bookings/, and the URL /api does not mean that code should be placed in the parent repository api/. The same contract is used after the product root is separated.
3. Per-Area Linkage Contents¶
| Area | Main linkages to define | Follow-up impact and exception scope |
|---|---|---|
| Administration, access and settings | session, user, role, menu and settings commands and queries | authority, valid settings and revision conflicts |
| Master data | company, item, unit and place queries and changes | data during a reference and the query selector |
| Trade | order, item, price and the execution source link | separating a save from a physical fulfilment |
| Inbound and outbound | execution order, inbound finalisation and outbound links | the source, the quantity and the partial effect |
| Field work and Transload | assignment, execution, correction and field material | the link between completion or correction and inventory and equipment |
| Weighing | weighing input, ticket, correction and void | the original evidence and the consumed result |
| Inventory and warehouse | lot queries, placement, allocation and reversal | the remaining quantity, concurrency and an unknown result |
| Transport and Booking | reservation, copy, Packing and transport queries and changes | the Booking HTTP detail is partially written |
| Equipment and yard | assignment, yard movement, return and photos | the equipment state and the file relationship |
| Documents and output | source queries, render, preview, files and dispatch | separating a preview from a real dispatch success |
| Billing and settlement | billing source, unit price, finalisation and settlement queries | distinguishing the amount snapshot, a cancellation and the provider |
The table other than Booking, Transload, Scale and Inventory is the authoring contents of the linkage detail. It does not mean the whole contract is complete; catalog/commands/, catalog/queries/ and catalog/events/ are compared one by one with the public contract of the actual owning module.
3.1 Currently Confirmed Command And Query Interface Families¶
| Area | Commands | Queries and read-back | State and basis |
|---|---|---|---|
| Commercial | create, update and delete an agreement | list, get and options | a public UUID contract and a Web→DB call path exist; some state and correction policy is unresolved |
| Fulfillment | create or update an execution order, explicit Receipt and Allocation actions | order, list and source lookups | a normal Save is separated from Receipt and Allocation |
| Operations | plan, assign, check-in, dock, start, complete, undo, document and contact flags | the execution workspace and loader work | the current action family is confirmed; it is not one universal state machine |
| Scale | capture, accept, correct and void a ticket | ticket and event lookup | the real schema, role and precision of a correction event are unresolved |
| Inventory | confirm a receipt, materialise, move or adjust a lot, apply, reverse or reconcile an allocation | lot, placement, workbench and read-back | the current apply route is confirmed; the whole public reverse and reconcile contract is incomplete |
| Transportation | Booking create, update, clone and link, internal dispatch, and an external milestone candidate | the Booking workspace and the dispatch, driver and external leg | the native Booking detail exists; the Shipment and Leg candidates are unimplemented |
| Equipment | reserve, claim and complete a Yard move, record or correct a return | the Yard queue and map, and the lifecycle and backlog | the current Yard and Return adapter exists; the target command approval is incomplete |
| Documents | render a Booking, Commercial, Fulfillment, Scale or Settlement preview | a scoped source projection | it is render-only and is not an issue, store or send command |
| Settlement | a source reconciliation projection | the AP and AR source and difference | the read model is confirmed; there is no posting or payment command |
The candidate command names here are the target mapping of the existing catalog and do not mean a callable endpoint. Only what is confirmed as a real route, function and payload is recorded as CURRENT in the individual detail.
3.2 Current HTTP And Compatibility Interface Examples¶
| Target | Current interface | Contract caution |
|---|---|---|
| Booking | /api/bookings and the native routes below it; a separate existing compatibility route |
the tenant or client of a request does not change the session tenant; the detail is the existing Booking interface |
| Allocation | GET /api/oms/allocations/workbench, target-shipments, allocatable-lots/search, and POST .../apply |
an Apply must re-read the target line, the allocation and the balance together; a blind retry is forbidden |
| Wiki specification | /wiki/specifications and /wiki/specifications/<document-id> |
the default list is the 9 system documents; area detail is reached by search or an area link; the read path does not duplicate the document authority |
The table above is part of the source-reconciled current routes. The remaining routes are added after comparing them with the real transport owner and the catalog. A C1 Legacy URL is a coexistence compatibility path, and the C2 reference path is not promoted to a common API name.
4. Individual Interface Authoring Items¶
It records the ID, name and purpose, the provider and consumer, the direction and protocol, the endpoint or public function and event, authentication, authority and tenant, the input fields, the response fields, examples, the preconditions and postconditions, errors and timeouts, concurrency, idempotency and retries, the DB and external effects, version and compatibility, and links to tests and requirements. Each field is linked to the meaning in the data dictionary.
5. Transportation Area And External Linkage Detail¶
The current detail of the Booking endpoint keeps the existing specification. The read and write, copy and document contracts of that path are not copied to another area. The real per-provider contracts for files, AI, mail and devices are separate unwritten items, and writing this document is not an approval of a provider call or an external dispatch.
6. Field Work Area — Transload Interface Detail¶
| IF ID | Current operation and route family | Request, response and work boundary | Recovery and open items |
|---|---|---|---|
| TRN-IF-01 | the Transload collection and detail /api/transloads |
the tenant-scoped execution list and detail, and a query of the authoritative record | a query result is not used as proof that a mutation completed |
| TRN-IF-02 | the loading plan preview and apply, and the planning board | the work type, target and up to 10 deduplicated operators are validated and the planner result is returned | saving the plan and the assignment or start are separate |
| TRN-IF-03 | assignment and work assignments | the UUID loader and the queue order are handled, and the assignment and planner are re-read | the canonical target of the two persisted assignment representations is unresolved |
| TRN-IF-04 | check-in, stage, dock, cancel check-in or dock, dock-in after clear, and no-show | the current state and the Yard and warehouse relationships are guarded and the per-command result is returned | the queue and the occupancy are re-read separately; a blind retry of a physical action is forbidden |
| TRN-IF-05 | start, complete and undo | the work type, state, equipment and location, photos and result are validated, and after the commit the authoritative Transload and the effects are returned | on WRITE_RESULT_UNKNOWN, read back per owner and resume only the missing step |
| TRN-IF-06 | spare, leftover, domestic pickup, scale evidence and ticket, and document submitted | the dedicated payload of each action and the owner result are used | the meanings are not merged into a generic update endpoint |
| TRN-IF-07 | completed transloads, the timeline and analysis, and warehouse labels | a read projection for completion, history and output | the projection does not newly confirm the Office confirmation, the Inventory or the provider result |
| TRN-IF-08 | the BOL email and the operation event and provider | the DB work result and a separate attempt and result are returned | on a provider failure a committed physical operation is not answered as a failure |
The implementation of the public route is connected to the Operations public contract in the product at apps/web/app/api/ and in semanticTransloadRoutes.ts. The Client identifier of a request does not change the session tenant, and a public work identifier uses a UUID. The real HTTP status and payload fields are confirmed from the source of each route and recorded in the detail card, and this table does not define an arbitrary common envelope.
7. Weighing Area — Scale Interface Detail¶
| IF ID | Operation and route | Request and result | Guard and recovery |
|---|---|---|---|
| SCL-IF-01 | GET /api/scale-tickets |
date, search, source order and item filters, and a ticket summary page | a Legacy row without a UUID is separated as an omitted count; a list is not proof of a mutation |
| SCL-IF-02 | POST /api/scale-tickets |
the Ticket UUID, the Order UUID, INBOUND or OUTBOUND, the first stage, the 5 axes, and reference, equipment, tractor, driver and remark → an authoritative summary | the order direction, commodity and tenant are validated, with UUID idempotency and read-back |
| SCL-IF-03 | PATCH /api/scale-tickets |
the Ticket UUID, the stage, the 5 axes and a correction reason → the stage result | the same values are IDEMPOTENT, with a completion, first-stage, reason, CAS and weight-order guard |
| SCL-IF-04 | DELETE /api/scale-tickets |
the Ticket UUID, the expected FIRST_STAGE or COMPLETE, and a reason → a VOID or REVERSAL result | a lifecycle and downstream reversible guard, and an exact reversal read-back |
| SCL-IF-05 | surface=scale-ticket-list with GET, POST, PATCH and DELETE |
editor read, create, update and delete; the snapshot fields, bad bales, signatures and expectedUpdatedAt | bms.scale-ticket and the read and record action; update and delete also use the shared reversal guard |
| SCL-IF-06 | the Scale evidence consumer | the exact Ticket UUID → the locked evidence state and net, or a blocker | only VALID evidence is given to the Inventory Receipt owner command |
| SCL-IF-07 | the Transload, Equipment and Load bridge | a compatibility link of the ticket number and ID | creating and releasing a link is distinguished from a downstream owner mutation |
| SCL-IF-08 | the correction lineage projection | the state, the event count, and the latest type and time | an event schema that is not applied is SCHEMA_NOT_APPLIED, not 0 events |
scaleTicketsRoute decides scale-portal or the editor surface and the scale.ticket.read/record action, then calls the Scale data owner from bootstrap. The HTTP code and the screen message follow the semantic error mapping of the real route, and this document does not define a new common envelope.
8. Inventory And Warehouse Area — Inventory Interface Detail¶
| IF ID | Operation and route | Result and boundary | Recovery |
|---|---|---|---|
| INV-IF-01 | GET /api/inventory-lots and GET /api/inventory-lots/{uuid} |
the tenant lot list and detail, and the balance, placement, allocation and lineage read model | a status filter and the exact detail are distinguished |
| INV-IF-02 | POST /api/receipts/physical |
the Receipt and Lot are finalised with the source and item, quantity, evidence and placement UUID | the Receipt and Placement partial results are read back under the same identity |
| INV-IF-03 | PATCH and DELETE /api/inventory-lots/{uuid} |
a Receipt correction or reversal | a version, lineage and downstream guard; it is not a normal lot delete |
| INV-IF-04 | GET /api/allocations?lotUuid=… |
a query of the target demand eligible for the source lot | the queried list is not the allocation authority |
| INV-IF-05 | POST /api/allocations |
target, source, quantity and net weight → the target item, allocation and balance result | a conditional overdraw guard; a blind replay after a lost response is forbidden |
| INV-IF-06 | DELETE /api/allocations/{allocationUuid} |
an allocation reversal and a lot, target and container read-back | it is separate from a Receipt reversal; a follow-up execution conflict is preserved |
| INV-IF-07 | POST /api/allocations?view=container-loading |
direct Container loading under the trade-inventory profile | a retry of the same container, time and identity; it is separate from a Brokerage link |
| INV-IF-08 | the Packing, Invoice, Billing and Settlement consumers | the Inventory and target source projection | an automatic zero or cancellation after a reversal is not guaranteed, and each consumer is re-read |
It uses the public UUID, the authenticated session tenant and the resolved inbound or outbound policy. The request body does not decide the scale, no-scale or partial policy, and a policy that is unavailable does not let a mutation proceed.
9. Error, Duplicate And Partial Effect Contract¶
| Classification | The result the caller needs | Follow-up handling |
|---|---|---|
| An authentication, authority or tenant denial | a stable error code and no change | a mutation retry is forbidden before the qualification and target relationship is fixed |
| An input or business precondition failure | identification of the wrong field, state or relationship | the user corrects it and resubmits the same intent |
| A version conflict | the current authoritative version or record, or the reload path | after re-reading the latest value, the user intent is reapplied |
| An unconfirmed result | a state that does not assert success or failure | the exact owner record, receipt, event and relationship are re-read, and only the missing command is resumed |
| A provider failure after the DB commit | the success of the owning record is separated from the provider failure | based on the durable attempt and result, only the provider is retried and reconciled |
| Partial success of a composite operation | the completed and the incomplete owner are named | only the incomplete step is executed instead of repeating the whole physical work |
Each individual interface fills in the real status, code and payload in a separate table. The classification above is by meaning, and it does not state that every endpoint uses the same HTTP code.
10. Individual Interface Detail Card¶
| Field | Authoring criteria |
|---|---|
| IF ID, purpose and peer | the provider and consumer, the direction, the transport, and the environment, endpoint, topic or file |
| Operation and version | the method, command or event, the schema or content type, and the compatibility and deprecation policy |
| Authentication and authority | a credential reference, the tenant, action and resource scope, and the sensitive data |
| Request and message | the field, type, required, default and domain, the meaning and mapping, and whether the example is fictitious |
| Response and result | the success status, the body or event, the authoritative result, and a partial success |
| Error and recovery | the code, the user meaning, the timeout, retry and backoff, the idempotency, and the result lookup and compensation |
| Performance and operations | the SLA and SLO, the size and rate, the log, metric, trace and audit, and the runbook owner |
| Verification and traceability | the related REQ, SDD, DATA, SEQ, SCREEN and test case, and the mock and real-integration evidence |
11. Change, Compatibility And Acceptance Review¶
A field, state or error change is checked against the consumer and the previous version, the retry, duplicate and ordering behaviour, and the migration, cutover and rollback impact. An external provider call success is not merged with an internal DB commit, and a contract that was not really integrated stays as source-only or NOT_RUN.¶
Source:
new-system/docs/specifications/INTERFACES.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.