Skip to content

CTC Field User Process System Test Runbook

  • Status: DATED FIELD TEST RUNBOOK
  • Owns: field-user process test execution and dated observed baselines
  • Does not own: current Runtime fact, release authorization or routine operator manual
  • Update when: an approved field-test scenario or its dated evidence changes

Purpose

It organises the business processes of field users, based on the operational DB and the operational server logs.

This document is the execution baseline for checking the following in a system test.

  • whether the screens, inputs, buttons and APIs that field users actually use keep working
  • whether a 400/403/500, an endless load or a missed save appears midway through a business step
  • whether a screen interaction matches the state change in the operational table
  • whether a regression test can run with a real field account rather than an administrator account

Browser Test Completion Criteria

browser test is neither entering a screen nor a representative CRUD smoke test. It recursively opens every screen in scope and the popups, modals, drawers, menus, tabs and follow-up screens derived from them, and executes in the real UI every button, link, row and bulk action, search, filter, sort, pagination, date range, input field, select/radio/checkbox/toggle, autocomplete, upload/download and keyboard and drag interactions. Every option that produces a different API request or behaviour is executed separately.

Each interaction is checked together with the screen response: the API method, path, payload, status and response, and the state of the follow-up screen. A write is checked through to an authoritative API/DB readback and cleanup or rollback. When a new control appears in a derived UI, the same rule repeats. A screen is complete only when every item is PASS or an evidenced NOT_APPLICABLE. If even one of FAIL, BLOCKED and NOT_RUN remains, that screen and every workflow that requires it are incomplete. An HTTP 200, a page render, a source/unit/contract test, a direct API call, a representative happy path or partial CRUD cannot substitute for it. Where authority for a Production, provider or destructive effect is missing, the item is not hidden but recorded accurately as BLOCKED or NOT_RUN.

The completion criterion of the full runtime test is not a fixed scenario count. It prioritises the user, tenant and business processes whose repeated use is confirmed in the operational logs, and checks that each process completes without interruption through the screen, API, state change and recovery. Log observation alone cannot prove success, so each observed process is mapped to a replay suite, or NOT_RUN/BLOCKED is left with its owner and blocker. The raw Production log may be used to trace a user, but passwords, tokens, IPs and raw session identifiers are not left in the test artifacts.

This document is the single process baseline that Playwright automation and browser runtime verification share. Both verification methods must use the same user, screen, input, expected result and scenarios A–E below, and an item verified on only one side is shown as a remaining gap in the final report.

Evidence

Checked on: 2026-06-24.

Operational DB:

  • Access path: load /etc/ctc/prod.env on production EC2 ctc, then query MySQL read-only
  • Confirmed DB host: ip-10-3-1-146:3306
  • DB: prod
  • MySQL: 8.0.45
  • DB current date: 2026-06-24

