alla-allaos-fullstack/docs/implementation/task-ep1.1-activity-domain-foundation-2026-07-10.md

Task EP.1.1 Activity Domain Foundation - 2026-07-10

Scope

• introduce the first additive crm_activities write model
• add activity API, service, lightweight repository, and read-model shaping
• add foundational UI building blocks for sheet, form, detail, and badges
• preserve legacy lead, opportunity, and quotation follow-up implementations

Review Summary

Reviewed before implementation:

• AGENTS.md
• plans/task-ep1.1.md
• docs/standards/task-contract-template.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/business/relationship-sales-workspace-blueprint-v1.md
• docs/implementation/task-bu-r.0.1-workspace-activity-business-blueprint-2026-07-07.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
• plans/task-eng.0.md
• existing follow-up services and route handlers under src/features/crm/leads/**, src/features/crm/opportunities/**, and src/features/crm/quotations/**
• existing CRM security, audit, and customer detail foundations

Foundations Reused

• src/lib/auth/session.ts
• src/features/crm/security/server/service.ts
• src/features/foundation/audit-log/service.ts
• src/features/foundation/display/server/display-resolver.ts
• existing customer, lead, opportunity, and quotation detail services for primary-record access validation

Implementation Notes

• crm_activities is additive and does not replace existing follow-up tables or audit-backed lead follow-up behavior.
• activity visibility reuses resolved CRM scope plus owner/assignee visibility and an internal-only rule for manager/admin style access.
• pricing-sensitive activity content is redacted when tied to quotation or PO context without quotation pricing visibility.
• follow-up adapters are documented as candidate contracts only in this phase. No data migration or dual-write was introduced.

Follow-up Gap Analysis

1. Lead follow-up is still audit-log-backed rather than row-backed, so migration needs an adapter that can translate immutable audit entries into activity candidates without rewriting history.
2. Opportunity follow-up is row-backed and is the cleanest EP.1.2 consolidation seam.
3. Quotation follow-up is row-backed and can follow the same adapter path as opportunity follow-up, but pricing visibility rules must stay active when notes expose commercial values.
4. Dashboard and report consumers still read legacy follow-up data today, so EP.1.2 needs continuity checks before any shared activity projection becomes source input.

Migration Preparation Report

• prepared:
  • shared activity write model
  • route-handler boundary
  • service-owned lifecycle validation
  • repository/read-model split
  • projection contract interfaces
  • basic activity UI foundation
• deferred intentionally:
  • timeline projection
  • calendar projection
  • notification fan-out
  • legacy follow-up storage migration
  • dashboard/report dataset swap

Verification Plan

• run npm run typecheck
• run npm run db:generate
• run targeted manual API smoke checks for create, update, assign, complete, cancel, reschedule, delete

Residual Risks

• current activity creation UI uses manual primary record id entry because source-record pickers are intentionally deferred to later workspace integration work
• contact primary-record validation remains lightweight and should be revisited when customer workspace activity embedding begins