PSA/ee/docs/plans/2026-05-25-ticket-audit-logs/SCRATCHPAD.md

# Scratchpad — Ticket Audit Logs / Unified Activity Timeline

## Context
- Goal: add user-facing operational timeline for tickets.
- User confirmed this is not a compliance-grade immutable ledger for v1.
- User prefers a unified ticket timeline: comments, internal notes, customer replies, field changes, assignment/status changes, inbound email, and system events appear together chronologically.

## Source context
- Code context summary: `context.md` in this worktree.
- Existing generic audit helpers:
  - `packages/db/src/lib/auditLog.ts`
  - `server/src/lib/logging/auditLog.ts`
- Ticket/comment mutation areas identified in `context.md`.
- Existing ticket event schemas are in `packages/event-schemas/src/schemas/domain/ticketEventSchemas.ts`.

## Decisions
- V1 is a user-facing operational timeline, not a compliance-grade immutable ledger.
- Timeline UI is unified: comments/internal notes/customer replies and operational events appear together chronologically.
- Comment/internal-note edits are metadata-only in timeline entries; do not store full old/new comment body in audit/activity rows for v1.
- V1 timeline is internal-only for MSP users; client portal continues to show existing public comment-oriented experience.
- Ticket field update events are curated for v1. Meaningful fields are listed in `CURATED_TICKET_FIELDS`.
- Dedicated `ticket_audit_logs` table (not the generic `audit_logs`). Distributed by tenant for Citus.
- Helper accepts explicit tenant so it works inside admin transactions; no `app.current_tenant` GUC dependency.

## 2026-05-25 implementation summary

### Migration
- `server/migrations/20260525231145_create_ticket_audit_logs.cjs` — creates `ticket_audit_logs` with tenant-scoped primary key, FK to tickets, FK to users, and `(tenant, ticket_id, occurred_at, audit_id)` index. Distributes on tenant for Citus.

### Shared library
- `shared/lib/ticketActivity/types.ts` — enum constants (`TICKET_ACTIVITY_EVENT`, `TICKET_ACTIVITY_ACTOR`, `TICKET_ACTIVITY_ENTITY`, `TICKET_ACTIVITY_SOURCE`), `CURATED_TICKET_FIELDS`, and TS interfaces.
- `shared/lib/ticketActivity/writeTicketActivity.ts` — `writeTicketActivity(knex, input)` insert helper with explicit-tenant requirement.
- `shared/lib/ticketActivity/curatedTicketDiff.ts` — `buildCuratedTicketDiff` and `buildCuratedTicketDiffWithLabels`.
- `shared/lib/ticketActivity/readTicketActivity.ts` — `readTicketActivity` and `buildUnifiedTicketTimeline`.
- `shared/lib/ticketActivity/index.ts` — public surface barrel.
- `shared/tsup.config.ts` and `shared/package.json` updated with the new entry points.

### Integration points wired
- Ticket create (`packages/tickets/src/actions/ticketActions.ts::addTicket`).
- Ticket update (`packages/tickets/src/actions/optimizedTicketActions.ts::updateTicketWithCache`) — selects most specific event type from curated diff (CLOSED / REOPENED / STATUS_CHANGED / PRIORITY_CHANGED / ASSIGNED / UNASSIGNED / BOARD_MOVED / RESPONSE_STATE_CHANGED / UPDATED).
- Comment add (both MSP-side `addTicketCommentWithCache` and server-action `createComment`) — picks event by visibility + responseSource (INTERNAL_NOTE_ADDED / CUSTOMER_REPLIED / MESSAGE_ADDED).
- Comment edit (`commentActions.updateComment`) — metadata-only, no body stored.
- Inbound email ticket create (`shared/workflow/actions/emailWorkflowActions.ts::createTicketFromEmail`) — emits CREATED + INBOUND_EMAIL_RECEIVED with safe email metadata.
- Inbound email comment create (`createCommentFromEmail`) — emits CUSTOMER_REPLIED or COMMENT_ADDED with safe metadata.
- Inbound reply reopen (`shared/services/email/processInboundEmailInApp.ts::applyInboundReplyReopenTransition`) — emits REOPENED with reopen_trigger=inbound_email_reply.
- Bundle reopen (`packages/tickets/src/actions/ticketBundleUtils.ts::maybeReopenBundleMasterFromChildReply`) — emits BUNDLE_REOPENED on master with child reference.
- REST API ticket create + update (`server/src/lib/api/services/TicketService.ts::createTicket` and `update`) — curated diff for updates, CREATED for creates with source=api.
- Document attach/remove (`TicketService.uploadTicketDocument` and `deleteTicketDocument`).

### Read + UI
- `packages/tickets/src/actions/ticketActivityActions.ts` — `getTicketTimelineEntries` and `getTicketActivityRows` server actions; both enforce internal `ticket:read` permission and explicitly reject `user_type === 'client'`.
- `packages/tickets/src/components/ticket/TicketActivityTimeline.tsx` — internal-only unified timeline component (Alga UI components, unique IDs).
- `packages/tickets/src/components/ticket/TicketConversation.tsx` — added an "Activity" tab (id `activity`) that is shown only in MSP context; client portal tab list excludes it.

### Docs + tests
- `ee/docs/plans/2026-05-25-ticket-audit-logs/conventions.md` — conventions and safe metadata rules.
- `server/src/test/unit/ticketActivityCuratedDiff.test.ts` — unit tests for curated diff (no-op skip, label resolution, non-curated field filtering, null handling, date normalization).
- `server/src/test/integration/ticketActivityLog.integration.test.ts` — DB-backed coverage for migration shape, helper write inside normal transaction, helper write without GUC, ordering, tenant isolation, empty timeline, unified merge.

## Open / deferred
- REST endpoint surface for timeline read (not in v1; only server action + UI).
- Bundle child→master reopen test is not yet added (covered indirectly by the bundle reopen activity wiring).
- Playwright UI smoke test for the Activity tab not yet added.