# Slot operations

## What it does

Funnels describe business stages. Slots own landing pages, one WhatsApp group,
the selling objective, offers and reusable automation. A session is one dated
execution of a scheduled slot. A Video Sales Letter (VSL) is an evergreen slot
without dated sessions.

**Nav:** Funnels → funnel → Slots → slot. Funnel tabs are Sessions (default), Slots and
Journey. An explicit `?tab=` link still opens its requested tab. A scheduled slot has Sessions, Selling, Automation, WhatsApp Group and
Landing. A VSL slot has Summary, Ads, Leads and the same configuration tabs.
Person-level tabs retain lead-visibility gates; configuration retains events permissions.
An old `/manage/events/funnels/{uuid}` link to a VSL funnel with exactly one video slot
redirects to that slot's page, keeping the query (bookmarks and older alerts named the
funnel); the funnel page's own tabs (`?tab=sessions|slots|journey`) never redirect, because
the slot page's back link is `?tab=slots`. The Selling and WhatsApp Group tabs save by
PUTting the page's whole `slot` prop to `SeriesController::update`, so every column that
update writes must be in `transformSlot()` (the demo unit was cleared until 2026-10-12;
the update now also writes `demo_catalog_project_uuid` only when the key is sent; the simulive fields
`is_simulive` / `simulive_record_file_id` / `simulive_record_label` / `simulive_to_live` follow the same
rule and ride `transformSlot()` for the same reason).

## How it works

- `EventSeries::TYPE_SESSION` and `TYPE_VSL` describe the slot. A VSL cannot be
  selected for session creation or a session move. Its times are null. New video
  slots can use a direct HTTPS `video_url`; existing bespoke Cochrane designs remain.
- Stage 1 defaults to Membership; Stage 2 and a stage linked to a sales project
  default to Project fee. Other stages require an explicit choice. Offers and
  payment links are configured on Selling; a payment link must match the exact
  product. Migration never invents products or prices.
- One slot has one `whatsapp_group_id` and its invite link. Group reminders use
  that room's shared WhatsApp Bridge channel. Private messages use WhatsApp Cloud.
  Legacy rules that target conflicting rooms are paused for review. Their content,
  room pivots and delivery history remain available.
- New group rules recur for every session of the slot. Historical one-session
  rules keep their session scope. Public group tokens are `event_title`,
  `event_date`, `event_time`, `register_link`, `whatsapp_group_link`; personal
  login links, tickets and personal Zoom join URLs cannot appear in group rules.
- Upcoming sessions use the slot's current automation. Their date, time, venue,
  visibility and Zoom webinar remain session-owned. Editing a reminder or changing
  its group does not change its delivery identity: the ledger claims at most one
  group send per rule and session. Existing sent reminders are not replayed.
  Deleting and recreating a rule creates a new identity; pause/edit to retain deduplication.
- A paused/deleted slot or funnel stops rule execution. Session registrant mutes
  and attendance/payment conditions still apply.
- `/{funnel-slug}/{slot-slug}` is the permanent slot landing. Scheduled slots select
  the next upcoming session. `/sessions/{uuid}/register` targets that exact session.
  Legacy funnel roots and merged URLs redirect to slots, preserving ad query parameters.
  Renaming a slot's slug, or its funnel's slug, records each old `/{funnel}/{slot}`
  path in `slot_landing_aliases` (`EventSeriesRepository::update`,
  `EventFunnelRepository::preserveSlotUrls`), so links already in ads and messages
  redirect to the new URL instead of 404ing. A slot whose design must survive a
  rename pins it in `landing_design`, because the fallback design path is built
  from the slugs.
  There is no funnel-owned landing page or funnel-wide auto-enrolment.
