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

Inbound Planning, Assignment, Loader And Workforce Migration Packet¶

Current process: PROC-TMS-INBOUND-PLANNING v0.5.0
Decomposition source: INBOUND_PLANNING_ASSIGNMENT_LOADER_RECONCILIATION.md
Packet status: M2 SOURCE-RECONCILED INPUT / M4 NOT READY
Source baseline: 4fc2f5a893765fbb95e0a2bdcb971322b0ec9fc0
Target: React + Next.js + framework-independent TypeScript on MySQL, with a separate Node.js worker for approved durable effects
Does not authorize: child Process IDs, Runtime implementation, DB or role/config changes, deployment or Wiki publication

1. Migration Unit¶

The migration unit is not the whole Inbound page and not every TMS transload route at once.

Recommended capability packets:

Packet A — Planning And Assignment
Packet B — Loader Job Execution
Packet C — Workforce Time And Break
Packet D — Notification / Provider Reconciliation

These packets may be composed into one user experience while retaining separate state, transaction and effect authority.

2. Current-To-Target Responsibility¶

Current responsibility	Current source	Target owner
planning/lane/queue read	PHP query helpers and page JS	TypeScript query/read model + React projection
plan/confirm/apply	broad TMS route/post helper	explicit planning commands
Loader assignment/order	`T_LOADING_PLANNER`, Assignment Board	assignment application service/repository
Loader Start/Complete	TMS/WMS inbound legacy action path	Loader execution commands
Clock/Break/job events	`T_STAFF_TIME_EVENT`	workforce application contract
Clock Out assignment release	staff-time route calling transload helper	explicit cross-process orchestration
Break queue	planner row with `QUEUE_BREAK`	`BreakQueueItem` contract over legacy adapter
Break expiry	read/cron helper side effect	deterministic worker or explicit command
Telegram	post-commit provider calls and `LAST_SENT_TIME`	notification intent/result and recovery contract
QuickBooks Time	post-commit sync helper	external workforce-time effect adapter/worker
files/photos	shared file API	shared file application contract
Inventory/Yard/Final Review handoff	current records/helpers	stable child-process handoff contracts

3. React UI Responsibility¶

Suggested composition:

InboundPlanningPage
├─ PlanningBoard
├─ AssignmentBoard
│  ├─ ReadyPool
│  ├─ LoaderQueueColumn
│  └─ OfficeOverrideActions
├─ LoaderExecutionPage
│  ├─ ReadyQueue
│  ├─ CurrentJob
│  ├─ CompletionForm
│  └─ CompletedHistory
└─ WorkforcePanel
   ├─ TimeClock
   ├─ CurrentBreak
   └─ ScheduledBreakAction

React owns rendering, interaction, accessible queue controls, client form state and visible recovery. React does not own lane/state eligibility, assignment authority, one-active-job policy, Clock/Break transitions, completion rules, notification completion or downstream handoffs.

4. Next.js Web Runtime¶

Candidate route groups:

app/(operations)/inbound/planning/page.tsx
app/(operations)/inbound/loader/page.tsx
app/(operations)/inbound/timeline/page.tsx
app/api/tms/inbound/planning/...
app/api/tms/inbound/assignments/...
app/api/tms/inbound/loader-jobs/...
app/api/tms/workforce/time/...
app/api/tms/workforce/breaks/...

Next.js owns pages/layout/navigation, Server Component query composition, Route Handler adapters, bounded UI-local Server Actions, session/tenant/actor bridge, request correlation and compatibility routing. Route files do not own SQL or process transitions.

5. TypeScript Application Contracts¶

Queries¶

GetInboundPlanningBoard;
GetAssignmentBoard;
GetLoaderQueue;
GetCompletedInboundWork;
GetLoaderTimeline.

Planning and assignment commands¶

CheckInInboundWork;
PreviewInboundPlan;
ApplyInboundPlan;
ConfirmInboundPlan;
AssignLoader;
UnassignLoader;
ReorderLoaderQueue;
SetAssignmentAutoMode.

Loader execution commands¶

