task-ep.1.5

docs/implementation/task-ep1.5-timeline-projection-foundation-2026-07-13.md

@@ -0,0 +1,155 @@
+# Task EP.1.5 Timeline Projection Foundation - 2026-07-13
+
+## Scope
+
+- introduced first production CRM Business Projection: Timeline
+- added `crm_timeline_projection` materialized read model schema
+- added Timeline event builder and Activity event mapping
+- added Timeline projection consumer contract and active CRM registration
+- added Timeline list/query storage service
+- added Timeline rebuild and legacy adapter contracts
+- added reusable Timeline UI components
+- added optional Activity detail Timeline integration seam
+- preserved Activity, Audit Log, Approval History, follow-up APIs, Dashboard, Reports, Notifications, and current detail-page behavior
+
+## Review Summary
+
+Reviewed before and during implementation:
+
+- `AGENTS.md`
+- `plans/task-ep.1.5.md`
+- `LAYOUT.md`
+- `docs/standards/engineering-constitution.md`
+- `docs/standards/project-foundations.md`
+- `docs/standards/architecture-rules.md`
+- `docs/standards/ui-ux-rules.md`
+- `docs/business/relationship-sales-workspace-blueprint-v1.md`
+- `docs/security/crm-authorization-boundaries.md`
+- `docs/implementation/task-ep1.4-projection-foundation-delivery-reliability-2026-07-13.md`
+- `docs/implementation/task-ep1.4.1-transactional-outbox-activation-worker-runtime-2026-07-13.md`
+- existing Activity business event adapter
+- existing Projection Runtime and Worker
+- existing CRM detail/audit UI patterns
+
+## Implementation Summary
+
+### Timeline Schema
+
+Added table:
+
+- `crm_timeline_projection`
+
+Generated migration:
+
+- `drizzle/0005_freezing_wendigo.sql`
+
+The table stores organization-scoped, rebuildable read-model rows with entity references, event provenance, visibility metadata, display fields, and projection version. It has indexes for event id/version idempotency, organization chronology, customer chronology, and activity/event lookup.
+
+### Timeline Builder
+
+Added:
+
+- `src/features/crm/timeline/server/builder.ts`
+
+Builder maps Business Events into business-readable Timeline items. Initial active mappings cover Activity lifecycle events:
+
+- `activity.created`
+- `activity.assigned`
+- `activity.reassigned`
+- `activity.started`
+- `activity.rescheduled`
+- `activity.completed`
+- `activity.cancelled`
+- `activity.deleted`
+
+Generic mapping is available for registered future CRM events until their business copy is specialized.
+
+### Timeline Consumer
+
+Added:
+
+- `src/features/crm/timeline/server/consumer.ts`
+- `src/features/crm/timeline/server/registration.ts`
+
+The consumer builds a Timeline item and persists it with idempotent `eventId + sourceProjectionVersion` storage. Foundation default consumers remain safe skeletons; CRM worker startup can opt into `CRM_TIMELINE_PROJECTION_CONSUMERS` for the active Timeline projection set.
+
+### Timeline Storage And Query Contract
+
+Added:
+
+- `src/features/crm/timeline/api/types.ts`
+- `src/features/crm/timeline/server/service.ts`
+
+Supported filters include organization, customer, lead, opportunity, quotation, activity, event, category, actor, search, date range, and cursor/limit contract. Timeline remains read-only.
+
+### Legacy Adapter And Rebuild Contracts
+
+Added:
+
+- `src/features/crm/timeline/server/legacy-adapters.ts`
+- `src/features/crm/timeline/server/rebuild.ts`
+
+Legacy adapters are explicitly read-only rebuild inputs for lead follow-up, opportunity follow-up, quotation follow-up, activity, approval, and audit history. No data migration was introduced.
+
+### Timeline UI
+
+Added:
+
+- `src/features/crm/timeline/components/timeline-list.tsx`
+
+Components:
+
+- `TimelineList`
+- `TimelineCard`
+- `TimelineEmpty`
+- `TimelineSkeleton`
+
+The UI follows the existing dashboard card language, uses deterministic shared date formatting, shadcn primitives, and app icon registry. It preserves a calm enterprise density while adding a clear vertical chronology.
+
+### Workspace Integration
+
+Added an optional `timelineItems` prop to Activity detail. Existing callers are unaffected; when supplied, Activity detail renders an additive Timeline card below the existing Activity detail card.
+
+## Security Notes
+
+- Timeline rows are organization-scoped.
+- Timeline visibility stores product type, pricing sensitivity, and internal-only flags.
+- Pricing-sensitive/internal-only event payloads continue to rely on source event minimization.
+- Timeline query service is storage-ready; route/API exposure must still apply CRM resolved access, branch/product scope, ownership, and pricing visibility before becoming public.
+- Timeline never mutates source domains and does not replace Audit Log.
+
+## Delivery Matrix
+
+Initial production path:
+
+| Business Event | Timeline Item | Workspace | Consumer | Projection |
+| --- | --- | --- | --- | --- |
+| `activity.created` | Activity created | Customer / Lead / Opportunity / Quotation / Activity | `timeline.projection.consumer` | `crm_timeline_projection` |
+| `activity.completed` | Activity completed | Customer / Lead / Opportunity / Quotation / Activity | `timeline.projection.consumer` | `crm_timeline_projection` |
+| `activity.cancelled` | Activity cancelled | Customer / Lead / Opportunity / Quotation / Activity | `timeline.projection.consumer` | `crm_timeline_projection` |
+
+Additional Activity events are supported in code and documented in the builder mapping.
+
+## UX Review
+
+- Layout: follows `LAYOUT.md` detail-card and timeline entry patterns.
+- Density: Timeline cards stay compact, scannable, and fit existing CRM dashboard surfaces.
+- Accessibility: items use semantic `article`, `time`, non-color badges, and text labels.
+- Loading/empty states: `TimelineSkeleton` and `TimelineEmpty` included.
+- Dark mode: tone classes include dark-mode variants.
+- Date rendering: uses `src/lib/date-format.ts`.
+
+## Verification
+
+- `npm run typecheck`
+- `node --disable-warning=ExperimentalWarning --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types --test src/features/foundation/business-events/*.test.ts src/features/foundation/projections/*.test.ts src/features/crm/activities/server/business-events.test.ts src/features/crm/timeline/server/*.test.ts`
+- `npx oxlint src/features/crm/timeline src/features/foundation/projections/registry.ts src/features/foundation/projections/consumers.ts src/features/foundation/projections/server/store.ts src/features/crm/activities/components/activity-detail.tsx src/db/schema.ts`
+- `npm run db:generate`
+
+## Residual Risks / Follow-up
+
+- Public Timeline route handlers and server-side CRM resolved-access filtering remain future work before exposing Timeline broadly.
+- Customer, Lead, Opportunity, and Quotation detail pages are not yet wired to fetch Timeline data; Activity detail has a backward-compatible render seam.
+- Approval, quotation, opportunity, customer, and PO event mappings have generic fallback support but need specialized business copy when those domains publish durable events.
+- Legacy adapters are contract-only in this slice; source-query rebuild implementation should be expanded as each workspace adopts Timeline.
+- EP.1.6 Calendar can reuse the same projection runtime and Activity event delivery path.