- `slot_registrations` holds independent first-touch attribution and VSL follow-up.
  Watch progress, consultation requests and caller rotations are slot-scoped.
  A registration on one VSL does not unlock another. Existing `lead_funnels` rows
  remain the funnel-level acquisition record. `new_registration` (the thank-you page's
  "returning" flag, Meta's CompleteRegistration status) is decided PER SLOT: a second slot
  of a known funnel counts as new (owner, 2026-10-12). An account merge folds
  `slot_registrations` like `lead_funnels` (`LeadRepository::mergeSlotRegistrations`).
- The slot landing sends `knownVisitor` only on a VSL slot the device's person registered
  on (the same `rememberedRegistrantOf()` question the video gate asks), so a returning
  registrant's CTA goes straight to `{landing_url}/video`. The AI-call checkbox and the
  thank-you countdown read only the slot's own on-register AI-call rule; a leftover
  funnel-wide rule never rings, so it is never offered.
- Call questions are configured on the scheduled slot, one independent set per
  before/after/paid moment. The human outcome form resolves its Journey's current
  Session → Slot. An empty set uses only that slot's registration AI-call profile
  (active rules first, then stable rule order); there is no sibling-slot or
  funnel-wide fallback. On a Preview (Stage 1) funnel the shared Stage 1 Needs
  pack fills in whatever that profile does not ask, and is the whole set for a
  journey with no Session yet (`HandoffQuestions::for()`). A Project funnel with
  no Session, slot or profile has no default questions.
  Actual AI-call answers retain the profile attached to the call, including
  archived profiles. Existing saved answers retain their original wording.
- `2026_10_08_150000_scope_call_questions_to_slots.php` preserves legacy question
  rows as archives and copies them to each existing slot. A merged slot's original
  funnel set takes precedence for its moment. Later edits and clearing one slot
  never change another. New slots start without custom questions.
- AI calls re-check their session's current slot before dialing. A queued call for
  a session moved to a different slot is skipped instead of using the old agent.
- Welcome sends carry `context_event_id` to render the session the person actually
  chose. The existing `event_id = null` welcome semantics are retained, so deliberate
  repeat registrations can still receive a welcome.

### Production deployment

Use the Production release directory and normal deployment account. Do not copy the
development database or `.env`. Take a full database backup first. Quiesce new requests
and the scheduler, allow in-flight work to finish, and pause workers for the ownership
change using the site's normal deployment process. Do not flush queues. The upgrade
refuses to run while an unscoped automation has a queued send; finish those jobs under
the old ownership before retrying. Keep traffic and workers paused on any failure.

Deploy this change with the frontend build, then run:

```bash
php artisan migrate --force

# The two previously requested webinar merges; preview the named destinations.
php artisan funnels:merge-property-webinars
php artisan funnels:merge-property-webinars --apply

# Ensure the two business stages have their intended sales flow.
php artisan funnels:sales-flow 07ef866f-3b68-4c26-8e77-abd69c707df5 preview --apply
php artisan funnels:sales-flow e28d76d4-008c-45a9-be38-1ad5c9ee5724 project --candidate-source=07ef866f-3b68-4c26-8e77-abd69c707df5 --apply

# Preview, then apply the slot ownership change.
php artisan funnels:upgrade-slots
php artisan funnels:upgrade-slots --apply
php artisan funnels:upgrade-slots
```

The last command must report `already_applied: true`. The operation is transactional,
creates a private before-image under `storage/app/private/slot-operations/`, and does
not dispatch messages, calls, Zoom provisioning or campaign jobs. Keep its backup with
the deployment record. The full database backup remains the rollback source: the schema
migrations deliberately refuse `down()` after slot-owned data can exist.

The upgrade keeps existing IDs, adopts VSL history into a new slot, retains custom
landing design paths, and maps effective whole-funnel welcome rules onto their original
slots. Slot-specific overrides win; slots moved from another funnel do not inherit the
destination's fallback welcome. Copies of historical delivery rows suppress replay on
split rules; they are inherited history, not newly sent messages. A version marker makes
reruns no-ops, so later admin edits are not reset.

Review `group_slots_requiring_review` from the command. For each listed UUID, open
`/manage/events/slots/{uuid}?tab=group`, choose its one room and correct invite link,
then review and enable its paused group rules. Configure missing offers on Selling.
Restart/resume workers on the new release, resume the scheduler and reopen traffic.

Verify old `/cochrane`, `/cochrane/video`, `/cochrane-webinar` and `/hk-data` links;
check their redirected slot, ad query parameters and the exact-session registration URL.
Never use a real customer destination for a deployment test message.

### Development validation

Applied only to `peta_zs_dev` on 2026-10-08. The Cochrane VSL's 344 registrations
were adopted; all 351 video-view rows, 182 consultation rows and 13,283 funnel
acquisition rows were retained. Group configurations requiring review are AI Masterclass
and Cochrane Webinar. Production was not changed.

Verification uses an empty, isolated local MySQL database, targeted feature tests,
isolated SQLite ownership/deduplication tests, frontend and SSR builds, and browser
checks of the real development data with outbound integrations suppressed. The test
suite's existing PHPUnit configuration deprecation is unrelated to this change.

## Related files

- `database/migrations/2026_10_07_190000_add_slot_operations.php`
- `src/Event/EventSeries.php`, `src/Event/SlotRegistration.php`
- `src/Event/Repositories/SlotOperationsRepository.php`, `SlotRegistrationRepository.php`
- `app/Console/Commands/UpgradeSlotOperations.php`
- `src/Event/Support/PublicSlotResolver.php`, `FunnelWhatsappComposer.php`, `VslLeadState.php`
- `app/Actions/RegisterLeadAction.php`, `DispatchFunnelWelcomeAction.php`
- `app/Http/Controllers/Manage/Events/FunnelsController.php`, `SeriesController.php`, `EventsController.php`
- `app/Http/Controllers/Main/LandingController.php`, `VideoProgressController.php`, `ConsultationController.php`
- `resources/js/Pages/Manage/Events/Funnels/Show.vue` and `Partials/Tabs/{Selling,SlotGroup,Landing,Automation}Tab.vue`
- `resources/js/Pages/Landings/DefaultVideo.vue`, `SlotLanding.vue`, `FunnelVideo.vue`
- `tests/Unit/Event/SlotOperationsTest.php`, `tests/Feature/Event/SlotOperationsTest.php`, `tests/Feature/Event/SlotCallQuestionsTest.php`
- `tests/Concerns/CreatesLandingSlots.php` — test fixtures: `landingSlot()` / `vslSlot()` (each writes the
  funnel-root alias the upgrade would) and `slotRegistrant()` (funnel row + slot row, as a registration writes them)
- `src/Lead/Journey/Support/HandoffQuestions.php`, `FunnelQuestionSet.php`, `Repositories/FunnelQuestionSetRepository.php`
- `app/Http/Controllers/Manage/Events/FunnelQuestionsController.php`, `Partials/CallQuestionsModal.vue`
- [Webinar merge runbook](/docs/modules_handbook/manage/events/funnels/merge-property-webinars.md)
