Skip to content

This is an internal working record, not an everyday instruction. It was written while the system was being rebuilt, for whoever maintains it. If you are here to do today's work, use the everyday documents instead: Procedures · Processes · Runbooks · The working day, step by step

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

  • Status: DETAILED SOURCE-RECONCILED INPUT / OWNER AND RUNTIME ACCEPTANCE REQUIRED
  • Operating profile: mk-order
  • Source baseline: qa@d96498360bb9c3541a1b5f862284596a7ed217b9
  • Rebuild packet: MK_TRADE_COST_RATE_DOCUMENT_OUTPUTS_CAPABILITY_REBUILD_PACKET.md
  • Source authority: MK_TRADE_COST_RATE_DOCUMENT_OUTPUTS_SOURCE_AUTHORITY.md
  • Policy matrix: MK_TRADE_COST_RATE_DOCUMENT_OUTPUTS_POLICY_DECISION_MATRIX.md
  • Sequence diagrams: MK_TRADE_COST_RATE_DOCUMENT_OUTPUTS_SEQUENCE_DIAGRAMS.md
  • Effect boundary: documentation only

1. Reconciliation Result

The current family is not a single “Trade Documents” process. It contains four fundamentally different execution classes.

Class Capabilities Current effect
Derived read Trade Summary query and browser CSV only
Composite multi-child command Export Brokerage local DB child create/cancel and compensation
Mutable local commands Outbound Cost, Packing Rate local AP or Sales-item mutation
Nondurable output projections Packing, Local Invoice, Booking Confirmation, Sales Weight Ticket server/browser render and browser print

A future implementation must preserve these boundaries. Combining them in one Next.js route, one status or one “document service” would recreate current authority confusion.

2. Cross-Process Non-Implication Matrix

Current result Does not imply
Trade row shows CLOSED accounting confirmed/closed, provider delivery or settlement complete
Trade filter matches CLAIMED a saved claim state or approved claim workflow
Trade CSV downloaded server file, QBO import, approval or retention
Export Brokerage returned child IDs every child is reconciled or safe to retry
Export cancel returned success every residual pointer/marker/source balance is clean
Outbound Cost saved AP confirmed/closed, files reconciled or QBO complete
Packing rate response says updated every intended item updated or the document reread uses the new value
Packing page rendered file/email/approval/flag exists
Purchase Local Invoice rendered a durable invoice exists
Booking Confirmation rendered Booking is approved/confirmed
Sales Weight Ticket rendered physical Scale occurred or Scale Ticket exists
Browser print dialog opened physical print succeeded, was retained or was distributed

3. Trade Summary Current Reconciliation

3.1 Current read path

Trade / Deal Ledger page
-> GET /api/oms/trade-summary or /api/oms/deal-ledger
-> equipment/order/Booking/transaction joins
-> equipment AP/AR totals
-> outbound-order AP total
-> derived margin/status
-> list/detail/CSV projection

The API performs no business mutation.

3.2 Derived status

Current status function:

abs(TOTAL_AP) >= 0.005 or abs(TOTAL_AR) >= 0.005
-> CLOSED

else ETA or ETD or SWB
-> SHIPPED

else
-> OPEN

Current CLAIMED filter:

MARGIN < 0
and amount exists

These are presentation formulas. They are not durable workflow transitions.

3.3 Source-class mismatch

Current header totals combine:

Equipment-linked AP/AR with selected statuses
+ Outbound-order AP through a different aggregate

Current detail lines emphasize outbound-order transaction rows and do not expose the complete equipment AP/AR contribution used by the header. Therefore:

header TOTAL_AP/TOTAL_AR/MARGIN
may not be reproducible from visible detail lines

Target Trade detail must return a complete source breakdown rather than hiding classes in header-only totals.

3.4 Source and deletion ambiguity

Existing source documentation identifies incomplete soft-delete predicates and MAX-style link attribution. The current target must:

  • exclude or explicitly classify deleted rows;
  • return all candidate Purchase/Sales links;
  • block unexplained multiple-link attribution;
  • return source cutoff and formula version;
  • avoid assigning business completion from projection labels.

3.5 Trade CSV

Current export is browser-local CSV based on the current projection. It has no server file ID, checksum, retained snapshot, approval or provider result.

Safe current recovery:

stale/missing CSV
-> rerun current read
-> confirm filters/source fingerprint
-> export again under human custody

No DB rollback is applicable.

4. Export Brokerage Current Reconciliation

4.1 Current create shape

