# Task EP.1.2 Activity Integration & Legacy Follow-up Adapter - 2026-07-13

## Scope

- introduced adapter-based Activity timeline integration for legacy lead, opportunity, and quotation follow-ups
- added additive `recentActivities` detail API data for customer, lead, opportunity, and quotation workspaces
- kept existing follow-up APIs, dashboard consumers, report datasets, and audit history unchanged
- added Activity numbering through the Document Sequence Foundation using `documentType = activity`
- added Activity attachment foundation service on top of Storage and Document Artifact foundations
- documented migration readiness without executing migration, dual-write, projections, calendar, timeline, notifications, or dashboard swaps

## Review Summary

Reviewed before and during implementation:

- `AGENTS.md`
- `plans/task-ep.1.2.md`
- `docs/standards/task-catalog.md`
- `docs/standards/project-foundations.md`
- `docs/standards/architecture-rules.md`
- `docs/standards/ui-ux-rules.md`
- `docs/standards/task-review-checklist.md`
- `docs/security/crm-authorization-boundaries.md`
- `docs/implementation/task-ep1.1-activity-domain-foundation-2026-07-10.md`
- `docs/implementation/task-ar.1-architecture-transition-plan-2026-07-07.md`
- `docs/implementation/task-ar.2-epic-technical-design-2026-07-07.md`
- `docs/implementation/task-ar.2-workspace-ui-ux-design-note-2026-07-07.md`
- existing lead, opportunity, quotation follow-up services and APIs
- existing dashboard and report follow-up consumers
- existing audit, storage, document artifact, and document sequence foundations

## Implementation Summary

### Legacy Follow-up Adapters

Created Activity-compatible timeline adapters:

- `src/features/crm/activities/server/adapters/lead-followup.adapter.ts`
- `src/features/crm/activities/server/adapters/opportunity-followup.adapter.ts`
- `src/features/crm/activities/server/adapters/quotation-followup.adapter.ts`

The adapters only read and translate legacy records. They do not migrate data, dual-write, or remove existing follow-up behavior.

### Compatibility Layer

Added `src/features/crm/activities/server/timeline-service.ts` as the single Activity compatibility read layer for detail-page recent activity views.

Current composition:

- new `crm_activities` rows queried by context columns such as `customerId`, `leadId`, `opportunityId`, and `quotationId`
- legacy lead follow-ups adapted from audit-log-backed records
- legacy opportunity follow-ups adapted from row-backed records
- legacy quotation follow-ups adapted from row-backed records

Dashboard and report datasets remain on their existing legacy sources for EP.1.2.

### Activity Context Integration

Integrated recent activity reads into:

- customer detail API and UI
- lead detail API and UI
- opportunity detail API and UI
- quotation detail API and UI

The UI uses `RecentActivitiesPanel` and keeps existing follow-up tabs and audit log tabs in place.

### Activity Type Governance

Expanded the official fallback Activity catalog to cover the EP.1.2 minimum types and kept backward-compatible aliases.

Reference data now prefers `crm_activity_type` master options when configured, with static catalog fallback for environments that have not seeded the new category yet.

### Activity Numbering Strategy

Activity creation now calls `generateNextDocumentCode()` from the Document Sequence Foundation using:

- `documentType = activity`
- branch scope from the resolved Activity context
- product type scope from the resolved Activity context
- default prefix `ACT`
- period-based sequence from the existing foundation

The generated code is stored in `crm_activities.metadata.activityCode` to avoid a schema migration in EP.1.2.

### Activity Attachment Foundation

Added `src/features/crm/activities/server/attachment-service.ts`.

The service supports Activity attachment metadata and binary storage through:

- Storage Foundation object writes
- Document Artifact Foundation metadata records
- `entityType = crm_activity`
- `artifactType = attachment`

Supported attachment kinds are `image`, `pdf`, `office_document`, `voice_recording`, `drawing`, and `other`.

No separate storage engine or attachment table was introduced.

## Adapter Validation

| Source | Legacy Storage | Adapter Output | Validation Status |
| --- | --- | --- | --- |
| Lead follow-up | audit log payload | `ActivityTimelineItem` | implemented |
| Opportunity follow-up | `crm_opportunity_followups` | `ActivityTimelineItem` | implemented |
| Quotation follow-up | `crm_quotation_followups` | `ActivityTimelineItem` | implemented |
| New Activity | `crm_activities` | `ActivityTimelineItem` | implemented |

## Legacy Usage Inventory

Existing consumers intentionally remain unchanged:

- lead follow-up API and panel
- opportunity follow-up API and tab
- quotation follow-up API and tab
- CRM dashboard service follow-up queries
- pipeline/report datasets reading legacy follow-up state
- audit log views for customer, lead, opportunity, and quotation details

## Projection Readiness

EP.1.3 can consume the following stable contracts:

- `ActivityTimelineItem`
- legacy follow-up adapters
- `listRecentActivitiesForContext()`
- Activity numbering metadata under `metadata.activityCode`
- Activity attachment artifacts under `entityType = crm_activity`

Projection consumers should still wait for EP.1.3 event and projection contracts before replacing dashboard, report, calendar, or timeline behavior.

## Migration Checklist

- Keep legacy follow-up writes active until adapter parity is validated with production-like data.
- Backfill or project legacy follow-ups only after a separate migration task approves the source-of-truth switch.
- Decide whether `metadata.activityCode` should become a first-class column in a future schema task.
- Add upload/download route handlers for Activity attachments when the UI workflow is scheduled.
- Add seeded `crm_activity_type` master options before disabling fallback catalog behavior.
- Run dataset regression checks before dashboard/report consumers switch from legacy follow-ups to Activity projections.

## Verification

- `npm run typecheck`
- targeted `npx oxlint` for Activity adapter, timeline, route, and detail UI files

## Residual Risks

- Activity attachment upload/download routes are intentionally deferred; the foundation service is ready for those routes.
- Activity numbering is metadata-backed in EP.1.2 to honor the no-migration constraint.
- Detail pages show recent activity read integration, but create-activity shortcuts from each detail page are still deferred to the next UI workflow task.