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

CTC Inbound Planning, Assignment, Loader And Workforce Reconciliation¶

Status: P6-007 SOURCE-RECONCILED PROCESS DECOMPOSITION INPUT
Current registered process: PROC-TMS-INBOUND-PLANNING v0.5.0
Current lifecycle: draft / partial
Source baseline: 4fc2f5a893765fbb95e0a2bdcb971322b0ec9fc0
Current process contract: INBOUND_PLANNING_WORKFLOW.md
Migration packet: INBOUND_PLANNING_MIGRATION_PACKET.md
Policy decisions: LOADER_WORKFORCE_POLICY_DECISION_MATRIX.md
Portfolio handoffs: CROSS_PROCESS_HANDOFF_AND_IDENTITY_MATRIX.md
Does not authorize: registry type change, new Process IDs, Runtime refactor, DB migration, role/config change, Wiki publication or deployment

1. Source-Level Conclusion¶

The current PROC-TMS-INBOUND-PLANNING document describes a real end-to-end operating segment, but it is too broad to remain one atomic migration unit.

Current source contains at least three materially independent authorities:

A. Office Planning And Assignment
   T_TRANSLOAD + T_LOADING_PLANNER plan/assignment/queue

B. Loader Job Execution
   planner/transload start, completion, files, inventory/Yard handoff

C. Loader Workforce Time And Break
   T_STAFF_TIME_EVENT + break queue + QuickBooks Time effect

These have different triggers, actors, records, commands, recovery paths and external effects. For migration, the current Process ID should be evaluated as a composite umbrella candidate with separate atomic children.

This document does not change the registry yet. Proposed child identities remain review candidates until P6 approves composition and stable IDs.

2. Proposed Process Decomposition¶

Current umbrella¶

PROC-TMS-INBOUND-PLANNING

Recommended future type after approval: composite.

Candidate child 1 — Office planning and assignment¶

Proposed ID:

PROC-TMS-INBOUND-PLAN-ASSIGN-CTC

Owns:

check-in and plan context;
lane and plan application;
Assignment Board;
Loader assignment/unassignment;
per-loader queue order;
assignment Telegram intent/result;
Office override and queue management;
handoff to Loader execution.

Candidate child 2 — Loader job execution¶

Proposed ID:

PROC-TMS-LOADER-JOB-EXECUTION-CTC

Owns:

assigned/current job identity;
allowed Start;
current/opened job;
loading/unloading/reload/spare/domestic completion variants;
completion inputs and files;
planner/transload/staff-job evidence;
post-commit notification handoff;
inventory/Yard/Final Loading Review handoff.

Candidate child 3 — Loader workforce time and break¶

Proposed ID:

PROC-TMS-LOADER-WORKFORCE-TIME-CTC

Owns:

Clock In/Clock Out;
current/day/week totals;
paid 10-minute break versus unpaid lunch;
scheduled break queue and Start Break;
BREAK_IN/BREAK_OUT events;
manager correction;
local-to-QuickBooks Time effect and reconciliation;
Clock Out release of unstarted scheduled assignments.

Why Break is not a normal loading-planner job¶

Current persistence uses T_LOADING_PLANNER with:

SPECIAL_INSTRUCTION = QUEUE_BREAK
LOADING_TYPE = Other
sentinel related IDs
JOB_STATUS = SCHEDULED / STARTED / FINISHED / CANCELED

This is a legacy storage adapter. It does not mean Break is a physical Loading Planner job or belongs to transload lifecycle authority.

Target application/domain code should expose a BreakQueueItem contract and hide the legacy row representation behind a repository adapter. A new table is not automatically required before a proven migration need.

3. Current User Surfaces¶

3.1 Inbound Planning¶

Primary Office surface:

inbound-planning;
planning board lanes and status;
embedded Assignment Board;
plan preview/apply;
check-in/dock/start preparation;
completed work and Timeline links.

3.2 Assignment Board¶

Current source:

frontend/pages/system/TMS/transload/loader-assignment-board.php.

