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 / Allocation / Scale — Post-Refresh Operator And Support Addendum

  • Status: CURRENT SOURCE-AWARE REPOSITORY RUNBOOK ADDENDUM / NOT FIELD-ACCEPTED
  • Release source: master@baff406d964b9f785bf98d2ae84cfb262e26f4b2
  • QA integration source: qa@1dfed7d5c827f992e763c63bfca95324a60af387
  • Parent authority: MK_TRADE_ALLOCATION_SCALE_POST_REFRESH_BRANCH_DELTA_2026-08-09.md
  • Phase implementation: USER HOLD

1. Purpose

Use this addendum when the current environment may be running either the released MK source or the QA integration candidate.

The first task is to identify the source lane.

release behavior
!= QA candidate behavior

Do not choose a recovery route merely because it exists in one repository branch or one test script.

2. Before Any Diagnosis

Record:

environment and URL
current date/time/timezone
deployed server SHA
browser asset SHA/cache identity
expected branch lane: RELEASE or QA CANDIDATE
CLIENT_ID and tenant/profile
actor and effective role
page and API route
Order/Ticket/Lot/Allocation/Transaction IDs
request/correlation ID if available
whether any provider/file/device effect is possible

Stop if the environment source is unknown or mixed.

3. Universal Recovery Rule

stop replay
-> reread authoritative local records
-> identify branch-specific command boundary
-> classify committed / missing / partial / conflict / unknown
-> resume only the missing owner step

Never use a second Order, Ticket, Allocation, Transaction or document send to discover whether the first action succeeded.

4. Trade And Reference Procedures

4.1 Date-filtered Trade result contains undated rows

Current released source can keep rows with no ETA and no ETD inside any selected date window.

Operator procedure:

  1. do not assume the row's date falls inside the selected period;
  2. inspect whether both ETA and ETD are missing;
  3. classify it as UNDATED / REQUIRES DATE OWNER;
  4. identify the Booking/Outbound owner responsible for the missing date;
  5. keep the row separate from period totals unless the accepted report policy explicitly includes it;
  6. do not invent a date to make the report look bounded.
visible in date-filtered result
!= dated inside the selected period

4.2 mk-trade-summary and mk-deal-ledger differ

Check:

  • normal menu entry;
  • direct URL;
  • current module-page row;
  • current tenant module state;
  • rendered owner and result count.

Do not apply the alias repair migration during diagnosis.

Classify:

CANONICAL_ALIAS
LEGACY_OWNER
DUPLICATE_MAPPING
MISSING_MAPPING
ACCESS_MISMATCH

4.3 Requested Booking or Commercial Order did not change

Current released shared order logic can preserve the stored reference when the submitted new reference is invalid, stale, foreign or wrong-type.

Procedure:

  1. stop repeated Save;
  2. reread the exact Order row;
  3. reread the linked Booking or Commercial Order;
  4. compare the requested ID with the persisted ID;
  5. classify:
  6. APPLIED;
  7. EXPLICITLY UNLINKED;
  8. PRESERVED CURRENT REFERENCE;
  9. REJECTED;
  10. UNKNOWN;
  11. correct the source selector or policy rather than overwriting the DB directly.
Save succeeded
!= submitted relation changed

4.4 Outbound Cost access differs from expectation

Do not grant a broader role or expose the control immediately.

Check independently:

menu/page access
module state
visible Cost control
Cost API route
handler/record state
current Transaction status

The removal of a shared advanced-operation guard is a source fact, not accepted role policy.

5. Allocation Procedures

5.1 Target Order has no active item

Do not Apply an Allocation.

Read:

  • target Order status/type;
  • active item count;
  • existing active Allocation count;
  • Booking/Commercial references;
  • Equipment Load bridge;
  • branch/deployed SHA.

Classify:

VALID EMPTY DRAFT
INVALID ALLOCATION TARGET
ITEM REMOVED AFTER ALLOCATION
SYNC PENDING
DATA CONFLICT

Do not create a placeholder item solely to satisfy Allocation.

5.2 Allocation points to a missing or deleted target item

Procedure:

  1. stop Order edits and Allocation repair;
  2. preserve Allocation, Lot, Order and item IDs;
  3. reread source Lot balance;
  4. reread active Allocation totals;
  5. determine whether the item was deleted, recreated or synchronized to a new identity;
  6. identify the owner of correction/reversal;
  7. do not decrement or restore Lot balances manually.
missing target item
!= safe to delete Allocation
!= safe to restore balance blindly

5.3 Reference Save after Allocation

After an Order/Booking/Commercial reference change:

  • reread the stored Order reference;
  • reread the Allocation target identity;
  • reread Equipment/Load bridge identity;
  • verify the Allocation still belongs to the intended shipment;
  • do not infer from the submitted payload.

5.4 QA synchronization differs from release