Operational logs:

  • AJAX/API logs: /var/log/ctc/ajax/*.jsonl
  • Email logs: /var/log/ctc/email/*.jsonl
  • QuickBooks Time logs: /var/log/ctc/integrations/quickbooks-time/*.jsonl
  • Confirmable AJAX log range: 2026-05-15 through 2026-06-23
  • Detailed usage-pattern analysis window: 2026-06-17 through 2026-06-23

Excluded administrator accounts and roles:

  • superadmin
  • admin
  • admin2
  • ROLE_ID=1 Administrator accounts: jaylee, richard

Important conclusions:

  • In the operational DB, CLIENT_ID=2 has no field account and only the admin2 administrator. This document therefore does not treat the MK/admin2 operational processes as field-user processes.
  • The subject of the field-process analysis is the CLIENT_ID=1 CTC user in the operational DB.

Current Field Users

Office Manager

Username Name Last login Observed production use
anahi Anahi Arce 2026-06-23 11:59:12 planning, loader assignment, loader telegram, break queue, dock/check-in
annie Annie Kim 2026-06-23 09:08:51 low recent log volume, office role access
danielcasillas Daniel Casillas 2026-06-23 06:06:31 yard dispatch queue, planning, dock-in, scale ticket
daviddlr David de la Rosa 2026-06-23 06:04:53 transload update, doc submitted, check-in/dock-in, BOL email
davidpark David Park 2026-06-23 18:36:35 transload form, final transload billing, booking, reconcile
lois Lois Lutz 2026-06-23 07:47:05 billing files, transaction close, chassis/trucking/transload billing
marc marc 2026-06-18 11:48:50 low recent log volume, office role access
montse montse 2026-06-23 05:59:21 delivery form, files, fleet, containers, transaction close/trucking
rafaelqhl Rafael Dominguez 2026-06-17 21:47:17 low recent log volume, office role access

Forklift / Loader

Username Name Last login Staff-time events Last staff-time event
cayo CAYO 2026-06-23 05:34:13 701 2026-06-23 14:50:46
oscar Oscar 2026-06-23 05:45:50 687 2026-06-23 16:17:26
ruma RUMA 2026-06-23 03:32:34 605 2026-06-23 15:13:21
manuel Manuel 2026-06-23 04:15:48 566 2026-06-23 15:35:01
rich RICH 2026-06-23 06:14:38 504 2026-06-23 16:44:40
danielmacias DANIEL 2026-06-23 06:16:21 452 2026-06-23 13:40:03
cristobal CRISTOBAL 2026-06-23 15:31:58 450 2026-06-23 17:50:43
edson EDSON 2026-06-23 16:18:12 367 2026-06-23 16:24:39
mario MARIO RENDON 2026-06-23 13:31:47 131 2026-06-23 17:45:32
davidc DAVID 2026-06-23 14:53:22 98 2026-06-23 18:36:12

Yard Truck

Username Name Last login Completed/claimed queue jobs Last completed
armando Armando Picado 2026-06-23 05:06:14 7,020 2026-06-23 16:52:16
ezek Ezekiel Baldwin 2026-06-23 06:39:42 4,511 2026-06-23 16:48:49

Note: users with combined role 4,6 also appear in yard-related actions, but armando and ezek are the primary yard truck users in production DB activity.

Truck Operator

High-volume delivery users in production DB:

Username Name Deliveries Completed Open-ish states Last delivery update
julio JULIO 2,629 2,623 1 delivered 2026-06-23 23:04:49
justin JUSTIN CONTRERAS 2,625 2,616 2 delivered 2026-06-23 23:52:07
roger ROGER 2,541 2,535 2 delivered 2026-06-23 23:47:32
michael MICHAEL ROJAS 2,386 2,379 2 delivered 2026-06-23 23:28:14
juanbernal JUAN BERNAL 2,359 2,352 2 delivered 2026-06-23 23:41:56
danny DANNY MEJIA 2,075 2,071 2 delivered 2026-06-23 23:18:02
anthony ANTHONY SUAREZ 1,949 1,943 1 dispatched 2026-06-23 22:32:27
antonio ANTONIO ECHEVERRIA 1,889 1,884 1 scheduled 2026-06-23 22:32:52
steven STEVEN BURROLA 1,799 1,795 1 scheduled 2026-06-22 23:14:04
lawrence LAWRENCE WALKER 1,730 1,723 0 2026-06-23 21:46:10
hector HECTOR BANUELOS 1,712 1,708 2 delivered 2026-06-23 23:31:09
fernando FERNANDO OSO 1,671 1,670 0 2026-06-23 22:51:23

Additional active truck users include alex, jovanny, norberto, victor, leo, jerry, franciscog, fermin, mariano, mariosoriano, luisarena, ramon, fgonzalez, hugo, and eric.

Warehouse Label Printer

Username Name Role Last login
CTC-WH CTC-WH Warehouse Label Printer NULL

There is no meaningful recent production log volume for this account in the inspected window, but menu/default role configuration still exposes warehouse-label-print.

Field Menu Access

Role Core menu/screens
Office Manager driver-operation, Yard group, Inbound group, Shipping group, Accounting, Report, Empty Schedule, Setting, AR Billing, Billing Presets
Forklift Operator appointment, fleet-management, inbound-loader, AR Billing/Billing Presets by menu role list
Truck Operator driver-operation, fleet-management, AR Billing/Billing Presets by menu role list
Yard Truck Driver Yard group including appointment, yard-closing, yard-instruction, fleet-management, AR Billing/Billing Presets by menu role list
Warehouse Label Printer warehouse-label-print

Important access signal from production logs:

  • Truck operators attempting direct yard move/vacate can receive 403: Yard move write access is not allowed for truck operator accounts.
  • This means test cases must distinguish driver-operation-mediated yard updates from direct yard move permissions.

Client 2 Runtime Coverage Without Production Logs

CLIENT_ID=2 is not an operating tenant, so its scenarios must not be inferred from Client 1 production logs. The Local full runtime test creates one disposable account for every active role in both tenants, signs in through login.php, and verifies every menu rendered for that role.

  • Each displayed menu must navigate successfully, render application content, and complete its read/refresh action with no browser 5xx/page error.
  • The Client 2 write workflows use disposable fixtures and authoritative readback: Commercial/Booking references, Inbound to Inventory, Outbound save/recovery, Allocation apply/restore, Brokerage cancel, Cost/Packing rate restore, and Scale check-in/reweigh/check-out/reversal/cleanup.
  • The shared KJView pass opens every routed and enabled view config and checks its configured read/create/edit/delete entry points. Disabled modules and stale unrouted configs are reported as NOT_RUN, not PASS.
  • Tests refuse to run when Client 2 Email, Telegram, or QuickBooks modules are enabled. The existing tenant module enablement is the effect boundary.
  • Run node scripts/run_full_runtime_test.js for every logic change. Record artifacts and cleanup result; this establishes Local runtime evidence only.

Operating Data Baseline

CTC execution tables

Table Production status snapshot
T_TRANSLOAD TRANSLOADED 27,899; SPARE 1,161; SCHEDULED 449; CANCELLED 413; NOSHOW 388; UNLOADED 72
T_LOADING_PLANNER blank legacy rows 32,037; FINISHED 2,141; SCHEDULED 1,421; STARTED 96; CANCELED 40
T_DELIVERY COMPLETED 43,488; SCHEDULED 760; DELIVERED 20; DISPATCHED 2
T_YARD_DISPATCH_QUEUE completed BRING 8,599; RELOCATE 5,665; PULL_OUT 5,213; one active CLAIMED/RELOCATE in snapshot

Recent production log activity by field user

Recent 7-day top field users by AJAX/API request count:

User Request count Primary meaning
danielcasillas 7,076 yard dispatch, planning, dock/check-in
daviddlr 3,050 transload update, check-in, BOL/doc flow
anahi 2,910 planning, loader assignment, break/telegram
armando 2,562 yard claim/confirm/complete
montse 2,204 delivery/fleet/container/transaction work
davidpark 1,826 transload/billing/booking/reconcile
lois 1,447 billing transaction work
ezek 1,210 yard claim/confirm/complete
cayo 697 loader execution
oscar 633 loader execution
manuel 571 loader execution
rich 511 loader execution
cristobal 500 loader execution
danielmacias 494 loader execution
edson 489 loader/yard execution
jovanny 467 driver/yard completion actions

Process 1: Office Planning And Dispatch

Primary users:

  • Heavy planning/dispatch: danielcasillas, anahi, daviddlr
  • Billing/document-heavy office: lois, davidpark, montse

Primary screens:

  • export-dashboard
  • appointment
  • inbound-planning
  • loader-assignment-board
  • loader-timeline
  • inbound-completed
  • yard-dispatch
  • yard-map
  • scale-ticket-list
  • booking and transaction screens through list pages

Observed production endpoints:

  • POST /api/tms/transloads/plan-preview
  • POST /api/tms/transloads/plan-apply
  • POST /api/tms/transloads/loader-assignment
  • POST /api/tms/loading-planner
  • POST /api/tms/transloads/check-in
  • POST /api/tms/transloads/dock-in
  • POST /api/tms/transloads/dock-in-after-clear
  • PATCH /api/tms/transloads/form
  • PATCH /api/tms/transloads/doc-submitted
  • PATCH /api/tms/transloads/driver-contacted
  • POST /api/tms/transloads/break-queue
  • GET /api/tms/transloads/break-queue
  • POST /api/tms/transloads/loader-telegram
  • POST /api/yms/yard-moves/preview
  • POST /api/yms/yard-moves/queue
  • PATCH /api/yms/yard-moves/queue
  • POST /api/yms/yard-moves/queue/reorder
  • POST /api/yms/yard-moves/queue/cancel
  • POST /api/yms/yard-locations/move
  • POST /api/yms/yard-locations/vacate
  • POST /api/bms/scale-tickets

Step-by-step process:

  1. Office user logs in.
  2. User lands on or opens daily shipping/inbound view.
  3. User opens inbound-planning.
  4. User selects work date.
  5. User scans lanes for scheduled, checked-in, plan-ready, docked, warehouse, or reload work.
  6. User searches by reference, load number, carrier, driver, booking, container, or dock.
  7. If incoming work is missing, user creates/checks in a transload.
  8. Required check-in inputs include reference/load, appointment time, customer/billing company, shipper, commodity, carrier, driver, phone, truck, trailer, and optional remark.
  9. User opens plan preview for the row.
  10. User reviews current status; planning is allowed only for statuses such as SCHEDULED, PRE_PLANNED, ARRIVED, AUTO_PLANNED, STAGING, DOCKED, or UNLOADED depending workflow.
  11. User sets loading type such as reload, unload, transload, or other.
  12. User selects unloading equipment/load context.
  13. User selects loading equipment or booking context when needed.
  14. User sets billing company.
  15. User sets commodity and quantity.
  16. User sets source/target area or dock/warehouse location.
  17. User assigns loader.
  18. User sets seal type, inspection, label, destination, appointment time, priority, and special instruction if needed.
  19. User applies plan.
  20. If the row needs loader sequencing, user opens assignment board or uses assignment actions.
  21. User reorders loading planner queue.
  22. User creates break queue item by loader, break type, and position.
  23. User sends loader telegram notification when needed.
  24. If truck arrived, user performs check-in.
  25. If dock is ready, user performs dock-in.
  26. If target dock/location is occupied, user must clear occupant or queue after clear.
  27. If yard move is required, user opens yard dispatch/preview.
  28. User creates yard queue item with entity type, entity id, dispatch type, from location, to location, assigned user, and remark.
  29. User reorders or edits queue.
  30. User cancels queue item if wrong.
  31. User monitors yard claim/complete status.
  32. User marks document submitted when BOL/docs arrive.
  33. User marks driver contacted when contact is complete.
  34. User creates or opens scale ticket if weight capture is required.
  35. User verifies status in completed/timeline views after loader execution.

Expected DB state:

  • T_TRANSLOAD.STATUS changes through planning/check-in/dock/execution states.
  • T_LOADING_PLANNER gets or updates assignment, queue order, loader, dock/warehouse plan, JOB_STATUS.
  • T_YARD_DISPATCH_QUEUE gets QUEUED, SCHEDULED, CLAIMED, COMPLETED, or CANCELLED.
  • T_YARD_LOCATION is authoritative for occupied/vacated location.
  • T_SCALE_TICKET is created/updated when scale work is initiated.

User-specific observations:

  • danielcasillas is the heaviest yard dispatch/planning operator: queue patch/reorder/create, plan preview/apply, loading planner, scale ticket, dock-in.
  • anahi heavily uses plan preview, loader assignment, loader telegram, plan apply, loading planner, break queue, dock-in/check-in.
  • daviddlr heavily uses transload form edits, doc submitted, check-in, dock-in, scale ticket, files, and BOL email.
  • davidpark heavily uses transload form, final transload billing, booking form, file updates, and load-to-load reconcile.
  • montse heavily uses delivery form, files, fleet management, container form, transaction close, trucking transaction.
  • lois heavily uses file updates and billing transaction flows: close, chassis, trucking, transload.

Production error signals to test:

  • Target location already occupied on dock-in.
  • PLAN_PREVIEW is only allowed... Current status: TRANSLOADING/TRANSLOADED/UNLOADING.
  • PLAN_APPLY is not allowed for dock-in-plan rows.
  • Only QUEUED or SCHEDULED items can be edited.
  • Loader assignment is only allowed... for invalid planner status.

Process 1A: Domestic Pickup Trailer-To-Trailer Transload

Primary users:

  • Office: danielcasillas, anahi, daviddlr
  • Loader: cayo, oscar, or another active forklift user

Primary screen:

  • inbound-planning

Observed/expected endpoints:

  • POST /api/tms/transloads/domestic-pickup
  • GET /api/tms/transloads/planning-board
  • POST /api/tms/transloads/dock-in
  • POST /api/tms/transloads/start-transloading
  • POST /api/tms/transloads/complete-transloading
  • POST /api/tms/transloads/cancel
  • POST /api/files

Step-by-step process:

  1. Office user creates a domestic pickup check-in using pickup number, customer, carrier, driver, truck, and trailer.
  2. System creates the pickup trailer unit because trailer photos/files must attach to an equipment/load record.
  3. System creates T_EQUIPMENT, T_EQUIPMENT_LOAD, and a domestic pickup T_TRANSLOAD row.
  4. The domestic pickup T_TRANSLOAD.LOAD_TYPE must be PICKUP; remark or a p/u suffix must not be the identity contract.
  5. The pickup T_TRANSLOAD.FINAL_EQUIPMENT_LOAD_ID points to the created T_EQUIPMENT_LOAD.ID.
  6. Office plans the full trailer transload and selects the domestic pickup T_EQUIPMENT_LOAD.ID as the loading/final equipment.
  7. Loader or office docks and starts the real full trailer transload row.
  8. Loader uploads required trailer photos/files against the equipment/load or transload record.
  9. Loader completes transloading from the full trailer into the pickup trailer.
  10. System changes the pickup trailer T_EQUIPMENT_LOAD.STATUS to FULL.
  11. System changes the source full trailer T_EQUIPMENT_LOAD.STATUS to EMPTY.
  12. System completes the real transload row as TRANSLOADED.
  13. System keeps the paired domestic pickup placeholder row active in the Domestic Pickup lane; real loading completion and scale-ticket empty/gross entry must not close or hide it.
  14. The domestic pickup placeholder must not be directly billable; billing source logic should include the real transload row only.
  15. Office completes the domestic pickup placeholder when the pickup trailer is ready to leave; this vacates trailer yard occupancy and moves the placeholder to CANCELLED so it is not treated as unloaded inventory.
  16. If the pickup is cancelled before completion, the domestic pickup row is cancelled and its yard occupancy is cleared.

Expected DB state:

  • T_TRANSLOAD.LOAD_TYPE='PICKUP' identifies the domestic pickup placeholder.
  • T_TRANSLOAD.REFERENCE_NUMBER and LOAD_NUMBER store the raw pickup number without p/u.
  • T_TRANSLOAD.FINAL_EQUIPMENT_LOAD_ID points to T_EQUIPMENT_LOAD.ID for the pickup trailer.
  • The paired full trailer transload is the billable/completable operational row.
  • The domestic pickup placeholder remains active after paired completion and ends as CANCELLED only after Office Complete.
  • T_EQUIPMENT_LOAD.STATUS moves source trailer to EMPTY and pickup trailer to FULL.
  • T_FILE stores uploaded trailer photos/files for the relevant equipment/load or transload context.

Production error signals to test:

  • Domestic pickup rows missing LOAD_TYPE='PICKUP' should not be inferred from remark.
  • Pickup reference numbers ending in p/u should be treated as legacy data only, not new write format.
  • Billing must reject or exclude selected pickup placeholder rows.
  • Cancelling the pickup placeholder must not leave stale yard occupancy.

Process 2: Loader / Forklift Execution

Primary users:

  • cayo, oscar, ruma, manuel, rich, danielmacias, cristobal, edson, mario, davidc

Primary screen:

  • inbound-loader

Observed production endpoints:

  • GET /api/tms/staff-time/current
  • POST /api/tms/staff-time/event
  • GET /api/tms/transloads/break-queue
  • POST /api/tms/transloads/break-queue/{id}/start
  • GET /api/tms/transloads/planning-board
  • POST /api/tms/transloads/mobile-check-in
  • POST /api/tms/transloads/dock-in
  • POST /api/tms/transloads/start-transloading
  • POST /api/tms/transloads/start-unloading
  • POST /api/tms/transloads/complete-transloading
  • POST /api/tms/transloads/complete-unloading
  • POST /api/tms/transloads/complete-unloading-spare
  • POST /api/tms/transloads/undo
  • POST /api/files

Step-by-step process:

  1. Loader logs in with personal account.
  2. Loader opens inbound-loader.
  3. Loader confirms current username and selected date.
  4. Loader refreshes job list.
  5. Loader checks time-clock panel.
  6. If not clocked in, loader taps Clock In.
  7. System writes T_STAFF_TIME_EVENT.EVENT_TYPE='CLOCK_IN' with source INBOUND_LOADER or system-equivalent path.
  8. QuickBooks Time sync runs after commit when configured.
  9. Loader checks active break state.
  10. If a scheduled break/lunch is assigned, loader taps Start Break or Start Lunch.
  11. System starts break queue and records break event.
  12. Loader selects current job tab.
  13. Loader searches by reference, customer, shipper, commodity, or dock.
  14. Loader opens assigned job card.
  15. If job needs check-in and button is available, loader taps Check In.
  16. If job needs dock-in, loader opens dock form.
  17. Loader enters or confirms dock number.
  18. Loader taps Confirm Dock In.
  19. For transload/reload/other, loader taps Start Job.
  20. For unload, loader taps Start Job or Confirm & Start.
  21. System writes planner start state and staff job-start event.
  22. Loader performs physical unload/transload/reload work.
  23. Loader uploads required files/photos.
  24. For transload completion, loader opens Complete Job.
  25. Loader enters final equipment/container/seal/quantity/weight fields shown by the form.
  26. Loader submits complete.
  27. For unload completion, loader opens Complete Unload.
  28. Loader enters final quantity, weight, warehouse location, bad bale/spare/leftover details when shown.
  29. Loader submits complete unload.
  30. If work is spare, loader uses Complete Spare.
  31. System writes planner end state and staff job-end event.
  32. Completed job appears in completed tab.
  33. Loader clocks out at end of shift.

Expected DB state:

  • T_STAFF_TIME_EVENT: CLOCK_IN, CLOCK_OUT, BREAK_IN, BREAK_OUT, JOB_START, JOB_END
  • T_LOADING_PLANNER: JOB_STATUS='STARTED' then FINISHED, JOB_START_TIME, JOB_END_TIME, JOB_ACCEPTED_USER
  • T_TRANSLOAD: moves to TRANSLOADING/UNLOADING, then TRANSLOADED/UNLOADED/SPARE
  • T_FILE: attachments/photos
  • T_INVENTORY_LOT and ledger rows may be created or adjusted on unload/spare paths
  • Inbound loader/planning warehouse-location saves must not block field work because the entered value is Firelane, blocked, inactive, or unmapped in Warehouse Map; invalid/unmapped values may remain only on the legacy T_TRANSLOAD.WAREHOUSE_LOCATION mirror without an active Warehouse Map placement.

Production activity pattern:

  • File/photo upload is one of the most frequent loader actions.
  • cayo, oscar, manuel, rich, danielmacias, cristobal, ruma show repeated start-transloading and complete-transloading.
  • oscar, rich, cayo also show start-unloading/complete-unloading.
  • QuickBooks Time logs show successful staff-time sync for staff user IDs matching loaders, plus skipped/manual review/failed cases.

Production error signals to test:

  • No sendable transloading job was updated.
  • No sendable unloading job was updated.
  • This break is already started or unavailable.
  • Target location not found.
  • QuickBooks Time failures such as clock-out before clock-in or already-on-clock must not break the CTC source write.

Process 3: Yard Truck Dispatch Execution

Primary users:

  • armando
  • ezek

Primary screens:

  • yard-instruction
  • yard-dispatch
  • yard-closing

Observed production endpoints:

  • POST /api/yms/yard-moves/queue/claim
  • POST /api/yms/yard-moves/queue/confirm
  • POST /api/yms/yard-moves/dispatch/complete
  • POST /api/yms/yard-moves/queue/unclaim
  • POST /api/yms/yard-moves/queue-after-clear
  • POST /api/yms/yard-locations/move
  • POST /api/yms/yard-locations/vacate
  • POST /api/bms/scale-tickets/closing
  • POST /api/files

Step-by-step process:

  1. Yard truck user logs in.
  2. User opens yard-instruction.
  3. User refreshes active dispatches.
  4. User reviews Scheduled work or the current user's claimed move; Queued work must first be scheduled by Office.
  5. User claims one Scheduled queue item.
  6. System writes CLAIMED_BY, CLAIMED_AT, and STATUS='CLAIMED'.
  7. User physically moves unit.
  8. If actual location is required, user selects actual delivered location.
  9. For a non-pull move, user selects Complete once; the queue-confirm request moves the item and immediately sets the queue to Completed.
  10. If target is occupied, user must stop and coordinate clear/queue-after-clear.
  11. If claim is wrong or stale before completion, user unclaims.
  12. For a pull-out, user opens Yard Closing, saves the required closing/scale data, and the alternate dispatch-complete request completes the same queue transition.
  13. Office rereads Completed and Yard Map; user may upload file/photo where the closing workflow requires it.

Expected DB state:

  • T_YARD_DISPATCH_QUEUE.STATUS: QUEUED -> Office SCHEDULED -> Yard Driver CLAIMED -> COMPLETED
  • T_YARD_DISPATCH_QUEUE.CLAIMED_BY: armando or ezek
  • T_YARD_LOCATION.OCCUPIED_TYPE/OCCUPIED_ID: changed at completion
  • related equipment mirror fields update after authoritative state

Production activity pattern:

  • armando: 936 recent queue claims, 425 queue confirms, 357 dispatch completes, 118 unclaims, 500 scale-ticket closings in recent logs.
  • ezek: 501 queue claims, 276 queue confirms, 171 dispatch completes, 116 scale-ticket closings in recent logs.

Production error signals to test:

  • Queue item already claimed by another driver.
  • Queue item not found.
  • Current location does not match planned FROM.
  • Target location D1/D3/D5/D11 is still occupied.
  • E Area 40FT requires sibling slot to be free.
  • Queue item must be claimed by the current driver before confirmation.

Process 4: Truck Operator Delivery Execution

Primary users:

  • High-volume: julio, justin, roger, michael, juanbernal, danny, anthony, antonio, steven, lawrence, hector, fernando
  • New/recent active: fgonzalez, hugo, eric

Primary screen:

  • driver-operation

Observed production endpoints:

  • POST /login.php
  • GET /api/tms/drivers/identity
  • GET /api/tms/driver-logs/current
  • GET /api/tms/deliveries/driver-list
  • PATCH /api/tms/deliveries/{id}/field
  • PATCH /api/tms/equipment/{id}/field
  • POST /api/tms/deliveries/{id}/status
  • POST /api/tms/deliveries/{id}/arrival-signal
  • PATCH /api/tms/deliveries/{id}/arrival-action
  • POST /api/tms/deliveries/{id}/location-ping
  • POST /api/yms/yard-locations/move
  • POST /api/yms/yard-locations/vacate
  • POST /api/files

Step-by-step process:

  1. Truck operator logs in.
  2. User opens driver-operation.
  3. System resolves driver identity from logged-in username.
  4. User taps top-level Check In if driver log is not active.
  5. System loads current driver log and delivery list.
  6. User reviews delivery cards.
  7. User starts scheduled delivery.
  8. Delivery status moves toward DISPATCHED.
  9. User enters or edits container number if field is shown.
  10. User enters or edits chassis number if field is shown.
  11. User enters remark if needed.
  12. User taps per-field Save.
  13. User uploads required photo/file.
  14. If entering or leaving yard, driver workflow may call yard move/vacate endpoint.
  15. User may send arrival signal.
  16. Office acts on arrival action if signal flow is enabled.
  17. User completes delivery.
  18. Delivery card locks or limits further edits.
  19. User taps top-level Check Out when done.

Expected DB state:

  • T_DELIVERY.STATUS: SCHEDULED -> DISPATCHED -> DELIVERED/COMPLETED
  • T_DELIVERY field updates for driver-entered values
  • T_DRIVER_LOG reflects active driver session
  • T_FILE stores uploaded delivery/photo files
  • yard location changes occur only through allowed driver/yard workflow

Production activity pattern:

  • Truck operators heavily use POST /api/files.
  • Many truck operators use POST /api/yms/yard-locations/move and vacate during driver/yard completion workflows.
  • Direct yard move writes can be rejected for truck operators.

Production error signals to test:

  • Yard move write access is not allowed for truck operator accounts.
  • Cannot start dispatch until active yard queue is completed.
  • No matching row on delivery/equipment field save.
  • Target location already occupied.
  • SQLSTATE[42S22]: Unknown column 'ARRIVAL_SIGNAL' in 'field list' on arrival-signal. This is an active production error pattern and should be treated as a high-priority regression/bug validation point.

Process 5: Billing / Document Office Work

Primary users:

  • lois
  • davidpark
  • montse
  • daviddlr

Primary screens:

  • AP/AR transaction list pages
  • ar-billing
  • billing-presets
  • scale-ticket-list
  • BOL/email dispatch via owner API v2 routes

localInvoice is gated by the MK document workflow and is not a CTC Billing completion surface.

Observed production endpoints/logs:

  • PATCH /api/bms/transactions/close
  • POST /api/bms/transactions/chassis
  • POST /api/bms/transactions/trucking
  • POST /api/bms/transactions/transload
  • POST /api/bms/transactions/apply-final-transload
  • POST /api/bms/ar-billing/preview
  • POST /api/bms/ar-billing/confirm
  • POST /api/bms/ar-billing/qbo-sync
  • POST /api/bms/scale-tickets
  • POST /api/bms/scale-tickets/closing
  • POST /api/tms/transloads/{id}/bol-email
  • POST /api/tms/bookings/{id}/packing-list/email
  • PATCH /api/files
  • POST /api/files/media/upload

Step-by-step process:

  1. Office/billing user logs in.
  2. User opens transaction, AR/AP, scale, or billing screen.
  3. User filters by date, customer/vendor, equipment/container, reference, or transaction type.
  4. User opens source record.
  5. User verifies source data: transload, trucking, chassis, scale ticket, booking, rates and file attachments.
  6. For a generic AP/AR item, user applies final transload billing or creates source transaction rows, then closes only the reviewed local transactions and rereads each row.
  7. For AR Billing, user opens Review and verifies customer, lines, quantity, rate, amount, invoice number and QBO grouping before selecting Complete once.
  8. Current Complete commits the local AR invoice and immediately attempts QBO delivery. User verifies the local AR result and the QBO result separately.
  9. If QBO reports ERROR, timeout or an unclear result, user searches QBO by customer, document number and amount before retry. A request can partially succeed by group.
  10. User uploads/updates required transaction files and rereads every intended file link.
  11. User sends BOL or packing-list email only through its TMS owner and verifies Gmail/provider evidence.
  12. User closes the work only after required local, provider, file and email checkpoints are independently verified.

Expected DB state:

  • Generic T_TRANSACTION/T_TRANSACTION_LIST rows have the intended local state.
  • AR Billing local rows exist independently of QBO provider state.
  • Local QBO ID/status and provider invoice agree for SYNCED groups; exceptions retain exact evidence/owner.
  • T_FILE rows and stored objects are readable for every intended transaction.
  • BOL/packing-list Gmail evidence is verified separately from accounting completion.

Production activity pattern:

  • daviddlr and davidpark dominate BOL email logs.
  • Recent email logs: daviddlr 162 successful Gmail controller requests, davidpark 116, plus SCALE_TICKET type 229.
  • lois is the strongest transaction user: file updates, close, chassis/trucking/transload transaction creation.

Production error signals to test:

  • Equipment #... has no chassis rate.
  • Container ... has no chassis rate.
  • Ref ... has no matching TRANSLOAD rate.
  • QBO ERROR can follow a provider-created/local-save failure; do not interpret it as proof that no invoice exists.
  • Email/Gmail request should not expose raw file paths or block the UI without a visible error.

Process 6: Warehouse Label Print

Primary user:

  • CTC-WH

Primary screen:

  • warehouse-label-print

Expected process:

  1. CTC-WH logs in.
  2. User opens warehouse-label-print.
  3. User searches/selects a candidate load.
  4. User reviews reference, commodity, quantity, offload date and warehouse location. The displayed three-character customer value is derived from the billing company name rather than a separate customer-code field.
  5. User opens/prints the label and verifies the physical output; the application has no print ledger.
  6. If warehouse location is missing or invalid, user asks office to correct it or uses the separately authorized update flow if enabled.
  7. After an update, user retains the returned selector value. Label reread can prefer planner location and Warehouse Map reads inventory-lot occupancy, so exact placement/mirror parity requires a separately authorized source-level read; after printer failure, user checks for a duplicate physical label before reprinting.

Expected DB state:

  • Candidate/detail reads and browser printing are read-only.
  • If location update is allowed, the active warehouse placement and T_TRANSLOAD.WAREHOUSE_LOCATION compatibility mirror change in one route transaction.
  • Printed labels should not change inventory/yard state.

Test caveat:

  • No meaningful recent production log volume was found for CTC-WH in the inspected window. This flow should still be included because the production role/menu exists.
  • Direct label detail does not repeat candidate status eligibility, and SPARE is printable while the inspected placement-update state set excludes it.

Canonical user procedure is Wiki ctc-labels-reports; mutation boundaries are owned by docs/processes/WAREHOUSE_LABEL_PRINT_WORKFLOW.md.

End-To-End System Test Scenarios

Scenario A: Office Plan To Loader Complete

Recommended users:

  • Office: danielcasillas or anahi
  • Loader: cayo or oscar

Steps:

  1. Office user logs in.
  2. Open inbound-planning.
  3. Select target date.
  4. Find scheduled transload or create test-safe check-in.
  5. Open plan preview.
  6. Set loading type, equipment/load context, billing company, commodity, quantity, dock/warehouse, loader.
  7. Apply plan.
  8. Confirm the row appears in loader-ready/assignment state.
  9. Assign or reorder loader queue if needed.
  10. Loader logs in.
  11. Loader opens inbound-loader.
  12. Loader clocks in.
  13. Loader finds assigned row.
  14. Loader performs dock-in if required.
  15. Loader starts job.
  16. Loader uploads files/photos if required.
  17. Loader completes transload/unload/spare path.
  18. Loader verifies completed tab.
  19. Office user opens loader-timeline.
  20. Office user verifies job start/end and staff-time blocks.

Pass criteria:

  • No new 500 in planning-board or loader APIs.
  • T_LOADING_PLANNER.JOB_STATUS reaches FINISHED.
  • T_STAFF_TIME_EVENT includes clock/job records.
  • UI shows completed row and no stuck spinner.

Scenario B: Office Yard Queue To Yard Truck Complete

Recommended users:

  • Office: danielcasillas
  • Yard: armando or ezek

Steps:

  1. Office user opens yard-dispatch.
  2. Create queue item with entity type, entity id, dispatch type, from location, to location, assigned user.
  3. Preview move if available.
  4. Reorder queue if needed.
  5. Yard user opens yard-instruction.
  6. Yard user claims the Scheduled queue.
  7. Yard user performs the physical move and selects actual location when required.
  8. For a non-pull move, Yard user selects Complete once; queue confirm immediately completes the item.
  9. If target occupied, stop and run clear/queue-after-clear workflow, then reread both queues and Yard Map.
  10. For a pull-out, the claiming user completes Yard Closing instead of the non-pull Complete path.
  11. Office user refreshes yard-map and Yard Dispatch Completed.
  12. Office user verifies occupied/vacated state and no remaining active queue for the entity.

Pass criteria:

  • Queue moves through QUEUED -> SCHEDULED -> CLAIMED -> COMPLETED; queue confirm and dispatch complete are alternate completion entry points, not sequential steps.
  • T_YARD_LOCATION authoritative state is correct.
  • Occupied-target validation remains visible.
  • Completed item is present in completed dispatch history.

Scenario C: Truck Driver Delivery

Recommended users:

  • julio, justin, danny, or another active truck operator with assigned work

Steps:

  1. Truck user logs in.
  2. Open driver-operation.
  3. Confirm driver identity loads.
  4. Check in.
  5. Review assigned delivery cards.
  6. Start scheduled delivery.
  7. Save container/chassis/remark fields.
  8. Upload file/photo.
  9. Trigger yard/location step only through allowed driver workflow.
  10. Send arrival signal if this feature is expected to be active.
  11. Complete delivery.
  12. Check out.

Pass criteria:

  • Delivery status advances.
  • Field saves persist after refresh.
  • File upload persists.
  • Direct forbidden yard move remains blocked.
  • Arrival signal does not hit missing-column SQL error.

Scenario D: Billing / BOL Email

Recommended users:

  • lois, daviddlr, or davidpark

Steps:

  1. Billing user opens relevant AP/AR/transaction screen.
  2. Locate completed transload/trucking/chassis/scale source.
  3. Verify source rates and customer mapping.
  4. Complete either the generic transaction path or AR Billing review path; do not treat them as the same API.
  5. If AR Billing Complete is used, verify the automatic QBO attempt separately from local confirm.
  6. Upload/update file if required and verify every intended link.
  7. Send BOL or packing-list email through the TMS owner when required.
  8. Refresh and verify local transaction, QBO provider, file and email evidence independently.

Pass criteria:

  • Missing rate shows clear validation.
  • Valid local transaction/AR state rereads as intended.
  • SYNCED requires matching provider and local evidence; uncertain ERROR is reconciled before retry.
  • Email provider evidence records the intended recipient/subject/parts.
  • UI does not expose raw server path or hang.

Scenario E: Staff Time And QuickBooks Sync

Recommended users:

  • cayo, oscar, manuel, or rich

Steps:

  1. Loader logs in.
  2. Open inbound-loader.
  3. Clock in.
  4. Start assigned job.
  5. Start assigned break if available.
  6. Complete job.
  7. Clock out.
  8. Inspect QuickBooks Time log for sync status.

Pass criteria:

  • CTC source event writes even if QuickBooks sync is skipped/manual-review/failed.
  • Failed QuickBooks sync is logged with clear status.
  • No invalid clock-out-before-clock-in sequence is generated by the UI.

Current Production Issues To Include In Regression

These are not theoretical; they appeared in recent production logs for field users.

Area Production signal Test expectation
Driver arrival Unknown column 'ARRIVAL_SIGNAL' Arrival signal endpoint/schema must be fixed or feature disabled visibly
Yard permissions truck operators get 403 for direct yard move Direct yard write remains blocked; driver-mediated workflow still works
Dock/yard occupancy target location occupied UI blocks with actionable message and supports clear/queue-after-clear
Loader complete no sendable job updated Button state/status guard prevents invalid duplicate completion
Yard claim item already claimed or not found UI refreshes queue and prevents stale action repeat
Billing rates missing chassis/transload rate Billing shows exact missing-rate validation
QuickBooks Time clock-out before clock-in / already on clock CTC event remains source of truth; sync failure visible in integration log
Menu favorites missing favoriteable menu UUID Favorite action must validate and recover visibly

Verification Queries

Run read-only against production DB through the production server.

SELECT @@hostname AS host, @@port AS port, DATABASE() AS db_name, CURRENT_DATE() AS db_date, VERSION() AS version;

SELECT CLIENT_ID, ROLE_ID, COUNT(*) AS user_count, MAX(LAST_LOGIN) AS latest_login
FROM T_USER
WHERE DELETED_AT IS NULL
  AND USERNAME NOT IN ('superadmin','admin','admin2')
  AND ROLE_ID <> '1'
GROUP BY CLIENT_ID, ROLE_ID
ORDER BY CLIENT_ID, ROLE_ID;

SELECT CLIENT_ID, STATUS, COUNT(*) AS cnt, MAX(UPDATED_AT) AS last_updated
FROM T_TRANSLOAD
WHERE CLIENT_ID = 1
  AND DELETED_AT IS NULL
GROUP BY CLIENT_ID, STATUS
ORDER BY cnt DESC;

SELECT CLIENT_ID, JOB_STATUS, COUNT(*) AS cnt, MAX(UPDATED_AT) AS last_updated
FROM T_LOADING_PLANNER
WHERE CLIENT_ID = 1
  AND DELETED_AT IS NULL
GROUP BY CLIENT_ID, JOB_STATUS
ORDER BY cnt DESC;

SELECT CLIENT_ID, STATUS, DISPATCH_TYPE, COUNT(*) AS cnt, MAX(UPDATED_AT) AS last_updated
FROM T_YARD_DISPATCH_QUEUE
WHERE CLIENT_ID = 1
  AND DELETED_AT IS NULL
GROUP BY CLIENT_ID, STATUS, DISPATCH_TYPE
ORDER BY cnt DESC;

SELECT d.USER_ID, u.USERNAME, u.NAME, COUNT(*) AS deliveries,
       SUM(d.STATUS='SCHEDULED') AS scheduled,
       SUM(d.STATUS='DISPATCHED') AS dispatched,
       SUM(d.STATUS='DELIVERED') AS delivered,
       SUM(d.STATUS='COMPLETED') AS completed,
       MAX(d.UPDATED_AT) AS last_updated
FROM T_DELIVERY d
LEFT JOIN T_USER u ON u.CLIENT_ID = d.CLIENT_ID
  AND u.ID = d.USER_ID
  AND u.DELETED_AT IS NULL
WHERE d.CLIENT_ID = 1
  AND d.DELETED_AT IS NULL
  AND (u.USERNAME IS NULL OR u.USERNAME NOT IN ('superadmin','admin','admin2','jaylee','richard'))
GROUP BY d.USER_ID, u.USERNAME, u.NAME
ORDER BY deliveries DESC;

Release Regression Pack

For any release touching operations, run these with field accounts, not admin accounts.

  1. danielcasillas: inbound-planning, plan preview/apply, yard queue create/edit/reorder, dock-in occupied validation.
  2. anahi: loader assignment, loader telegram, break queue, loading planner.
  3. daviddlr: transload form update, doc submitted, check-in/dock-in, BOL email.
  4. cayo or oscar: inbound-loader clock in, start job, complete job, file upload, clock out.
  5. armando or ezek: yard-instruction claim, confirm, complete, occupied target validation.
  6. julio or justin: driver-operation identity, delivery start, field save, file upload, complete.
  7. lois: billing transaction create/close and missing-rate validation.
  8. CTC-WH: warehouse-label-print load/print smoke.

Do not count superadmin, admin, admin2, jaylee, or richard as passing evidence for field-user workflow readiness.

Local read-only screen baseline — 2026-07-19

This merges the CTC technical screen capture into the test source. It used the authorized Local admin Client-1 menu with GET/HEAD-only routing, aborted all mutation requests, and recorded 20 screens with zero browser writes, zero console/page errors. It is source/navigation evidence only: role matrix, empty/partial/retry, provider, field, and Production behavior remain unproven.

Screen family Entry, state boundary, and required reread Capture / limit
Email Approval Email request, matched transload, appointment and provider reply are separate; never replay appointment mutation only to resend a reply. queue, screen; live role/error matrix unknown.
Appointment / Planner Appointment status is operational authority; capacity blocks do not create/reschedule an appointment. screen, planner; recovery capture unknown.
Inbound Planning / Loader SCHEDULED → ARRIVED → planned/assigned → execution → COMPLETED; planner, staff time, Yard and provider notification are separate owners. planning, loader; error/partial recovery unknown.
Timeline / Completed Timeline and completed views are projections; neither permits execution replay. timeline, completed.
Yard Map / Dispatch / Instruction Map occupancy, queue state, actual placement, Closing and photo evidence are separate; ambiguous completion requires reread of queue and location. map, dispatch, closing; recovery capture unknown.
Driver / delivery logs Delivery execution and Yard handoff are separate; timeout or Undo rereads both owners. driver, list; field-role matrix unknown.
Inventory / reports Physical draft/finalized status is separate from source-lot projection; reports do not authorize overwrites. inventory, administration.
AR Billing / warehouse CTC transaction commit and QBO delivery are separate; label/map/adjustment mutations require exact source/ledger reread. billing, label.

Synthetic local GET-response error screenshots exist for 18 screens under docs/wiki/assets/ctc-screen-manual/. They prove only client error presentation, not a real empty/partial/retry/provider failure. The remaining runtime capture is explicitly UNKNOWN; no behavior fix is inferred from this baseline.

Pre-release local candidate — Assignment Board / Loader

  • Office Manager: Inbound Planning → Assignment Board → Assign Work or Clock Out; select one/many eligible Loaders, inspect each result, retry failed Telegram, and use Assigned-only Edit/Cancel.
  • Forklift Operator: Inbound Loader → NEXT ASSIGNMENT → Start; verify revealed detail/timer, Complete Work, or use the Clock Out workflow. Daily/Deep cleaning requires Cleaning Complete before workflow Clock Out. When assigned, Final Break requires Start Final 10-Minute Break; workflow Clock Out remains disabled until the server timer reaches 10 minutes and never offers Clock Back In.
  • Regression boundary: verify Load/Unload/Reload/DIP, normal Break/Lunch, Timeline, next-job Telegram, Clock In/general Clock Out, and multi-Loader Load separately. Final Break source/local DB evidence is available; Production/provider and target-role field acceptance remain pending.

Source: docs/runbooks/CTC_FIELD_USER_PROCESS_SYSTEM_TEST_RUNBOOK.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged. A user instruction quoted inside the text is kept in its original language.