Skip to content

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

Platform Access Diagnostics — Current Operational Surface Addendum

  • Status: CURRENT SOURCE-RECONCILED SUPPORT DRAFT / NOT FIELD ACCEPTED
  • Review ref: qa/master@2c0dd0bfadde7633337ec4357be1cbf9835c5c8b
  • Parent Runbook: PLATFORM_ACCESS_DIAGNOSTICS_ADMIN_SUPPORT_RUNBOOK.md
  • Source refresh: PLATFORM_AUTHORIZATION_CURRENT_SURFACE_REFRESH_2026-08-08.md
  • Action matrix: PLATFORM_AUTHORIZATION_CURRENT_ACTION_MATRIX_2026-08-08.md
  • Evidence package: RBR-ACCESS-001-READONLY-CURRENT-SURFACE-PREFLIGHT.md
  • Phase implementation: USER HOLD

1. Purpose

Use this addendum when a user reports:

The page is missing.
The page opens but data does not load.
The action button is missing.
The action button appears but the API denies it.
A direct API request succeeds while the UI hides the action.
Client 1 and Client 2 behave differently.
An Administrator works but the operational role does not.

This is a diagnostic procedure. It does not authorize broad role changes or action retries.

2. Required Diagnostic Order

Always investigate in this order:

1. Environment and source SHA
2. Physical actor / effective subject / tenant
3. Role IDs and role names
4. Module resolution
5. Menu findability
6. Direct page access
7. Initial GET API
8. Action-control visibility
9. Route metadata
10. Handler actor predicate
11. Record tenant/relation
12. Record state
13. Config/credential/provider requirement
14. Expected versus actual decision

Do not skip directly to a role grant.

3. Evidence To Capture

Environment:
Source SHA:
Config reference:
Tenant/profile:
Actor user ID:
Effective subject user ID:
Impersonation mode:
Role IDs:
Role names:
Page route:
Normal menu path:
Initial GET API:
Action label:
Action route/method:
Approved record ID:
Record tenant/state:
Expected result:
Actual result:
Mutation observed: YES/NO
Provider effect observed: YES/NO

Do not include passwords, cookies, tokens or broad customer data.

4. Loader Work Assignment

4.1 Manager cannot see or manage assignments

Check separately:

Page UI compatibility:
CLIENT_ID 1 and numeric role 1/2/3 on Inbound Planning

API manager compatibility:
role name contains Administrator, Office Manager or Manager

Possible mismatch:

numeric page allow + role-name API deny
numeric page hide + role-name API allow

Do not fix this by assigning Administrator. Record both decisions and escalate the exact mismatch.

4.2 Loader cannot see or act on own assignment

Verify:

  • effective staff user ID;
  • planner LOADER_NAME relation;
  • tenant;
  • SPECIAL_INSTRUCTION='QUEUE_WORK_ASSIGNMENT';
  • current/next queue position;
  • SCHEDULED or STARTED state;
  • clock/break state;
  • competing current work.

A manager's ability to act does not prove the Loader self path is correct.

4.3 Hidden general Clock Out versus workflow Clock Out

The Work Assignment route and the general Staff Time route use different guards. Diagnose the exact row representation and current state before concluding the action is denied or available correctly.

Do not advise the Loader to bypass the workflow with the general Clock Out action.

5. Street Turn

5.1 Create unavailable

Check:

Import Dispatch page access
YMS Container Tracking module
Street Turn control visibility
Booking search access through TMS Booking
source equipment load is EMPTY
matching equipment relation
supported size
matching active EXPORT booking
shipping line
cutoff

The create route has strong record/state checks but no dedicated action-role declaration in the reviewed source.

5.2 Revert unavailable

Check:

Export page access
TMS Booking module
Revert control state
exact generated export equipment-load ID
container Street Turn status AVAILABLE
no Delivery history
no Transload history
matching prior RETURNED import load

Create access does not prove Revert access because the routes use different module keys.

5.3 Do not bypass blockers

Do not remove Delivery/Transload history, change state manually or call a generic mutation to force Revert.

6. Final Loading Review

6.1 Page opens but write action denied

For Client 1, current write helper expects numeric role 1, 2 or 3.

For other tenants, the same helper does not apply an equivalent explicit role restriction. Record the tenant-specific result; do not copy the Client 1 numeric rule into another tenant as an emergency fix.

6.2 Control visible to a denied user

The current page renders operational controls and relies on the API for final enforcement. Record:

control visible
API result
record state
no-mutation proof

Hide/show mismatch is a UI/API parity issue, not proof that the API must be opened.

6.3 Record-state denial

Confirm whether the denial is caused by:

  • role/tenant policy;
  • stale expected values;
  • Pending/Confirmed state;
  • missing source/weight/leftover data;
  • domain mutation guard.

Do not solve a state denial by changing a role.

7. AR Billing And QBO

7.1 Read page unavailable

Check:

bms.transaction module
current menu row
current role list
normal page entry
AR Billing GET APIs
schema readiness

7.2 Confirm or QBO action unexpectedly available

The reviewed routes do not declare a dedicated action role. Before changing anything, record:

  • current role/account;
  • menu/page source;
  • control visibility;
  • direct API result only if a disposable authorized fixture exists;
  • current local QBO state;
  • whether a provider effect occurred.

Do not test QBO delivery merely to determine access.

7.3 Unexpected denial

Separate:

access denial
business validation
QBO state conflict
credential/config unavailable
provider failure

Giving a broader role cannot resolve missing source mapping, stale QBO state or provider configuration.

8. BOL And Packing List Email

8.1 Send control missing

Check page/menu/module and current UI conditions. The send routes do not contain a dedicated action-role declaration in the reviewed source.

8.2 Send API denies or fails

Separate:

access
record not found/foreign tenant
recipient missing/invalid
attachment generation/readability
report-mode prerequisite
provider initialization
provider rejection/unknown result

Do not resend after a missing response until provider evidence is reconciled.

9. Safe Temporary Disposition

While policy remains unknown:

Unexpected allow
-> stop the consequential action
-> preserve evidence
-> do not broaden use

Unexpected deny
-> preserve current operational fallback if one is already accepted
-> do not assign Administrator
-> escalate exact matrix row

UI/API mismatch
-> treat API as the enforcement result
-> preserve no-mutation evidence
-> correct only through a bounded approved change

Tenant asymmetry
-> document profile/role expectation
-> do not add another numeric tenant branch

10. Escalation Packet

Incident/request title:
Environment/source/config:
Tenant/profile:
Actor/subject/roles:
Page/menu result:
API route/method:
Route module/role metadata:
Handler actor predicate:
Record ID/tenant/state:
Expected decision:
Actual decision:
UI/API mismatch:
Mutation/provider effect:
Current workaround:
Proposed bounded correction:
Rollback:
Evidence links:

11. Completion Criteria

A diagnostic is complete only when:

the exact failing access layer is identified
+ business-state errors are separated from access errors
+ no unintended mutation occurred
+ no broad role grant was used
+ expected/actual matrix row is recorded
+ the next owner is named

This Runbook does not establish M3 or authorize a policy rollout.

---

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