Capabilities:

Ready pool;
per-loader assignment queues;
multiple loader tokens in LOADER_NAME;
assignment/unassignment;
queue reorder;
Assignment Telegram;
Start/Open/Confirm and Complete from the board;
manager Break queue drafting/management through embedded events;
auto-assignment status display.

3.3 Loader Page¶

Current source:

frontend/pages/system/TMS/transload/inbound-loader.php.

Capabilities:

DIP / Ready / Opened / Completed views;
session-linked Loader identity;
current queue order;
Start and Complete;
completion inputs/files;
Time Clock;
self-service scheduled Break/Lunch Start;
exact current/day/week display.

3.4 Loader Timeline¶

Office/manager view:

staff time events;
open clocks;
job timing;
manager correction and QuickBooks Time sync support;
potential expired-break closure side effect during current read flows.

4. Current API And Command Inventory¶

Planning and assignment¶

GET /api/tms/transloads/planning-board;
plan preview/apply/edit/confirm routes;
POST|PATCH /api/tms/transloads/assign-submit;
POST|PATCH /api/tms/transloads/loader-assignment;
PATCH /api/tms/transloads/assignment-order;
GET|PATCH /api/tms/transloads/assignment-auto-mode;
POST /api/tms/transloads/loader-telegram;
loading-planner CRUD compatibility routes.

Loader execution¶

dock-in and dock-in-after-clear commands;
POST /api/tms/transloads/start-transloading;
POST /api/tms/transloads/start-unloading;
complete transloading/unloading/spare/domestic-pickup commands;
Undo;
file upload/read/delete;
completed-list and planning-board reads.

Break queue¶

GET /api/tms/transloads/break-queue;
POST /api/tms/transloads/break-queue;
POST /api/tms/transloads/break-queue/{id}/telegram;
POST /api/tms/transloads/break-queue/{id}/start;
PATCH /api/tms/transloads/break-queue/{id};
DELETE /api/tms/transloads/break-queue/{id}.

Staff time¶

GET /api/tms/staff-time/current;
POST /api/tms/staff-time/event for Clock In/Out;
GET /api/tms/staff-time/timeline;
current-context update;
manager event create/update/delete;
manager QuickBooks Time sync.

5. Current Records And Authority¶

Record	Current role
`T_TRANSLOAD`	operational lifecycle, load context, final result and downstream handoff
`T_LOADING_PLANNER`	plan/assignment/runtime projection, queue order and legacy Break queue row
`T_STAFF_TIME_EVENT`	local attendance, break and job timing source of truth
`T_OPERATION_EVENT`	supporting operation/automation event after guarded behavior
`T_FILE`	completion/photo/evidence records through shared file owner
`T_EQUIPMENT*`	equipment/container and load association
`T_WAREHOUSE_LOCATION` / `T_INVENTORY_LOT`	downstream inventory/placement owners after completion
`T_YARD_DISPATCH_QUEUE` / `T_YARD_LOCATION`	downstream Yard owner
QuickBooks Time	external workforce-time projection/effect; not local source of truth
Telegram	external notification effect; not assignment/job completion authority

Important projection rule¶

T_LOADING_PLANNER is an assignment/runtime projection. T_TRANSLOAD remains the operational work lifecycle owner. T_STAFF_TIME_EVENT owns workforce-time events.

The current source couples these records inside helper transactions, but migration must not collapse them into one generic command or one table model.

6. Planning And Assignment State¶

Planning context¶

Current workflow uses operational and UI-derived groupings including:

PRE_PLANNED / DIP;
SCHEDULED;
ARRIVED;
AUTO_PLANNED;
STAGING;
DOCKED;
Ready queue;
TRANSLOADING / UNLOADING;
TRANSLOADED / UNLOADED / SPARE.

Not every visible grouping is a stored process state. The target contract must identify stored transload state, planner job state and derived lane/queue projection separately.

Assignment¶

Current assignment writes Loader tokens into T_LOADING_PLANNER.LOADER_NAME, clears/sets queue metadata and can send Telegram after commit.

