User Journey Click any block

What happens

Admin creates a new EventDef. This is the root of the hierarchy — every match, purchase, sale, and credential downstream belongs to one event.

Form preview

Data written

Scenarios

Side effects

• Notification event.created → role:ops_manager
• Activates the event switcher dropdown — users can switch into it
• Nothing allocated or purchased yet — event in DRAFT

Why

Schedules are typically acquired 12+ months in advance. System accepts the whole season/tournament in one file, parses venues / categories / sessions, and creates MatchDef[] in bulk. Placeholder teams are preserved for later resolution.

Form preview · column mapper

Parsing logic

• Group flat rows by Session CODE → one MatchDef + N SubGameCategory
• Normalise match codes: M1/M01/M001 → M01 (FIFA). Olympics codes pass verbatim
• Parse S.Desc stage keywords: Final, Finals, Semi-finals, Bronze, Group N, Qualifications, Preliminary, Round of 16, Eliminations
• Fuzzy-match Venue against Venues master; create new Venue records on the fly for unknowns (with admin review)
• Detect placeholder teams: TBD, Qualifier N, Winner {match-ref}, Winner Group A vs Runner-up Group B
• Medal = Y/N → isMedalSession: boolean (drives notification priority)

Data written

Scenarios

Form preview · Add match

Placeholder team support

• Placeholder values accepted at creation: TBD · Qualifier 1 · Winner QF1 · Winner Group A · Runner-up Group B
• Stored verbatim in teamsOrDescription. Also parsed into a structured teams object with placeholderRef field
• Tickets can be sold against placeholder matches immediately
• See B7b · Placeholder resolution for how they resolve

Auto-sort (natural order)

Data written

When needed

• FIFA match: 1 SubGame (auto-created, type MATCH)
• F1 weekend: 4 SubGames — FP1 · Qualifying · Sprint · Race
• Olympics session: 1 SubGame per session (already modelled in the flat import); rarely split further
• Concert multi-day: 1 SubGame per day

Form preview

Session types

Schemes (per event)

Data written

Form preview

Why

Enables visual allocation, "consecutive seats" support, seat-proximity scoring, and client-portal block/row/seat filtering.

Form preview

What visual allocation unlocks (see B18)

• Lasso-select seats to allocate a block of contiguous tickets
• "Consecutive seats" special-instruction enforcement
• Seat-proximity penalty in allocation scoring (so scattered allocation is discouraged)
• Client portal can filter by Block / Row / Seat range

Form preview · Enter match result

Cascade

• All matches with teams.home.placeholderRef == "Winner QF1" update to "Brazil"
• Each resolution triggers a notification match.teams_resolved → clients holding tickets for that match
• Client portals refresh automatically (the Game column updates)
• If resolving M57 makes M61 fully resolvable, cascade continues

Scenarios

Form preview

Special: Matthias masking

Form preview

One client · many matches

A client buys tickets across many matches in one tournament. The Sales form's line-item section supports mixed matches — see B14.

Form preview

Per-event or global

• eventId = null → global credential (fallback across events)
• eventId = evtX → event-specific (wins over global)
• getBestCredential(vendorId, eventId) prefers event-specific

Form preview

Credential history

Form preview · revised layout

Client rules

• Invoice per purchase. Every new purchase carries its own Invoice No. — purchases are created as virgin entries with no pre-linked contract data. Contract is an optional afterthought, not an auto-fill.
• Bulk across matches: same Vendor + Invoice (and, when relevant, Contract) can cover many matches in one purchase — Match is chosen per line, not per purchase.
• Each line item = its own Set. A different match OR the same match + different category = a separate SetID. A set represents a contiguous seat bundle (Block/Row/Seats) for allocation.
• Unit IDs are immutable. Once units are generated they keep their ID forever, even if the purchase is edited or partially cancelled.
• Cancellation-safe. Cancelling a whole purchase, a single line, or an individual unit only deletes those rows — other units in the same purchase are untouched.
• Match / session dropdown is natural-sorted. Tournament codes render M01 → M02 → M10 → … → M64 → M100 → M104 regardless of the order they were imported or created.

Data written

What happens

