Skip to content

MK Trade, Cost, Rate And Document Outputs — Source Authority

  • Status: CURRENT SOURCE-AUTHORITY MAP / POLICY, ROLE, WIKI AND RUNTIME ACCEPTANCE REQUIRED
  • Operating profile: mk-order
  • Current qa baseline: 4f6165bc4c53a7d98b0c246392dd9ed5bd75c21c
  • Detached unrelated Loader candidate: d96498360bb9c3541a1b5f862284596a7ed217b9
  • Family rebuild packet: MK_TRADE_COST_RATE_DOCUMENT_OUTPUTS_CAPABILITY_REBUILD_PACKET.md
  • Family reconciliation: MK_TRADE_COST_RATE_DOCUMENT_OUTPUTS_RECONCILIATION.md
  • Effect boundary: documentation only; no Runtime, DB, provider, Wiki, deployment or Production change

1. Baseline Correction

Several documents in this family were initially labeled:

qa@d964983...

That label is incorrect as a branch statement.

Current Git relationship:

current qa = 4f6165...
d964983... = one detached/unmerged commit ahead of current qa

Commit d964983... changes Loader Assign Work / Clock Out files and does not change the Trade/Cost/Rate/Document source families analyzed here. Therefore:

  • the substantive source analysis remains applicable to current qa@4f6165...;
  • this Source Authority supersedes the inaccurate branch metadata in the family packet, policy, diagrams, Runbook, Wiki projection, evidence and handover;
  • those files must be read as using the current Trade-family source content at qa@4f6165...;
  • no claim is made that d964983... is merged into qa.

If the Trade-family source changes after 4f6165..., the affected packet must be re-reconciled.

2. Authority Rule

This family is not one process and must not be rebuilt as one module or one status.

Trade Summary
= derived read and discrepancy explanation

Export Brokerage
= optional multi-child orchestration and compensation

Outbound Cost
= mutable local AP transaction command

Packing Rate Correction
= source Sales-item rate correction

Packing / Local Invoice / Booking Confirmation / Sales Weight Ticket
= browser output projections

Durable file / email / provider effect
= separate process only when one actually exists

Use the following authority order:

Product/profile intent
-> owning atomic Process
-> accepted business policy
-> current source-reconciled behavior
-> authoritative schema/data
-> operator Runbook and Wiki projection
-> target React/Next.js/TypeScript/repository/worker migration contract

Current source proves implementation behavior. It does not by itself approve:

  • Trade close or claim semantics;
  • accounting classification;
  • Export Brokerage provenance, retry or compensation policy;
  • which AP row is the Outbound Cost row;
  • valid cost/rate ranges;
  • fixed document terms, dates, branding or recipients;
  • print as completion;
  • creation of a durable snapshot/file/email effect;
  • numeric Client/Role branching as target policy.

3. Process Family

Capability Process owner Core result
Trade Summary PROC-OMS-TRADE-SUMMARY-RECONCILIATION-MK explainable read projection by equipment/deal
Export Brokerage PROC-OMS-EXPORT-BROKERAGE-MK one reviewed multi-child create or compensating cancel result
Outbound Order Cost PROC-BMS-OUTBOUND-ORDER-COST-MK one explicitly owned mutable AP transaction and line set
Packing Rate Correction PROC-OMS-PACKING-RATE-CORRECTION-MK exact Booking-linked Sales item rate correction
Packing Document PROC-TMS-PACKING-DOCUMENT-MK current browser Packing/Invoice projection
Purchase Local Invoice PROC-BMS-PURCHASE-LOCAL-INVOICE-OUTPUT-MK current browser Purchase invoice projection
Booking Confirmation PROC-TMS-BOOKING-CONFIRMATION-OUTPUT-MK current browser Booking instruction/confirmation projection
Sales Weight Ticket PROC-BMS-SALES-WEIGHT-TICKET-OUTPUT-MK current browser Sales-order weight projection

The parent order-first composite does not merge these owners. Trade reads several children; Export Brokerage invokes several children; outputs read current children. None becomes a universal completion owner.

4. Current Source Families

4.1 Trade Summary

Source Current responsibility
app/systems/OMS/trade-summary/api_routes.php read-only list/detail and deal-ledger aliases under oms.trade-summary
app/systems/OMS/trade-summary/trade_summary_query_helper.php list/detail source joins, AP/AR totals, derived status, paging and source-class calculation
current Trade Summary / Deal Ledger page filters, row/detail rendering and browser CSV export
V_EQUIPMENT_DEAL_LINK current equipment-to-inbound/outbound bridge used by the query
T_EQUIPMENT, T_LOAD, T_LOAD_ITEM, T_BOOKING, T_TRANSACTION, T_TRANSACTION_LIST current source rows contributing to the projection

