task-ep.1.5
This commit is contained in:
phaichayon
878
plans/task-ep.1.5.md
Normal file
878
plans/task-ep.1.5.md
Normal file
@@ -0,0 +1,878 @@
|
||||
# Task EP.1.5 – Timeline Projection Foundation
|
||||
|
||||
Status: Completed
|
||||
|
||||
Priority: Critical
|
||||
|
||||
Type: Projection Platform / Timeline Read Model
|
||||
|
||||
---
|
||||
|
||||
# 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
|
||||
* 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
|
||||
* ENG.0 Engineering Constitution
|
||||
|
||||
---
|
||||
|
||||
# Objective
|
||||
|
||||
Introduce the first production Business Projection of ALLA OS.
|
||||
|
||||
This phase builds the Timeline Projection that becomes the official chronological business history of CRM.
|
||||
|
||||
Timeline is **not** Activity.
|
||||
|
||||
Timeline is **not** Audit Log.
|
||||
|
||||
Timeline is **not** Follow-up.
|
||||
|
||||
Timeline is a generated business projection that explains everything that happened to a Customer, Lead, Opportunity, Quotation, Activity, Approval, and PO in business language.
|
||||
|
||||
Timeline becomes the foundation for:
|
||||
|
||||
* Customer Workspace
|
||||
* Lead Workspace
|
||||
* Opportunity Workspace
|
||||
* Quotation Workspace
|
||||
* Relationship Workspace
|
||||
* Manager Workspace
|
||||
* Executive Workspace
|
||||
|
||||
Future Calendar, My Day, Dashboard and Forecast continue consuming Business Events independently.
|
||||
|
||||
Timeline never owns business state.
|
||||
|
||||
---
|
||||
|
||||
# Background
|
||||
|
||||
Current repository already contains
|
||||
|
||||
* Audit Log
|
||||
* Activity Domain
|
||||
* Business Event Foundation
|
||||
* Transactional Outbox
|
||||
* Projection Runtime
|
||||
* Legacy Follow-up Adapters
|
||||
|
||||
What still does not exist is a single business timeline.
|
||||
|
||||
Today users must inspect
|
||||
|
||||
* Audit Log
|
||||
* Lead Follow-up
|
||||
* Opportunity Follow-up
|
||||
* Quotation Follow-up
|
||||
* Activity
|
||||
* Approval History
|
||||
|
||||
to understand one customer journey.
|
||||
|
||||
Timeline consolidates these into one governed projection.
|
||||
|
||||
---
|
||||
|
||||
# Timeline Principles
|
||||
|
||||
## Timeline is Business History
|
||||
|
||||
Timeline answers
|
||||
|
||||
> "What happened?"
|
||||
|
||||
not
|
||||
|
||||
> "What changed in the database?"
|
||||
|
||||
---
|
||||
|
||||
## Timeline is Read Only
|
||||
|
||||
Timeline never edits data.
|
||||
|
||||
Timeline never owns lifecycle.
|
||||
|
||||
Timeline is always rebuildable.
|
||||
|
||||
---
|
||||
|
||||
## Timeline is Projection
|
||||
|
||||
Timeline is generated from
|
||||
|
||||
* Business Events
|
||||
* Activity
|
||||
* Legacy Follow-up adapters
|
||||
* Approval events
|
||||
* Source queries during rebuild
|
||||
|
||||
---
|
||||
|
||||
## Timeline is Human Friendly
|
||||
|
||||
Example
|
||||
|
||||
Instead of
|
||||
|
||||
```text
|
||||
activity.completed
|
||||
```
|
||||
|
||||
Timeline shows
|
||||
|
||||
```text
|
||||
Completed site survey.
|
||||
|
||||
Outcome:
|
||||
Customer requested revised quotation.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Timeline is Chronological
|
||||
|
||||
Every Timeline Item has
|
||||
|
||||
* occurredAt
|
||||
* source
|
||||
* actor
|
||||
* entity
|
||||
* business meaning
|
||||
|
||||
---
|
||||
|
||||
# Review Required
|
||||
|
||||
Review
|
||||
|
||||
Governance
|
||||
|
||||
* AGENTS.md
|
||||
* Engineering Constitution
|
||||
* Project Foundations
|
||||
* Architecture Rules
|
||||
* UI/UX Rules
|
||||
* Task Review Checklist
|
||||
|
||||
Business
|
||||
|
||||
* Relationship Sales Workspace Blueprint
|
||||
* BU-R.1
|
||||
|
||||
Architecture
|
||||
|
||||
* AR.1
|
||||
* AR.2
|
||||
|
||||
Implementation
|
||||
|
||||
* EP.1.2
|
||||
* EP.1.3
|
||||
* EP.1.4
|
||||
* EP.1.4.1
|
||||
|
||||
Existing
|
||||
|
||||
* Activity Timeline Compatibility Layer
|
||||
* Audit Log
|
||||
* Approval History
|
||||
* Customer Detail
|
||||
* Lead Detail
|
||||
* Opportunity Detail
|
||||
* Quotation Detail
|
||||
|
||||
Review
|
||||
|
||||
layout.md
|
||||
|
||||
Review
|
||||
|
||||
ui-ux-rules.md
|
||||
|
||||
Review
|
||||
|
||||
ui-ux-pro-max
|
||||
|
||||
Timeline UI must follow the Workspace UI Constitution.
|
||||
|
||||
---
|
||||
|
||||
# Scope
|
||||
|
||||
## Part 1 — Timeline Projection Schema
|
||||
|
||||
Introduce
|
||||
|
||||
crm_timeline_projection
|
||||
|
||||
Minimum fields
|
||||
|
||||
* id
|
||||
* organizationId
|
||||
* branchId
|
||||
* customerId
|
||||
* leadId
|
||||
* opportunityId
|
||||
* quotationId
|
||||
* activityId
|
||||
* eventId
|
||||
* entityType
|
||||
* entityId
|
||||
* timelineType
|
||||
* timelineCategory
|
||||
* occurredAt
|
||||
* actorId
|
||||
* actorDisplay
|
||||
* title
|
||||
* summary
|
||||
* icon
|
||||
* color
|
||||
* priority
|
||||
* visibility
|
||||
* metadata
|
||||
* sourceEvent
|
||||
* sourceProjectionVersion
|
||||
* createdAt
|
||||
|
||||
Timeline rows are rebuildable.
|
||||
|
||||
Timeline rows are never source-of-truth.
|
||||
|
||||
---
|
||||
|
||||
## Part 2 — Timeline Builder
|
||||
|
||||
Implement
|
||||
|
||||
TimelineProjectionBuilder
|
||||
|
||||
Responsibilities
|
||||
|
||||
* consume Business Events
|
||||
* transform event
|
||||
* enrich display
|
||||
* resolve references
|
||||
* write projection
|
||||
|
||||
Builder must never mutate source domains.
|
||||
|
||||
---
|
||||
|
||||
## Part 3 — Timeline Event Mapping
|
||||
|
||||
Create mapping from
|
||||
|
||||
Business Event
|
||||
|
||||
↓
|
||||
|
||||
Timeline Item
|
||||
|
||||
Example
|
||||
|
||||
```text
|
||||
activity.completed
|
||||
|
||||
↓
|
||||
|
||||
Completed Site Survey
|
||||
```
|
||||
|
||||
Another
|
||||
|
||||
```text
|
||||
quotation.approved
|
||||
|
||||
↓
|
||||
|
||||
Quotation Approved
|
||||
```
|
||||
|
||||
Every supported Business Event requires mapping.
|
||||
|
||||
---
|
||||
|
||||
## Part 4 — Legacy Timeline Adapter
|
||||
|
||||
Support timeline rebuild using
|
||||
|
||||
Lead Follow-up
|
||||
|
||||
Opportunity Follow-up
|
||||
|
||||
Quotation Follow-up
|
||||
|
||||
Activity
|
||||
|
||||
Approval
|
||||
|
||||
Audit
|
||||
|
||||
No migration.
|
||||
|
||||
Adapters remain read-only.
|
||||
|
||||
---
|
||||
|
||||
## Part 5 — Timeline Projection Consumer
|
||||
|
||||
Activate Timeline consumer.
|
||||
|
||||
Consumer responsibilities
|
||||
|
||||
* consume event
|
||||
* build timeline item
|
||||
* persist projection
|
||||
* checkpoint
|
||||
* retry
|
||||
* rebuild safe
|
||||
|
||||
Consumer uses Projection Runtime.
|
||||
|
||||
---
|
||||
|
||||
## Part 6 — Timeline Categories
|
||||
|
||||
Freeze categories
|
||||
|
||||
Activity
|
||||
|
||||
Communication
|
||||
|
||||
Meeting
|
||||
|
||||
Site Survey
|
||||
|
||||
Approval
|
||||
|
||||
Quotation
|
||||
|
||||
Revision
|
||||
|
||||
Assignment
|
||||
|
||||
Status
|
||||
|
||||
Forecast
|
||||
|
||||
PO
|
||||
|
||||
Customer
|
||||
|
||||
System
|
||||
|
||||
Categories must be configurable using Master Options later.
|
||||
|
||||
---
|
||||
|
||||
## Part 7 — Timeline Rendering Model
|
||||
|
||||
Freeze UI model
|
||||
|
||||
Timeline Item
|
||||
|
||||
contains
|
||||
|
||||
Header
|
||||
|
||||
Timestamp
|
||||
|
||||
Actor
|
||||
|
||||
Business Message
|
||||
|
||||
Reference Links
|
||||
|
||||
Status Badge
|
||||
|
||||
Icon
|
||||
|
||||
Optional Detail
|
||||
|
||||
Attachment Indicator
|
||||
|
||||
No editing inside Timeline.
|
||||
|
||||
---
|
||||
|
||||
## Part 8 — Timeline Visibility
|
||||
|
||||
Timeline follows CRM Authorization.
|
||||
|
||||
Visibility
|
||||
|
||||
Organization
|
||||
|
||||
↓
|
||||
|
||||
Branch
|
||||
|
||||
↓
|
||||
|
||||
Product
|
||||
|
||||
↓
|
||||
|
||||
Pricing
|
||||
|
||||
↓
|
||||
|
||||
Ownership
|
||||
|
||||
↓
|
||||
|
||||
Internal Only
|
||||
|
||||
Timeline never exposes hidden quotation pricing.
|
||||
|
||||
---
|
||||
|
||||
## Part 9 — Timeline Projection Rebuild
|
||||
|
||||
Implement
|
||||
|
||||
Timeline rebuild
|
||||
|
||||
Supports
|
||||
|
||||
Organization
|
||||
|
||||
Customer
|
||||
|
||||
Lead
|
||||
|
||||
Opportunity
|
||||
|
||||
Quotation
|
||||
|
||||
Date Range
|
||||
|
||||
Dry Run
|
||||
|
||||
Reset Existing
|
||||
|
||||
Progress
|
||||
|
||||
Restart
|
||||
|
||||
---
|
||||
|
||||
## Part 10 — Timeline Projection Health
|
||||
|
||||
Track
|
||||
|
||||
Items
|
||||
|
||||
Lag
|
||||
|
||||
Last Event
|
||||
|
||||
Checkpoint
|
||||
|
||||
Rebuild Time
|
||||
|
||||
Health
|
||||
|
||||
Errors
|
||||
|
||||
---
|
||||
|
||||
## Part 11 — Timeline UI Components
|
||||
|
||||
Introduce reusable components
|
||||
|
||||
TimelineList
|
||||
|
||||
TimelineCard
|
||||
|
||||
TimelineItem
|
||||
|
||||
TimelineFilter
|
||||
|
||||
TimelineGroup
|
||||
|
||||
TimelineEmpty
|
||||
|
||||
TimelineLoading
|
||||
|
||||
TimelineSkeleton
|
||||
|
||||
TimelineVirtualList
|
||||
|
||||
Use
|
||||
|
||||
shadcn/ui
|
||||
|
||||
Follow
|
||||
|
||||
layout.md
|
||||
|
||||
Follow
|
||||
|
||||
ui-ux-rules.md
|
||||
|
||||
Apply
|
||||
|
||||
ui-ux-pro-max
|
||||
|
||||
Timeline must feel modern and readable.
|
||||
|
||||
---
|
||||
|
||||
## Part 12 — Workspace Integration
|
||||
|
||||
Embed Timeline into
|
||||
|
||||
Customer Detail
|
||||
|
||||
Lead Detail
|
||||
|
||||
Opportunity Detail
|
||||
|
||||
Quotation Detail
|
||||
|
||||
Activity Detail
|
||||
|
||||
Timeline replaces fragmented history panels over time.
|
||||
|
||||
Existing panels remain until cutover.
|
||||
|
||||
---
|
||||
|
||||
## Part 13 — Filtering
|
||||
|
||||
Support
|
||||
|
||||
Date
|
||||
|
||||
Actor
|
||||
|
||||
Timeline Category
|
||||
|
||||
Entity
|
||||
|
||||
Activity
|
||||
|
||||
Approval
|
||||
|
||||
Quotation
|
||||
|
||||
Customer
|
||||
|
||||
Opportunity
|
||||
|
||||
Lead
|
||||
|
||||
PO
|
||||
|
||||
Attachment
|
||||
|
||||
Search
|
||||
|
||||
Unread
|
||||
|
||||
Internal Only
|
||||
|
||||
---
|
||||
|
||||
## Part 14 — Timeline Grouping
|
||||
|
||||
Support grouping
|
||||
|
||||
Today
|
||||
|
||||
Yesterday
|
||||
|
||||
Earlier This Week
|
||||
|
||||
Last Week
|
||||
|
||||
Earlier This Month
|
||||
|
||||
Older
|
||||
|
||||
Optional
|
||||
|
||||
Group by Entity
|
||||
|
||||
Group by Customer
|
||||
|
||||
Group by Opportunity
|
||||
|
||||
---
|
||||
|
||||
## Part 15 — Timeline Search
|
||||
|
||||
Introduce
|
||||
|
||||
Full text search
|
||||
|
||||
Business Message
|
||||
|
||||
Summary
|
||||
|
||||
Actor
|
||||
|
||||
Customer
|
||||
|
||||
Opportunity
|
||||
|
||||
Quotation
|
||||
|
||||
Activity
|
||||
|
||||
Category
|
||||
|
||||
---
|
||||
|
||||
## Part 16 — Timeline Performance
|
||||
|
||||
Support
|
||||
|
||||
Virtual scrolling
|
||||
|
||||
Incremental loading
|
||||
|
||||
Cursor pagination
|
||||
|
||||
Projection indexes
|
||||
|
||||
Lazy detail expansion
|
||||
|
||||
No N+1 queries.
|
||||
|
||||
---
|
||||
|
||||
## Part 17 — Timeline Delivery Matrix
|
||||
|
||||
Freeze
|
||||
|
||||
Business Event
|
||||
|
||||
↓
|
||||
|
||||
Timeline Item
|
||||
|
||||
↓
|
||||
|
||||
Workspace
|
||||
|
||||
↓
|
||||
|
||||
Consumer
|
||||
|
||||
↓
|
||||
|
||||
Projection
|
||||
|
||||
Every event path documented.
|
||||
|
||||
---
|
||||
|
||||
## Part 18 — Timeline UX Review
|
||||
|
||||
Before merge
|
||||
|
||||
Review
|
||||
|
||||
layout.md
|
||||
|
||||
Review
|
||||
|
||||
ui-ux-rules.md
|
||||
|
||||
Review
|
||||
|
||||
ui-ux-pro-max
|
||||
|
||||
Verify
|
||||
|
||||
Typography
|
||||
|
||||
Spacing
|
||||
|
||||
Hierarchy
|
||||
|
||||
Icons
|
||||
|
||||
Density
|
||||
|
||||
Mobile
|
||||
|
||||
Accessibility
|
||||
|
||||
Keyboard
|
||||
|
||||
Dark Mode
|
||||
|
||||
Loading
|
||||
|
||||
Empty State
|
||||
|
||||
Skeleton
|
||||
|
||||
Sticky Date Header
|
||||
|
||||
Infinite Scroll
|
||||
|
||||
---
|
||||
|
||||
# Deliverables
|
||||
|
||||
1. Timeline Projection Schema
|
||||
|
||||
2. Timeline Builder
|
||||
|
||||
3. Timeline Projection Consumer
|
||||
|
||||
4. Timeline Projection Registry
|
||||
|
||||
5. Event-to-Timeline Mapping
|
||||
|
||||
6. Legacy Timeline Adapter
|
||||
|
||||
7. Timeline Projection Storage
|
||||
|
||||
8. Timeline Rebuild
|
||||
|
||||
9. Timeline Health
|
||||
|
||||
10. Timeline UI Components
|
||||
|
||||
11. Workspace Timeline Integration
|
||||
|
||||
12. Timeline Filtering
|
||||
|
||||
13. Timeline Search
|
||||
|
||||
14. Timeline Grouping
|
||||
|
||||
15. Timeline Delivery Matrix
|
||||
|
||||
16. Timeline UX Review Report
|
||||
|
||||
17. Projection Readiness Report
|
||||
|
||||
---
|
||||
|
||||
# Constraints
|
||||
|
||||
Must preserve
|
||||
|
||||
* Activity
|
||||
* Audit Log
|
||||
* Approval History
|
||||
* Follow-up APIs
|
||||
* Dashboard
|
||||
* Reports
|
||||
* Notifications
|
||||
* Current Detail Pages
|
||||
|
||||
Timeline is additive.
|
||||
|
||||
Do not replace
|
||||
|
||||
Audit Log.
|
||||
|
||||
Do not replace
|
||||
|
||||
Activity.
|
||||
|
||||
Do not replace
|
||||
|
||||
Calendar.
|
||||
|
||||
Do not replace
|
||||
|
||||
Notification.
|
||||
|
||||
Do not replace
|
||||
|
||||
Dashboard.
|
||||
|
||||
No business state mutation.
|
||||
|
||||
No workflow changes.
|
||||
|
||||
No permission changes.
|
||||
|
||||
---
|
||||
|
||||
# Testing
|
||||
|
||||
Projection
|
||||
|
||||
Consumer
|
||||
|
||||
Builder
|
||||
|
||||
Rebuild
|
||||
|
||||
Retry
|
||||
|
||||
Checkpoint
|
||||
|
||||
Timeline UI
|
||||
|
||||
Search
|
||||
|
||||
Grouping
|
||||
|
||||
Filtering
|
||||
|
||||
Pagination
|
||||
|
||||
Virtual List
|
||||
|
||||
Authorization
|
||||
|
||||
Pricing Visibility
|
||||
|
||||
Legacy Adapter
|
||||
|
||||
Workspace Integration
|
||||
|
||||
Dark Mode
|
||||
|
||||
Accessibility
|
||||
|
||||
Performance
|
||||
|
||||
---
|
||||
|
||||
# Acceptance Criteria
|
||||
|
||||
* Timeline Projection is generated entirely from Business Events and approved adapters.
|
||||
* Timeline never mutates source domains.
|
||||
* Timeline can be rebuilt safely.
|
||||
* Timeline respects all CRM authorization rules.
|
||||
* Timeline integrates into Customer, Lead, Opportunity, Quotation, and Activity detail pages without replacing existing history panels.
|
||||
* Legacy Follow-up history appears through adapters without data migration.
|
||||
* Timeline UI follows `layout.md`, `ui-ux-rules.md`, and `ui-ux-pro-max`.
|
||||
* Timeline supports filtering, grouping, search, cursor pagination, and virtual scrolling.
|
||||
* Projection health, rebuild, retry, and checkpoints integrate with the Projection Runtime.
|
||||
* Existing APIs, Dashboard, Notifications, Reports, and Approval flows remain unchanged.
|
||||
|
||||
---
|
||||
|
||||
# Success Criteria
|
||||
|
||||
ALLA OS gains its first production-grade Business Projection.
|
||||
|
||||
Users can understand the complete customer and sales journey from one unified Timeline instead of opening multiple follow-up tabs, audit logs, and approval histories.
|
||||
|
||||
Timeline becomes the canonical business history used by future Calendar, My Day, Manager Workspace, Executive Workspace, Relationship Health, Forecast, and Customer 360 features.
|
||||
|
||||
Ready for:
|
||||
|
||||
# EP.1.6 – Calendar Projection Foundation
|
||||
Reference in New Issue
Block a user