152 lines
6.5 KiB
Markdown
152 lines
6.5 KiB
Markdown
# 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.
|