ACFS VBS Pickup Portal

Core registered user. Umbrella term covering wholesale Freight Forwarder, Freight Forwarder, Transporter, NVOCC (Non-Vessel Operating Common Carrier), Farmers, and Customer/Clearing agents — represented as a single user group with equal feature access (BRD V2.0 §2.1). Access is at COMPANY-ACCOUNT level (one login per company; internal access managed within each company), not individual named users. NVOCCs such as AGS use this same LSP portal to provide release authority as part of the delegation workflow (BRD V2.0 §2.1/glossary) — release authority is an LSP feature, not a separate actor. Each LSP sees only shipments allocated to them. Can delegate to another LSP or a one-off P4TC. Replaces the previous WFF/FF/Carrier actor split. Note: roles are contextual per HBL — the same organisation can appear at different levels (e.g. top-level party on one HBL, delegatee on another). Visibility and role enforcement must be HBL-scoped, not user-scoped.

Deferred to fast follow (BRD v1.5 excludes from Phase 1). Tertiary/one-off user with no portal credentials. Receives email with shipment roster and document portal URL. No persistent account or history. Replaces previous "One-off Customer" and "Freight Forwarder" (magic-link) actors.

Secondary user. No portal access. No direct system communication — the booking party manages driver rostering externally and forwards booking details to the driver.

Internal ACFS staff. Manages HBL assignment, slot configuration, booking operations, DO validation, pickup verification, HBL hierarchy correction, and user management. REVISED 2026-08-20: the former Admin / User pair is superseded by EIGHT granular capability roles — Gatehouse (read-only, default), Validate Delivery Orders, Apply Override Release, Correct HBL Hierarchy, FAK Frontdesk, Amend Bookings, Create New LSP Accounts, Full Admin (BR-014, Confluence LCBP 2715320321). Roles are grants and combine, so one person may hold several. Two operational groups sit behind these roles: GATEHOUSE staff, who police site access and admit only trucks holding a booking (read-only booking list, searchable by truck rego), and FAK FRONT DESK staff, who take the booking reference from the arriving driver and process the collection in Maximus. Where a responsibility below says "Admin", read it as the Full Admin role unless a narrower role covers it.

Primary tracking unit for a shipment. Sourced from Maximus in REAL TIME via MuleSoft APIs — fetched on each page load of relevant views and on manual refresh (BRD V2.0 §6.2/§7, FR-ADM-16; supersedes the former once/twice-daily batch sync — OQ-006). HBL hierarchy level is determined by the FFO flag from the EDI Requested Cargo table (BR-040): records WITHOUT an FFO flag are lowest-level HBLs (require a DO); records WITH an FFO flag are intermediate/upper-level (require only a digital release, BR-041). Two orthogonal dimensions: milestone (physical progress) and HBL status (delegation/booking state). BRD v1.5 flattens these into a single lifecycle (Unassigned → Assigned → Delegated → Booked → Collected) — the mapping is: BRD lifecycle = hbl_status + the "collected" milestone. Both dimensions are needed for implementation since an HBL can be e.g. in_yard + delegated simultaneously. HBLs exist in a hierarchy: AGS issues master HBLs (often 500-prefix), freight forwarders issue lower-level HBLs (e.g. 4033-prefix for Mondial). Mostly 1:1 parent-child relationship. The portal primarily deals with the lowest-level HBL as the primary identifier. An HBL may cover multiple cargo items (forwarders may consolidate multiple shipments into a single HBL per BRD v1.6 Addendum 1); when a forwarder splits cargo across different transport partners it generates child HBL references for the subsets, and items logically inherit the parent HBL reference (no physical re-tagging on the cargo). Full audit trail lives on HBL — shows all hops, delegation chain, assignment changes, and status transitions. Note: "booked" is derived from related_bookings and is NOT surfaced as a shipment-level status in the ACFS shipments/assignment view (VBS daily standup 2026-06-04) — though it remains an hbl_status value for the data model and the ACFS bookings view.

Groups one or more HBLs into a pickup window, distributed across one or more TRUCKS (BRD V2.0 §4.3, FR-LSP-30). Created by LSP or P4TC. Each truck carries its own driver details and its own assigned HBL list (see truck entity); a single consolidated payment covers the whole booking regardless of truck count (FR-LSP-36). No truck type distinction for Phase 1 — booking party is responsible for bringing the correct truck. Slim audit trail at booking level (created, payment confirmed). Full hop history lives on the HBL entity instead. "Complete" status is derived — booking becomes complete when all its HBLs reach the "collected" milestone (Tally Out; no manual status change). Booking statuses are Open / Processed / Complete / Cancelled (BRD V2.0 §6.1; see lifecycle warn for the mapping from the older standup names). NOTE: BRD V2.0 restructures the former single-driver/single-truck booking into a booking → many-trucks shape; the driver_name/driver_license/truck_rego fields moved off Booking onto the truck entity.

