Skip to content

Commercial And Service Intake — Source-Reconciled Current Contract

  • Status: COMMERCIAL SOURCE_RECONCILED / SERVICE INTAKE SOURCE_MAPPED
  • Task: NS0-003
  • Current-source revision: 98b3a59d76ce66c3e69788c93aac7e3e08e6edff
  • Profiles: mk-order, ctc-execution
  • Evidence level: repository source/schema/migration/document review
  • Live DB/browser/operator verification: NOT_RUN

1. Authority Decision

The current system contains at least three different intake concepts:

Commercial Agreement
= T_COMMERCIAL_ORDER + T_COMMERCIAL_ORDER_ITEM

Execution Order
= T_LOAD + T_LOAD_ITEM

Appointment / Service / Physical Work Request
= T_TRANSLOAD and related appointment/source records

They are not interchangeable.

A critical terminology collision is:

Booking.SALES_ORDER_ID
-> points to an outbound SALES T_LOAD execution order

not
-> T_COMMERCIAL_ORDER

The target model must use explicit names in APIs and UI to avoid treating an agreement as execution.

2. MK Commercial Agreement

2.1 Current authority

T_COMMERCIAL_ORDER
= agreement header

T_COMMERCIAL_ORDER_ITEM
= material, quantity, UOM, rate and LME line facts

Current header facts include:

  • Purchase or Sales type;
  • order/reference number;
  • counterparty and contact;
  • contract/shipping period;
  • Incoterm, payment and currency;
  • loading/destination port;
  • container intent;
  • estimated total and required documents;
  • opposite-order link;
  • visible status;
  • signatures when schema columns are present.

2.2 Current commands

Current API exposes:

Create Commercial Order
Update Commercial Order
Delete Commercial Order

Create:

  • requires tenant counterparty;
  • requires at least one meaningful line;
  • validates positive quantity, UOM and commodity;
  • can generate POYYYYMMDD-### or SOYYYYMMDD-### under a MySQL lock;
  • writes header and lines in one transaction.

Update:

  • rereads the active agreement;
  • validates the same-tenant counterparty and opposite-type link;
  • can replace line items before execution;
  • blocks type change when active execution exists;
  • preserves existing line items when execution exists.

Delete:

  • blocks when active T_LOAD.COMMERCIAL_ORDER_ID execution exists;
  • clears other agreements pointing to the deleted agreement;
  • prepares attached file cleanup;
  • soft-deletes files, lines and header.

2.3 Current status

Current values:

DRAFT
OPEN
PARTIAL
FULFILLED
CANCELLED

Source review found no automatic transition derived from execution quantity or completion. Current PATCH accepts a listed status without a transition matrix.

Therefore:

commercial status
= current operator-selected label

not proven
= approved lifecycle or derived completion

LINKED_ORDER_ID must refer to a same-tenant, non-self agreement of the opposite type. Current UI favors Purchase -> Linked Sales, while the backend validates only opposite type.

Current source does not establish:

  • one-to-one cardinality;
  • reciprocal link persistence;
  • eligible status;
  • cycle prevention beyond self-link;
  • an approved business completion meaning.

3. Execution Order

Current execution/order authority uses:

T_LOAD
T_LOAD_ITEM

It carries:

  • Purchase/Sales class;
  • inbound/outbound direction;
  • execution status;
  • commercial agreement reference;
  • Booking reference;
  • company references;
  • item quantities/weights/rates;
  • allocation, equipment, scale and transload bridges.

This record is closer to current Fulfillment/Execution than to a Commercial Agreement.

3.1 Commercial bridge

T_LOAD.COMMERCIAL_ORDER_ID
T_LOAD_ITEM.COMMERCIAL_ORDER_ITEM_ID when available

connect execution to commercial intent.

Commercial Agreement commands do not create execution rows. Separate order/bridge paths create or update T_LOAD.

3.2 Post-execution restriction

Once execution exists, Commercial Agreement type, line replacement and delete are restricted. The complete allowed header-edit subset remains a business decision.

4. CTC Service And Appointment Intake

4.1 Current appointment surface

The appointment page is an operational register over T_TRANSLOAD with visible states such as:

Scheduled
Pre-Planned
Arrived
Docked
Transloaded
Warehouse

It exposes check-in, dock, stage, start, complete, undo, document and assignment actions. This is already operational execution, not merely a commercial/service request.

4.2 Appointment block authority

T_TRANSLOAD_APPOINTMENT_BLOCK

stores tenant/billing-company/date-range/timeblock/status rows. Current create:

  • validates company, date range and at least one time block;
  • splits selected weekdays into date ranges;
  • skips an existing active duplicate;
  • inserts active/inactive blocks.

Remove marks matching active blocks inactive.

