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

Final Loading Review — Current Source Delta 2026-08-08¶

Status: CURRENT SOURCE-RECONCILED DELTA / POLICY AND TARGET-ROLE EVIDENCE REQUIRED
Current maintenance successor: CURRENT_SOURCE_DOCUMENTATION_MAINTENANCE_2026-08-11.md
Parent Process: FINAL_LOADING_REVIEW_WORKFLOW.md
Current source baseline: qa/master@13991b627eb95b5b675a4eb05048d56f20538439
Relevant commits:
b09c339ec1a7305554af16bd55bc4be1685719b5 — refine Final Loading Review references
13991b627eb95b5b675a4eb05048d56f20538439 — edit Final Review outbound values
Current source owners:
app/systems/WMS/inventory/bale_review_helper.php
app/systems/WMS/inventory/api_routes.php
frontend/pages/system/WMS/inventory/inventory-adjustment.php
Evidence: current RBR-FLR-001; outbound-edit evidence extension defined here as RBR-FLR-002
Effect boundary: documentation only

1. Delta Summary¶

Current source adds two material responsibilities to the earlier Final Loading Review packet.

A. Reference and comparison read model¶

The review now presents four separate business measurements:

Shipper
CTC Inbound
Loading Difference
CTC Outbound

It also presents:

Shipper variance separately from Loading Difference;
one shared Avg/Bale calculation path;
opposite-sign inconsistency;
high average-weight warning;
selected-row preservation after actions;
compact Ready/Confirmed action presentation.

B. Pending outbound correction command¶

Office can edit current CTC Outbound quantity/weight inside a Pending Final Loading Review through a guarded WMS command.

POST /api/wms/inventory/bale-reviews/update-outbound

This is a business command, not a display-only form change.

2. Authority Boundaries¶

Shipper values
= external/reference comparison values
!= workflow state owner

CTC Inbound
= current inbound baseline/fallback displayed by the review read model

CTC Outbound
= current final outbound quantity/weight on T_TRANSLOAD

Loading Difference
= CTC Outbound - CTC Inbound

Shipper Variance
= separate comparison between Shipper and CTC measurement

The current source contract test explicitly requires that SHIPPER_* fields do not affect the workflow state function.

Shipper mismatch
!= automatic DATA_REQUIRED
!= automatic SOURCE_REQUIRED
!= automatic LEFTOVER_REQUIRED
!= automatic WEIGHT_REVIEW

The Shipper comparison is a review aid unless a separately approved policy promotes it to a blocker.

3. Current Queue Column Order¶

Shipper
Inbound
Loading Diff
Outbound

The Inbound/Outbound reference column remains separate and should show inbound reference before outbound reference.

Current visible labels include:

Shipper
CTC Inbound
Loading Difference
CTC Outbound

A future UI may change layout, but it must preserve the four distinct concepts and their provenance.

4. CTC Inbound Baseline¶

Current UI can identify an Initial fallback when the preferred CTC Inbound value is unavailable.

The exact baseline precedence must be documented and accepted from current source/data evidence before migration.

Required target query output:

value
sourceField
sourceRecord
fallbackUsed
fallbackReason
UOM
available

React must not infer the baseline from non-null fields independently.

5. Loading Difference¶

quantity difference
= CTC Outbound quantity - CTC Inbound quantity

weight difference
= CTC Outbound weight - CTC Inbound weight

The difference remains the basis for Extra/Leftover/Load-to-Load review behavior. Shipper variance is not substituted for it.

6. Avg/Bale Calculation¶

The current UI contract uses one calculation path for queue and expanded detail.

Rules:

Avg/Bale is shown only for Pending reviews.
If quantity difference or weight difference is zero, do not calculate a normal average.
If quantity and weight differences have opposite signs, show an inconsistent-difference warning.
When both differences have the same non-zero sign, display:

abs(weight difference / quantity difference)

Negative/negative differences therefore produce a positive displayed average.
High-average warning uses the unrounded average.
Current threshold:

average > 2000 lb/bale

The high-average style applies only to the difference section, not the entire review row.

