CTC Yard Dispatch, Pull Out Closing And Driver Partial-Result Runbook¶

Purpose¶

Status: SOURCE-RECONCILED OPERATOR DRAFT / NOT RUNTIME-TESTED - Processes: - PROC-YMS-YARD-DISPATCH - PROC-OPS-YARD-TO-DRIVER-HANDOFF-CTC - PROC-TMS-DRIVER-DELIVERY - Source-inspection baseline: 4fc2f5a893765fbb95e0a2bdcb971322b0ec9fc0 - Primary audiences: Office/Disp

Who does this¶

Whoever owns this job.

Before you start¶

You have the right account (see Permissions and Access).
The record and date you are working on are correct.
Words you do not know are in the Glossary.
Status: SOURCE-RECONCILED OPERATOR DRAFT / NOT RUNTIME-TESTED
Processes:
PROC-YMS-YARD-DISPATCH
PROC-OPS-YARD-TO-DRIVER-HANDOFF-CTC
PROC-TMS-DRIVER-DELIVERY
Source-inspection baseline: 4fc2f5a893765fbb95e0a2bdcb971322b0ec9fc0
Primary audiences: Office/Dispatch, Yard Truck Driver, Truck Operator, Administrator recovery owner
Current pages: Yard Dispatch, Yard Instruction, Yard Closing, Yard Map, Driver
Runtime test: NOT PERFORMED
Target-role test: NOT PERFORMED
Production verification: NOT PERFORMED
Related:

1. Purpose¶

Use this runbook to operate and recover Yard/Driver work without collapsing these independent facts:

queue state
physical Yard movement
Yard Map occupancy
closing/scale evidence
delivery state
photo/file evidence
parking state
Telegram/provider result

A success in one boundary does not prove the others completed.

2. Role Boundaries¶

Role	Normal responsibility	Must not do
Office / Dispatch	Verify physical baseline, create/edit/schedule/cancel Yard work, assign/review Driver work, reconcile partial results.	Use request payload flags as permission or complete physical work by changing status only.
Yard Truck Driver	Claim one scheduled instruction, move the physical item and complete through Yard Instruction/Closing.	Move another item or complete a stale route merely to clear a queue.
Truck Operator	Check In, execute assigned delivery, record evidence, Start/Finish/Parking through personal Driver page.	Use another driver's visible card or repair Yard state directly.
Administrator	Resolve module/access/schema/provider/config exceptions and coordinate bounded recovery.	Treat admin access as authority to fabricate physical evidence or bypass process owners.

Current source derives important Office override capability server-side. It also contains personal-name compatibility logic in the Yard Truck roster; that logic is not an approved target role model.

3. Stable Identity Checklist¶

Carry these identities through every handoff:

Yard queue ID
entity type and entity ID
container/equipment ID
load/equipment-load ID
current FROM location
planned TO / destination kind
actual TO when selected
claimed user
Delivery ID / Ticket
assigned Driver user ID
closing/scale record identity
photo/file identity
parking state

Do not correlate only by display name, time or similar route text.

4. Office Pre-Dispatch Review¶

Before creating or scheduling Yard work:

verify the physical item identifier;
read Yard Map current occupancy;
read active queue for the same entity/location;
identify exact movement purpose: Bring, Pull Out, Relocate, Drop, Area or Stack Group;
verify destination is active and compatible;
identify any blocker or relocate-before-pull-out work;
confirm the intended Yard Truck Driver/priority when current operation uses them;
do not create a duplicate queue solely because an older row is not visible in the current filter.

Stop when physical state and system state disagree.

5. Create And Schedule Yard Work¶

Create¶

choose exact entity and source location;
choose exact spot, area, stack group, drop or approved temporary flow;
add reason/remark needed by the operator;
submit once;
reread queue ID, entity, route and status.

Schedule¶

resolve TEMP before field execution;
confirm final FROM and TO;
verify destination remains available;
move the row to Scheduled;
order work explicitly;
reread after any multi-row/bulk change because requests can partially succeed.

Multi-request partial result¶

If some rows are created/scheduled before an error:

refresh the queue;
identify committed queue IDs;
preserve those rows;
continue only missing items;
do not repeat the whole batch.

6. Claim¶

Yard Driver procedure¶

use personal Yard Instruction page;
refresh scheduled work;
compare entity and physical FROM;
claim one intended row once;
verify Claimed By You and queue ID;
do not claim a second row while another active claim remains unless approved current policy explicitly allows it.

Claim failure¶

Possible causes:

another driver claimed it;
current status changed;
physical/current location no longer matches;
destination is missing/unresolved;
actor lacks Yard Instruction or Office capability.

Recovery:

refresh queue and Yard Map;
coordinate unclaim/reassignment through Office;
do not forge Office override or claimant text.

Unclaim¶

Current source may retain assigned/claimed display text while status returns to Scheduled. Treat status/current claim authority—not retained label—as the ownership checkpoint.

7. Non-Pull Physical Move¶

sequenceDiagram
    autonumber
    actor Office
    participant Dispatch as Yard Dispatch
    actor YardDriver as Yard Truck Driver
    participant API as Yard API
    database DB as MySQL
    participant Map as Yard Map

    Office->>Dispatch: Create, verify and schedule queue item
    YardDriver->>API: Claim scheduled item
    API->>DB: Conditional claim
    DB-->>YardDriver: Claimed queue ID
    YardDriver->>YardDriver: Move physical entity from FROM to TO
    YardDriver->>API: Complete with actual destination
    API->>DB: Validate claim/source/target/occupancy
    API->>DB: Commit queue COMPLETED + location/mirror updates
    DB-->>YardDriver: Completion result
    Office->>Dispatch: Refresh Completed
    Office->>Map: Refresh actual occupancy
    Note over Dispatch,Map: Queue and Yard Map must agree with physical state.

Procedure¶

follow the exact claimed instruction;
physically move only the bound entity;
for Area/Stack Group choose the exact actual spot;
select Complete once;
Office refreshes Completed and Yard Map;
verify no unintended active queue remains for the same entity.

Completion timeout¶

Do not repeat the physical move.

Reread:

queue status;
actual destination;
Yard Map occupancy;
equipment/load mirrors;
any auto-completed dependent queue.

Retry only the missing system boundary after Office review.

8. Occupied Or Blocked Target¶

When target is occupied, inactive, blocked or violates stack/trailer/size rules:

do not complete to a different spot unless the instruction explicitly allows Area/Stack selection;
stop physical completion;
verify occupant and target in Yard Map;
use queue-after-clear only when a real clearing instruction exists;
keep the original waiting queue identity;
verify both clearing and waiting rows later.

9. Queue After Clear¶

origin process complete/pending
+ waiting Yard queue exists
+ physical target still blocked

Procedure:

record waiting queue ID and target;
identify blocking entity/location and clearing queue;
complete the clearing move under its owner;
refresh waiting queue and Yard Map;
verify whether auto-completion occurred;
if still active, continue from current state—not from the original Finish action;
never perform a second physical move merely because the origin card is complete.

sequenceDiagram
    autonumber
    actor Operator
    participant Origin as Delivery/Yard Origin
    participant Queue as Yard Queue
    actor ClearingDriver as Yard Driver
    database DB as MySQL
    participant Map as Yard Map

    Operator->>Origin: Finish toward occupied target
    Origin->>Queue: Create waiting queue-after-clear
    Queue->>DB: Commit waiting identity
    Origin-->>Operator: Origin result with pending Yard
    ClearingDriver->>Queue: Complete blocker move
    Queue->>DB: Update blocker and evaluate waiting queue
    alt Guards pass
        Queue->>DB: Auto-complete waiting placement
    else Still blocked/ineligible
        Queue->>DB: Keep waiting queue active
    end
    Operator->>Queue: Reread waiting status
    Operator->>Map: Reread target occupancy

10. Pull Out Closing¶

Current browser flow uses two requests:

BMS closing/scale save
-> YMS queue completion

This creates a known partial-result boundary.

Before Closing¶

Verify:

claimed Pull Out queue ID;
bound equipment/load/container;
closing page did not switch selection;
required photos;
empty/tare/gross/net inputs;
scale-skip/inspector policy where applicable;
actual final destination requirements;
current physical state.

Submit¶

review all closing data;
submit once;
BMS closing/scale may commit first;
YMS then attempts queue completion;
reread both sources after success or failure.

sequenceDiagram
    autonumber
    actor YardDriver
    participant Closing as Yard Closing
    participant BMS as Closing/Scale API
    participant YMS as Yard Completion API
    database DB as MySQL
    actor Office

    YardDriver->>Closing: Submit photos and scale/closing data
    Closing->>BMS: Save closing
    BMS->>DB: Commit closing/scale evidence
    DB-->>Closing: Closing saved
    Closing->>YMS: Complete Pull Out queue
    alt YMS succeeds
        YMS->>DB: Commit queue/location completion
        DB-->>Closing: Completed
    else YMS fails or response is lost
        YMS--xClosing: Partial/unknown result
        YardDriver-->>Office: Report queue/equipment IDs
        Office->>BMS: Reread closing/scale
        Office->>YMS: Reread queue/location
        Note over Office,DB: Resume only the missing boundary.
    end