Current facts:

  • the API is read-only;
  • /oms/trade-summary* and /oms/deal-ledger* are aliases;
  • page and API module keys can differ in current metadata;
  • DEAL_STATUS is derived, not persisted;
  • any absolute AP or AR total of at least 0.005 currently derives CLOSED;
  • otherwise ETA/ETD/SWB evidence can derive SHIPPED, else OPEN;
  • CLAIMED is a filter on negative margin plus amount presence, not a stored state;
  • equipment AP/AR includes only selected transaction statuses;
  • outbound-order AP is added through a different source expression and can use different status/deleted-row behavior;
  • detail lines do not expose every source class used by header totals;
  • browser CSV is a local projection export, not settlement, accounting close, file retention or provider delivery.

4.2 Export Brokerage

Source Current responsibility
app/systems/OMS/export-brokerage/api_routes.php feature gate, Booking lookup, AI proposal extraction, child create, cancel/compensation and markers
app/systems/OMS/inbound-order/mk_post_helper.php current Purchase/Transload/Lot/Allocation child operations used by orchestration
app/systems/TMS/delivery/post_helper.php current equipment/container-related child operations
EXPORT_BROKERAGE_WORKFLOW_ENABLED tenant feature gate
[EB:generated] equipment marker current compatibility provenance for generated equipment shells
[EB:generated-booking] Booking marker current compatibility provenance for generated Booking cleanup

Current facts:

  • no dedicated Export Brokerage Job table or stable Job ID exists;
  • create and cancel execute inside bounded local DB transactions;
  • create can materialize Purchase, item, Transload, Inventory Lot, Outbound order/item, Equipment/Equipment Load, Booking relation and Allocation children;
  • generated-equipment and generated-Booking markers exist, correcting older no-marker documentation;
  • returned child IDs are the immediate result handle;
  • AI extraction is proposal input and does not authorize Create;
  • child authority remains with Commercial/Inbound/Outbound/Booking/Inventory/Allocation/Scale owners;
  • current cancel is compensation, not general delete, and is blocked by progressed child evidence;
  • unknown Create/Cancel response still requires child search before retry because no durable request token/result query exists;
  • the existence of a generated-Booking marker constant does not prove which current Create path generated a Booking; controlled source/Runtime characterization remains required.

4.3 Outbound Order Cost

Source Current responsibility
app/systems/OMS/outbound-order/cost_helper.php Outbound assertion, AP query, mutable-state guard, header normalization, replace-all lines, create/update/delete
Outbound order API routes /api/oms/outbound-orders/{id}/costs read/write adapter
Outbound Detail cost UI displays and edits one selected/latest cost transaction
T_TRANSACTION, T_TRANSACTION_LIST local AP header and lines
T_FILE and transaction-document owner independent file object/link lifecycle

Current facts:

  • no durable Outbound-Cost subtype/discriminator exists;
  • helper queries active AP transactions linked to the Outbound order;
  • if no transaction ID is supplied, the latest matching AP row can become the write target;
  • CREATED, OPEN and DRAFT are mutable; CONFIRMED and CLOSED are blocked;
  • update replaces the complete line set in one local transaction;
  • omitted header fields can be defaulted or cleared by submitted payload;
  • no optimistic version, idempotency token or source fingerprint exists;
  • files are not part of cost delete/restore;
  • Trade Summary can consume mutable outbound AP under a source rule that differs from equipment AP/AR.

4.4 Packing Rate Correction

Source Current responsibility
frontend/pages/system/TMS/booking/mkPackingList.php invoice-mode rate UI and transient amount presentation
app/systems/TMS/booking/api_routes.php::tmsBookingApiUpdatePackingListRates() Booking-linked Sales-item RATE update
T_LOAD_ITEM.RATE persisted source rate

Current facts:

  • only RATE is durable; browser-edited Amount is transient;
  • request can contain multiple item IDs;
  • invalid, foreign, deleted or wrong-Booking IDs are silently skipped;
  • if at least one row updates, response can report success even when other intended rows did not update;
  • rate is cast to float; no accepted zero/negative/range policy is enforced here;
  • no expected old rate, version, request token, correction history or exact server readback exists;
  • blur autosave can race with print/render.

4.5 Browser Output Projections

Packing Document

Current sources:

  • frontend/pages/system/TMS/booking/mkPackingList.php;
  • app/addons/reports/query_helper.php::packing_list();
  • Booking, Outbound Sales, Equipment Load, Equipment Commodity, company and rate rows.

Current facts:

  • direct page requires login and requirePageRoleAccess('mkPackingList');
  • report helper still contains a deployment-local CLIENT_ID === 2 branch;
  • one missing equipment-commodity set can switch the complete output to Outbound-item fallback;
  • several terms/ports/currency/date values are template constants;
  • textarea and amount edits are transient;
  • print is browser-only;
  • no current MK file, email, approval or print-acknowledgement effect is created by this page.