Current observations:

multiple Loader IDs can be represented in a comma-separated field;
Loader page uses current session user ID as its token;
Assignment Board can explicitly choose Loader IDs;
assignment queue order is stored in LOADER_QUEUE_ORDER with legacy fallback from priority/draft metadata;
assignment Telegram can be automatic or manual;
business assignment can remain committed even when Telegram fails;
Clock Out releases scheduled/unstarted assignments for the loader.

Queue meaning¶

For each Loader:

opened/started job
-> current job

scheduled assigned jobs ordered by LOADER_QUEUE_ORDER
-> next queue

break queue item after Telegram and queue precedence
-> self-service Break/Lunch Start

The exact server-side enforcement of every UI queue-order rule requires controlled characterization. Client-side button order is not sufficient authority.

7. Dual Entry For Start And Complete¶

Both Assignment Board and Loader Page can invoke Start/Complete paths.

Current intent inferred from source¶

Loader Page is the normal self-service execution surface.
Assignment Board is an Office/manager coordination and override surface.
Forklift operational sessions are resolved to the assigned Loader actor before Start.
Office/Admin sessions preserve explicit Loader-token behavior.

Risk¶

Without a documented entry policy, the same command can be triggered from two UIs with different validation, confirmation, context and error handling.

Recommended process rule¶

normal execution entry
= Loader Page

office entry
= coordination, recovery or explicitly authorized override

Both must call the same application command and enforce identical business invariants. UI-only queue or photo checks are not accepted as server policy.

8. Loader Start¶

Current source behavior¶

Start Transloading and Start Unloading are separate legacy actions behind API v2 routes.
Loader identity is resolved from session/assignment for Forklift operational roles.
Office/Admin retains explicit Loader selection behavior.
planner and transload state are updated in one current command path;
transition evidence exists for selected Start/Undo paths;
concurrent Start has a focused retry adapter for one Start path;
job/operation events may be added;
no source-proven universal requirement that Clock In precedes Start was identified in this reconciliation.

Required Start contract¶

Before M3/M4, approve and verify:

allowed starting transload/planner states;
assigned Loader ownership;
whether multiple assigned Loaders can Start;
one active physical job per Loader policy;
queue-order enforcement at server boundary;
Clock In requirement or explicit independence;
Break-open prohibition;
duplicate/concurrent Start behavior;
exact planner/transload/staff-event readback;
Office override capability and audit.

Completion evidence¶

Start is complete only when the intended planner/transload current-job state rereads. A Telegram or UI tab change is not Start completion.

9. Loader Complete¶

Current process supports multiple variants:

Transload/Reload completion;
Unload completion;
Spare completion;
Domestic Pickup completion;
stack/footprint review handoff;
completion with files/photos/quantity/weight/seal/location fields depending on variant.

Current effect boundary¶

Core DB work commits before post-commit effects such as:

completion Telegram;
next-queue Telegram;
assignment Telegram;
post-commit email;
auto operation event.

A post-commit notification failure does not roll back the completed business job. Recovery must retry/reconcile the missing effect only.

Required downstream handoff¶

completed Reload / Transload
-> Final Loading Review

completed Unload / Spare / other variant
-> exact Inventory / Warehouse / Yard / Office next owner

Completion must carry stable transload/planner/equipment/lot/queue identities. It must not rely on visible reference text alone.

10. Clock In And Clock Out¶

Local source of truth¶

T_STAFF_TIME_EVENT records:

CLOCK_IN;
CLOCK_OUT;
BREAK_IN;
BREAK_OUT;
JOB_START;
JOB_END.

Clock In¶

Current Loader endpoint records a local Clock In event with:

WORK_CONTEXT = FORKLIFT
SOURCE = INBOUND_LOADER

Current source does not establish that Clock In is a mandatory precondition for Loader Start. Product/Operations must decide whether attendance and job execution are coupled or only reconciled.

Clock Out¶

Current endpoint:

creates the local Clock Out event;
releases the Loader's scheduled/unstarted assignments in the same DB transaction;
commits;
triggers QuickBooks Time sync after commit;
returns released-assignment count.

Clock Out does not prove an active started job was completed, stopped or reassigned. The policy for Clock Out with an active job or open Break requires explicit confirmation and negative testing.

External effect¶

QuickBooks Time sync is secondary. Local event remains committed if external sync is skipped, fails or needs manual review.

11. Break Queue And Break Time¶

Queue representation¶

Current Break rows are stored in T_LOADING_PLANNER with SPECIAL_INSTRUCTION='QUEUE_BREAK' and normal planner queue fields.

Create is manager-controlled and writes:

Break type in COMMODITY_NAME;
Loader token(s);
metadata in FINAL_DRAFT;
appointment time;
status SCHEDULED;
queue order.

Telegram and current eligibility¶

Break queue row has LAST_SENT_TIME after successful Telegram.
Loader self-service UI only presents a current-date scheduled break assigned to that Loader after Telegram was sent.
API rejects a queued break that is not yet current/sent.
Manager or the assigned primary Loader may Start according to current route logic.

Start Break¶

Start performs a conditional planner update to Started with a start time and creates or reconciles a linked BREAK_IN staff-time event.

The event is linked by:

JOB_SOURCE_TYPE = LOADING_PLANNER
JOB_SOURCE_ID = break planner ID
WORK_CONTEXT = FORKLIFT

Duration and closure¶

Current staff-time logic treats:

10-minute break as paid;
lunch as 30 minutes and unpaid.

Expired Break closure is performed by current helper logic invoked from route/list/timeline/cron paths and can create/repair BREAK_OUT. This means a nominal read path may cause a staff-time write and external sync scheduling.

Migration concern¶

Target design should move time-based expiration to one deterministic worker/job owner or an explicit command. GET/list/read composition should not be the primary transition owner.

12. Telegram Effects¶

Current notification families include:

assignment Telegram;
manual assignment Telegram;
Break Telegram;
completion Telegram;
next-queue Telegram.

Authority rule¶

assignment/job/break business state
!= Telegram delivery state

Current behavior often commits local state before or independently from Telegram.

Required target effect contract:

stable notification intent identity;
recipient resolution from stable Loader/Telegram relation;
sent/failed/unknown result;
duplicate prevention or provider readback where available;
retry owner;
manual fallback;
no replay of assignment/job/break mutation to resend a message.

The current use of LAST_SENT_TIME as both notification evidence and queue-readiness input must be explicitly preserved or replaced; it cannot be silently dropped in migration.

13. Error, Duplicate And Recovery Matrix¶

ID	Boundary	Current/likely failure	Required recovery
`EXC-010`	Plan save/apply	saved planner but later apply fails	reread transload/planner; resume missing owner only
`EXC-020`	Assignment	response lost or duplicate assignment	reread planner Loader tokens/order before retry
`EXC-030`	Telegram	assignment committed but message failed	retry notification only; do not reassign
`EXC-040`	Queue order	client shows one order but server state differs	reread all assigned planners; server policy decides next
`EXC-050`	Loader Start	stale/unassigned/concurrent Start	reread assignment, planner, transload and active job
`EXC-060`	Multiple entries	Office board and Loader page submit same command	one conditional application command; duplicate conflict/readback
`EXC-070`	Clock In/Out	duplicate or invalid transition	reread current staff-time state; no fabricated event
`EXC-080`	Clock Out release	event committed and scheduled assignments released	reread staff event and all released planners; notify/reassign separately
`EXC-090`	Clock Out with active job	policy/behavior unclear	do not infer completion; carry active job to Office recovery
`EXC-100`	Break create	duplicate/ambiguous queue row	search active Break rows for Loader/date before create
`EXC-110`	Break Telegram	message failed	Break remains queued/not current; resend effect only
`EXC-120`	Break Start	stale, already started, wrong Loader or unsent	reread break row and staff event; do not duplicate BREAK_IN
`EXC-130`	Break expiry	planner status and BREAK_OUT differ	reconcile both owners once; worker/manual recovery
`EXC-140`	Complete	DB commit succeeds, post-commit message fails	reread job completion; retry only missing effect
`EXC-150`	Undo	partial compensation	inspect transload/planner/staff/inventory/equipment/Yard effects; no full rollback claim
`EXC-160`	QuickBooks Time	local event committed, provider failed/unknown	preserve local event; provider/manual reconciliation only
`EXC-170`	Read path write	Timeline/Planning read closes expired Break	record effect/readback; target moves ownership to worker/command

