845 lines
12 KiB
Markdown
845 lines
12 KiB
Markdown
# Task EP.1.6 – Calendar Projection, Workspace & Big Calendar Foundation
|
||
|
||
**Status:** Foundation Implemented
|
||
|
||
**Priority:** Critical
|
||
|
||
**Type:** Projection Platform / Workspace / UI Foundation
|
||
|
||
---
|
||
|
||
# Depends On
|
||
|
||
* EP.1.1 Activity Domain Foundation
|
||
* EP.1.2 Activity Integration & Legacy Follow-up Adapter
|
||
* EP.1.3 Business Event Foundation
|
||
* EP.1.4 Projection Foundation & Delivery Reliability
|
||
* EP.1.4.1 Transactional Outbox Activation & Worker Runtime
|
||
* EP.1.5 Timeline Projection Foundation
|
||
* BU-R.0 Business Blueprint Freeze
|
||
* BU-R.0.1 Workspace & Activity Blueprint
|
||
* BU-R.1 Business Capability Audit
|
||
* AR.1 Architecture Transition Plan
|
||
* AR.2 Epic Technical Design
|
||
* AR.2 Workspace UI/UX Design Note
|
||
* ENG.0 Engineering Constitution
|
||
|
||
---
|
||
|
||
# Objective
|
||
|
||
Introduce the first production Calendar Workspace of ALLA OS by combining:
|
||
|
||
* Calendar Projection
|
||
* Calendar Workspace
|
||
* Big Calendar UI Foundation
|
||
* Activity scheduling
|
||
* Business milestones
|
||
* Team visibility
|
||
* Calendar interaction
|
||
|
||
Calendar becomes the operational scheduling workspace for CRM while preserving existing source-domain ownership.
|
||
|
||
Calendar is **NOT**:
|
||
|
||
* a source-of-truth
|
||
* another Activity module
|
||
* another Opportunity module
|
||
* another Quotation module
|
||
|
||
Calendar is a governed projection and operational workspace.
|
||
|
||
---
|
||
|
||
# Business Outcome
|
||
|
||
After EP.1.6 users can answer:
|
||
|
||
* What should I do today?
|
||
* Which customers should I visit?
|
||
* Which follow-ups are overdue?
|
||
* Which quotations are expiring?
|
||
* Which projects are Hot Projects?
|
||
* Which approvals are waiting?
|
||
* Which customer visits are scheduled?
|
||
* What is my team's workload today?
|
||
* What are tomorrow's priorities?
|
||
|
||
Managers gain a Team Calendar without creating duplicate business data.
|
||
|
||
---
|
||
|
||
# Calendar Business Principles
|
||
|
||
## Calendar is Projection
|
||
|
||
Calendar is generated from:
|
||
|
||
* Activity
|
||
* Business Events
|
||
* Opportunity milestones
|
||
* Quotation milestones
|
||
* Approval milestones
|
||
* Legacy adapters during rebuild
|
||
|
||
Calendar rows are rebuildable.
|
||
|
||
---
|
||
|
||
## Activity Owns Operational Work
|
||
|
||
Editable Calendar events always belong to Activity.
|
||
|
||
Examples:
|
||
|
||
* Follow-up
|
||
* Meeting
|
||
* Site Survey
|
||
* Visit
|
||
* Internal Task
|
||
* Phone Call
|
||
* Reminder
|
||
|
||
Calendar actions must call Activity Services.
|
||
|
||
Calendar never edits projection rows directly.
|
||
|
||
---
|
||
|
||
## Milestones Remain Source-Owned
|
||
|
||
Read-only Calendar milestones include:
|
||
|
||
* Expected Award Date
|
||
* Expected Delivery Date
|
||
* Quotation Expiration
|
||
* Approval Due
|
||
* Approval Escalation
|
||
* PO Milestones
|
||
|
||
Editing must always occur through the owning domain.
|
||
|
||
---
|
||
|
||
## Calendar ≠ Timeline
|
||
|
||
Timeline answers:
|
||
|
||
> What happened?
|
||
|
||
Calendar answers:
|
||
|
||
> What must happen?
|
||
|
||
Both consume Business Events but serve different business purposes.
|
||
|
||
---
|
||
|
||
# UI Foundation Decision
|
||
|
||
The Calendar UI must adopt:
|
||
|
||
**lramos33/big-calendar**
|
||
|
||
Repository:
|
||
|
||
```text
|
||
https://github.com/lramos33/big-calendar
|
||
```
|
||
|
||
This repository becomes the Calendar UI foundation only.
|
||
|
||
It does **NOT** become:
|
||
|
||
* Calendar database
|
||
* Calendar backend
|
||
* Activity service
|
||
* Projection runtime
|
||
* CRM authorization
|
||
* Source-of-truth
|
||
|
||
The governed architecture remains:
|
||
|
||
```text
|
||
Activity / Opportunity / Quotation / Approval
|
||
↓
|
||
Business Events
|
||
↓
|
||
Projection Runtime
|
||
↓
|
||
crm_calendar_projection
|
||
↓
|
||
Calendar Adapter
|
||
↓
|
||
lramos33/big-calendar
|
||
```
|
||
|
||
---
|
||
|
||
# Review Required
|
||
|
||
## Governance
|
||
|
||
Review:
|
||
|
||
* AGENTS.md
|
||
* Engineering Constitution
|
||
* Project Foundations
|
||
* Architecture Rules
|
||
* UI UX Rules
|
||
* Task Review Checklist
|
||
* CRM Authorization Boundaries
|
||
* LAYOUT.md
|
||
|
||
## Business
|
||
|
||
Review:
|
||
|
||
* Relationship Sales Workspace Blueprint
|
||
* BU-R.1
|
||
|
||
## Architecture
|
||
|
||
Review:
|
||
|
||
* AR.1
|
||
* AR.2
|
||
* Workspace UI UX Design Note
|
||
|
||
## Existing Runtime
|
||
|
||
Review:
|
||
|
||
* Projection Runtime
|
||
* Worker Runtime
|
||
* Timeline Projection
|
||
* Activity Service
|
||
* Business Event Registry
|
||
* Calendar-related Activity scheduling
|
||
* Date formatting utilities
|
||
* CRM security
|
||
|
||
## UI Review
|
||
|
||
Must use:
|
||
|
||
* ui-ux-pro-max
|
||
* LAYOUT.md
|
||
* ui-ux-rules.md
|
||
|
||
No code-first Calendar implementation is allowed.
|
||
|
||
---
|
||
|
||
# Scope
|
||
|
||
# Part 1 — Calendar Projection Schema
|
||
|
||
Introduce:
|
||
|
||
```text
|
||
crm_calendar_projection
|
||
```
|
||
|
||
Containing:
|
||
|
||
* organization
|
||
* branch
|
||
* product
|
||
* activity
|
||
* customer
|
||
* lead
|
||
* opportunity
|
||
* quotation
|
||
* approval
|
||
* owner
|
||
* assignee
|
||
* title
|
||
* summary
|
||
* location
|
||
* start
|
||
* end
|
||
* timezone
|
||
* priority
|
||
* category
|
||
* editable
|
||
* milestone
|
||
* overdue
|
||
* hot project
|
||
* projection version
|
||
* source event
|
||
* metadata
|
||
|
||
Projection rows remain rebuildable.
|
||
|
||
---
|
||
|
||
# Part 2 — Calendar Projection Builder
|
||
|
||
Implement
|
||
|
||
CalendarProjectionBuilder
|
||
|
||
Responsibilities
|
||
|
||
* Business Event mapping
|
||
* milestone mapping
|
||
* display enrichment
|
||
* permission metadata
|
||
* icon registry
|
||
* urgency calculation
|
||
* projection persistence
|
||
|
||
Builder never mutates source domains.
|
||
|
||
---
|
||
|
||
# Part 3 — Activity Event Mapping
|
||
|
||
Support
|
||
|
||
* activity.created
|
||
* activity.assigned
|
||
* activity.reassigned
|
||
* activity.started
|
||
* activity.rescheduled
|
||
* activity.completed
|
||
* activity.cancelled
|
||
* activity.deleted
|
||
|
||
Projection updates must be incremental through Business Events.
|
||
|
||
---
|
||
|
||
# Part 4 — Milestone Projection
|
||
|
||
Project:
|
||
|
||
Opportunity
|
||
|
||
* Expected Award Date
|
||
* Expected Delivery Date
|
||
* Hot Project review
|
||
|
||
Quotation
|
||
|
||
* Valid Until
|
||
* Delivery milestone
|
||
|
||
Approval
|
||
|
||
* Due
|
||
* Escalation
|
||
|
||
Milestones are read-only.
|
||
|
||
---
|
||
|
||
# Part 5 — Calendar Projection Consumer
|
||
|
||
Activate Calendar consumer through Projection Runtime.
|
||
|
||
Must support:
|
||
|
||
* checkpoint
|
||
* retry
|
||
* dead letter
|
||
* rebuild
|
||
* idempotency
|
||
|
||
---
|
||
|
||
# Part 6 — Calendar Query Service
|
||
|
||
Provide secured query service.
|
||
|
||
Filters:
|
||
|
||
* date range
|
||
* user
|
||
* team
|
||
* branch
|
||
* product
|
||
* customer
|
||
* lead
|
||
* opportunity
|
||
* quotation
|
||
* activity type
|
||
* category
|
||
* priority
|
||
* overdue
|
||
* milestone
|
||
* Hot Project
|
||
* search
|
||
|
||
Supported lenses:
|
||
|
||
* Personal
|
||
* Team
|
||
* Manager
|
||
* Executive
|
||
|
||
---
|
||
|
||
# Part 7 — Calendar Rebuild
|
||
|
||
Hybrid rebuild.
|
||
|
||
Initial build:
|
||
|
||
* Activity
|
||
* Opportunity
|
||
* Quotation
|
||
* Approval
|
||
|
||
Incremental:
|
||
|
||
* Business Events
|
||
|
||
Support:
|
||
|
||
* organization
|
||
* customer
|
||
* opportunity
|
||
* quotation
|
||
* date range
|
||
* dry run
|
||
* reset existing
|
||
* restart
|
||
|
||
---
|
||
|
||
# Part 8 — Calendar Workspace
|
||
|
||
Route:
|
||
|
||
```text
|
||
/dashboard/crm/calendar
|
||
```
|
||
|
||
Views:
|
||
|
||
* Day
|
||
* Week
|
||
* Month
|
||
* Agenda
|
||
|
||
Agenda is default for:
|
||
|
||
* mobile
|
||
* manager
|
||
* high-density work
|
||
|
||
---
|
||
|
||
# Part 9 — Big Calendar Source Audit
|
||
|
||
Before implementation:
|
||
|
||
Audit:
|
||
|
||
* dependency compatibility
|
||
* React compatibility
|
||
* Next.js compatibility
|
||
* shadcn compatibility
|
||
* Tailwind compatibility
|
||
* accessibility
|
||
* dark mode
|
||
* timezone assumptions
|
||
* drag/drop libraries
|
||
* demo code
|
||
* mock data
|
||
|
||
Document:
|
||
|
||
* files adopted
|
||
* files rejected
|
||
* modification strategy
|
||
|
||
---
|
||
|
||
# Part 10 — Big Calendar Adaptation
|
||
|
||
Do **NOT** import the whole repository.
|
||
|
||
Only adapt:
|
||
|
||
* Calendar Views
|
||
* Toolbar
|
||
* Event Rendering
|
||
* Drag & Drop
|
||
* Resize
|
||
* Navigation
|
||
* User Filter
|
||
* Working Hours
|
||
|
||
Move adapted source into:
|
||
|
||
```text
|
||
src/features/crm/calendar/
|
||
```
|
||
|
||
Maintain ALLA OS architecture.
|
||
|
||
---
|
||
|
||
# Part 11 — Calendar Adapter Layer
|
||
|
||
Introduce
|
||
|
||
CalendarProjectionItem
|
||
|
||
↓
|
||
|
||
BigCalendarEvent
|
||
|
||
Implement
|
||
|
||
```ts
|
||
mapCalendarProjectionToBigCalendarEvent()
|
||
```
|
||
|
||
UI must never consume database rows directly.
|
||
|
||
---
|
||
|
||
# Part 12 — Calendar Rendering Strategy
|
||
|
||
Differentiate:
|
||
|
||
## Editable Activity
|
||
|
||
Examples
|
||
|
||
* Follow-up
|
||
* Meeting
|
||
* Visit
|
||
* Site Survey
|
||
|
||
Supports
|
||
|
||
* Complete
|
||
* Reschedule
|
||
* Cancel
|
||
* Open
|
||
* Reassign
|
||
|
||
---
|
||
|
||
## Read-only Milestone
|
||
|
||
Examples
|
||
|
||
* Expected Award
|
||
* Expected Delivery
|
||
* Approval Due
|
||
* Quotation Expiration
|
||
|
||
Supports
|
||
|
||
* Open Source
|
||
* View Detail
|
||
* Create Related Activity
|
||
|
||
No editing.
|
||
|
||
---
|
||
|
||
# Part 13 — Drag and Drop
|
||
|
||
For Activities
|
||
|
||
Drag
|
||
|
||
↓
|
||
|
||
Activity API
|
||
|
||
↓
|
||
|
||
Business Event
|
||
|
||
↓
|
||
|
||
Projection Update
|
||
|
||
↓
|
||
|
||
Calendar Refresh
|
||
|
||
No direct Calendar persistence.
|
||
|
||
Milestones cannot be dragged.
|
||
|
||
---
|
||
|
||
# Part 14 — User Filter
|
||
|
||
Integrate upstream user filter with:
|
||
|
||
* CRM permissions
|
||
* team hierarchy
|
||
* ownership
|
||
* manager scope
|
||
|
||
Never load unauthorized users.
|
||
|
||
---
|
||
|
||
# Part 15 — Working Hours
|
||
|
||
Support
|
||
|
||
* organization defaults
|
||
* user preferences
|
||
* Bangkok timezone
|
||
* all-day events
|
||
* current time
|
||
* business hours
|
||
|
||
---
|
||
|
||
# Part 16 — Schedule Conflict Detection
|
||
|
||
Detect
|
||
|
||
* overlapping visits
|
||
* meetings
|
||
* site surveys
|
||
* tasks
|
||
|
||
Read-only advisory.
|
||
|
||
No blocking.
|
||
|
||
---
|
||
|
||
# Part 17 — Calendar Summary
|
||
|
||
Display
|
||
|
||
* Due Today
|
||
* Overdue
|
||
* Meetings
|
||
* Visits
|
||
* Milestones
|
||
* Approval Due
|
||
* Hot Projects
|
||
|
||
Derived from Calendar projection.
|
||
|
||
---
|
||
|
||
# Part 18 — Calendar Performance
|
||
|
||
Support
|
||
|
||
* indexes
|
||
* bounded queries
|
||
* lazy loading
|
||
* virtual agenda
|
||
* cursor pagination
|
||
* projection batching
|
||
|
||
No N+1.
|
||
|
||
---
|
||
|
||
# Part 19 — Projection Health
|
||
|
||
Track
|
||
|
||
* lag
|
||
* retries
|
||
* dead letters
|
||
* row count
|
||
* stale rows
|
||
* rebuild status
|
||
|
||
---
|
||
|
||
# Part 20 — Calendar Delivery Matrix
|
||
|
||
Document
|
||
|
||
Source
|
||
|
||
↓
|
||
|
||
Business Event
|
||
|
||
↓
|
||
|
||
Projection
|
||
|
||
↓
|
||
|
||
Calendar Item
|
||
|
||
↓
|
||
|
||
Workspace
|
||
|
||
Include:
|
||
|
||
* Activity
|
||
* Opportunity
|
||
* Quotation
|
||
* Approval
|
||
|
||
---
|
||
|
||
# Part 21 — Calendar UI / UX Review
|
||
|
||
Review with
|
||
|
||
* ui-ux-pro-max
|
||
* LAYOUT.md
|
||
* ui-ux-rules.md
|
||
|
||
Validate
|
||
|
||
* hierarchy
|
||
* spacing
|
||
* typography
|
||
* icons
|
||
* filters
|
||
* density
|
||
* accessibility
|
||
* dark mode
|
||
* responsiveness
|
||
* keyboard
|
||
* loading
|
||
* empty state
|
||
|
||
---
|
||
|
||
# Part 22 — Upstream License
|
||
|
||
Retain
|
||
|
||
MIT License
|
||
|
||
Document
|
||
|
||
* adopted files
|
||
* attribution
|
||
* modification history
|
||
|
||
---
|
||
|
||
# Deliverables
|
||
|
||
1. Calendar Projection Schema
|
||
2. Calendar Builder
|
||
3. Calendar Projection Consumer
|
||
4. Calendar Query Service
|
||
5. Calendar Rebuild
|
||
6. Calendar Workspace
|
||
7. Day / Week / Month / Agenda
|
||
8. Big Calendar Source Audit
|
||
9. Big Calendar Adaptation
|
||
10. Calendar Adapter Layer
|
||
11. Activity Calendar Actions
|
||
12. Milestone Projection
|
||
13. Drag & Drop Integration
|
||
14. User Filter Integration
|
||
15. Working Hours Support
|
||
16. Schedule Conflict Detection
|
||
17. Calendar Summary Panels
|
||
18. Projection Health
|
||
19. Calendar Delivery Matrix
|
||
20. UI/UX Review Report
|
||
21. Upstream License & Attribution Report
|
||
22. EP.1.7 Readiness Report
|
||
|
||
---
|
||
|
||
# Constraints
|
||
|
||
Must preserve:
|
||
|
||
* Activity ownership
|
||
* Opportunity ownership
|
||
* Quotation ownership
|
||
* Approval ownership
|
||
* Timeline
|
||
* Dashboard
|
||
* Reports
|
||
* Notifications
|
||
* Audit Log
|
||
* CRM security
|
||
* Projection Runtime
|
||
|
||
Do NOT implement:
|
||
|
||
* Google Calendar Sync
|
||
* Outlook Sync
|
||
* recurring engine
|
||
* My Day
|
||
* Manager Workspace
|
||
* Executive Workspace
|
||
* Relationship Health
|
||
* Forecast
|
||
* automatic Activity generation
|
||
* legacy migration
|
||
|
||
Calendar remains an additive projection.
|
||
|
||
---
|
||
|
||
# Testing
|
||
|
||
* Projection
|
||
* Builder
|
||
* Consumer
|
||
* Rebuild
|
||
* Activity Events
|
||
* Milestones
|
||
* Query
|
||
* Permissions
|
||
* Drag & Drop
|
||
* Resize
|
||
* Agenda
|
||
* Day
|
||
* Week
|
||
* Month
|
||
* Timezone
|
||
* Conflict Detection
|
||
* UI
|
||
* Accessibility
|
||
* Dark Mode
|
||
* Performance
|
||
* Compatibility
|
||
|
||
---
|
||
|
||
# Acceptance Criteria
|
||
|
||
* Calendar Projection is fully rebuildable.
|
||
* Calendar uses Business Events for incremental updates.
|
||
* Activity remains the only editable operational work source.
|
||
* Opportunity, Quotation, and Approval milestones are projected as read-only Calendar items.
|
||
* `lramos33/big-calendar` is successfully adopted as the UI foundation without importing its application shell or backend.
|
||
* A dedicated adapter maps `CalendarProjectionItem` to the Calendar UI event model.
|
||
* Drag-and-drop and resize update Activities only through Activity Services and Business Events.
|
||
* Read-only milestones cannot be dragged or resized.
|
||
* Personal, Team, Manager, and Executive lenses enforce existing CRM authorization.
|
||
* Day, Week, Month, and Agenda views are available, with Agenda optimized for managers and mobile.
|
||
* Working hours, timezone, and schedule conflict detection behave consistently.
|
||
* Calendar integrates with the Projection Runtime (checkpoint, retry, rebuild, health).
|
||
* UI conforms to `LAYOUT.md`, `ui-ux-rules.md`, and `ui-ux-pro-max`.
|
||
* Existing Activity, Timeline, Dashboard, Reports, Notifications, Approval flows, and Follow-up APIs remain unchanged.
|
||
|
||
---
|
||
|
||
# Success Criteria
|
||
|
||
ALLA OS gains a production-ready Calendar Workspace built on a governed Projection architecture.
|
||
|
||
Users can plan and execute daily operational work from a single Calendar while preserving Activity, Opportunity, Quotation, and Approval as the authoritative business domains.
|
||
|
||
The Calendar foundation is ready for:
|
||
|
||
**EP.1.7 – My Day Workspace Foundation**
|