Purchase Local Invoice

Current sources:

  • frontend/pages/system/BMS/invoice/localInvoice.php;
  • app/addons/reports/query_helper.php::purchase_local_invoice();
  • Purchase order/items and shipper company.

Current facts:

  • page starts a session and applies MK document config gate;
  • inspected source still lacks an explicit page-role check;
  • invoice number is the current order-number label, not an independent invoice record;
  • totals are calculated from current item quantity/weight/UOM/rate plus trucking fee and credit;
  • every open recomputes from current source;
  • browser print creates no invoice/file/approval/acknowledgement state;
  • direct-page and V2 read gates are not proven equivalent.

Booking Confirmation

Current sources:

  • frontend/pages/system/TMS/booking/bookingConfirmation.php;
  • app/addons/reports/query_helper.php::booking_confirmation();
  • Booking/company/optional Sales-reference data.

Current corrections:

  • current direct page explicitly calls requirePageRoleAccess('bookingConfirmation');
  • older documentation saying page-role behavior was only unverified is stale;
  • page renders current-date and template-derived content without durable version;
  • linked Sales order number can replace displayed PO context;
  • print is browser-only and does not confirm/approve Booking.

Sales Weight Ticket

Current sources:

  • frontend/pages/system/BMS/scale-ticket/scaleticket.php?ORDER_ID=...;
  • app/addons/reports/query_helper.php::sales_weight_ticket();
  • Sales order/items, Booking/company and outbound equipment links.

Current corrections:

  • current physical IDS[] branch is role-, tenant- and active-row-scoped;
  • ORDER_ID branch remains a separate Sales-order projection, not Physical Scale evidence;
  • it can render without a physical T_SCALE_TICKET;
  • mixed UOM values can be aggregated without accepted conversion;
  • print is browser-only and creates no durable output state.

5. Cross-Family Completion Boundaries

Trade row displayed
!= source reconciled
!= accounting close
!= settlement

Trade CSV downloaded
!= durable file
!= QBO/provider delivery

Export Brokerage create returned
!= every child reconciled
!= safe to retry after response loss

Outbound Cost saved
!= accounting confirmed/closed
!= file lifecycle complete

Packing rate response succeeded
!= every intended item updated
!= rendered document refreshed

Packing / Local Invoice / Booking Confirmation / Sales Weight Ticket rendered
!= source approved
!= printed successfully
!= file retained
!= emailed
!= business process completed

6. Current High-Risk Gaps

  • TCRD-GAP-001: Trade header/detail source coverage mismatch.
  • TCRD-GAP-002: derived Trade labels can be mistaken for authoritative state.
  • TCRD-GAP-003: Export Brokerage has no durable Job/request/result identity.
  • TCRD-GAP-004: Outbound Cost target ownership is ambiguous.
  • TCRD-GAP-005: Packing Rate response can be business-partial.
  • TCRD-GAP-006: current outputs are nondurable browser projections.
  • TCRD-GAP-007: output access/configuration differs by page/API.
  • TCRD-GAP-008: profile policy remains hardcoded in report composition.

7. Target Ownership Map

React Trade Reconciliation View
-> Next.js query adapter
-> TypeScript Trade Projection Query
-> read repositories only

React Export Brokerage Workspace
-> Next.js adapters
-> TypeScript Export Brokerage Application
-> explicit child owner commands
-> durable request/job/result identity

React Outbound Cost Editor
-> TypeScript Outbound Cost Application
-> typed AP ownership policy

React Packing Rate Editor
-> TypeScript Rate Correction Application
-> expected-value/version/per-item readback

React Document Preview
-> typed document projection query
-> optional separately approved snapshot/file/delivery application

Target UI/adapters do not own source mutation, accounting close, compensation or durable delivery.

8. Caller And Consumer Disposition

Before migration inventory at least:

  • Trade Summary and Deal Ledger routes, aliases and CSV callers;
  • Export page, AI extraction, Create/Cancel and child helpers;
  • Outbound Cost UI/API, generic transaction/file consumers and Trade Summary;
  • Packing rate autosave and every source-rate consumer;
  • direct document URLs, popup/menu links, print buttons and help links;
  • report helpers and template assets;
  • adjacent File/Email/provider actions that are not owned by the output.

Do not retire a direct URL or helper until stable Wiki/current application links, parity, replacement entry and static/runtime caller-zero are verified.

9. Evidence Boundary

This source map does not prove:

  • current target-role page/API/record access;
  • accounting approval of formula/status/rate/cost policy;
  • Export runtime child parity or compensation;
  • browser print custody;
  • current T_WIKI_PAGE content;
  • Production behavior;
  • migration readiness.

Those remain separate Process, role, browser, DB, accounting and field evidence.

---

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