14. Current Structural Risks¶

PROC-TMS-INBOUND-PLANNING is too broad as one atomic migration unit.
Assignment Board and Loader Page both execute Start/Complete.
LOADER_NAME stores comma-separated user IDs.
Break queue reuses Loading Planner rows and sentinel values.
LAST_SENT_TIME couples notification delivery to queue readiness.
Clock Out mixes attendance and assignment release.
read paths may close expired Breaks and write staff events.
QuickBooks Time is post-commit but lacks a complete user-visible reconciliation flow.
client-side queue/order/photo rules may exceed server-side enforcement.
generic legacy action handlers still own broad transaction/effect orchestration.
unexpected errors may be remapped to validation errors.
process/user role decisions still depend on numeric role/current session assumptions.

These are migration inputs. They do not automatically authorize immediate refactoring.

15. Source-Reconciled Readiness¶

current umbrella lifecycle: draft / partial
current umbrella readiness: M2 candidate, not fully current-source reconciled for every child
planning/assignment slice: M2 source-reconciled input
loader execution slice: M2 source-reconciled input
staff-time/break slice: M2 source-reconciled input
proposed child registry entries: NOT CREATED
M3 target-role verification: incomplete
M4 migration ready: incomplete

The source-level decomposition is strong enough to design separate migration packets, but not to change the registry type or activate Runtime conversion without user/process-owner review.

16. Required User/Operations Decisions¶

retain current umbrella as composite or keep one atomic process with internal capability packets;
normal Start/Complete entry versus Office override;
whether Clock In is mandatory before job Start;
Clock Out behavior with active job/open Break;
multi-Loader assignment semantics;
server-enforced one-active-job and queue order;
Break queue precedence and when Telegram makes it current;
paid Break and lunch duration/policy;
expired Break transition owner;
Telegram retry/audit/manual fallback;
QuickBooks Time user-visible reconciliation;
Undo/correction authority;
role/capability mapping;
exact Wiki structure and target-role procedure.

17. Wiki Projection Requirements¶

Current slugs:

inbound-planning;
loader-yard;
roles;
errors-recovery;
ctc-daily.

User content must distinguish:

Office planning / assignment
Loader job execution
Time Clock
Break queue / Break time
Telegram notification
post-completion next process

Required explicit guidance:

which page is the normal Start/Complete surface;
assignment versus current job versus next queue;
when Clock In/Out changes assignments;
how Break becomes available;
what to do when Telegram fails;
what to reread after timeout/duplicate;
what Loader Complete does not finish;
how Office handles active-job/clock/break exceptions.

Current T_WIKI_PAGE content has not been read in this source reconciliation.

18. Next P6/P2/P5/P7/P12 Actions¶

P6-007¶

approve decomposition and stable child IDs or reject with rationale;
merge current operational changes and registry scenarios;
define handoff and M3 packet.

P2-007¶

role/menu/API matrix;
Loader self-service versus Office override;
Client 1 regression and profile/capability parameterization.

P5¶

application commands and public contracts;
eliminate business authority from generic orchestration only in approved waves;
external effect contracts.

P7¶

separate Assignment Board, Loader, Time Clock and Break component/lifecycle ownership;
reduce shared inline/global coupling without changing process semantics.

P12¶

migrate accepted child capability packets one writer at a time;
keep MySQL authority;
worker owns expiration/notification/reconciliation where approved;
caller-zero before PHP retirement.

---¶

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