alla-allaos-fullstack/docs/implementation/task-ep1.2-activity-integration-legacy-followup-adapter-2026-07-13.md

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.