New entity (BRD V2.0 §6.1, FR-LSP-30). A vehicle assigned to collect one or more HBLs within a single booking. A booking may contain multiple trucks, each with its own driver details and its own assigned HBL list. Driver details are entered fresh per truck per booking for Phase 1 (saved drivers deferred — A-025). Trucks with unresolved readiness errors or incomplete driver details are visually flagged in the booking UI (FR-LSP-33).

A configurable pickup window at a specific site. Configured by ACFS admin. No truck type distinction for Phase 1. Granularity is AM / PM half-day for Phase 1 (start/end times bound the half-day window). The slot selector is presented INLINE within the booking interface (not a pop-up) and supports week-by-week navigation (BRD V2.0 FR-LSP-14). Each slot card shows the NUMBER OF TRUCKS already booked on that slot for the selected date — the client decided on 2026-07-09 to reveal the actual truck count, reversing the earlier "heatmap without revealing counts" model (see OQ-065; FR-LSP-14 addendum). This count is booked_truck_count (a derived, per-date aggregate, NOT a stored field on the slot template) — see below. The heat_map_threshold is retained to optionally colour the count by busyness band, but the raw number is now the primary display. Booking is never blocked by the count — it is informational only (no hard capacity limits, BR-005). Note: AM/PM half-day granularity is retained as the working assumption.

Physical warehouse/pickup location. Seeded directly in the database — no admin CRUD UI for Phase 1. The pickup site for an HBL is resolved from its branch code (BRD V2.0 FR-INT-06, BR-043): branch code is the mapping key, with one FAK location per branch/state for the initial mapping (to be validated with ACFS Operations before go-live — OQ-047).

HBLs are assigned to the target LSP and visible in their shipment list on next login.

Pickup slots are configured and available for LSP/P4TC booking.

Release authority is recorded per HBL (digital release for non-lowest levels, DO uploaded for lowest levels), allowing downstream parties to proceed toward booking once all required levels have release authority.

Shipments are delegated to the chosen recipient(s). Target LSP(s) receive email with a secure access link. HBL status moves to "delegated" and assigned_lsp updates to the delegatee (BR-038).

Booking is confirmed with a unique reference, spanning one or more trucks with their assigned HBLs, paid via a single consolidated payment. HBLs move to hbl_status "booked". Confirmation sent to account email.

Delegation can happen at any milestone — no unpack gate. Booking requires all included HBLs to have milestone "unpacked" or later (confirmed via a CFS Tally In Head record, BRD V2.0 §3/§4.3) AND fully customs cleared (including quarantine) AND release authority granted — EXCEPT under-bond HBLs, whose verified movement permission stands in for customs clearance. Release authority for the BOOK gate means a DIGITAL RELEASE for non-lowest-level HBLs, or all required DOs ACFS-VALIDATED (or do_waived) for lowest-level HBLs. REVISED 17 Jul 2026 (Jaffar update from Matt/Roni): merely uploaded or pending-validation DOs no longer permit booking. LSPs upload DOs independently from the shipment page; ACFS validates them on the Documents queue; only then does the HBL become available to book. This supersedes the BRD V2.0 FR-LSP-08/29 uploaded-only wording and removes the former asymmetry between release_status and the booking gate. The gate is therefore: milestone "unpacked"-or-later (Tally In) AND (customs cleared OR under_bond_verified) AND (release authority: digital release [non-lowest] OR DOs validated/do_waived [lowest]). Delegate remains available independently of booking readiness. (Under-bond customs substitution is an inference pending confirmation — OQ-045.) CLARIFIED 2026-08-20 (VBPP-226 BR-4, VBPP-227): the hbl.release_status SUMMARY FIELD is not itself an eligibility condition at any of its values — including "Override". Eligibility is evaluated on HBL status, customs status and DO docs status only. This is not a loosening of the gate: for a LOWEST-level HBL the DO-docs condition already carries the release requirement, and an INTERMEDIATE HBL cannot initiate a booking at all (only the lowest-level reference holder can), so there is no case where an intermediate's pending release should block someone else's booking. Read release_status as reporting, and the three conditions above as gating.

