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 Inventory Allocation — Parity And Cutover Matrix¶
- Status:
MIGRATION INPUT / NO WAVE ACTIVATED - Process:
PROC-OMS-INVENTORY-TO-OUTBOUND-ALLOCATION-MK - Rebuild packet:
MK_INVENTORY_ALLOCATION_CAPABILITY_REBUILD_PACKET.md - Policy matrix:
MK_INVENTORY_ALLOCATION_POLICY_DECISION_MATRIX.md - Effect boundary: documentation only
1. Parity Principle¶
Migration preserves business outcome and accepted compatibility, not legacy file/helper structure.
source selection
+ existing target selection
+ accepted basket semantics
+ source-to-target relation
+ source balance integrity
+ exact readback
+ recovery
The target must not copy:
- generic mutation;
- broad
mk_post_helper.phpresponsibility; - numeric tenant/role policy;
- missing idempotency;
- hidden Booking allocation mutation;
- weight-only balance behavior without an accepted quantity policy;
- blind retry.
2. Read Parity¶
| Read | Current source | Target | Acceptance |
|---|---|---|---|
| eligible sources | Allocation query helper | GetEligibleInventoryLots |
same accepted active rows, identities, balances and blocking reasons |
| eligible targets | target query helper | GetAllocationTargets |
same accepted existing target set plus explicit reasons |
| basket preview | browser-derived | GetAllocationPreview |
normalized rows, exact target, projected balances and fingerprint |
| target allocation state | Outbound detail/projections | GetOutboundAllocationState |
target items, allocation rows and source identities agree |
| lot history/balance | lot/detail/report queries | GetInventoryLotBalanceAndAllocationHistory |
original, allocated, reversed and remaining values reconcile |
| unknown result | manual search | GetAllocationResultByRequestToken |
committed/absent/conflict outcome without replay |
Read parity does not require reproducing confusing labels. Target may show clearer independent state if values and source identity remain correct.
3. Write Parity¶
Initial Apply parity¶
| Behavior | Current | First target writer |
|---|---|---|
| target | existing Outbound only | preserve |
| source | eligible source lots | preserve with stronger command revalidation |
| lot amount | full displayed remaining | preserve unless policy changes |
| target item | one new item per source row | preserve initially |
| allocation | one row per target item/source lot | preserve |
| basket | all-or-nothing local transaction | preserve |
| provider effect | none | none |
| result | target + created item IDs | return target/item/allocation IDs and before/after balances |
| duplicate | no durable protection | require request idempotency |
| timeout | manual reread | deterministic request reconciliation |
Integrity delta allowed in first target writer¶
The following are required fixes, not parity breaks:
- semantic authorization and record scope;
- command-side source/target eligibility recheck;
- request-token idempotency;
- source/target freshness;
- UOM validation;
- accepted quantity/weight lower-bound behavior;
- exact allocation/lot readback;
- safe error codes/correlation ID.
4. Role Parity¶
| Action | Current evidence | Target requirement |
|---|---|---|
| view sources/targets | assigned module/menu plus legacy context | oms.allocation.view and tenant/record scope |
| apply | advanced-operations compatibility | oms.allocation.apply |
| preview | current browser review | oms.allocation.preview |
| correct/reverse | no complete current owner | stronger correct/reverse capabilities |
| support/reconcile | manual source/DB investigation | bounded support capability with read-only default |
Before cutover, run:
- intended MK allocation operator;
- denied operational role;
- manager/recovery role;
- foreign tenant/direct ID;
- inactive/deleted source and target;
- record-level denial.
5. UI Parity¶
| State | Current | Target |
|---|---|---|
| loading | page spinners/client fetch | explicit source/target loading |
| empty source | no eligible rows | reasoned empty state |
| empty target | no existing target | reasoned target state; no create promise |
| basket | client rows | typed basket + server preview |
| validation | alert/error | field/row-level stable errors |
| stale | generic failure | explicit source/target stale state |
| submitting | button state | single pending request token |
| success | clear/reload | exact IDs and balance changes |
| unknown | generic error | reconciliation state; Apply disabled |
| conflict | generic error | stop/escalate with exact rows |
| denied | route/API error | role-appropriate denied state |
| correction/reversal | absent | separate reviewed flow when activated |
6. Data Parity¶
Must preserve¶
- tenant scope;
- source order/item/transload/lot identity;
- target order/item identity;
- allocation relation identity;
- allocated quantity, weight, UOM, rate and remark;
- current remaining values;
- soft-delete/current active-row semantics until replaced;
- target equipment bridge relationship;
- timestamps/audit available in current source.
Must clarify before migration¶
- decimal versus integer quantity normalization;
- weight precision;
- UOM conversion;
- quantity/weight authority;
- duplicate relation uniqueness;
- request-token persistence;
- correction/reversal data model;
- status and downstream-lock projection.
7. Migration Waves¶
ALLOC-W0 — Source, Schema, Role And Caller Characterization¶
Deliver:
- exact source revision;
- MySQL schema/index/precision;
- source/target query results;
- current Apply transaction and failure injection;
- role/page/API/record matrix;
- all allocation/lot writers/readers;
- unknown-result and duplicate behavior;
- current Wiki content.
Exit: current behavior can be reproduced and cleaned up with controlled fixtures.
ALLOC-W1 — TypeScript Read Model¶
Deliver typed repositories and queries against MySQL.
Exit: source/target/detail/history parity by stable IDs.
ALLOC-W2 — React + Next.js Read-Only Workspace¶
Deliver source/target search, basket and server preview. Current PHP remains the only writer.
Exit: target-role UI acceptance for read-only states.
ALLOC-W3 — Shadow Preview/Freshness¶
For current PHP requests, compute target preview/fingerprint without writing and compare normalized rows/balances.
Exit: accepted parity and named discrepancies.
ALLOC-W4 — One-Writer Apply¶
Route one bounded cohort to TypeScript AllocateInventoryBasket.
Required:
- one writer selector;
- request token;
- full command revalidation;
- accepted quantity/weight/UOM rule;
- all-or-nothing transaction;
- exact readback;
- rollback switch.
ALLOC-W5 — Idempotency And Unknown Recovery¶
Activate duplicate-result lookup and operator reconciliation UI.
Exit: response-loss test proves no double consumption.
ALLOC-W6 — Correction/Reversal¶
Only after Product accepts policies and downstream locks.
Exit: original evidence, compensating balance, target disposition and audit are correct.
ALLOC-W7 — Target-Role Stabilization¶
Run normal, negative, stale, concurrent, duplicate, unknown, conflict, recovery, mobile/accessibility and field observation.
ALLOC-W8 — PHP Caller-Zero¶
Inventory and remove old UI/API/helper callers only after zero static/runtime callers and user acceptance.
ALLOC-W9 — PostgreSQL Later¶
After React + Next.js + MySQL stabilization, validate decimals, constraints, transactions, indexes, idempotency and reversal history.
8. One-Writer Matrix¶
| Cohort/capability state | Read owner | Write owner |
|---|---|---|
| legacy | PHP or target read | PHP Apply only |
| read-shadow | both | PHP only |
| target read-only | TypeScript/React | PHP only |
| migration cohort | TypeScript | TypeScript only |
| rollback cohort | TypeScript or PHP | PHP only for new requests after in-flight reconciliation |
| retired | TypeScript | TypeScript |
Forbidden:
PHP and TypeScript both write the same request/cohort
9. Cutover Preconditions¶
- [ ] source/target/role characterization complete;
- [ ] quantity/weight/UOM policy accepted;
- [ ] full/partial and target-line model accepted;
- [ ] request-token persistence implemented;
- [ ] current Booking compatibility interaction characterized;
- [ ] downstream correction/reversal scope accepted or excluded;
- [ ] exact readback and errors implemented;
- [ ] controlled fixture cleanup proven;
- [ ] rollback selector and in-flight reconciliation ready;
- [ ] Wiki/Runbook current/future wording reviewed;
- [ ] user authorizes selected cohort.
10. Rollback Matrix¶
| Failure | Immediate action | Preserve | Do not do |
|---|---|---|---|
| target read mismatch | keep PHP writer; disable target read for role if needed | source evidence | change data to match UI |
| Apply error before commit | keep request result/trace; PHP for later requests | source/target rows | replay automatically |
| response unknown | stop new retry; reconcile token/rows | committed evidence | route same request to PHP |
| data conflict after commit | stop cohort; reconcile exact rows | allocations/items/balances | delete/recreate blindly |
| broader target defect | route new requests to PHP after in-flight review | all target commits | dual write |
| correction/reversal defect | disable those commands, keep Apply if safe | original/reversal evidence | hard-delete history |
11. Caller-Zero Checklist¶
Before deleting current Apply path:
- [ ] Workbench JS no longer calls old routes;
- [ ] current PHP page no longer exposes old action;
- [ ] no direct API integrations call old Apply;
- [ ] no internal helper calls
APPLY_WORKBENCHfor active flow; - [ ] support/manual tools use new reconciliation query;
- [ ] Booking/Inbound/Outbound compatibility does not rely on old allocation helper;
- [ ] reports and downstream queries read accepted repositories/views;
- [ ] route logs show zero use over accepted observation window;
- [ ] rollback period ended;
- [ ] Wiki current links point to target workspace;
- [ ] user accepts retirement.
12. Stable Migration Scenarios¶
ALLOC-MIG-SCN-010 Source-list parity
ALLOC-MIG-SCN-020 Target-list parity
ALLOC-MIG-SCN-030 Preview/freshness parity
ALLOC-MIG-SCN-040 One target, one source Apply parity
ALLOC-MIG-SCN-050 Multi-source all-or-nothing parity
ALLOC-MIG-SCN-060 Concurrent lower-bound conflict
ALLOC-MIG-SCN-070 Duplicate request-token result
ALLOC-MIG-SCN-080 Response-loss reconciliation
ALLOC-MIG-SCN-090 Rollback to PHP without replay
ALLOC-MIG-SCN-100 Correction/reversal parity
ALLOC-MIG-SCN-110 PHP caller-zero
ALLOC-MIG-SCN-120 PostgreSQL decimal/constraint parity
Each scenario records exact revision, actor/tenant, request token, before/after rows, result IDs, cleanup, rollback and limitations.
13. Stop Conditions¶
Do not activate the next wave when:
- business policy would be invented;
- quantity/weight/UOM remains ambiguous;
- one-writer cannot be guaranteed;
- request idempotency is missing;
- rollback would replay provider/business work;
- role/record scope is unknown;
- Booking/Inbound/Outbound adjacent writes can still corrupt the selected fixture without detection;
- current Wiki/runbook would instruct unsafe retry;
- user-visible result differs materially from accepted parity.
---¶
Source:
docs/processes/MK_INVENTORY_ALLOCATION_PARITY_AND_CUTOVER_MATRIX.md— ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.