# Sales Checklist Completed History

**Status:** Approved

**Target:** Local PETA V3 demo on `dev-chen`

## Context

The Sales `Today's Checklist` currently returns only open Lead Action Items
created from approved Zoom Action Plans. After the server confirms `Done`, the
frontend removes the item immediately. This keeps the list short, but Sales can
no longer see what they just completed and cannot review completed work from
other Leads.

The approved product direction is to keep the existing checklist modal and add
two tabs:

1. `Current Tasks` shows open work and completed sibling steps for the same
   Lead and Zoom Action Plan.
2. `Completed History` shows completed Zoom-plan tasks across all Leads that
   the signed-in Sales user may still view.

## Goals

- Keep a completed step visible beside the remaining work for its Lead and
  source Zoom Action Plan.
- Move a newly completed step from `To Do` to `Completed` only after the server
  confirms success.
- Provide a completed-history tab covering the signed-in salesperson's other
  Leads.
- Show completion time and preserve plan progress.
- Keep completed history available when there are no open tasks.
- Avoid loading an unbounded task history on the initial Dashboard request.
- Preserve the current feature flag, assignment scope, Lead visibility rules,
  and existing completion endpoint.

## Non-goals

- No new task type or parallel task table.
- No manual Lead Action Items in this history; only items generated from
  approved Zoom Action Plans are included.
- No Sales-side edit, reassignment, reopen, delete, due-date, reminder, or
  notification behavior.
- No changes to Super Admin Action Plan approval.
- No change to the Zoom meeting's separate `followed_up_at` close/reopen state.

## User Experience

### Modal tabs

The existing `Today's Checklist` modal gains two tabs:

- `Current Tasks` with an open-item count.
- `Completed History` with completed records loaded on first selection.

The modal continues to open on `Current Tasks` after Sales signs in with open
work. Switching tabs never changes task state.

### Current Tasks

Only Leads with at least one open, assigned Zoom-plan item appear after a fresh
Dashboard load. Each Lead remains grouped by source Zoom Action Plan and each
plan displays:

- Meeting date and `done / total` progress.
- A `To Do` section containing open steps and the existing `Done` action.
- A `Completed` section containing completed sibling steps from that same
  approved plan, rendered with a check mark, muted styling, and completion
  time.

After `Done` succeeds, the item moves immediately from `To Do` to `Completed`
within the same plan and progress increments. A failed completion leaves the
item in `To Do` with the existing inline error.

When the final open step for a Lead is completed, the Lead leaves `Current
Tasks` and its completed records remain available in `Completed History`. The
UI confirms this transition with a short success message rather than making
the completed work appear lost.

### Completed History

The history tab is read-only. It shows the signed-in salesperson's completed
Zoom-plan tasks across all visible Leads, newest completion first. Rows show:

- Lead name.
- Task body.
- Source Zoom meeting date.
- Completion time.

Records are grouped visually by Lead after loading. The endpoint returns 20
records at a time and the tab exposes `Load more` while another page exists.
The first history request is made only when Sales opens the tab.

The history includes completed tasks for Leads that also appear in `Current
Tasks`; this makes the tab a complete audit view rather than a partial list of
"other" Leads.

### Empty states and Dashboard card

- No open work: `Current Tasks` shows `You're all caught up` while the history
  tab remains available.
- No completed work: `Completed History` shows `No completed tasks yet`.
- When the Dashboard has zero open items, its checklist card exposes `View
  history` instead of becoming non-interactive.

## Data Contracts

### Initial Dashboard payload

The existing `actionPlanChecklist` prop remains the source for current work.
Each plan adds `completed_items` beside `open_items`:

```text
{
  total_open,
  groups: [{
    lead,
    plans: [{
      plan_uuid,
      meeting_uuid,
      meeting_date,
      progress,
      open_items: [{ uuid, body }],
      completed_items: [{ uuid, body, done_at }]
    }]
  }]
}
```

The initial query first identifies approved plans that contain at least one
open item assigned to the signed-in user. Completed siblings are then included
only for those plans, only when assigned to the same user, and only while the
Lead remains visible to that user. This keeps the initial payload bounded by
current work.

### Lazy history endpoint

Add an authenticated, feature-flagged Manage endpoint for completed history.
It returns completed `LeadActionItem` rows that:

- Have a non-null Action Plan source.
- Belong to an approved Zoom Action Plan.
- Are assigned to the signed-in user.
- Belong to a Lead the signed-in user may currently view.

The query orders by `done_at DESC, id DESC` and uses cursor pagination with 20
rows per page. The JSON response returns flat rows plus the next cursor; the
frontend merges pages immutably and groups the loaded rows by Lead.

## Client State

- Replace the current remove-only helper with an immutable completion helper
  that moves one item from `open_items` to `completed_items`, increments plan
  progress, and recomputes `total_open`.
- Keep the current request latch and inline error keyed by item UUID.
- History is `idle`, `loading`, `loaded`, or `failed` and loads once on first
  tab selection.
- A newly completed item is inserted into already-loaded history state so the
  two tabs agree without another request.
- If history has not loaded yet, its first request is authoritative and already
  contains the new completion.

## Authorization and Privacy

- The feature remains invisible and its endpoint unavailable while
  `features.zoom_action_plan_demo` is disabled.
- Assignment is not authorization. Both the current payload and history query
  apply the existing Lead visibility scope.
- Sales receives only tasks assigned to their own `users.id`.
- Completed tasks from Leads that were later reassigned or moved out of scope
  are omitted.
- The existing completion endpoint remains the only write path.

## Error Handling

- Completion failure keeps the task open and displays the existing inline
  message.
- History request failure shows a retry action inside the history tab without
  breaking the Dashboard or Current Tasks.
- An invalid or expired pagination cursor returns the normal validation/error
  response and does not discard already loaded history.
- Orphaned or soft-deleted Leads and action items are excluded.

## Testing

### Backend

- Current payload includes completed sibling items for a plan with open work.
- Current payload excludes plans with no open items after a fresh load.
- Completed history returns only the signed-in user's assigned items.
- Completed history includes multiple Leads and orders newest first.
- Both payloads exclude inaccessible and orphaned Leads.
- Draft-plan, manual, open, deleted, and feature-disabled rows are excluded.
- Cursor pagination returns stable non-duplicated pages.

### Frontend

- The modal renders `Current Tasks` and `Completed History` tabs.
- A confirmed completion moves the item into `Completed` and advances progress.
- A failed completion leaves the item open.
- Completing the final open item removes the Lead from Current Tasks and makes
  the item available in history.
- History lazy-loads once, supports retry and `Load more`, and groups by Lead.
- The Dashboard card exposes history when the open count is zero.

## Manual Demo

1. Super Admin approves the `Tay Ern Chai` Draft and assigns `Demo Sales
   Agent`.
2. Sales opens `Today's Checklist` and sees three steps in `Current Tasks`.
3. Sales completes one step; it moves into that Lead's `Completed` section and
   progress becomes `1/3`.
4. Sales opens `Completed History` and sees this item plus completed work from
   other Leads.
5. Sales completes the remaining steps; the Lead leaves Current Tasks but all
   records remain in Completed History.

## Acceptance Criteria

- Sales can see newly completed steps without losing the current Lead context.
- Sales can review completed Zoom-plan tasks across other visible Leads.
- Open counts and plan progress remain correct after each confirmed completion.
- History remains available when no open tasks exist.
- Initial Dashboard load does not fetch unbounded completed history.
- Existing assignment, feature-flag, visibility, and completion security rules
  remain enforced.