Release authority per HBL has TWO forms selected by hbl_level_indicator (BR-040): a DIGITAL RELEASE for intermediate HBLs (owned by BR-041) or a DO-based release for lowest-level HBLs (owned by THIS rule). A shipment cannot be collected unless release authority is satisfied at ALL required levels; release_status is the derived per-HBL rollup. This rule governs the LOWEST-LEVEL DO/waiver chain. DO requirement per (lowest-level) HBL: each delegation tier uploads its own DO (uploads are per-tier, not auto-copied), but the required DO SET for a child HBL is its own DO PLUS all ancestor-tier DOs — release authority cascades down the split chain (VBS daily standup 2026-06-04: parent shipment 1 holds DO1; child shipment 2 needs DO1 + DO2, child shipment 3 needs DO1 + DO3, so the driver collecting HBL3 carries DO1 + DO3). BRD v1.6 Addendum 1 frames this as a release-authority chain: each party validates the next lower level and provides a Digital Release Authority, and a shipment must have a release from ALL parties (plus unpacked + customs cleared) to be collectable. ACFS validates each DO individually (HBL-centric). DO requirement is waived by under_bond flag OR free_release flag, both of which require ACFS verification outside the portal before do_waived becomes true. Set-by-party differs: under_bond can be marked by LSP or ACFS (manual flag, ACFS-verified), but free_release is ACFS-only — LSPs cannot self-mark and must request offline; ACFS then sets and verifies in the admin portal. (free_release ACFS-only confirmed in VBS Screen Review meeting 2026-05-21 — Matt: "it would definitely need to be verified [by ACFS]".) Bottom-most party must have all applicable tiers' DOs present (own + inherited).

An LSP can either delegate OR book a given HBL — never both — for the hop they currently hold. Mutual exclusivity is per-HBL AND per-hop: once the active party (assigned_lsp) delegates the HBL onward, THEY can no longer book it (it has left their hands), but the delegatee — now the assigned_lsp — can. Enforce against assigned_lsp + the viewing party, NOT by reading the global hbl_status "delegated" value (which would wrongly block the delegatee). See the hbl_status field note and BR-038.

Slots are AM / PM half-day windows. Slot cutoffs are relative day + time (e.g. "previous working day, 4 PM" or "same day, 10 AM"). Booking cutoff and change cutoff configured separately per slot template. Per-site configuration. No hard capacity limits. BLACKOUT DATES (added 2026-08-20): blackout dates are slot configuration data written through the same admin API as the slot itself and must round-trip to the slot read (VBPP-212). They are not merely display — "previous working day" arithmetic for BOTH cutoffs must SKIP blackout dates and non-working days when resolving the actual cutoff datetime (VBPP-256). Cutoff enforcement is server-side: a booking or change attempt after the resolved cutoff is refused with a cutoff notice, not silently accepted (VBPP-202, VBPP-232, VBPP-253, VBPP-254). Two cutoff questions remain open — whether cutoff times resolve in each site's local timezone (OQ-079) and whether a site may be configured with no booking cutoff at all (OQ-080); this rule currently assumes a cutoff always exists. The slot selector is inline (not a pop-up) with week-by-week navigation and each slot card shows the NUMBER OF TRUCKS already booked on that slot for the selected date (slot.booked_truck_count) — client decision 2026-07-09 (OQ-065, FR-LSP-14 addendum), which reveals the actual count and supersedes the earlier "heatmap without revealing counts" model. heat_map_threshold now only optionally colours that visible number by busyness band. The count is informational and NEVER blocks booking (no hard capacity limits).

ACFS can partially process bookings — HBLs that have cleared customs proceed to "processed" while blocked ones are rebooked separately.

Driver has no portal access. Booking party manages driver communication externally.

P4TC (one-off) has no persistent credentials. Services shipments via magic link + OTP only. No account history. No saved driver records.

Site management is DB-seeded for Phase 1 — no admin CRUD UI. Sites have name + branch code only.

Desktop/laptop only. No tablet or mobile responsive design required. Portal is not meant for warehouse staff walking around — it is for counter/desk use.

Email is the primary notification channel. In-app notifications are available for logged-in users (LSPs, ACFS) but are not a Phase 1 blocker. P4TC (no login) receives email only.

What are the confirmed milestone statuses from the client?

What is the full list of release types and their DO rules?

What is the minimum charge amount and is the rate truly flat across all scenarios?

What is the exact definition and lifecycle of under-bond shipments?

What is the first-time signup flow for a booking party (LSP)?