Skip to content

MK Inventory Allocation — Source Authority

  • Status: CURRENT SOURCE-AUTHORITY RECONCILIATION
  • Process: PROC-OMS-INVENTORY-TO-OUTBOUND-ALLOCATION-MK
  • Operating profile: mk-order
  • Current module: oms.allocation
  • Rebuild packet: MK_INVENTORY_ALLOCATION_CAPABILITY_REBUILD_PACKET.md
  • Effect boundary: documentation only; no Runtime, schema, Wiki DB, provider, deployment or Production change

1. Authority Decision

No single page or helper owns the complete allocation meaning.

Process contract
-> current Workbench and PHP routes
-> Inventory Lot / Allocation / Outbound data authorities
-> operator Runbook and Wiki projection
-> rebuild packet and migration matrices

The Process contract owns business semantics. Current source owns implemented behavior. This source-authority map prevents a future writer from treating the Workbench JavaScript, mk_post_helper.php or one table as the entire business contract.

2. Current Semantic Owner

PROC-OMS-INVENTORY-TO-OUTBOUND-ALLOCATION-MK owns:

  • selecting received inventory as an outbound source;
  • applying accepted source quantity/weight to an existing outbound shipment;
  • the source-lot-to-target-item allocation relation;
  • source balance consumption;
  • exact allocation/balance readback;
  • allocation conflict and recovery.

It does not own:

  • Inbound receipt/lot creation;
  • ordinary Outbound CRUD;
  • Scale/Packing/Delivery completion;
  • Booking lifecycle;
  • arbitrary Inventory correction;
  • Commercial fulfillment.

3. Current Runtime Source Families

Page

frontend/pages/system/OMS/allocation/mk-allocation-workbench.php

Current facts:

  • module key is oms.allocation;
  • normal action is labeled Apply to Existing Shipment;
  • source list, client-side basket and existing target selector are separate panels;
  • page query parameters can carry source/inbound/branch context;
  • branch/source context is navigation/display input, not durable allocation authority;
  • target must already have an operational container and size.

Browser module

public/assets/js/modules/oms/allocation-workbench.js

Current facts:

  • source and target rows are loaded from dedicated APIs;
  • basket identity is INVENTORY_LOT_ID:SOURCE_ORDER_ITEM_ID;
  • the full displayed REMAIN_QUANTITY and REMAIN_NET_WEIGHT are copied into the basket;
  • the UI has no partial-lot amount editor;
  • target/date/source-mode convenience is kept in browser state/localStorage;
  • Apply sends one basket request;
  • success clears the basket and reloads sources/target;
  • missing/error response has no durable request-token reconciliation;
  • browser state is not authoritative.

API routes

app/systems/OMS/allocation/api_routes.php

Current routes:

GET  /api/oms/allocation-workbench/sources
GET  /api/oms/allocation-workbench/targets
POST /api/oms/allocation-workbench/apply

Current facts:

  • sources and targets use the legacy request context;
  • Apply uses apiRouteRunLegacyWrite();
  • no explicit route-level strictTenantPrincipal or semantic role/capability metadata was found in the current route definition;
  • the write is locally transactional through the shared endpoint wrapper.

Query adapters

app/systems/OMS/allocation/query_handler.php
app/systems/OMS/allocation/allocation_query_helper.php

Source-query eligibility currently includes:

  • active T_INVENTORY_LOT;
  • LOT_STATUS='OPEN';
  • REMAIN_NET_WEIGHT > 0;
  • active source order/item and receipt relationships;
  • optional inbound-order/search filters;
  • result limit;
  • derived source mode such as Warehouse or Scheduled.

Target-query eligibility currently includes:

  • active Outbound Sales order;
  • active equipment-load/equipment bridge;
  • nonempty container and size;
  • equipment-load status not Returned/Broken;
  • optional search/date/target filters;
  • allocated-weight projection from active allocation rows.

Query eligibility does not itself prove the write rechecks every predicate.

Write adapter

app/systems/OMS/allocation/post_handler.php

Current facts:

  • only the Apply action is accepted;
  • advanced-operations compatibility is required;
  • the handler includes the Inbound mk_post_helper.php family;
  • it delegates to mk_sales_order_post_handle(..., 'APPLY_WORKBENCH', ...);
  • Allocation has no bounded public application service in the current source.

Shared MK write implementation

app/systems/OMS/inbound-order/mk_post_helper.php

Relevant current functions/actions:

mk_sales_order_post_handle(... APPLY_WORKBENCH ...)
mk_sales_order_insert_allocated_item(...)
Inbound lot synchronization/recalculation helpers
Outbound item update/delete guards
Booking compatibility callers

Current Apply behavior:

  1. validate basket rows and target order;
  2. validate target active Outbound Sales + container/size/equipment bridge;
  3. for each row create a new T_LOAD_ITEM;
  4. insert a T_LOAD_ALLOCATION relation;
  5. conditionally subtract ALLOCATED_WEIGHT from T_INVENTORY_LOT.REMAIN_NET_WEIGHT;
  6. verify affected row count;
  7. synchronize target bridge/scale projections;
  8. commit the request transaction;
  9. return target order and created item IDs.

