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

Yard Dispatch, Closing And Driver-Handoff Migration Packet¶

Processes:
PROC-YMS-YARD-DISPATCH
PROC-OPS-YARD-TO-DRIVER-HANDOFF-CTC
related PROC-TMS-DRIVER-DELIVERY
Source reconciliation: YARD_DISPATCH_CLOSING_DRIVER_RECONCILIATION.md
Packet status: M2 SOURCE-RECONCILED INPUT / M4 NOT READY
Source baseline: 4fc2f5a893765fbb95e0a2bdcb971322b0ec9fc0
Target: React + Next.js + framework-independent TypeScript/MySQL; separate worker for approved deferred/effect work
Does not authorize: Runtime implementation, schema changes, role/config/provider effects, deployment or Wiki publication

1. Migration Units¶

The Yard portfolio should migrate by capability, not by current PHP file.

Packet A — Yard Planning And Queue
Packet B — Yard Claim And Physical Move
Packet C — Pull Out Closing Orchestration
Packet D — Queue-After-Clear / Deferred Physical Work
Packet E — Yard Workforce Time And Break
Packet F — Yard-To-Driver Handoff
Packet G — Notification / Provider / Supporting Event Reconciliation

Driver Delivery has its own process packet but shares F/G handoff contracts.

2. React UI Target¶

Suggested composition:

YardDispatchPage
├─ QueueFiltersAndSummary
├─ UnmappedEntityPanel
├─ YardQueueTable
│  └─ YardQueueRow
├─ PlanMoveEditor
├─ ReorderAndScheduleControls
└─ OfficeExceptionPanel

YardInstructionPage
├─ CurrentAssignedInstruction
├─ ClaimAndUnclaimActions
├─ PhysicalSourceTargetContext
├─ ActualLocationSelector
├─ CompleteAction
└─ YardTruckBreakPanel

YardClosingPage
├─ BoundQueueAndEquipmentSummary
├─ ClosingPhotoEvidence
├─ ScaleAndTareInputs
├─ ActualSpotSelector
├─ ClosingCheckpointStatus
└─ ResumePartialClosingAction

DriverPage
└─ consumes separate Driver application contracts and Yard handoff state

React owns interaction and visible recovery. It does not own queue eligibility, claim authority, occupancy, scale, delivery status or provider completion.

3. Next.js Runtime Target¶

Candidate groups:

app/(operations)/yard/dispatch/page.tsx
app/(operations)/yard/instruction/page.tsx
app/(operations)/yard/closing/page.tsx
app/(operations)/yard/map/page.tsx

app/api/yms/yard-queues/...
app/api/yms/yard-locations/...
app/api/yms/yard-closing/...
app/api/yms/yard-workforce/...
app/api/tms/deliveries/...  # separate Driver owner

Next.js owns routing/rendering, tenant/session bridge, HTTP adapters, request correlation and compatibility aliases. Route Handlers/Server Actions call application commands and never become physical/queue authority.

4. TypeScript Application Contracts¶

Yard queries¶

GetYardDispatchQueue;
GetYardInstructionQueue;
GetYardMapState;
GetAvailableYardLocations;
GetYardClosingContext;
GetYardToDriverHandoffState.

Planning commands¶

CreateYardQueueItem;
UpdateYardQueueItem;
ReorderYardQueue;
CancelYardQueueItem;
CreateRelocateBeforePullOut;
ReserveReturningEmpty.

Execution commands¶

ClaimYardQueueItem;
UnclaimYardQueueItem;
CompleteYardMove;
MoveYardEntity;
VacateYardEntity;
CreateQueueAfterClear;
CompleteQueueAfterClear.

Closing orchestration¶

RecordPullOutClosingCheckpoint;
CompletePullOutYardQueue;
GetPullOutClosingProgress;
ResumePullOutClosing.

Do not pretend there is one distributed transaction. The application contract must expose partial checkpoints and resume only the missing owner.

Workforce/effects¶

StartYardTruckBreak;
RequestYardNotification;
RequestWorkforceTimeSync;
RecordSupportingOperationEvent.

5. Repository Boundaries¶

Yard queue repository¶

Owns:

queue identity/status/order/claim;
planned and actual movement context;
active-entity conflict query;
conditional state updates.

Yard occupancy repository¶

Owns:

exact physical-system location;
move/vacate/claim fields;
occupied/available/block semantics;
current stable entity identity.

Closing adapter¶

Coordinates with BMS Scale/Closing through an explicit application contract. BMS retains closing/weight authority; YMS retains queue/occupancy authority.

Driver handoff adapter¶

Reads delivery, equipment and Yard state without creating a second shared status. Any future durable correlation must be explicitly approved.

Legacy compatibility¶

Current menu-derived Office capability, hardcoded roster and equipment mirrors remain adapters to be characterized and retired, not target domain fields.

6. One-Writer Sequence¶

Y0 current PHP characterization
-> Y1 TypeScript read shadow for queue/map
-> Y2 React read-only Yard Dispatch/Map
-> Y3 one queue planning command writer
-> Y4 claim/unclaim writer
-> Y5 non-Pull-Out Complete writer
-> Y6 Pull Out checkpoint/resume orchestration
-> Y7 queue-after-clear/deferred worker or command
-> Y8 Yard workforce/effects
-> Y9 Yard-to-Driver handoff parity
-> Y10 PHP caller-zero and retirement

Do not cut over Pull Out Closing, queue-after-clear and Driver Finish in one wave.

7. Recommended First References¶

Read-only¶

GetYardDispatchQueue + GetYardMapState reconciliation.

Why:

visible operational value;
exposes queue/location disagreement;
validates tenant/role/entity identity;
no physical mutation.

First write¶

ClaimYardQueueItem, after claim/Office override/retained-assignee policy is approved.

Why:

bounded conditional transition;
clear stable queue identity;
no scale/provider/physical target move yet;
strong concurrency test.

Avoid starting with Pull Out Closing or Driver/Yard combined Finish.

8. Worker Responsibilities¶

Potential worker-owned behavior after approval:

queue-after-clear due/triggered completion;
supporting operation-event retry;
Telegram retry/reconciliation;
QuickBooks Time retry/manual review;
stale claim/queue monitoring only if policy defines it.

Worker commands must reread current queue/location/delivery state and remain idempotent. An in-memory Next.js timer is insufficient.

9. M4 Blockers¶

semantic planning/execution/override capabilities;
role/config roster replacing hardcoded names;
active-entity queue uniqueness and claim concurrency;
assigned versus actively claimed Driver semantics;
planned versus actual location/correction;
Pull Out checkpoint/resume policy;
queue-after-clear identity/idempotency;
Yard/Driver durable or explicit manual correlation;
delivery list/log/assigned-driver parity;
parking Telegram/local transaction separation;
Undo/correction/compensation;
physical and target-role M3 evidence;
one-writer rollback/caller inventory;
Wiki procedure and field acceptance.

10. PostgreSQL Handoff¶

P11 receives accepted TypeScript/MySQL contracts and must preserve:

conditional queue transitions;
active-entity uniqueness policy;
claim concurrency;
queue order;
location occupancy and block semantics;
closing checkpoint identities;
deferred queue-after-clear idempotency;
delivery/equipment correlation;
actor/time/audit;
migration/failback for active claims, queues and partial closing.

PostgreSQL remains separate from initial React/Next.js migration.

11. Current Status¶

source boundary: reconciled
read-only candidate: identified
first write candidate: identified
Pull Out orchestration: documented, policy incomplete
M3: not met
M4: not met
Runtime implementation: not started

---¶

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