flowchart TB
    Q[Quantity difference]
    W[Weight difference]
    Z{Either value zero?}
    S{Same sign?}
    A[Average = abs(W / Q)]
    H{Average > 2000?}
    N[No normal average]
    I[Inconsistent difference]
    O[Normal Avg/Bale]
    R[High avg. weight review warning]

    Q --> Z
    W --> Z
    Z -- Yes --> N
    Z -- No --> S
    S -- No --> I
    S -- Yes --> A --> H
    H -- No --> O
    H -- Yes --> R

Open policy:

whether 2,000 remains the accepted business threshold;
whether the warning is advisory or blocking;
UOM conversion and rounding;
whether zero/zero means exact match or unavailable;
whether weight-optional rows omit the entire weight-average calculation.

Current source presents a warning; it does not establish a new server-side Confirm blocker from the threshold alone.

7. Shipper Variance¶

The UI separately reports whether CTC values match the Shipper reference.

Required states include:

Comparison unavailable
Matches shipper
Variance present

Target query output must return the comparison state and calculation inputs. It must not rely on React text parsing.

Open policy:

whether comparison uses CTC Inbound, CTC Outbound, or another accepted basis for each field;
null versus zero semantics;
tolerance and rounding;
UOM mismatch;
when a variance requires an operator note.

8. Pending Outbound Edit Command¶

Current endpoint:

POST /api/wms/inventory/bale-reviews/update-outbound

Current access uses the WMS Final Review owner and Office-style role guard.

Current command flow:

sequenceDiagram
    actor O as Office Operator
    participant UI as Final Review UI
    participant WMS as Final Review Command
    participant DB as MySQL

    O->>UI: Edit Outbound
    UI->>WMS: ID + new values + expected old values
    WMS->>DB: Acquire bounded transload lock
    WMS->>DB: Assert review mutable and reread row
    WMS->>DB: Require operational status TRANSLOADED/SPARE
    WMS->>DB: Validate expected old quantity/weight
    WMS->>DB: Validate new quantity/weight
    WMS->>DB: Conditional update only while PENDING
    WMS->>DB: Clear weight-review reason
    WMS->>DB: Reread state
    WMS-->>UI: Updated values + derived review state
    UI-->>O: Keep selected row and show current state

9. Outbound Edit Preconditions¶

The current command requires:

exact tenant-scoped active Transload;
Final Review remains mutable;
current review status remains PENDING;
operational Transload status is TRANSLOADED or SPARE;
expected old quantity matches current value within the command comparison contract;
expected old weight matches current value;
new quantity is numeric, positive, and a whole number;
weight is required and positive unless the current compatibility rule says weight is optional;
conditional update matches the old quantity/weight at write time.

Current weight-optional compatibility:

uppercase billing company display name == TGI

This customer-name rule is current compatibility behavior, not the desired target policy selector.

Target behavior must use a profile/capability/field policy, not company display-name branching.

10. Outbound Edit Mutation¶

Current source updates:

T_TRANSLOAD.FINAL_COMMODITY_QUANTITY
T_TRANSLOAD.FINAL_COMMODITY_WEIGHT
T_TRANSLOAD.BALE_REVIEW_WEIGHT_REASON = ''

and returns the newly derived review state.

The command does not automatically:

change BALE_REVIEW_STATUS to Confirmed;
create or reverse Inventory Lot/Ledger rows;
create Source/Leftover adjustments;
alter Loader completion evidence;
complete Yard/Driver work;
preserve the previous outbound values in a dedicated immutable correction record.

The last point is an audit/reconstruction gap.

11. Outbound Edit Concurrency¶

The command uses both:

a bounded transload lock; and
expected old quantity/weight comparisons at request and update time.

Conflicts return a refresh-and-retry error instead of overwriting another operator.

response conflict
-> refresh selected review
-> compare current outbound values
-> re-enter intended correction if still valid

Do not bypass the conflict through generic T_TRANSLOAD editing.

12. Outbound Edit Response Loss¶