Closing saved, queue still Claimed¶

Do not submit the full closing form again.

Recovery:

reread closing/scale record;
verify bound equipment/load and values;
reread queue status and Yard Map;
if closing exists and queue is active, complete/recover only Yard boundary through approved command;
if queue completed but closing is missing/invalid, escalate to BMS owner;
record which request committed.

11. Yard-To-Driver Handoff¶

This handoff applies only when the current Driver delivery has a relevant active Yard blocker.

Office correlation¶

Compare:

Delivery ID/Ticket;
assigned Driver;
equipment/container/load;
current Driver origin;
Yard queue entity/current location;
active queue status.

Do not match by name/time alone.

Sequence¶

sequenceDiagram
    autonumber
    actor Office
    participant Yard as Yard Queue / Map
    actor YardDriver
    participant Driver as Driver Page / API
    actor TruckDriver
    database DB as MySQL

    Office->>Yard: Verify active blocker for delivery equipment
    Yard-->>Driver: Driver Start remains blocked
    YardDriver->>Yard: Complete/correct physical prerequisite
    Yard->>DB: Commit queue/location result
    Office->>Yard: Reread no active blocker
    TruckDriver->>Driver: Refresh assigned delivery
    TruckDriver->>Driver: Start once
    Driver->>DB: Validate actor and current blocker
    DB-->>Driver: DISPATCHED or blocked
    Office->>Yard: Verify no unexplained queue/location
    Office->>Driver: Verify delivery state

Dispositions¶

Disposition	Meaning
`YARD_BLOCKED`	Applicable Yard work remains active.
`READY_FOR_DRIVER`	Yard prerequisite is verified; delivery still Scheduled.
`DRIVER_STARTED`	Delivery is Dispatched and Yard evidence reconciled.
`PARTIAL_REVIEW`	Sources disagree or request result is uncertain.

These are manual reconciliation labels, not stored statuses.

12. Driver Check In And Assignment¶

Before delivery actions:

personal Driver identity is correct;
an active Driver Log exists;
card belongs to the assigned Driver;
Ticket/freight/from/to/equipment match;
required Yard blocker is resolved;
physical unit agrees with system state.

After Check In:

reread active Driver Log;
verify card actions are enabled only for intended work;
after timeout, do not create a second log before reread.

13. Driver Start¶

select Start once on intended Scheduled card;
for Yard-origin Return/Relocate verify active Yard queue is absent;
reread delivery as Dispatched;
verify pickup/start time;
verify Yard Map/queue when the UI or server cleared Yard state.

Partial Start¶

The UI/server may involve Yard vacate/clear and Delivery status boundaries. If Yard is cleared but delivery remains Scheduled:

do not vacate/move again;
preserve physical state;
reread queue, Yard Map and delivery;
resume only missing Delivery status boundary under Office coordination.

14. Driver Evidence And Finish¶

Photo upload can commit before Finish.

photo saved
!= delivery finished

External destination¶

upload/review required photo;
submit Finish once;
reread Delivered status, delivery time and equipment/load effects;
do not re-upload photo after Finish failure unless evidence is actually missing.

Tenant Yard direct placement¶

Current UI may perform Yard move and Delivery finish as separate requests.

After error/timeout reread:

existing photo;
delivery state;
Yard Map;
active queue;
equipment/load.

Continue only the missing boundary.

Occupied target¶

If queue-after-clear is created and delivery reports Delivered, treat Yard placement as pending until queue and Map prove completion.

15. Parking¶

Parking has independent checkpoints:

REQUESTED
ASSIGNED
PHYSICAL/YARD CONFIRMED
DELIVERY COMPLETED
TELEGRAM SENT/FAILED

Driver request¶

confirm eligibility and tenant-yard destination;
request once;
reread parking state;
provider failure does not justify repeating without checking local state.

Office assignment¶

choose actual valid spot/area/lane;
assign once;
reread delivery parking fields;
check notification separately.

Driver confirm parked¶

follow physical instruction;
choose exact actual spot when required;
satisfy evidence requirements;
confirm once;
reread Yard state and parking confirmation;
Delivery completion may require a later request.

Parking confirmed, delivery still Dispatched¶