This table configures availability/reservation constraints. It is not the individual appointment authority.

4.3 Reserved time compatibility

Current source contains company-name-based reserved time rules for specific companies. This is current compatibility evidence, not an acceptable target customer branch.

Target policy should use typed appointment-slot policy and persisted slot facts rather than hard-coded company names.

4.4 Current request/source records

Current CTC intake may reference:

T_CUSTOMER_PO
T_CUSTOMER_PO_ITEM
pickup/load number
billing company
shipper company
commodity
email appointment input
manual Office input

A domestic pickup helper can match a customer PO item and detect prior T_TRANSLOAD use. The exact universal trigger and cardinality remain unverified.

4.5 Service intake lifecycle gap

Current source reviewed in this wave does not prove one independent Service Request aggregate that exists before T_TRANSLOAD.

Therefore:

current service intake
= SOURCE_MAPPED across source/reference + T_TRANSLOAD

target Service Request
= CANDIDATE / OPEN_DECISION

5. CTC/MK Comparison

Dimension CTC current evidence MK current evidence Target representation
Primary intake appointment/service/pickup context Commercial Order and execution Sales/Purchase Order separate intake policies
Commercial authority often PO/reference text T_COMMERCIAL_ORDER header + lines Commercial aggregate
Execution order T_TRANSLOAD/T_LOAD depending flow T_LOAD Purchase/Sales Fulfillment/execution bridge
Price secondary in Booking/service flow line-level rate/UOM/LME accepted commercial snapshot
Appointment central operational surface conditional capability + typed slot policy
Capture actor Office + Loader/field Office commonly typed capture policy
Completion operational states agreement status plus independent execution independent states

6. Target Process Direction

6.1 Commercial

CreateCommercialAgreement
UpdateCommercialAgreement
CancelCommercialAgreement
CorrectCommercialAgreement
LinkOppositeCommercialAgreement
UnlinkCommercialAgreement

Exact commands remain candidates until status/link/correction decisions are approved.

6.2 Service/Appointment

CreateServiceRequest
ScheduleAppointment
RescheduleAppointment
CancelAppointment
CreateFulfillmentFromServiceRequest

T_TRANSLOAD execution should not be silently created by a generic Save unless an approved command explicitly owns that bridge.

6.3 Explicit bridge rule

Commercial Agreement or Service Request
-> explicit CreateFulfillment
-> optional Booking / Scale / Transload / Transport

Prohibited target pattern:

SaveCommercialOrder
-> silently create every execution record

SaveAppointment
-> silently complete physical work

7. Current Gaps

ID Gap Consequence
INTAKE-GAP-010 Sales Order names both agreement and T_LOAD execution concepts target APIs/pages can bind the wrong record
INTAKE-GAP-020 commercial status is operator-selected target transition rules are unapproved
INTAKE-GAP-030 agreement link cardinality/status eligibility is not enforced target link command needs a business decision
INTAKE-GAP-040 service request is not clearly independent from T_TRANSLOAD target intake/fulfillment boundary remains open
INTAKE-GAP-050 reserved slots contain company-name branches typed policy migration required
INTAKE-GAP-060 CTC source trigger varies across PO, pickup, email and manual input one universal trigger cannot be assumed
INTAKE-GAP-070 post-execution Commercial edits are only partly constrained correction policy remains open
INTAKE-GAP-080 appointment slot capacity/status model is not fully reconstructed final AppointmentField contract remains blocked
INTAKE-GAP-090 current role-by-command matrix is incomplete UI action visibility cannot be finalized

8. Lifecycle Result

process.commercial.manage-agreement
= SOURCE_RECONCILED

process.intake.service-appointment
= SOURCE_MAPPED

T_LOAD execution-order bridge
= SOURCE_RECONCILED at boundary level

target Commercial lifecycle
= OPEN_DECISION

target Service Request aggregate
= OPEN_DECISION

target Appointment slot policy
= SOURCE_MAPPED / REQUIRES FOCUSED RECONCILIATION

9. Evidence Sources

app/systems/OMS/commercial-order/api_routes.php
app/systems/OMS/commercial-order/commercial_order_query_helper.php
app/systems/OMS/commercial-order/commercial_order_post_helper.php
frontend/pages/system/OMS/commercial-order/mk-commercial-orders.php
app/systems/OMS/inbound-order/order_reference_helper.php
app/systems/OMS/inbound-order/sales_order_write_helper.php
app/systems/TMS/transload/request_create_helper.php
app/systems/TMS/transload/appointment_slot_helper.php
frontend/pages/system/TMS/transload/appointment.php
.agents/reference/schema.sql
docs/processes/MK_COMMERCIAL_ORDER_WORKFLOW.md

The legacy Process document is secondary evidence; current source is the current-behavior authority.

---

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