# Zoom AI Action Plan and Sales Checklist Demo **Status:** Approved design **Target:** Local PETA V3 test environment on `dev-chen` **Production behavior:** Disabled and invisible **Demo date:** 6 August 2026 ## Context Zoom meetings already store a unified AI conversation analysis. Its `meeting_report.next_steps` field contains practical follow-up steps derived from the meeting summary, customer needs and concerns, sales performance, and meeting report. PETA V3 also already has Lead Action Items that can be assigned to staff and completed individually. The missing workflow is the bridge between those two features: 1. A Super Admin must review the AI-generated next steps before assigning them. 2. The approved steps must become the existing Lead Action Items instead of a second, competing task system. 3. The assigned salesperson must see all unfinished work when they next sign in, grouped by the relevant Lead. This first version is a local demo on `petav3.test`. It must not appear in production. ## Goals - Turn `ai_analysis.meeting_report.next_steps` into an editable Action Plan draft without making another AI request. - Let any Super Admin in the PETA V3 test environment review, edit, assign, and approve the draft. - Create one existing `LeadActionItem` per approved checklist step. - Group all steps from the same Zoom meeting into one Action Plan in the UI. - Show every unfinished item assigned to the signed-in salesperson in a dashboard-style login checklist, grouped by Lead. - Keep unfinished items visible on every login until they are completed. - Make approval idempotent and safe when two Super Admins act concurrently. - Provide three realistic local demo cases based on selected production data. ## Non-goals - No second AI generation request. - No due dates, overdue calculation, scheduling, reminders, or escalation. - No assignment notification, WhatsApp message, email, or personal-chat alert. - No automatic approval or automatic assignment beyond preselecting the Lead's current account manager. - No changes to production behavior or production feature visibility. - No new generic task-management platform. - No copying of Zoom audio, video, or transcript files for the demo. ## Core Product Decisions - The existing `meeting_report.next_steps` array is the AI Action Plan source. - One Zoom meeting has at most one Action Plan. - One Action Plan contains one or more individually completable steps. - Each approved step becomes a normal `LeadActionItem`. - A plan has one selected salesperson; all steps are initially assigned to that salesperson. - All Super Admins may review and approve plans while the demo flag is enabled. - Salespeople may only see and complete items assigned to themselves. - A plan is displayed as Completed when all of its generated Lead Action Items are done. - Reanalysis may refresh an unapproved draft but must never modify already approved Lead Action Items. - The Action Plan is a separate 1:1 entity rather than additional workflow columns on the already-wide `zoom_meetings` table. ## Feature Isolation Add a server-side feature flag exposed to the frontend as `features.zoom_action_plan_demo`. - The committed/default value is disabled. - The local PETA V3 test `.env` enables it. - Routes, controller actions, Inertia props, review controls, dashboard card, and login modal all enforce the flag. - Review and approval endpoints additionally require `isSuperAdmin()`. - The Sales checklist endpoint/props additionally scope all rows to the current user's assignment pivot. Disabling the flag hides the feature and rejects its dedicated endpoints. The existing Zoom analysis, Zoom Action Items queue, Lead Discussion tab, and Lead Action Items continue to work unchanged. The flag isolates behavior, not database schema. If the demo migration is later deployed to production, production will receive the inert `zoom_meeting_action_plans` table and two nullable source-link columns on `lead_action_items`, even while the flag remains disabled. This is an accepted consequence of deploying the migration. At the time of this demo the work is local on `dev-chen` and is not being pushed or deployed to production. ## User Flow ### 1. Draft creation After a Zoom analysis is saved, the Action Plan draft service normalizes the AI data and delegates persistence to the Action Plan repository. It inspects the meeting: - The feature flag must be enabled. - The meeting must be linked to a Lead. - `meeting_report.next_steps` must contain at least one non-empty string. - The meeting must not already have an approved plan. For an eligible meeting, the service creates or replaces the draft checklist. Each normalized step receives a stable generated key and an editable body. The Lead's `assigned_admin_id` is preselected only when that user is an active manage-portal user who can view the Lead; otherwise the assignee remains empty. Replacing a Draft after reanalysis intentionally discards any manual step edits that a Super Admin made before approval. The latest AI analysis is authoritative while the plan remains Draft. This is an explicit demo-scope decision; Approved plans are immutable from reanalysis. The same service is called after a Lead is linked to an already-analysed Zoom meeting. Existing eligible rows are initialized by a local one-time command, not by writing during a GET request. ### 2. Super Admin review The existing Zoom Action Items page adds a plan state to eligible meeting cards: - **Draft** — review is required. - **Approved** — Lead Action Items have been created and are in progress. - **Completed** — every generated Lead Action Item is done. A Super Admin opens `Review Action Plan`. The review drawer/modal contains: - Meeting and Lead identity. - Meeting summary. - Customer needs and concerns. - Sales performance summary and improvement points. - Editable checklist steps. - A single Sales assignee selector. The reviewer may add, edit, reorder, or remove steps and change the assignee. Approval is disabled until: - The meeting is linked to a Lead. - At least one non-empty step remains. - An active manage-portal Sales user who can view the Lead is selected. ### 3. Approval Approval runs through the Action Plan repository in one database transaction with the Action Plan row locked. The server validates the feature flag, Super Admin permission, plan state, Lead, assignee, and steps again. For every reviewed step, the approval repository creates one `LeadActionItem`, assigns the selected salesperson through the existing assignee pivot, and records the source plan and source step key. These writes remain inside the same approval transaction and bypass the HTTP controller that invokes the current assignment notifier. After every step is created, the meeting plan is marked approved with the reviewer and approval time. A repeated or concurrent approval does not create duplicates and returns an already-approved result. Approval does not change the Zoom meeting's existing `followed_up_at` field. That existing queue-level close/reopen state remains a separate workflow. ### 4. Sales login checklist The current login flow already shares a one-request `justSignedIn` value. When the demo flag is enabled, the Manage Dashboard also receives the current user's open assigned Lead Action Items that originated from approved Zoom plans. On a successful Sales login: - If at least one open item exists, a near-full-screen `Today's Checklist` modal opens automatically. - Items are grouped first by Lead and then by source Zoom meeting. - Newly assigned/recent plans appear first. - Each group shows the Lead name, meeting date, plan progress, and open steps. - Clicking the Lead opens the existing Lead detail experience. - Each step can be marked done individually using the existing Action Item completion behavior. - A step is removed from the open portion only after the server confirms the completion. Closing the modal does not dismiss the work. The Manage Dashboard retains a Checklist card that reopens the same view. On later logins, every item still open appears again. If no open work exists, the modal does not interrupt login and the Dashboard card shows a clear completed/empty state. ## Data Design ### Zoom meeting Action Plan Create a 1:1 `zoom_meeting_action_plans` table and a `Src\Zoom\ZoomMeetingActionPlan` standard key model. The table contains: - `id`, `uuid`, blame columns, timestamps, and soft delete columns per project convention. - `zoom_meeting_id`: unique source meeting id, enforcing one plan record per meeting; a soft-deleted plan is restored rather than recreated. - `status`: `unsignedInteger()` defaulting to model constant `STATUS_DRAFT = 1`; the other value is `STATUS_APPROVED = 2`. - `items`: JSON array of `{ key, body }` reviewed checklist steps. - `assignee_id`: selected salesperson's `users.id`. - `approved_by`: approving Super Admin's `users.id`. - `approved_at`: approval timestamp. The model defines a `STATUSES` metadata array for Draft and Approved UI labels and colors. Completed is not a stored status; it is computed from generated Lead Action Item statuses. The demo exposes no Action Plan deletion endpoint; soft delete support follows the project's standard key-model shape. The existing `zoom_meetings.action_items` JSON remains the raw mirror of the latest AI analysis next steps. The separate plan row is the editable workflow snapshot. This separation prevents reanalysis from changing an approved plan and avoids adding five demo workflow columns to the `zoom_meetings` hot table. ### Lead Action Item source linkage Add nullable source fields to `lead_action_items`: - `source_action_plan_id`: originating `zoom_meeting_action_plans.id`. - `source_step_key`: stable key from the reviewed plan step. A unique index on `(source_action_plan_id, source_step_key)` prevents duplicate task creation. Manually created Lead Action Items keep both fields null and remain unaffected. Add model relationships from Zoom meeting to its Action Plan, from the Action Plan to generated Lead Action Items, and from a generated Lead Action Item back to its source plan. ### Completion and soft deletion Only non-deleted generated Lead Action Items participate in progress. A plan is Completed when, and only when, it has at least one active generated item and every active generated item is Done. Deleting one generated item intentionally removes that step from plan progress. If other active items remain, completion is recomputed from those items. If all generated items are soft-deleted, the plan stays Approved/In progress and shows `No active steps — review required`; an empty set must never become Completed. ## State and Reanalysis Rules | Current state | Event | Result | |---|---|---| | No plan | Eligible analysis saved or Lead linked | Create Draft | | Draft | Analysis rerun | Intentionally replace all edited draft steps from latest `next_steps`; preserve the selected assignee when still eligible, otherwise select the current eligible Lead owner, otherwise leave empty | | Draft | Super Admin edits | Persist reviewed steps and selected assignee | | Draft | Super Admin approves | Create Lead Action Items and mark Approved | | Approved | Analysis rerun | Update normal AI analysis fields only; leave plan snapshot and tasks unchanged | | Approved | Some tasks done | Remain Approved/In progress | | Approved | All tasks done | Display Completed | | Approved | One generated task is soft-deleted | Exclude it and recompute progress from remaining active tasks | | Approved or Completed | All generated tasks are soft-deleted | Display Approved/In progress with `No active steps — review required` | | Completed | A generated task is reopened | Display Approved/In progress again | ## Authorization - Draft list, review, edit, and approval require both the demo feature flag and a Super Admin user. - Approval validates the selected assignee against active manage-portal users and the existing Lead visibility rules. The picker uses the same constraint, so an assignee can always open the Lead and complete the task through the existing Action Item endpoint. - Dashboard checklist queries join the action-item assignee pivot and only return items assigned to the authenticated user, and additionally filter to Leads the authenticated user may still see under the existing Lead visibility rules. - Completion continues to use existing Lead visibility and Action Item rules; the checklist never exposes another salesperson's Lead or task. - Client-side hiding is present for usability but is never the authorization boundary. Lead visibility is enforced at BOTH approval time and read time. The assignee picker and the approval transaction validate the selected salesperson against the Lead's visibility rules, and the Dashboard checklist re-applies those rules on every read. If a Lead is later moved to another group or owner, the already-assigned salesperson's checklist stops listing it — the Lead name and the follow-up step text disappear along with the row, matching the 403 the completion endpoint already returned. (Revised 2026-08-05 after a security review. The original design accepted read-time exposure as a demo limitation and deferred the filter to production hardening; the checklist showed a stale row whose Lead name and step text remained readable after access was lost. The filter was added instead. The still-open follow-up is the inverse case: an item assigned to someone who can no longer see the Lead is now silently invisible rather than reassigned, so a moved Lead can strand approved work with no owner. Reassignment on visibility change remains production-hardening scope.) ## Error Handling - Unlinked meeting: show `Link lead first`; do not create or approve a draft. - Empty AI next steps: show no draft state. - Empty reviewed checklist: reject save/approval with field feedback. - Missing, inactive, or Lead-ineligible assignee: reject approval and request a new selection. - Duplicate/concurrent approval: return the existing approved plan without creating more Lead Action Items. - Partial database failure during approval: roll back the whole approval and every generated item. - Completion request failure: keep the item visible and show an inline error. - All generated items deleted: retain Approved/In progress and surface the review-required empty state rather than reporting Completed. - Feature flag disabled: dedicated endpoints return unavailable/forbidden and no demo props are shared. ## Demo Data Use three selected production Zoom cases that already have: - A linked Lead. - Completed `ai_analysis`. - At least one `meeting_report.next_steps` item. Copy only the database fields needed to render the Lead identity, Zoom meeting identity, AI analysis, and Action Plan workflow. The user has explicitly approved using real records for this local demo. The copied records must remain local database data only: - Do not commit customer names, phone numbers, email addresses, analysis JSON, SQL exports, fixtures, Seeders, logs, screenshots, or browser artifacts. - Do not copy recording media or transcript files. - Do not add an automated production connection to the application. - Use a one-time operator-controlled import or manual local insertion. At least one case should have an existing Lead owner to demonstrate automatic preselection. The other cases may demonstrate changing the assignee during review. ## Testing Strategy ### Backend feature tests - Feature flag disabled hides/rejects all demo behavior. - Non-Super Admin cannot list, edit, or approve drafts. - Every Super Admin can review and approve when enabled. - Eligible analysis produces a normalized draft. - Unlinked or empty-next-step meetings do not produce drafts. - Draft reanalysis refreshes steps. - Approved-plan reanalysis preserves reviewed steps and Lead Action Items. - Approval requires a valid assignee and at least one step. - Approval creates one assigned `LeadActionItem` per step. - Approval does not invoke assignment notifications. - Repeated and concurrent approval cannot create duplicates. - Sales checklist returns only the authenticated user's open assigned items. - Completing all generated items makes the plan report Completed; reopening one returns it to In progress. - Deleting one generated item recomputes progress from the remaining active items. - Soft-deleting every generated item never reports Completed and produces the review-required empty state. ### Frontend component tests - Review controls render only for authorized Super Admins while enabled. - Review form supports add, edit, reorder, remove, and assignee selection. - Login modal opens only when `justSignedIn` and open items are both present. - Checklist groups items by Lead and Zoom meeting. - Dashboard card remains available after closing the modal. - Failed completion keeps the item visible. ### Manual demo verification 1. Sign in as a Super Admin. 2. Open Zoom Action Items and choose a Draft case. 3. Review the analysis context, edit steps, and assign a salesperson. 4. Approve and confirm the existing Lead Discussion tab contains the generated Action Items. 5. Sign out and sign in as the assigned salesperson. 6. Confirm Today's Checklist opens automatically and shows the correct Lead. 7. Close and reopen it from the Dashboard card. 8. Complete the steps individually. 9. Return as Super Admin and confirm the plan displays Completed. 10. Rerun or simulate analysis and confirm approved tasks are unchanged. ## Acceptance Criteria - The complete manual demo flow works on `https://petav3.test` using three local realistic cases. - No feature UI or behavior is visible when the demo flag is disabled. - Any Super Admin can review and approve; non-Super Admins cannot. - Approved steps appear as the existing Lead Action Items and are not duplicated. - Assigned Sales users see only their own unfinished steps on login and on the Dashboard card. - No due date or notification is created. - Approved tasks survive Zoom reanalysis unchanged. - No production customer data is present in Git history or committed files. ## Likely Change Areas - Zoom analysis persistence and Lead-link workflows to initialize/update drafts. - New Zoom Meeting Action Plan model/table/repository and Lead Action Item source-link migration/relationships. - A focused Action Plan service for normalization and an Action Plan repository for every draft/approval write and transaction. - Super Admin review endpoints and Zoom Action Items UI. - Manage Dashboard query props and Sales checklist components. - Feature configuration and Inertia feature sharing. - Backend feature tests, frontend component tests, and a local-only demo data preparation procedure. Implementation must remain surgical: reuse current repositories, Action Item completion routes, Lead modal, authentication flash state, and existing visual patterns rather than building parallel infrastructure. ## Demo-first Implementation Order Implementation follows the ten-step manual demo path and prioritizes the risks that could invalidate the demo: 1. Feature flag, schema, integer status constants, models, and relationships. 2. Authorization and feature-flag tests. 3. Draft/approval repository with transaction, row lock, unique index, and idempotency tests. 4. Draft creation after analysis/Lead linking and reanalysis behavior tests. 5. Super Admin review UI and approval happy path. 6. Sales-scoped Dashboard query, login modal, and persistent Dashboard card. 7. Completion, reopening, and soft-delete progress behavior. 8. Three local production-derived demo records. 9. End-to-end manual rehearsal of the ten acceptance steps. 10. Remaining frontend states and lower-risk regression tests.