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

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

Data written

What happens

• For each line item with qty N → create N _PURCHASE_UNITS rows
• UnitID = P00001 … P00055 (sequential, 5-digit, zero-padded, globally unique)
• SetID = PR<4-digit sourceRow>-S01 (e.g. PR0017-S01)
• SetSize = N · SetPos = 1..N
• Status = AVAILABLE · AllocatedToSalesID = ""
• Block/Row/Seat blank at first; allocator can fill later via seat tools

Success screen

Data written

Form preview

Form preview · revised layout

Form UX rules (revised)

• Client field moves up, typable with autocomplete
• Match field moves DOWN into each line item — one client can buy across many matches in one sale
• Currency is USD or EUR only. FX field removed
• 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

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.

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)

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
• 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

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.