Current write does not immediately decrement REMAIN_QUANTITY.

4. Current Data Authorities

Record Authority
source inbound T_LOAD Purchase receipt header/reference
source T_LOAD_ITEM exact receipt line and quantity/UOM evidence
T_TRANSLOAD source receipt/execution bridge
T_INVENTORY_LOT received inventory and remaining values
target outbound T_LOAD existing shipment header
target T_LOAD_ITEM current Apply-created outbound line
T_LOAD_ALLOCATION authoritative source-lot-to-target-item relation
T_EQUIPMENT / T_EQUIPMENT_LOAD target container/equipment bridge

A table reference does not transfer process authority. Inbound creates the source lot, but Allocation owns accepted consumption. Outbound owns shipment demand, but ordinary Outbound Save does not allocate.

5. Current Read/Write Asymmetry

Source list versus write

The list query checks LOT_STATUS='OPEN' and positive remaining weight. The write helper rechecks tenant, active lot and weight balance, but the complete list/source-item/transload eligibility set is not represented as one explicit command predicate.

Quantity versus weight

The allocation row stores quantity and net weight. The target item stores quantity/weight. The immediate source-lot write decrements only remaining net weight.

UI full-lot versus server payload

The UI sends the full displayed balance. The server helper accepts numeric quantity/weight inputs and does not itself define a universal full-lot-only business rule.

Basket transaction versus missing idempotency

The request is one local transaction, but no durable request token prevents a complete duplicate basket after a lost response.

6. Adjacent Writers And Integrity Risks

Inbound correction

Current Inbound item/lot synchronization can recalculate remaining quantity/weight from source values and active allocation sums. Post-receipt updates require careful reconciliation.

Outbound correction

Current Outbound allocated-item delete is blocked. Allocated-item update can change line values without a complete allocation/lot correction transaction.

Booking compatibility

Current Booking compatibility can update or remove Order, Item, Lot or Allocation state. A Booking error or retry can therefore affect allocation evidence outside the Workbench.

Direct/manual writes

No generic direct DB/manual correction is accepted as process authority. Any such current operational recovery must be identified and either formalized or retired.

7. Current Versus Target Ownership

Concern Current implementation Target owner
source/target search PHP query helpers + JS typed Allocation queries
basket browser memory React presentation + request/preview identity
eligibility query filters + broad helper checks Allocation Policy
transaction shared PHP write wrapper/helper Allocation Application + repository transaction
target item creation mk_post_helper.php Allocation Application under accepted parity model
allocation relation direct helper insert Allocation Repository
lot balance conditional helper update + later sync Allocation/Inventory repository contract
duplicate/unknown manual reread request-token reconciliation
correction/reversal no general owner confirmed explicit Allocation command
UI PHP page/JS React Allocation Workspace
HTTP PHP route arrays Next.js Route Handlers
database MySQL through KJDatabase typed MySQL repository, later PostgreSQL

8. Mandatory Read Order Before Implementation

  1. AGENTS.md and current Product/Context/Design/Roadmap.
  2. MK_SCHEDULE_ALLOCATION_WORKFLOW.md.
  3. MK_ORDER_FIRST_CORE_CAPABILITY_REBUILD_PACKET.md for adjacent owner boundaries.
  4. This source-authority map.
  5. MK_INVENTORY_ALLOCATION_CAPABILITY_REBUILD_PACKET.md.
  6. Current schema/index and exact source files.
  7. Current operator Runbook and authorized Wiki read.
  8. Selected P5/P6/P7/P12 Task/stage and role matrix.

Do not reconstruct the capability from mk_post_helper.php alone.

9. Source Re-Pin Checklist

Before Runtime work:

  • exact branch/commit/working tree;
  • MySQL server/database/schema/index/precision;
  • current tenant/profile/module/config;
  • role/page/API/record matrix;
  • all T_LOAD_ALLOCATION writers/readers;
  • all T_INVENTORY_LOT.REMAIN_* writers;
  • all Outbound item update/delete callers;
  • all Inbound source/lot correction callers;
  • Booking compatibility callers;
  • Scale/Packing/Delivery/Trade consumers;
  • current Workbench browser behavior;
  • current T_WIKI_PAGE rows and rendered pages;
  • active traffic and support/manual recovery paths.

10. Target Removal Conditions

The current allocation route/helper path may be retired only when:

  • React/Next.js normal role flow is accepted;
  • TypeScript queries and Apply command own the selected cohort;
  • request idempotency and unknown recovery are proven;
  • quantity/weight/UOM policy is accepted;
  • correction/reversal policy is accepted or explicitly deferred outside the first wave;
  • old route/browser/helper callers are zero;
  • Booking/Inbound/Outbound adjacent writes no longer corrupt allocation integrity;
  • rollback is rehearsed;
  • Wiki and Runbook are aligned;
  • stabilization observation is complete.

---

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