# PRD — Ticket Watch Lists and CC-Style Notifications

- Slug: `ticket-watch-lists`
- Date: `2026-02-25`
- Status: Draft

## Summary
Add a ticket-level Watch List so teams can include additional recipients (including technicians) on customer-visible ticket notifications. Watchers are managed on the ticket, auto-populated from inbound email `To`/`CC`, and notified via separate individual emails (not CC headers).

## Problem
Current ticket notification behavior primarily targets the ticket contact/client plus internal assignment/resource recipients. Customers and internal stakeholders often need extra ad-hoc visibility for a specific ticket thread. Without a Watch List:
- Teams manually forward updates.
- Inbound email context (`To`/`CC`) is lost after ingestion.
- Visibility is inconsistent across customer-visible ticket updates.

## Goals
1. Provide a per-ticket Watch List that can include any email address (techs included).
2. Auto-add inbound email `To`/`CC` recipients to Watch List during ingestion.
3. Let users uncheck/remove Watch List recipients from the ticket UI.
4. Send Watch List notifications only for customer-visible ticket updates.
5. Send Watch List recipients as separate individual emails.

## Non-goals
- Global watcher templates/distribution lists across all tickets.
- Changing existing notification preference architecture for non-watch-list recipients.
- Replacing core recipient logic (contact/client/assigned/resource); Watch List is additive.
- Introducing SMS/push channels.

## Users and Primary Flows
- Dispatcher / coordinator:
  - Adds or removes watcher emails on a ticket.
  - Expects watchers to receive customer-visible updates going forward.
- Technician / internal stakeholder:
  - Can be added as watcher by email.
  - Receives same customer-visible updates as other watchers.
- Inbound email flow:
  - Incoming message creates/replies on a ticket.
  - Recipients in `To`/`CC` are merged into ticket Watch List automatically.

## UX / UI Notes
- Add a `Watch List` section on ticket details (properties panel).
- UI elements:
  - Email input + `Add` action.
  - List of watcher entries with checkbox (`active`) and remove action.
- Checkbox behavior:
  - Checked: watcher receives notifications.
  - Unchecked: watcher remains listed but inactive (no notifications).
- Clarified customer choice: notifications to watchers are separate individual sends, not a single email with CC recipients.

## Requirements

### Functional Requirements
- FR-01: Ticket attributes include a Watch List array of recipients with at least email + active state.
- FR-02: Manual add validates/normalizes email and prevents duplicate active entries by normalized email.
- FR-03: Manual remove deletes the watcher entry from the ticket.
- FR-04: Manual uncheck toggles watcher to inactive without deleting required history fields.
- FR-05: Inbound email ingestion collects `To` + `CC` recipients and merges them into Watch List.
- FR-06: Inbound merge excludes sender and provider mailbox address to avoid self-watch loops.
- FR-07: Inbound merge reactivates an existing inactive watcher when that email appears again in `To`/`CC`.
- FR-08: Watchers receive notifications for customer-visible ticket events:
  - ticket created
  - ticket updated
  - ticket assigned (customer-visible notification path)
  - ticket comment added (public/customer-visible comments only)
  - ticket closed
- FR-09: Watcher notifications are sent as individual emails (one watcher per send).
- FR-10: Watcher recipients are deduped against existing recipients per event.
- FR-11: Public comment watcher notifications must not notify the comment author.
- FR-12: Existing recipient behavior (contact/client/assigned/additional resources) remains unchanged except dedupe where applicable.

### Non-functional Requirements
- NFR-01: No schema migration required for v1 (use `ticket.attributes.watch_list`).
- NFR-02: Behavior must be backward-compatible for tickets with null/legacy attributes.
- NFR-03: Errors in watch-list enrichment should not break inbound email ticket/comment creation.

## Data / API / Integrations
- Storage target:
  - `tickets.attributes.watch_list` (JSON array).
- Suggested entry shape:
  - `email: string` (normalized lowercase)
  - `active: boolean`
  - optional metadata: `name`, `source` (`manual|inbound_to|inbound_cc`), timestamps.
- Inbound integration:
  - `shared/services/email/processInboundEmailInApp.ts`
  - `shared/workflow/actions/emailWorkflowActions.ts`
- Outbound integration:
  - `server/src/lib/eventBus/subscribers/ticketEmailSubscriber.ts`
- UI integration:
  - `packages/tickets/src/components/ticket/TicketProperties.tsx`
  - `packages/tickets/src/components/ticket/TicketDetails.tsx`

## Security / Permissions
- Watch List edits follow existing ticket update permissions.
- No privileged bypass: only authorized ticket editors can modify watchers.
- Email validation/sanitization required for manual entry and inbound ingestion.

## Observability
- Use existing notification logs and email send instrumentation.
- Errors in watcher merge/send should include ticketId/tenantId/recipient context in existing logger paths.

## Rollout / Migration
- v1 rollout can be immediate without migration because data is in ticket attributes.
- Existing tickets start with empty Watch List unless updated manually or by inbound email processing.

## Open Questions
1. Should inactive watchers remain visible indefinitely or be auto-pruned after a period?
2. Should Watch List edits themselves generate an audit event/comment in the ticket timeline?
3. Should watcher sends respect internal user notification preference toggles when watcher email matches an internal user?

## Acceptance Criteria (Definition of Done)
1. Users can add, uncheck, and remove watcher emails on a ticket.
2. Inbound email processing auto-adds `To`/`CC` recipients to Watch List, excluding sender/provider mailbox.
3. Active watchers receive customer-visible ticket updates via separate individual emails.
4. Public comment notifications do not email the comment author.
5. Duplicate emails are not sent to the same address for a single event.
6. Existing non-watcher recipients continue to receive expected notifications.
7. Automated tests cover watch-list parsing/merge logic, inbound recipient enrichment, and outbound watcher fan-out per event path.