task-ep.1.2

plans/task-ep.1.2.md

@@ -0,0 +1,382 @@
+# EP.1.2 – Activity Integration & Legacy Follow-up Adapter
+
+Status: Completed
+
+Priority: Critical
+
+Type: Feature Integration
+
+Depends On
+
+- EP.1.1 Activity Domain Foundation
+- ENG.0 Engineering Constitution
+- AR.1 Architecture Transition Plan
+- AR.2 Epic Technical Design
+
+---
+
+# Objective
+
+Introduce the Activity Integration Layer that connects the new Activity Domain with existing CRM modules while preserving all legacy follow-up implementations.
+
+This phase establishes adapter-based integration without introducing data migration, dual-write, or projection consumers.
+
+The objective is to prepare existing modules to consume Activity incrementally while maintaining production stability.
+
+---
+
+# Background
+
+EP.1.1 introduced the additive `crm_activities` write model.
+
+Current CRM still contains multiple follow-up implementations:
+
+- Lead (audit-log-backed)
+- Opportunity (row-backed)
+- Quotation (row-backed)
+
+Business Constitution defines Activity as the long-term operational model.
+
+Architecture Constitution requires:
+
+- Preserve existing production behavior.
+- Introduce Activity through adapters.
+- Delay consolidation until adapters are validated.
+
+---
+
+# Review Required
+
+Review
+
+Business
+
+- Relationship & Sales Workspace Blueprint
+- Activity Blueprint
+
+Architecture
+
+- AR.1 Architecture Transition Plan
+- AR.2 Epic Technical Design
+
+Engineering
+
+- Engineering Constitution
+
+Implementation
+
+- EP.1.1 Activity Foundation
+- Existing Lead Follow-up
+- Existing Opportunity Follow-up
+- Existing Quotation Follow-up
+- Existing Dashboard queries
+- Existing Reports
+- Existing Audit Log
+
+UI
+
+- Workspace UI/UX Design Note
+- layout.md
+- ui-ux-rules.md
+- ui-ux-pro-max
+
+---
+
+# Scope
+
+## Part 1 — Legacy Follow-up Adapter Layer
+
+Introduce adapter interfaces.
+
+Create
+
+LeadFollowUpAdapter
+
+OpportunityFollowUpAdapter
+
+QuotationFollowUpAdapter
+
+Responsibilities
+
+Read legacy follow-up
+
+Translate legacy model
+
+Produce Activity-compatible DTO
+
+No database migration.
+
+No dual write.
+
+---
+
+## Part 2 — Activity Context Integration
+
+Integrate Activity with
+
+Customer
+
+Contact
+
+Lead
+
+Opportunity
+
+Quotation
+
+PO
+
+Activity must resolve context without changing ownership of those domains.
+
+---
+
+## Part 3 — Activity Type Governance
+
+Freeze the official activity catalog.
+
+Minimum types
+
+- Meeting
+- Visit
+- Phone Call
+- Email
+- Site Survey
+- Presentation
+- Reminder
+- Internal Task
+- Follow-up
+- Delivery Coordination
+- Approval Action
+
+Introduce `crm_activity_type` master options.
+
+No hard-coded types.
+
+---
+
+## Part 4 — Activity Context Strategy
+
+Freeze
+
+contextType
+
+contextId
+
+supported contexts
+
+Exactly one primary context.
+
+Optional related references.
+
+Prepare Timeline and Calendar compatibility.
+
+---
+
+## Part 5 — Activity Number Strategy
+
+Introduce configurable document numbering.
+
+Example
+
+ACT2607-0001
+
+Support
+
+Organization
+
+Branch
+
+Period
+
+Sequence
+
+Reuse existing Document Sequence Foundation.
+
+---
+
+## Part 6 — Activity Attachment Foundation
+
+Integrate Activity with existing Storage Foundation.
+
+Support
+
+Images
+
+PDF
+
+Office Documents
+
+Voice Recording
+
+Drawing
+
+No new storage engine.
+
+Reuse current abstraction.
+
+---
+
+## Part 7 — Activity UI Integration
+
+Extend existing pages.
+
+Customer Detail
+
+Opportunity Detail
+
+Quotation Detail
+
+Lead Detail
+
+Add
+
+Recent Activities
+
+Create Activity
+
+Activity Summary
+
+Do NOT replace Follow-up UI.
+
+Run both in parallel.
+
+---
+
+## Part 8 — Permission Integration
+
+Reuse existing CRM permission model.
+
+Support
+
+Owner
+
+Assignee
+
+Manager
+
+Administrator
+
+Organization
+
+Branch
+
+Product Type
+
+Pricing visibility
+
+Internal-only Activity
+
+---
+
+## Part 9 — Compatibility Layer
+
+Introduce compatibility interfaces.
+
+Legacy Follow-up
+
+↓
+
+Activity Adapter
+
+↓
+
+Activity DTO
+
+Current consumers remain unchanged.
+
+No existing API removed.
+
+No schema migration.
+
+---
+
+## Part 10 — Migration Readiness
+
+Produce
+
+Adapter validation
+
+Compatibility report
+
+Legacy usage inventory
+
+Projection readiness report
+
+Migration checklist
+
+No migration execution.
+
+---
+
+# Deliverables
+
+1. Lead Follow-up Adapter
+2. Opportunity Follow-up Adapter
+3. Quotation Follow-up Adapter
+4. Activity Context Integration
+5. Activity Type Governance
+6. Activity Numbering Strategy
+7. Activity Attachment Foundation
+8. Activity UI Integration
+9. Compatibility Layer
+10. Migration Readiness Report
+
+---
+
+# Constraints
+
+Must preserve
+
+- Existing Follow-up
+- Existing APIs
+- Existing Reports
+- Existing Dashboard
+- Existing Audit History
+- Existing Permissions
+
+No Timeline.
+
+No Calendar.
+
+No Notification.
+
+No My Day.
+
+No Dashboard Projection.
+
+No Event Publishing.
+
+No data migration.
+
+No dual write.
+
+---
+
+# Acceptance Criteria
+
+- Activity integrates with all major CRM modules.
+- Existing Follow-up continues to function.
+- Adapter Layer becomes the only integration point.
+- Activity Types are centrally governed.
+- Activity Numbering follows Document Sequence Foundation.
+- Activity Attachments reuse existing Storage Foundation.
+- No production behavior changes.
+- No breaking API changes.
+- No duplicated business logic.
+- No duplicated lifecycle.
+
+---
+
+# Success Criteria
+
+Activity is fully integrated into the CRM foundation.
+
+Legacy Follow-up remains operational.
+
+All future projection epics can consume Activity through stable interfaces.
+
+Repository remains backward compatible.
+
+Ready for
+
+EP.1.3 – Business Event Foundation & Projection Contracts.