If the environment runs QA source, collect:

  • OrderSync result;
  • pre/post target item IDs;
  • Allocation relation ID;
  • source Lot remaining values;
  • any duplicate or replaced target item.

Do not copy a QA recovery step into a released environment.

6. Scale Procedures

6.1 Determine which Check-out command exists

Released source expectation

/check-in/execute exists
/check-out/execute absent
legacy /check-out exists

QA candidate expectation

/check-in/execute exists
/check-out/execute exists
legacy /check-out also exists

Use browser network observation and deployed source. Do not probe by submitting a Scale write.

6.2 Sales/Export Check-in

The old Gross-prefix contradiction is no longer the current released source issue.

Current released concern:

entry stage = Tare
entry numeric value = commodity Gross aggregate

Before any correction:

  1. record the original request payload only when separately approved and safely redacted;
  2. reread Order items;
  3. reread Scale Ticket Gross/Tare stage values;
  4. reread bridge identity;
  5. identify whether the environment runs release or QA;
  6. classify the Tare value source:
  7. operator ticket input;
  8. commodity Gross aggregate;
  9. migrated/legacy value;
  10. corrected/reweighed value;
  11. unknown.

Do not edit the Ticket directly.

6.3 Release Check-out appears to call /check-out/execute

This indicates a source/asset mismatch or an unreviewed deployment state because the released server source does not register that route.

Procedure:

  1. stop Check-out submission;
  2. record server source SHA;
  3. record browser asset/source SHA;
  4. record requested route and HTTP result;
  5. check for mixed cache/deployment;
  6. do not fall back to the legacy route after a failed integrated request without confirming that no write occurred.

6.4 QA integrated Check-out response is missing

QA candidate command can save the Order and perform Scale Out in one route boundary.

Recovery:

reread Order header/items
+ reread Ticket stages
+ reread Transload or Equipment Load bridge
+ reread Ticket events
+ reread Purchase Finalize / Outbound child state

Classify:

  • NOT COMMITTED;
  • ORDER SAVED / SCALE NOT COMPLETED;
  • SCALE COMPLETED / CHILD PENDING;
  • COMPLETED;
  • CONFLICT;
  • UNKNOWN.

Do not repeat the whole command unless absence is proven.

6.5 Legacy and integrated Check-out both exist

This is a one-writer issue.

Do not let an operator choose between them.

Required owner decision:

caller/cohort
-> one authoritative route
-> one readback contract
-> one recovery contract
-> rollback
-> old caller-zero

6.6 Purchase Finalize fails after Scale Out

Do not repeat Scale Out.

Resume only:

FinalizePurchaseReceiptFromScale

or the current released equivalent, after rereading the Scale Ticket and inbound bridge.

6.7 Outbound child remains open after Scale Out

Do not reverse or repeat Scale Out solely to close the outbound child.

Reread:

  • Ticket;
  • Order;
  • Equipment Load;
  • Booking/Delivery/Outbound state;
  • exact branch-specific close owner.

6.8 Reweigh, Void and Reversal

Existing YMS event/reason and downstream blocker rules still apply.

The post-refresh Check-in/Check-out changes do not authorize:

  • generic Ticket PATCH;
  • BMS/YMS competing writes;
  • event deletion;
  • physical operation replay;
  • direct link cleanup.

7. Support Classification

Use these exact labels:

RELEASE SOURCE MATCH
QA CANDIDATE SOURCE MATCH
MIXED SOURCE / BLOCKED
REFERENCE APPLIED
REFERENCE PRESERVED
UNDATED TRADE ROW
ALLOCATION TARGET CONFLICT
SCALE ENTRY PROVENANCE CONFLICT
LEGACY CHECK-OUT AUTHORITY
INTEGRATED CHECK-OUT CANDIDATE
PARTIAL CHILD RESULT
UNKNOWN — DO NOT REPLAY

Avoid vague labels such as failed, not saved, or Scale issue without the authoritative reread.

8. Escalation Packet

Collect:

environment and deployed SHA
browser asset SHA/cache state
release or QA lane
CLIENT_ID/profile
actor/role/page/API
Order/Item/Booking/Commercial Order IDs
Lot/Allocation IDs
Ticket/bridge/event IDs
requested versus persisted reference
Trade date filter and undated status
Scale stage and weight provenance
last confirmed successful boundary
unknown/partial classification
no-replay confirmation

Exclude credentials, broad business payloads and unrelated tenant data.

9. Current Limitations

This repository addendum has not been validated through:

  • current DB reads;
  • current role/account browser sessions;
  • Scale device or physical workflow;
  • Trade accounting acceptance;
  • Allocation correction/reversal;
  • current Wiki rendering;
  • field-user acceptance.

It is current source-aware guidance, not M3 evidence.

10. Completion Boundary

Source branch identified
+ authoritative rows reread
+ command boundary identified
+ partial/unknown classified
+ no unsafe replay
= diagnostic completion

This does not mean the underlying business process is complete or migration-ready.

---

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