# Historical webinars in funnel Journeys

On **Zoom → Recordings → Webinars**, **Assign to funnel** attaches a finished historical webinar to a Stage 1 or Stage 2 Slot. This is separate from the future-facing **Link Zoom webinar** flow in Events.

1. Open **Assign to funnel** on an unassigned recording. The preview reads the locally stored attendance and shows matched customers, unmatched attendance records, staff records excluded, and attendees with incomplete duration.
2. Choose the business-stage **Funnel** and a **Zoom webinar Slot**. Inactive Slots are allowed for history; VSL Slots are not.
3. Create a completed Session on the original occurrence's local date/time, or explicitly select an existing ended Session in that Slot on the same date. An existing Session must have no other webinar. A Session already occupying that Slot/date prevents a duplicate, including a deletion tombstone.
4. Save. The recordings list displays its Funnel / Slot and an **Open Session** link. **Refresh history** repeats the same assignment after attendance or identity corrections, without duplicating Sessions, registrations or minutes. Moving an already linked Session uses Events' existing move flow, not re-import.

The recording's occurrence UUID must match the attendance webinar's UUID exactly, including case. When either UUID is absent, the exact UTC start must match. A reused numeric Zoom ID alone is insufficient. Duplicate webinar records for an already assigned occurrence are rejected.

## Attendance and counting

- Existing customer `lead_id` attribution wins. Unattributed emails use the shared `WebinarAttendeeLinker::preview()` identity lookup. No Lead/account is created, no identity is guessed from a display name, and staff are excluded.
- Each matched customer has one `EventRegistration` with `STATUS_ATTENDED`. Newly created registrations use `SOURCE_IMPORT`, retain the historical attendance timestamp, and have reminders muted.
- Duration comes from participant segments, never the recording's overall length. Duplicate join instants collapse; overlapping device intervals merge; genuine reconnects accumulate. An incomplete duration stays unknown, including when a later refresh adds an incomplete segment. Re-import recomputes rather than adds the same minutes again.
- Attendees qualify as Stage 1 **Ready for Stage 2** across all Slots. Stage 1 cumulative duration and Stage 2 attendance/source eligibility use the existing Journey board services immediately. A person attending several Sessions remains one customer.
- An attendee-only report does **not** prove which absent registrants were No-shows. Other registrations retain their status. Unmatched records remain available for identity correction; incomplete duration is not silently assigned to the under-60-minute group.
- No historical AI outcome, payment, deal, or Journey progression is fabricated. The operation does not change first-touch acquisition attribution.

## Persistence and automation

`LegacyWebinarSessionsController` serves the read-only preview and explicitly maps the import request to `ZoomWebinarRepository::importHistoricalSession()`. Classification validation is in `ImportLegacyWebinarRequest`; writes and assignment guards are transactional in the repository. Both endpoints require `view-zoom`, `manage-zoom`, `manage-events`, and company-wide `view-leads-all`, plus normal recording visibility.

The linked webinar keeps `SOURCE_LEGACY` (integer 3) and ended status. It remains externally managed for Zoom sync/teardown. No Zoom creation, welcome dispatch, registration-import job, Journey hook, AI Call, or reminder is triggered by historical import. Session reminder scanners exclude this provenance, including WhatsApp group posts; the normal attendance reconcile job skips it so incomplete history cannot become a No-show verdict or replay follow-up hooks.

Manual attendance sync for an imported webinar targets its occurrence UUID. Without a UUID it does not fetch a reusable numeric ID's potentially different occurrence. Syncing raw attendance does not automatically refresh the Session projection: use **Refresh history** afterwards. The existing Zoom report import/identity tools remain the path for missing historical evidence.

No new schema migration is needed for this feature; it uses the existing Slot, Session, webinar source and attendance fields. Deploy the code through the normal application deployment flow (including normal route-cache/worker refresh). No automatic classification or mass data migration runs during deployment. Administrators choose each webinar's Funnel / Slot in the UI in each environment.

## Bulk import from a reviewed plan

`php artisan zoom:import-legacy-webinars` (`App\Console\Commands\ImportLegacyWebinars`) does the same assignment for
many webinars in one run, from a reviewed CSV — default `database/data/legacy_webinars/2026-10-14-plan.csv`, columns
`webinar_id,start_myt,action,funnel_id,slot,project_id,topic,note`. It previews by default, and `--apply` refuses
to start while the preview shows any error. Re-running refreshes what it already imported.

- **`webinar_id` is the `zoom_webinars` row**, not the recording. `start_myt` must match that row's start
  (`Y-m-d H:i`, user timezone). That match stops a plan written against one database from running against another.
- **`slot` is a Slot title inside `funnel_id`.** A missing one is created **paused** (Zoom mode, no auto webinar),
  so history never reaches a live Slot's lists. A `project_id` becomes that Slot's Project offer.
  **The Stage 2 board reads a Session's Project only from its Slot's offer**: there is no per-Session picker, and an
  import never freezes an `event_offers` snapshot. Without an offer the Session counts as "project unknown", and an
  attendee who bought the project shows as "joined, no fee yet".
- **Two things the page cannot do.**
  - Webinars Zoom kept **no recording** of are imported from the webinar row
    (`ZoomWebinarRepository::importHistoricalWebinar()`, dated by `LegacyWebinarAttendance::webinarStart()`).
    The page lists recordings only.
  - A Slot in a funnel **without a Journey** is allowed, such as After Sales or Knowledge Sharing
    (`$journeyFunnelsOnly = false`). Those attendees count in that funnel only and never reach a Journey board.
- **Guards checked in the preview:**
  - one Session per Slot per date, within the plan and against the Slot's own Sessions, including deleted ones;
  - one import per sitting. Discovery sometimes stored one sitting twice under the same numeric Zoom id: same id plus
    same local day means one sitting, whether the second record is in the plan or already attached to a Session;
  - an already-imported webinar may only refresh into its own Slot.
- **Same guarantees as the page:** nothing is sent, and no Journey, task, reminder or Zoom call starts.

The 2026-10-14 plan holds 114 rows: 85 import, 29 skip (paid classes, member Q&A, tests, and the three duplicate
records #12, #40 and #77). Its decisions and evidence are in `docs/temp/7-10-temp/11-legacy-webinar-assign-list-2026-10-14.md`.

## Verification

`tests/Feature/Zoom/LegacyWebinarSessionTest.php` covers original dates, duplicate/overlapping joins, cumulative attendance, repeat imports, existing Sessions, unmatched/staff/unknown-duration records, Stage 1 and Stage 2 counts, conflicting occurrences, authorization, silent reconciliation, reminder candidate exclusion, occurrence-specific report refresh, and the bulk plan (preview writes nothing; apply files recorded and unrecorded webinars under paused Slots, with a Project offer and a non-Journey funnel; a second run only refreshes; a sitting stored twice or a wrong start blocks the whole run).