• For each line item with qty N → generate a new SetID and create N _PURCHASE_UNITS rows inside that set.
• SetID = P<5-digit running counter> — e.g. P00012, P00013, P00014. Each line gets a fresh SetID, even within the same purchase.
• UnitID = <SetID>-<SetPos> — e.g. P00012-1, P00012-2, … P00012-5. Sequential per set, 1-based.
• SetSize = N · SetPos = 1..N · Status = AVAILABLE · AllocatedToSalesID = "".
• Block/Row/Seat blank at first; allocator or supplier portal fills them later.

Example · 3-line purchase above

Immutability & cancellation

• UnitIDs never change. Editing the parent Purchase (price correction, delivery channel change) preserves every unit row.
• Partial cancel: cancelling one line or a few units only removes those specific rows — the rest of the set and other sets in the same purchase keep their IDs and statuses.
• If a cancelled unit had already been allocated to a sale, the AllocatedToSalesID link is cleared and the linked DistRow flips back to UNALLOCATED.

Data written

Form preview

Form preview · revised layout

Form UX rules (revised)

• Invoice No. is mandatory per sale — sales are virgin records, not auto-linked to any contract. Contract field is optional, manually chosen only when a negotiated B10 contract applies.
• Client field moves up, typable with autocomplete. Client's Phone from the master (B9) is shown next to the client name for quick urgent-contact lookup.
• Match field moves DOWN into each line item — one client can buy across many matches in one sale. Match dropdown is natural-sorted (M01 → M02 → M10 → … → M64 → M100 → M104).
• Currency is USD or EUR only. FX field removed — user rationale: "only 2 currencies USD & EUR, no need for FX in here"
• Real-time inventory feedback per line: green enough · amber close · red oversell

Data written

Credit check

• Computes currentOutstanding + saleTotal vs client.creditLimit
• Operator: blocked if exceeded → requires manager override
• Manager: tick creditOverridden + enter reason → proceed

Oversell check

• Per-line: if qty > available inventory → oversellFlag=true · status=PENDING_APPROVAL
• Fires notification oversell.raised → ops_manager
• Line waits for resolution (see B19c)

What happens

• Each sale-line with qty N → N child DistRows
• ID = S<salesId>-<n> e.g. S147-1, S147-2, S147-3, S147-4
• SalesLineKey = <SourceSaleID>#<child> — immutable dedup key for re-imports
• Sets field: N on parent-child row only, 0 on others
• Vendor / Email / Password / AllocatedUnitIDs all blank (allocator fills later)

Re-import safety

Sales ↔ Purchase traceability

• When the allocator assigns units to this sale, each DistRow records the concrete UnitID(s) it received — e.g. S147-1 → P00012-7, S147-2 → P00012-8.
• On the unit side, _PURCHASE_UNITS.AllocatedToSalesID is stamped with the SalesID that consumed it.
• These two pointers are the permanent trail — for any ticket we can always answer "which client did this go to?" (Unit → SalesID) and "which tickets did this client get?" (SalesID → DistRow.AllocatedUnitIDs).
• Edits or partial cancels on either side update the link but never change SalesID or UnitID themselves.

4-strategy generator

• EXACT — smallest single set with count ≥ qty (min waste)
• GREEDY_LARGEST — fill from largest sets (fewer chunks)
• GREEDY_SMALLEST — fill from smallest (tighter fit)
• ROTATED_DESC — up to 5 rotations of largest-first ordering (vendor diversity)

Dedup canonical signatures. Sort: closest-to-target → fewest chunks → largest total. Return top 6.

Scoring formula

Components

• Exactness — linear decay from 1 if plan total = target qty
• Margin — (saleUnitPrice − avgCost) / saleUnitPrice
• Continuity — 1 / chunks.length (single-set = 1.0, two-set = 0.5)
• Upgrade penalty — fires when pulling from higher-tier category
• Multi-vendor penalty — discourages mixing sources
• Split penalty — (chunks − 1) / chunks

Constraints

1. Vendor blocklist
2. Vendor whitelist
3. Upgrade allowed
4. Upgrade rank gap ≤ N
5. Downgrade allowed
6. Downgrade rank gap ≤ N
7. Minimum margin %
8. Max auto-commit value (FULLY_AUTO only)
9. Split policy: SINGLE_SET_ONLY / ALLOW_MULTI_SET / REQUIRE_MIN_CHUNK_SIZE
10. Require vendor diversity
11. Exclude VIP (Al Habtoor Group is VIP)

Each plan gets passesPolicy flag + violation messages. Top-scoring passing plan is the recommendation.