Current source validates tenant/config, parties/reference, Booking requirements, containers and line values, then performs one bounded local transaction across a child set.

Conceptually:

reviewed proposal/input
-> Purchase order/items
-> Transload
-> Inventory Lot
-> Outbound order/items
-> Booking relation or generated Booking compatibility
-> Equipment/Equipment Load
-> Allocation
-> exact immediate result IDs

The child records remain owned by their processes.

4.2 Current provenance improvements

Current source includes compatibility markers:

[EB:generated]
[EB:generated-booking]

These improve generated Equipment/Booking cleanup compared with the older Process document. They do not provide:

  • a Job row;
  • request idempotency;
  • immutable child manifest;
  • job lifecycle/history;
  • a stable reloadable cancellation handle.

4.3 Create transaction and unknown result

Known server exception:

transaction rollback
-> no child write from that request

Unknown client response:

server may have committed
-> blind retry can create another child set

Safe recovery requires search/reconciliation of every child class before another Create.

4.4 Current cancel

Current cancel validates the specified inbound/outbound set, reference and active allocations, then checks progressed evidence. It can:

  • remove generated allocations;
  • delete generated Outbound children;
  • release compatible generated Equipment shells;
  • remove generated Inbound/Transload/Lot children;
  • release generated Bookings marked by current compatibility provenance;
  • preserve pre-existing Booking/Equipment where policy requires.

It is not a general delete mechanism. Unknown cancel response requires full child reread.

4.5 Remaining provenance and balance risks

  • no durable Job ID/request token;
  • markers are strings in business remarks, not a typed provenance record;
  • manually composed child sets can resemble generated sets;
  • multi-line and lot cardinality may conflict;
  • post-allocation lot synchronization can disagree with allocation balance;
  • progressed child evidence can make compensation unsafe;
  • AI fields remain proposals and may not propagate every source remark/context.

5. Outbound Cost Current Reconciliation

5.1 Current target selection

Current source identifies AP transactions by:

TYPE = AP
RELATED_TABLE_NAME = T_LOAD
RELATED_TABLE_ID = Outbound Order ID

No durable subtype distinguishes Outbound Cost from another AP workflow linked to the same order.

If the command omits a transaction ID, current source can select the latest AP row. Therefore one visible UI row is not enough to prove ownership.

5.2 Current write

Create/update:

assert Outbound order
-> find explicit/latest AP
-> reject immutable state
-> force/default header
-> soft-delete prior lines
-> insert submitted nonzero lines
-> commit

Delete:

assert exact mutable AP
-> soft-delete header and lines
-> files remain separate

5.3 Partial and overwrite risk

  • header metadata absent from the UI can be defaulted/blanked;
  • replace-all lines can remove omitted lines;
  • zero rows are skipped;
  • no expected version or request token prevents lost update;
  • Trade Summary can immediately consume mutable AP under a different classification policy;
  • file links and physical objects are outside the cost command.

Safe current recovery starts with a full inventory of all order-linked AP rows, headers, lines and files.

6. Packing Rate Current Reconciliation

6.1 Current write path

Packing invoice Rate field loses focus
-> PATCH Booking packing-list rates
-> for each supplied Order Item ID:
   validate tenant + active + Booking-linked Sales Outbound
   update RATE when eligible
   silently skip otherwise
-> return updated count

6.2 Business-partial success

A response can succeed when only a subset of intended IDs updated. The current client can clear local dirty state without an independent server reread.

Target must return per-item results or reject the complete intended set according to accepted policy.

6.3 Amount and print race

The browser Amount field can be edited transiently but is not persisted by this process. Rate autosave can still be pending or failed when the operator prints.

Required user rule:

visible amount change
!= persisted source correction

rate response count
!= complete intended correction

7. Packing Document Current Reconciliation

Current flow:

Booking Detail
-> mkPackingList page
-> current Booking / Sales / Equipment / Commodity / Rate read
-> fallback selection
-> browser render
-> optional transient edits
-> browser print

Important current facts:

  • explicit login and page-role check exist;
  • helper still selects MK behavior by numeric Client branch;
  • complete equipment-commodity coverage is required to avoid whole-document fallback;
  • fixed template ports/terms/currency/date can differ from business source;
  • edits in textareas/amount are presentation-only;
  • rate correction is a separate write process;
  • no MK file/email/snapshot/approval state is created.

8. Purchase Local Invoice Current Reconciliation

Current flow:

