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

Final Loading Review Migration Packet

  • Process: PROC-WMS-FINAL-LOADING-REVIEW-CTC
  • Packet status: M2 SOURCE-RECONCILED / M4 NOT READY
  • Source baseline: 4fc2f5a893765fbb95e0a2bdcb971322b0ec9fc0
  • Target: React + Next.js + framework-independent TypeScript on MySQL, then later PostgreSQL
  • Owner: P6-007 process semantics; P5 application ownership; P7 UI boundary; P12 migration execution
  • Does not authorize: Runtime implementation, DB migration, deployment, role/config change or Wiki publication

1. Business Capability Being Migrated

The capability is not the PHP page or the five API routes. The migration unit is:

identify an eligible completed Reload/Transload
-> evaluate quantity/weight/ledger readiness
-> resolve required Source/Leftover/weight decision
-> confirm one review with exact readback
-> block review-sensitive changes while confirmed
-> reopen and correct with preserved provenance

A route-by-route port that omits the business sequence is not an accepted migration.

2. Current Runtime Inventory

Concern Current owner/surface Migration significance
Page route inventory-adjustment existing URL/menu compatibility
UI inventory-adjustment.php inline HTML/CSS/JS React decomposition required
Queue/read model wmsInventoryBaleReviewQueue() query contract and LA-date semantics
Readiness policy wmsInventoryBaleReviewState() + adjustment metrics domain/application policy extraction
Confirm/Reopen/Bulk bale_review_helper.php explicit commands and conditional state transitions
Use inbound weight named MySQL lock + conditional update transaction/concurrency characterization
Source/Leftover bale_adjustment_helper.php separate process/application contract
BAL TRK/L2L bale_tracking_helper.php derived read model
Final metric guard direct WMS helper calls from TMS/BMS compatibility adapter/public-policy replacement
API routing WMS api_routes.php thin Next.js Route Handler adapter target
Persistence T_TRANSLOAD.BALE_REVIEW_* MySQL first; later PostgreSQL parity
Evidence T_INVENTORY_LOT_LEDGER reversal-aware query and handoff
Access menu role list, WMS module gate, Client-1-specific role helper must become semantic capability policy
Variation Client ID and customer display name migration blocker

3. Target Responsibility Map

3.1 React UI

Suggested component responsibilities:

FinalLoadingReviewPage
├─ ReviewDateFilter
├─ ReviewScopeTabs
├─ ReviewSearch
├─ ReviewQueueTable
│  └─ ReviewQueueRow
├─ ReviewDetailPanel
│  ├─ QuantityWeightComparison
│  ├─ BaleTrackingEvidence
│  ├─ SourceResolutionPanel
│  ├─ LeftoverResolutionPanel
│  ├─ WeightDecisionPanel
│  └─ ReviewActionBar
├─ ConfirmDialog
├─ ReopenDialog
└─ ResultAndRecoveryNotice

React owns:

  • rendering and accessible interaction;
  • pending/loading/error/empty presentation;
  • user confirmation dialogs;
  • local form state;
  • exact command result presentation.

React does not calculate authoritative readiness from browser values and does not own role/tenant decisions.

3.2 Next.js Web Runtime

Candidate route structure:

app/(operations)/inventory/final-loading-review/page.tsx
app/api/wms/final-loading-reviews/route.ts
app/api/wms/final-loading-reviews/[transloadId]/confirm/route.ts
app/api/wms/final-loading-reviews/[transloadId]/reopen/route.ts
app/api/wms/final-loading-reviews/[transloadId]/use-inbound-weight/route.ts
app/api/wms/final-loading-reviews/bulk-confirm/route.ts

Responsibilities:

  • parse and runtime-validate HTTP input;
  • resolve session, tenant and actor context;
  • call application query/command;
  • map typed errors to safe responses;
  • attach request/process correlation;
  • preserve old URL/API compatibility during cutover.

Server Components call the application query directly. They do not call the application's own Route Handler over HTTP.

3.3 Framework-Independent TypeScript

Proposed application contracts:

ListFinalLoadingReviews
GetFinalLoadingReview
EvaluateFinalLoadingReview
ConfirmFinalLoadingReview
BulkConfirmFinalLoadingReviews
ReopenFinalLoadingReview
UseInboundWeightForReview
AssertFinalLoadingReviewMutable

Suggested value/policy types:

ReviewStatus = PENDING | CONFIRMED
ReviewReadiness = DATA_REQUIRED | SOURCE_REQUIRED | LEFTOVER_REQUIRED |
                  WEIGHT_REVIEW | READY_TO_CONFIRM | CONFIRMED
ReviewIdentity = tenant + transload UUID/ID + optional planner ID
ReviewMetrics = expected/final quantity and weight + explicit UOM/precision
ReviewEvidence = active source/leftover/reload/spare ledger summary
ReviewPolicy = allowed load types + weight requirement/tolerance + role capability