Do not repeat physical parking. Retry only Delivery completion after reread.

16. Telegram / Provider Unknown Result¶

Parking or other notifications may occur within or around local DB transactions depending on current path.

When provider result is uncertain:

reread local queue/delivery/parking state;
check stored provider/result identity if available;
do not repeat local business action solely to resend message;
use explicit notification retry or manual communication;
record divergence for later reconciliation.

17. Trouble And Undo¶

Driver Trouble and Undo do not fully compensate all prior effects.

Before Undo:

record delivery state/time;
read photos;
read equipment/load;
read Yard queue/location;
read parking/provider state;
confirm which effect needs correction.

After Undo:

delivery may return to Dispatched;
physical/equipment/Yard/provider effects may remain;
Office must reconcile every source;
do not describe Undo as full rollback.

18. Check Out With Pending Work¶

Before Driver Check Out:

review all Started/Trouble/Parking/pending-Yard cards;
identify any partial handoff;
record next owner;
do not delete Driver Log or force Delivered to clear the page.

Check Out completion does not resolve pending delivery or Yard work.

19. Required Readback Matrix¶

Action	Required readback
queue create/schedule	queue ID, entity, from/to, status/order
claim	queue ID, status Claimed, current actor, physical source
non-pull complete	queue Completed, actual destination, Yard Map occupancy, no duplicate active queue
queue-after-clear	waiting queue ID, blocker, target, origin child, eventual queue/Map state
Pull Out closing	BMS closing/scale and YMS queue/location separately
Yard-to-Driver	no active blocker, Yard Map, assigned delivery, Driver Log, Dispatched state
Driver Start	delivery status/time plus Yard queue/location when applicable
photo upload	file identity/readability/link
Driver Finish	delivery, photo, equipment/load and Yard/parking when applicable
parking request	local parking state and provider result separately
parking assign	assigned location, actor/time and notification separately
parking confirm	Yard placement, parking status and delivery status separately
Undo	delivery plus all retained side effects
Check Out	Driver Log only; pending work remains separately owned

20. Escalation Evidence¶

Provide:

environment / CLIENT_ID
account and intended role
queue ID / entity / equipment/load / current and target locations
Delivery ID / Ticket / assigned Driver
closing/scale identity
photo/file identity
parking state
queue status and claimant
physical item/location
requested action and timestamp
response/error/request ID
provider result
exact Yard Dispatch, Yard Map and Driver reread
which boundary is known committed

21. Future Test Matrix¶

Scenario	Required evidence	Current state
queue create/schedule	Office role + exact queue readback	NOT TESTED BY THIS SLICE
concurrent claim	one claimant, safe loser response	NOT TESTED
wrong actor claim/complete	denied with no mutation	NOT TESTED
non-pull complete	physical + queue + Map parity	NOT TESTED
occupied target	blocked/no wrong placement	NOT TESTED
queue-after-clear	one waiting identity and eventual exact placement	NOT TESTED
Pull Out normal	BMS + YMS success/readback	NOT TESTED
Pull Out second-request failure	closing retained, queue recoverable without duplicate	NOT TESTED
Yard-to-Driver blocker	active queue blocks Start; completion enables correct assigned Driver	NOT TESTED
Driver wrong assignment	denied without mutation	NOT TESTED
Yard-origin Start partial	no repeated physical vacate	NOT TESTED
Driver Finish with photo	file retained and status/equipment correct	NOT TESTED
tenant-yard Finish partial	Yard/delivery independent recovery	NOT TESTED
parking provider failure	local state known and no duplicate request	NOT TESTED
parking confirmed/delivery pending	retry only delivery boundary	NOT TESTED
Undo	retained effect matrix visible	NOT TESTED
Yard roster policy	role/config replaces personal names	DECISION/IMPLEMENTATION REQUIRED
target-role matrix	Office/Yard Driver/Truck Operator/API combinations	NOT TESTED
Production	release/schema/config/role/physical observation	NOT VERIFIED

22. No-Go Rules¶

Do not:

claim/complete stale or wrong physical work;
treat retained assignee text as current claim authority;
repeat physical movement after a response loss;
submit Pull Out closing again before reading BMS and YMS separately;
treat Delivered as proof of final Yard placement;
repeat local parking request merely to resend Telegram;
use another driver's card because it is visible;
treat Undo as full compensation;
hardcode personal names into target roles/process policy;
force statuses to clear daily queues;
claim target-role or field acceptance from source inspection;
publish Wiki content without authorized DB/rendered readback.

---¶

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