StartLoaderJob;
CompleteLoaderJob with an explicit completion variant;
RequestStackFootprintReview;
UndoLoaderJob as documented compensation, never generic rollback.

Workforce commands¶

ClockInLoader;
ClockOutLoader;
CreateScheduledBreak;
SendBreakNotification;
StartScheduledBreak;
CompleteExpiredBreak;
CancelScheduledBreak;
CorrectStaffTimeEvent.

Effect intents¶

assignment/completion/next-queue notification;
QuickBooks Time synchronization;
provider reconciliation/manual review.

Local command result and external effect result remain separate.

6. Data And Repository Boundaries¶

Planning/assignment¶

T_TRANSLOAD is operational lifecycle authority.
T_LOADING_PLANNER is plan/assignment/runtime projection and current queue persistence.
stable transload/planner IDs are required for every command.

Loader execution¶

The command transaction may update planner, transload, staff job events, equipment/load context and completion evidence. Inventory, Yard and Final Loading Review remain child owners unless the command calls their approved public contract.

Workforce¶

T_STAFF_TIME_EVENT is the local Clock/Break/Job event authority. QuickBooks Time remains a secondary external projection.

Break compatibility adapter¶

Initial target code may map BreakQueueItem to current T_LOADING_PLANNER rows. Sentinel IDs and SPECIAL_INSTRUCTION='QUEUE_BREAK' must not leak into the domain/application contract. A new table requires a separate evidence-backed decision.

7. Recommended Reference Order¶

First read-only reference¶

GetAssignmentBoard or GetLoaderQueue.

This exercises role/tenant/identity/queue/Break normalization without a write and produces a visible React reference.

First write reference¶

AssignLoader, after role, multi-loader, queue and Telegram semantics are approved.

It is bounded, has exact planner readback and separates local assignment from notification effect. Do not start with Complete, Undo or Break expiry.

8. One-Writer Coexistence¶

I0 current PHP characterization
-> I1 TypeScript read shadow
-> I2 React read-only surface
-> I3 one AssignLoader writer
-> I4 one StartLoaderJob writer
-> I5 Complete one variant at a time
-> I6 Clock/Break and worker-owned effects
-> I7 caller-zero and legacy retirement

At every write stage:

one cohort/capability selects exactly one writer;
old/new UI must call the same application command or one side is disabled;
MySQL remains authority;
exact readback and rollback selector are recorded;
no PHP and TypeScript dual mutation.

9. Worker Responsibilities¶

After explicit approval, the separate worker may own:

deterministic Break expiry;
idempotent BREAK_OUT completion;
planner/staff-event reconciliation;
next-queue and other notification retries;
QuickBooks Time retry/backoff/manual review;
overdue-work signals.

A GET request, in-memory Next.js timer or browser refresh is not the durable transition owner.

10. Migration Blockers Before M4¶

approved umbrella decomposition and stable child ownership;
semantic role/capability matrix;
normal Loader path versus Office override;
multi-Loader semantics;
one-active-job and queue-order server policy;
Clock In requirement;
Clock Out with active job/open Break policy;
Break priority, Telegram-current and expiry policy;
completion-variant contracts and downstream identities;
Telegram and QuickBooks Time retry/reconciliation;
UI/server validation parity;
Undo/correction semantics;
one-writer rollback and caller inventory;
target-role M3 evidence;
current Wiki/manual coverage and field acceptance.

11. PostgreSQL Handoff¶

P11 consumes the accepted TypeScript/MySQL capability contracts and must preserve:

active assignment and queue order;
multi-loader normalization decision;
conditional status transitions;
open Clock/Break intervals;
paid/unpaid time calculation;
idempotent job/break events;
external effect intent/result;
stable IDs/correlation;
migration/failback for active jobs and open breaks.

PostgreSQL conversion remains separate from initial React/Next.js cutover.

12. Current Readiness¶

process semantics: source-reconciled at umbrella/capability level
migration decomposition: proposed, not approved
read-only candidate: identified
transaction candidate: identified
M3: not met
M4: not met
Runtime implementation: not started

---¶

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