Application/domain code must not import React, next/*, browser globals or transport types.

3.4 Repository / Transaction

Required repository interfaces:

  • FinalLoadingReviewRepository;
  • TransloadMetricsRepository;
  • LoadingPlannerReviewEligibilityRepository;
  • BaleLedgerEvidenceRepository;
  • ReviewPolicyRepository or explicit configuration adapter;
  • ReviewAuditRepository if a dedicated audit contract is approved.

Transaction expectations:

  • individual Confirm: conditional PENDING -> CONFIRMED in one transaction;
  • Reopen: approved metadata semantics in one transaction;
  • Use Inbound Weight: conditional current-value update and readback;
  • Bulk Confirm: explicitly chosen all-or-partial contract with durable per-row result;
  • Source/Leftover remains a separate owning command and transaction.

3.5 Worker

No worker is required for core review state.

A worker is allowed only for a separately approved effect such as:

  • notification after Confirm;
  • overdue-review reminder;
  • reconciliation report;
  • audit export.

The web request must not enqueue an undocumented effect merely because a worker exists.

4. Current-To-Target Contract Mapping

Current function/surface Target contract Disposition
wmsInventoryBaleReviewQueue ListFinalLoadingReviews rewrite query behind stable DTO
wmsInventoryBaleReviewState EvaluateFinalLoadingReview extract policy and test as pure logic where possible
wmsInventoryBaleReviewConfirm ConfirmFinalLoadingReview preserve conditional update and readback
wmsInventoryBaleReviewReopen ReopenFinalLoadingReview resolve metadata-clearing policy first
wmsInventoryBaleReviewApplyInboundWeight UseInboundWeightForReview preserve stale-value conflict; replace connection lock only with proven alternative
wmsInventoryBaleReviewBulkConfirm BulkConfirmFinalLoadingReviews approve partial/all-or-nothing semantics
wmsInventoryBaleReviewAssertMutable application/domain mutation policy expose through public contract, not internal include
wmsInventoryBaleReviewLedgerSummary BaleLedgerEvidenceRepository preserve reversal awareness
wmsInventoryBaleReviewDisplay React presentation mapping do not make display text business state
wmsInventoryBaleAdjustmentMetrics typed review metrics policy remove customer-name branching
inline page JS React components + API client bounded replacement, no browser-owned authority

5. One-Writer Coexistence Plan

The process must never have independent PHP and TypeScript writers for the same command.

Phase R0 — Characterization

  • PHP remains sole writer and reader authority.
  • TypeScript contracts/tests may be drafted with no Runtime route.
  • Current behavior and open decisions are characterized.

Phase R1 — Read-only shadow

  • New TypeScript query reads the same MySQL source.
  • No user-facing cutover is required initially.
  • Compare row identity, eligibility, metrics, readiness, ordering and BAL TRK.
  • PHP remains sole writer.

Phase R2 — React read-only reference

  • React/Next.js page renders the TypeScript query result for approved accounts.
  • Existing PHP page remains rollback path.
  • No TypeScript mutation route is enabled.

Phase R3 — One command cutover

Recommended first command: individual Confirm only after policy decisions are resolved.

cutover flag/capability
-> exactly one Confirm owner
-> old PHP Confirm adapter calls new command or is disabled for selected cohort
-> exact readback and rollback

Do not cut over Bulk, Reopen and Source/Leftover simultaneously.

Phase R4 — Remaining review commands

  • Reopen;
  • Use Inbound Weight;
  • Bulk Confirm;
  • public mutable-policy contract for TMS/BMS callers.

Phase R5 — PHP caller-zero

  • no menu/page traffic to PHP review UI;
  • no browser calls to legacy review endpoints;
  • no internal direct review helper callers except bounded compatibility adapters;
  • no scheduled/script/test consumer requiring legacy implementation;
  • rollback window completed.

Then retire only the confirmed caller-zero source.

6. Cutover Controls

Each command requires:

tenant/profile/capability selector
+ command owner selector
+ exact release identity
+ same stable input identity
+ same MySQL authority
+ request/process correlation
+ old/new response and error mapping
+ rollback selector

Forbidden:

  • selecting target behavior from numeric tenant ID;
  • enabling both PHP and TypeScript mutation paths for one user/action;
  • treating UI routing as the writer selector;
  • changing DB engine during the initial cutover;
  • silently changing weight/source policy during framework migration.

7. Parity Matrix

7.1 Read parity

  • LA date boundary;
  • Pending/Completed scope;
  • Reload/Transload/finished eligibility;
  • stable row identity;
  • inbound baseline fallback;
  • TGI/current weight-exemption characterization;
  • quantity/weight difference;
  • active non-reversed ledger evidence;
  • L2L/BAL TRK values;
  • ordering and pagination;
  • search by load/reference/company;
  • empty/loading/error behavior.

7.2 Command parity

  • Confirm success and actor/time;
  • duplicate/stale Confirm conflict;
  • failed Confirm with reason prewrite characterization;
  • Reopen and retained metadata;
  • Use Inbound Weight stale-value conflict and idempotent no-op;
  • Bulk mixed result;
  • Confirmed mutation guard across TMS/BMS callers;
  • Source/Leftover handoff and reread.

7.3 Role/tenant parity

  • expected page visibility;
  • expected API allow;
  • expected API deny;
  • direct URL/API negative;
  • foreign tenant identity negative;
  • module-disabled behavior;
  • profile policy behavior without numeric tenant branches.

7.4 Recovery parity

  • response lost after commit;
  • conditional update conflict;
  • bulk partial result;
  • source adjustment succeeds but confirm fails;
  • confirm succeeds and later provider/UI action fails;
  • reopen then correction then reconfirm;
  • rollback to PHP writer during cutover.

8. Error Contract Target

Suggested typed errors:

Error HTTP User behavior
invalid input / missing data 400 inline correction
unauthenticated 401 sign-in/session recovery
forbidden capability/role 403 no action; contact owner
review/transload not found 404 refresh/search
stale/duplicate/not-pending 409 exact reread before retry
schema/config unavailable 503 or controlled unavailable state no blind retry; operator escalation
unexpected server error 500 + request ID preserve safe message; log original cause

Internal SQL/provider messages must not become public validation messages.

9. Data And Audit Decisions Before M4

Reopen metadata

Choose and document one:

  1. Clear current confirmation actor/time on Reopen and store history elsewhere.
  2. Retain actor/time as last-confirmed metadata with names that say so.
  3. Add an immutable review-event audit before PostgreSQL transition.

The current ambiguous field meaning must not be copied unchanged into a new domain model.

Weight reason

Decide whether reason is:

  • a Pending draft field;
  • a Confirm command field stored only on successful Confirm;
  • immutable event evidence;
  • cleared or retained on Reopen.

Review intent

Decide whether Pending is:

  • implicit for every eligible completed row;
  • explicitly created by an operational completion event;
  • calculated without a stored Pending state until first action.

Process audit

Decide whether existing actor/time fields are sufficient or whether review transitions require a dedicated audit/event contract.

10. Migration Acceptance Gates

Gate M2 complete

  • current source map accepted;
  • source discrepancies and unknowns recorded;
  • process contract versioned;
  • no Runtime effect.

Current status: SOURCE-RECONCILED CANDIDATE.

Gate M3 complete

  • target-role page/API matrix accepted;
  • normal, validation, duplicate, stale, response-loss, reopen and correction scenarios pass;
  • exact environment/source/schema identity recorded;
  • Wiki procedure is role-reviewed;
  • stabilization observations exist.

Current status: NOT MET.

Gate M4 complete

  • policy decisions above approved;
  • TypeScript command/query/repository contracts approved;
  • one-writer cutover and rollback approved;
  • parity matrix executable;
  • caller inventory complete;
  • P12 activation explicit.

Current status: NOT MET.

Gate M5 complete

  • React/Next.js/TypeScript path accepted and stabilized;
  • PHP callers are zero;
  • old URL/API compatibility retired or intentionally preserved;
  • Wiki points to current path;
  • MySQL remains reconciled until separate P11 cutover.

Current status: NOT STARTED.

11. Rollback Contract

Rollback during migration means switching the command/page owner back to the accepted PHP path. It does not mean reversing a business Confirm.

Required rollback facts:

  • exact old/new release IDs;
  • writer selector before/after;
  • commands accepted during new-owner window;
  • exact review rows reread;
  • no dual processing;
  • browser cache and route recovery;
  • incident owner;
  • Wiki/current-path correction when necessary.

A business Reopen is not deployment rollback.

12. Caller-Zero Evidence

Before legacy retirement inventory:

  • page routes and menus;
  • API route strings;
  • browser source and network calls;
  • TMS/BMS helper includes and function calls;
  • scripts and tests;
  • operational bookmarks;
  • Wiki links;
  • direct URL traffic/log evidence where approved;
  • support/runbook references.

Classify every caller:

ACTIVE
COMPATIBILITY
TEST ONLY
HISTORICAL
UNKNOWN
REMOVED AND VERIFIED

Unknown callers block deletion, not bounded coexistence.

13. PostgreSQL Handoff

P11 receives the accepted TypeScript/MySQL process, not the legacy PHP behavior alone.

Required parity concerns:

  • enum/check constraint semantics;
  • conditional Pending-to-Confirmed update;
  • timestamp/timezone semantics;
  • actor default and nullability;
  • numeric/decimal precision and tolerance;
  • unique/idempotency/audit design;
  • transaction isolation and bulk mixed-result behavior;
  • ledger reversal query behavior;
  • migration and failback of existing review rows.

PostgreSQL migration is separate from React/Next.js cutover.

14. Immediate Next Actions

  1. Accept or revise the separate process boundary.
  2. Reconcile the new process into the canonical registry and CTC daily composite.
  3. Approve target role/capability matrix under P2-007.
  4. Replace customer-name and numeric-tenant policy with explicit parameter contracts.
  5. Decide Reopen metadata, weight reason, threshold and Bulk semantics.
  6. Run controlled current-role scenarios for M3.
  7. Read current Wiki content and prepare role-oriented update.
  8. Select the first read-only React/Next.js comparison after P12 activation.

---

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