task-ep.1.6

docs/implementation/task-ep1.6-calendar-projection-workspace-big-calendar-foundation-2026-07-13.md

@@ -0,0 +1,153 @@
+# Task EP.1.6 Calendar Projection, Workspace & Big Calendar Foundation - 2026-07-13
+
+## Scope Delivered
+
+- introduced `crm_calendar_projection` materialized read model schema and migration `drizzle/0006_massive_scalphunter.sql`
+- added Calendar projection contracts under `src/features/crm/calendar/**`
+- added Activity business-event mapping for scheduled Activity calendar rows
+- added terminal Activity event handling that removes completed/cancelled/deleted Activity rows from Calendar projection
+- added Calendar projection consumer, registration seam, rebuild plan contract, query service, API route, React Query service, and dashboard workspace route
+- added `CalendarProjectionItem -> BigCalendarEvent` adapter so UI never consumes database rows directly
+- added Calendar Workspace UI at `/dashboard/crm/calendar` with Agenda, Day, Week, Month tabs, summary cards, search, empty/loading states, and read-only/editable visual distinction
+- added Calendar navigation item under CRM
+- preserved Activity, Timeline, Dashboard, Reports, Notifications, Approval, Follow-up APIs, and source-domain ownership
+
+## Review Summary
+
+Reviewed before/during implementation:
+
+- `AGENTS.md`
+- `plans/task-ep.1.6.md`
+- `docs/standards/engineering-constitution.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-ar.2-epic-technical-design-2026-07-07.md`
+- `docs/implementation/task-ar.2-workspace-ui-ux-design-note-2026-07-07.md`
+- `docs/implementation/task-bu-r.0.1-workspace-activity-business-blueprint-2026-07-07.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`
+- `docs/implementation/task-ep1.5-timeline-projection-foundation-2026-07-13.md`
+- existing Projection Runtime, Activity Business Events, Timeline Projection, CRM security, and date formatting utilities
+
+## Big Calendar Source Audit
+
+Upstream: `https://github.com/lramos33/big-calendar`
+
+Findings:
+
+- Compatibility: upstream is a Next.js, TypeScript, Tailwind, shadcn-oriented calendar app, but targets Next.js 14 and Tailwind v3 while this repo is Next.js 16 and Tailwind v4.
+- React/Next: source is useful as UI composition reference, but the upstream app shell, provider model, demo data, and direct event mutation flow are not compatible with ALLA OS projection governance.
+- shadcn/Tailwind: visual approach is compatible, but code must be adapted to existing dashboard shell and token usage.
+- Accessibility/dark mode/responsive: upstream explicitly supports responsive and dark-mode calendar behavior; ALLA OS implementation keeps shadcn primitives, semantic cards, badges, buttons, and deterministic date rendering.
+- Timezone: upstream uses general date-fns/date string assumptions; ALLA OS calendar rendering uses `src/lib/date-format.ts` and stores projection timezone as `Asia/Bangkok`.
+- Drag/drop: upstream supports direct drag/drop rescheduling. ALLA OS does not persist Calendar mutations directly; drag/resize must call Activity APIs, publish Business Events, and refresh the projection.
+- License: upstream repository is MIT licensed.
+
+Adoption decision:
+
+- Adopted conceptually: Agenda/Day/Week/Month views, toolbar/search pattern, event rendering, editable vs read-only event behavior, user/lens filter seam, working-hours/timezone constraints.
+- Rejected: upstream app shell, backend assumptions, mock event store, direct event CRUD, global Calendar context, uncontrolled user lists, direct drag/drop persistence.
+- Modification strategy: implement native ALLA OS components under `src/features/crm/calendar/`, keep projection adapter as boundary, and wire future drag/resize only through Activity services.
+
+## Implementation Summary
+
+### Calendar Schema
+
+Added `crm_calendar_projection` with organization, branch, product, source refs, activity/customer/lead/opportunity/quotation/approval refs, owner/assignee, event provenance, title/summary/location, start/end/timezone, priority/category, editable/milestone/overdue/hot-project/all-day flags, visibility metadata, source event, projection version, timestamps.
+
+Indexes cover organization/date range, owner/assignee/date range, branch/date range, category/date range, customer/date range, activity/event lookup, and event/version idempotency.
+
+### Calendar Builder and Consumer
+
+Activity events supported:
+
+- `activity.created`
+- `activity.assigned`
+- `activity.reassigned`
+- `activity.started`
+- `activity.rescheduled`
+- `activity.completed`
+- `activity.cancelled`
+- `activity.deleted`
+
+Non-terminal scheduled Activity events upsert one current Calendar row per Activity. Terminal events delete the Activity calendar row so Calendar remains a forward-looking operational workspace, not a history timeline.
+
+### Query and Security
+
+Calendar query service supports:
+
+- date range
+- user/team user IDs
+- branch/product
+- customer/lead/opportunity/quotation
+- activity type/category/priority
+- overdue/milestone/hot-project flags
+- search
+- Personal/Team/Manager/Executive lens contract
+
+The service applies bounded SQL first, then server-side CRM scope checks through `CrmSecurityContext` and `canAccessScopedCrmRecord()`. Owner/assignee direct visibility is preserved. Internal-only rows remain restricted unless directly assigned or organization-wide scope applies.
+
+### Workspace
+
+Added `/dashboard/crm/calendar` using `PageContainer`, React Query prefetch/hydration, and existing shadcn UI primitives.
+
+Workspace includes:
+
+- summary cards: Due Today, Overdue, Meetings, Hot Projects
+- Agenda default view
+- Day/Week/Month tabs
+- search
+- empty/loading states
+- event cards with read-only milestone vs editable activity distinction
+
+### Rebuild and Health
+
+Calendar rebuild contract added as a plan/result helper for hybrid rebuild:
+
+- sources: Activity, Opportunity, Quotation, Approval, Business Event replay
+- supports organization/date range/dry-run/reset/restart contract
+
+Runtime checkpoint/retry/dead-letter behavior remains owned by Projection Runtime. Calendar consumer can be registered with runtime consumers without changing source-domain writes.
+
+## Delivery Matrix
+
+| Source | Business Event / Source Signal | Projection | Calendar Item | Workspace |
+| --- | --- | --- | --- | --- |
+| Activity | `activity.created`, assigned, reassigned, started, rescheduled | `crm_calendar_projection` | editable Activity event | Calendar Agenda/Day/Week/Month |
+| Activity | `activity.completed`, cancelled, deleted | delete projection row | removed from forward schedule | Calendar refresh |
+| Opportunity | Expected Award / Expected Delivery / Hot Project | rebuild contract seam | read-only milestone | future source adapter |
+| Quotation | Valid Until / Delivery milestone | rebuild contract seam | read-only milestone | future source adapter |
+| Approval | Due / Escalation | rebuild contract seam | read-only milestone | future source adapter |
+
+## UI/UX Review
+
+- Layout follows AR.2 Calendar Workspace note: PageContainer, header, compact filter/search, calendar body, summary cards.
+- Agenda is default manager/mobile-friendly dense view.
+- Day/Week/Month views are available as foundation tabs.
+- State coverage includes loading skeleton and empty state.
+- Status is not color-only: badges show overdue/hot-project/read-only/category text.
+- Date/time rendering uses `src/lib/date-format.ts`.
+- UI avoids importing upstream shell, backend, provider, or mock data.
+
+## Known Follow-ups
+
+- Opportunity, Quotation, and Approval milestone projection adapters are contract-ready but not populated until those domains publish durable milestone events or rebuild source adapters are expanded.
+- Drag/drop and resize UI actions are represented as Activity-only affordances, but direct mutation wiring is intentionally deferred until Activity reschedule API integration is added to Calendar UI.
+- User/team filter contract exists; UI currently exposes lens/search foundation only. Manager team hierarchy should be wired after team graph/scope UX is formalized.
+- Working hours and conflict detection are schema/service-ready concepts but need fuller UI and source preference integration in a follow-up slice.
+- `INITIAL_PROJECTION_CONSUMERS` remains skeleton-safe for foundation runtime tests; CRM runtime composition should opt into `CRM_CALENDAR_PROJECTION_CONSUMERS` or combined CRM registration when running production projection workers.
+
+## Verification
+
+- `npm run typecheck`
+- `node --disable-warning=ExperimentalWarning --disable-warning=MODULE_TYPELESS_PACKAGE_JSON --experimental-strip-types --test src/features/crm/calendar/server/builder.test.ts src/features/crm/timeline/server/builder.test.ts src/features/foundation/projections/runtime.test.ts`
+- `npx oxlint src/features/crm/calendar src/app/api/crm/calendar src/app/dashboard/crm/calendar src/features/foundation/projections/consumers.ts src/features/foundation/projections/registry.ts src/features/crm/timeline/server/registration.ts src/db/schema.ts`
+- `npm run db:generate`
+
+## Outcome
+
+EP.1.6 now has a governed Calendar Projection and first Calendar Workspace foundation. Calendar remains additive, rebuildable, and non-authoritative. Activity remains the only editable operational work source; Timeline remains unchanged as historical chronology.