sequenceDiagram
    actor O as Operator
    participant UI as Browser
    participant WMS as Command
    participant DB as MySQL

    UI->>WMS: Save Outbound with expected values
    WMS->>DB: Conditional update commits
    WMS--xUI: Response lost
    O->>UI: Refresh selected Pending Review
    UI->>DB: Read current outbound + review state
    alt Current values equal submitted values
        UI-->>O: Treat as committed; do not resubmit
    else Current values equal old values
        UI-->>O: Controlled retry after revalidation
    else Different/current conflict
        UI-->>O: Stop and review concurrent change
    end

The current command has no independent request-token result lookup. Exact state reread is required.

13. Review State Recalculation¶

After outbound edit, server-side review state is recalculated from the updated Transload and current ledger summary.

Possible outcomes include:

DATA_REQUIRED
SOURCE_REQUIRED
LEFTOVER_REQUIRED
WEIGHT_REVIEW
READY
CONFIRMED-related display only when status permits

The exact current state function remains authoritative. UI code must not duplicate or override it.

14. Selected-Row Preservation¶

Current source preserves the selected Pending review during in-place review actions and visually de-emphasizes other queue rows.

This is a presentation/continuity requirement:

action result
-> refresh current queue/state
-> keep the affected pending review selected when it remains pending

It does not change Process authority.

15. Current Source Taxonomy¶

Concept	Authority/type
Shipper quantity/weight	external/reference fields
CTC Inbound	server/query baseline with possible initial fallback
CTC Outbound	`T_TRANSLOAD.FINAL_COMMODITY_*`
Loading Difference	derived CTC Outbound - CTC Inbound
Shipper Variance	derived separate comparison
Avg/Bale	derived display/review warning
workflow state	server-side Final Review state function
outbound correction	guarded WMS command while Pending
Confirm/Reopen	existing Final Review commands
Source/Leftover	separate Inventory adjustment commands

16. Target Query Contract¶

Recommended query:

GetFinalLoadingReviewDetail

Required output:

review identity/status/version
operational status
shipper reference values and availability
CTC inbound values, provenance, fallback
CTC outbound values and mutability
loading difference
shipper variance
Avg/Bale result and warning state
weight-optional policy source
review state/outcome
source/leftover/ledger summary
available commands and denial reasons

React only presents this typed result.

17. Target Outbound Correction Command¶

CorrectFinalLoadingOutbound

Input:

review/transload identity
expected version or expected old values
new quantity
new weight or explicit policy-driven omission
reason/reference
request token

Result:

updated outbound values
immutable correction evidence
recalculated review state
difference/variance/average readback
next available actions

Open decision: whether current BALE_REVIEW_WEIGHT_REASON should be cleared, retained, versioned, or replaced by explicit correction history.

18. Evidence Packages¶

`RBR-FLR-001`¶

Existing normal/display/recovery evidence:

queue scopes;
review states;
Confirm/Bulk/Reopen;
Source/Leftover;
Shipper/Inbound/Difference/Outbound display;
Avg/Bale and warning;
role/mobile/current Wiki.

`RBR-FLR-002` — Outbound Correction¶

Required:

intended Office role and denied roles;
Pending-only behavior;
TRANSLOADED and SPARE variants;
positive whole quantity validation;
required/optional weight policy;
stale expected-value conflict;
concurrent operators;
response loss and exact reread;
resulting state transitions;
reason/audit behavior;
Confirm after correction;
Reopen interaction;
source/leftover/ledger non-mutation;
current mobile UI and selected-row preservation;
current Wiki wording.

No evidence execution is authorized by this document.

19. Current Completion¶

Current source delta located: PASS
Read-model behavior source-reconciled: PASS
Outbound correction source-reconciled: PASS
Business policy for reference/tolerance/threshold: OPEN
Role/DB/browser evidence: NOT_RUN
Current Wiki: NOT_READ
M3: NO
M4: NO

20. Maintenance¶

Update this delta when reference provenance, difference/variance formulas, average threshold, weight-optional policy, outbound correction fields, reason/audit behavior, server state calculation, or UI action flow changes.

---¶

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