4.0 KiB
Task K.1: CRM Report Foundation
Objective
Create a reusable reporting foundation for all future CRM reports.
This task does not focus on business reports themselves.
Instead it builds:
- report architecture
- report filters
- report security
- report exports
- report datasets
- report metadata registry
for all future report modules.
Background
Completed foundations:
- Customer Ownership (C.1)
- Contact Sharing (C.1)
- Lead / Enquiry Lifecycle (D.3)
- Won / Lost Governance (D.4)
- Revenue Attribution (D.2.1)
- CRM Dashboard KPI (J)
- CRM Authorization (L)
The data model is now stable enough to support reporting.
Scope K1.1 Report Registry
Add:
crm_report_definitions
Purpose:
Store report metadata.
Fields:
id
code
name
description
category
isSystem
isActive
createdAt
updatedAt
Example:
lead_pipeline enquiry_pipeline sales_performance lost_analysis revenue_by_customer
Scope K1.2 Report Categories
Seed:
Pipeline
Sales
Revenue
Customer
Quotation
Approval
Outcome
Executive
Used for:
- report navigation
- report grouping
- future permissions
Scope K1.3 Shared Report Filter Model
Create reusable filter object.
Support:
Date Range
Branch
Product Type
Sales
Customer
Customer Owner
Lead Source
Pipeline Stage
Won/Lost
Lost Reason
Reusable across all reports.
Scope K1.4 Report Query Context
Create:
ResolvedReportContext
Combines:
Organization
Branch Scope
Product Scope
Ownership Scope
Permissions
Must reuse CRM authorization model.
Scope K1.5 Report Dataset Layer
Create:
src/features/crm/reports/server/
Structure:
datasets/
builders/
filters/
exports/
Purpose:
Single source of truth for report queries.
Reports must never query database directly from UI routes.
Scope K1.6 Report Security
All reports must use:
resolveCrmAccess()
and
ResolvedReportContext
Security rules inherited from:
- Task L
- Task L.1
- Task L.2
- Task L.3
- Task L.3.1
Scope K1.7 Report Export Foundation
Create common export service.
Supported:
CSV
Excel
All reports share same export mechanism.
Scope K1.8 Report Audit Logging
Entity:
crm_report
Actions:
view
export_csv
export_excel
Audit payload:
reportCode
filters
userId
Scope K1.9 Report Navigation
Add:
CRM
└─ Reports
Landing page only.
Display:
Pipeline Reports
Sales Reports
Revenue Reports
Customer Reports
Outcome Reports
Approval Reports
No business reports yet.
Only report catalog.
Scope K1.10 Foundation APIs
Add:
GET /api/crm/reports
GET /api/crm/reports/catalog
GET /api/crm/reports/filters
Purpose:
Report discovery.
No heavy report execution yet.
Scope K1.11 Permissions
Add:
crm.report.read
crm.report.export
Future reports inherit these permissions.
Scope K1.12 Documentation
Create:
docs/adr/0017-report-foundation.md
docs/implementation/task-k1-report-foundation.md
Document:
- report architecture
- security model
- dataset model
- export model
Explicit Non-Scope
Do NOT build:
- Lead Report
- Sales Report
- Revenue Report
- Customer Report
- Executive Report
Those belong to:
K.2
K.3
K.4
K.5
K.6
Deliverables
- Report Registry
- Report Catalog
- Shared Filters
- Dataset Layer
- Export Foundation
- Security Foundation
- Report Navigation
- Audit Logging
- ADR 0017
Definition of Done
Task K.1 is complete when:
- Reports menu exists
- Report catalog exists
- Shared filter model exists
- Dataset architecture exists
- Export foundation exists
- Security foundation exists
- Report permissions exist
- Report ADR exists
Result:
CRM Report Center Foundation = READY
Ready for:
K.2 Pipeline Reports
K.3 Outcome Analytics
K.4 Revenue Analytics
K.5 Sales Performance
K.6 Customer Analytics
K.7 Approval Analytics