allagroup/alla-allaos-fullstack
Template
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
bu-frzzess
alla-allaos-fullstack/plans/task-ep.1.5.md
phaichayon 2bc8dd184c task-ep.1.5
2026-07-13 15:03:17 +07:00

879 lines
9.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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 View Git Blame Copy Permalink