Inbound Purchase Detail
-> localInvoice direct page
-> current Purchase order/items/company read
-> formula calculation
-> browser render/print

Current formulas:

MT   = NET_WEIGHT * RATE / 2204.590
LT   = NET_WEIGHT * RATE / 2240.000
ST   = NET_WEIGHT * RATE / 2000.000
EACH = QUANTITY * RATE
other = NET_WEIGHT * RATE

Current boundary:

  • no independent invoice ID/lifecycle;
  • displayed invoice number is the order number;
  • every open recalculates from current source;
  • no durable file/print/approval result;
  • current direct page applies session and feature gate but lacks an explicit page-role check in the inspected source;
  • API/direct helper access and class/error behavior need role/config parity evidence.

9. Booking Confirmation Current Reconciliation

Current flow:

Booking Detail
-> role-protected direct page
-> feature gate
-> current Booking/company/optional Sales reference read
-> fixed/derived template
-> browser print

Current correction to older documentation:

requirePageRoleAccess('bookingConfirmation')

is present in current source.

Remaining gaps:

  • no durable confirmation/version/file/approval;
  • current server date changes later renders;
  • optional linked Sales order can replace displayed PO context;
  • special instruction/remark and fixed template semantics require field approval;
  • print result remains human-custody only.

10. Sales Weight Ticket Current Reconciliation

Current order-derived flow:

Outbound Sales order
-> ORDER_ID output helper
-> current order/items/equipment aggregation
-> browser render/auto-print

It is not the Physical Scale ticket owner and does not require a T_SCALE_TICKET.

Current correction to older documentation:

  • current generic physical IDS[] branch is role-, tenant- and active-row-scoped;
  • the ORDER_ID output remains separate and must not be used as evidence of physical weighing.

Remaining gaps:

  • no durable output/file/acknowledgement;
  • mixed UOM can be summed without conversion;
  • multiple equipment values can aggregate;
  • no accepted recipient/retention/replacement policy.

11. Cross-Family Failure And Recovery

11.1 Unknown read/export

query/export failed
-> refresh exact filters/source
-> compare current projection fingerprint
-> export again only after review

No mutation rollback applies.

11.2 Unknown Export Create/Cancel

response missing
-> search request/reference/child markers
-> reread Inbound/Booking/Outbound/Equipment/Lot/Allocation
-> classify committed / absent / partial / unknown
-> retry only a proven absent command

11.3 Unknown Cost write

response missing
-> list all order-linked AP
-> identify typed/intended target
-> compare header/lines/siblings/files
-> retry only a proven absent command

11.4 Unknown Rate write

response missing or mixed count
-> reread every intended Sales item
-> compare expected/current rate
-> retry exact unchanged items only

11.5 Unknown print

print result unknown
-> no DB/provider state exists
-> reopen and reconcile current source
-> human document owner decides replacement/reprint

Do not add automatic print retries or claim completion.

12. Target Decomposition

TradeProjectionQuery
  read-only, explainable source classes

ExportBrokerageApplication
  durable request/job/manifest and explicit child commands

OutboundCostApplication
  typed AP ownership, optimistic concurrency and exact readback

PackingRateApplication
  expected-value correction and per-item result

DocumentProjectionQueries
  deterministic source/template projection

Optional DocumentSnapshot/Delivery Applications
  only after explicit Product acceptance

React and Next.js are adapters, not business owners.

13. Reconciliation Stop Conditions

Stop implementation or migration when:

  • a Trade total cannot be explained by returned sources;
  • multiple source links are silently collapsed;
  • Export Job provenance is inferred from reference alone;
  • an Export unknown result has not been child-reconciled;
  • a Cost target is selected as latest rather than explicitly typed/owned;
  • cost header/line metadata cannot be preserved;
  • rate correction can silently skip intended items;
  • rate source is unresolved when printing;
  • a document template/fallback conflicts with source and no policy owner decides;
  • an output is being modeled as durable completion without Product decision;
  • page/API/record access differs and target role evidence is absent;
  • any target proposal introduces numeric Client/customer branching.

14. Current Evidence Ceiling

Source/process reconciliation: detailed M2 input
Policy acceptance: incomplete
Target-role access: not verified in this wave
Accounting approval: not verified
Export child/balance runtime: not verified
Cost/rate browser+DB: not verified
Document browser/print custody: not verified
Current Wiki content: not read
Publication: not authorized
M4 migration: not established

The packet is detailed implementation input after owner decisions; it is not proof that current Runtime is correct.

---

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