Transaction (with 20s lock)

• Distribution child rows: Status=ALLOCATED · Vendor · Email · Password · Cont. No. · Tix=1 · ACC Tix · AllocatedUnitIDs · AllocatedCount=1 · AllocNote · RunID
• _PURCHASE_UNITS: Status AVAILABLE→ALLOCATED · AllocatedToSalesID · AllocatedAt
• Matthias masking applied on write (see B8)
• Process_Now checkbox unticked (single-checkbox guard)

Visual allocator (if seat map available)

Optional: operator picks consecutive seats on the rendered stadium layout. Seats flagged OCCUPIED. Same commit path, with Block/Row/Seat populated.

Why this view exists

Before accepting a new sale, re-allocating, or quoting a small client, ops needs a single screen that answers "what do we still have on hand, and where are those seats?". The Remaining Stocks view reads _PURCHASE_UNITS where Status = AVAILABLE and groups by match → category → (block, row), so unassigned stock is visible at a glance.

Layout preview

Group-by rules

• Match — natural-sorted by code (M01 → M104).
• Category — sorted by level (Top Cat 1 → Cat 1 → Cat 2 → … or First → A → B → C → …).
• Seat location — grouped by (block, row). Every group shows count, seat-range (derived from consecutive seat numbers), and a link that opens those specific units in the allocator.
• Unassigned tail — units where block/row/seat are blank render last per category as "unassigned / remaining".

Computation

Client use case

Operations

• INV_unallocateSelectedSale — release all units for a sale
• INV_unallocateBySetId — release units from one SetID only
• INV_resetSeatsBySetId — clear Block/Row/Seat (keep allocation)
• INV_setAllocFromCategoryForSelectedSale — category upgrade override
• INV_clearAllocFromCategoryForSelectedSale — revert to base category

Confirm UX

Trigger

Allocator finds no AVAILABLE units for the target (match + category). Writes:

Resolution

Procurement team sources more — once new units enter _PURCHASE_UNITS, operator re-runs allocation.

Three paths

• Approve — source extra inventory (bear the risk). Line → ALLOCATED
• Reject — remove line from sale · client notified · refund triggered
• Upgrade — proposes higher category (new price/margin) · AllocFromCategory set → allocator draws from that pool

Row schema

Action types

What happens

• Normalise company name → group key (strips VIP/Premium/Inc/Ltd suffixes)
• Filter Distribution rows where Company matches group
• Create / refresh workbook named after group
• Exact column layout (K–U read-only, AB–AF editable yellow — see B22)
• Token URL generated, valid for event.portalTokenExpiryDays (default 14)

Why this exists

Clients (both logged-in on the portal and prospective small clients receiving a link) need to see what categories exist, what they cost, and what the seats actually look like — before they commit to a sale. This is one page with two modes of access.

Layout preview

Two access modes

• Embedded in Client Portal (B21). Logged-in clients see a "Price List" tab alongside their allocation workbook. Seat-map hover / click highlights the category zone and the remaining count updates live from _PURCHASE_UNITS.
• Standalone shareable link — ops generates an independent token URL (/price-list/<eventId>?token=…) for small clients who don't have a portal workbook yet. Read-only. Doesn't expose stock-per-block; shows category-level availability only ("Many", "Limited", "Sold out"). Expires on the same portalTokenExpiryDays default.

Seat-map rendering

• Pulls the venue's _SEAT_MAP (B7) and re-colours zones using the active category palette.
• Hover reveals: category label · price · remaining count.
• Mobile-friendly fallback: a sorted price table (no SVG), still linked to the same numbers.

Data source

Advanced filter bar (new requirement)

Yellow guest block (AB–AF)

One row per allocated ticket. Editable fields:

P vs Q columns (screenshot #3)

• P · Total SETS / Purchased qty — e.g. 4 if client bought 4 tickets
• Q · Allc / Allocated qty — populated from Distribution. If 4 → 4 attendee rows editable; if 0 → all rows greyed (waiting allocation)

Copy-down

Common: all 4 tickets in a set go to one booker. One-click copies guest block down to selected rows.

OnEdit cascade

1. Client edits AB:AF cell
2. onEdit trigger writes to hidden _CLIENT_INPUTS vault (preserves data across refreshes)
3. Batch sync (or onEdit) writes back to Distribution: First name · Last Name · Client Email · Comment · Clients notes
4. Distribution onEdit cascades to Staff Queue (ClientFirstName / ClientLastName / ClientEmail) and Supplier Queue

Three UX patterns

• Per-ticket — "Accept" button on each SENT row
• Bulk — multi-select → "Accept selected" (e.g. 50 rows)
• Filtered-bulk — "Accept all SENT in current filter view"

Form preview

Cascade

Triggers dispatch.accepted notification → sale operator + ops_manager. Closes out dispatch obligation.

Auto-build

• Every Distribution SALES row with AllocatedUnitIDs → row in _STAFF_QUEUE
• Same rows where vendor is a FEW-supplier → also in _SUPPLIER_QUEUE (with redaction)
• Preserves existing AssignedTo · Priority · DispatchStatus · DispatchedAt · StaffNotes

Form

Detail panel

• TaskID · Match · Category · Qty · Company · INV_NO · Block/Row/Seat
• Vendor: Email · Password (show/hide · PASSWORD_VIEWED audit fires · auto-hide 30s)
• Client: First name · Last Name · Email · Phone · Notes

1. Staff opens vendor website
2. Logs in using stored email + password
3. Searches for listing by INV_NO
4. Enters Client Email → send ticket
5. Captures proof (screenshot / confirmation URL) → returns to TicketOps

Form

Sequence (user-confirmed)

1. FEW supplier detected via SUPPLIER_manualGroupMap_() + email-pattern fallback
2. For every _PURCHASE_UNITS row from that supplier → row in supplier sheet (inventory listing)
3. Supplier can verify their own purchases against our records before any sale happens

Canonical data flow

Redaction (enforced at write-time)

• Company = "MIRRA" hardcoded on every supplier row — on the supplier sheet this is letter-column N (14th column). User wording: "Column N hides or limits client details to protect privacy"
• Vendor / Password / Email (vendor side) columns hidden
• Price / Total hidden (our margin)
• First name / Last Name / Client Email visible (needed for delivery)
• INV-NO visible (their own reference)

Supplier emails/uploads the ticket to the Client Email via their own system. No TicketOps login required for the send itself.

Allowed Delivery values

UPLOADED is unique to supplier Delivery — means ticket has been uploaded to their platform but client hasn't confirmed.

Chain

1. Staff/Supplier marks status on their workbook
2. onEdit writes to _STAFF_QUEUE / _SUPPLIER_QUEUE
3. Queue onEdit writes to Distribution: Delivery · DispatchNotes · DispatchedAt
4. Distribution onEdit refreshes affected Client portal workbook's AG column
5. Live: client can see "SENT" within seconds of staff marking

Invariant

COUNT(distinct UnitID in Distribution) == COUNT(_PURCHASE_UNITS where Status=ALLOCATED)

Checks

• MISSING_UNIT_IN_PURCHASE_UNITS · DUPLICATE_UNIT_IN_DISTRIBUTION · SALES_ID_MISMATCH
• ORPHAN_ALLOCATED_PURCHASE_UNIT · PURCHASE_UNIT_POINTS_TO_MISSING_SALES_ID
• COUNT_MISMATCH · PURCHASE_UNIT_MISSING_ALLOCATED_SALES_ID
• STATUS_LOOKS_AVAILABLE_BUT_REFERENCED · STATUS_LOOKS_ALLOCATED_BUT_UNLINKED

Row actions

Target UX: Inventory & Distribution Command Center

• KPI stats: Total Sold · Total Purchased · Allocated % · Pending Dispatch
• Action Center: urgent items (oversells · awaiting confirmation · stuck dispatches)
• Match Summary Widgets — per-match completion donuts
• Stock Overview — grouped by category
• Open Distribution CTA

Report tabs

Game Dashboard (per-match) — TDS-specified display formats

• Oversell alert (exact wording): "Top Cat 1 oversold by 1 ticket — 128 sold but only 127 purchased"
• KPI row (exact format): "462 · $1,870K revenue · Net remaining 185"
• Dispatch record display: "Assigned to jmeester · Priority: Normal · DispatchStatus SENT · 07/04/2026"

1. Admin marks CLOSED (blocks new sales)
2. Final audit run
3. Outstanding dispatches surfaced + resolved
4. Financial close (invoicing reconciliation — TBD)

Portal tokens invalidated. Data retention clock starts (default auditRetentionDays=365). Read-only reports remain accessible.