393 lines
4.0 KiB
Markdown
393 lines
4.0 KiB
Markdown
# 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:
|
|
|
|
```txt
|
|
crm_report_definitions
|
|
```
|
|
|
|
Purpose:
|
|
|
|
Store report metadata.
|
|
|
|
Fields:
|
|
|
|
```txt
|
|
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:
|
|
|
|
```txt
|
|
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:
|
|
|
|
```txt
|
|
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:
|
|
|
|
```txt
|
|
ResolvedReportContext
|
|
```
|
|
|
|
Combines:
|
|
|
|
```txt
|
|
Organization
|
|
|
|
Branch Scope
|
|
|
|
Product Scope
|
|
|
|
Ownership Scope
|
|
|
|
Permissions
|
|
```
|
|
|
|
Must reuse CRM authorization model.
|
|
|
|
---
|
|
|
|
# Scope K1.5 Report Dataset Layer
|
|
|
|
Create:
|
|
|
|
```txt
|
|
src/features/crm/reports/server/
|
|
```
|
|
|
|
Structure:
|
|
|
|
```txt
|
|
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:
|
|
|
|
```txt
|
|
resolveCrmAccess()
|
|
```
|
|
|
|
and
|
|
|
|
```txt
|
|
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:
|
|
|
|
```txt
|
|
CSV
|
|
Excel
|
|
```
|
|
|
|
All reports share same export mechanism.
|
|
|
|
---
|
|
|
|
# Scope K1.8 Report Audit Logging
|
|
|
|
Entity:
|
|
|
|
```txt
|
|
crm_report
|
|
```
|
|
|
|
Actions:
|
|
|
|
```txt
|
|
view
|
|
export_csv
|
|
export_excel
|
|
```
|
|
|
|
Audit payload:
|
|
|
|
```txt
|
|
reportCode
|
|
filters
|
|
userId
|
|
```
|
|
|
|
---
|
|
|
|
# Scope K1.9 Report Navigation
|
|
|
|
Add:
|
|
|
|
```txt
|
|
CRM
|
|
└─ Reports
|
|
```
|
|
|
|
Landing page only.
|
|
|
|
Display:
|
|
|
|
```txt
|
|
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:
|
|
|
|
```txt
|
|
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:
|
|
|
|
```txt
|
|
crm.report.read
|
|
crm.report.export
|
|
```
|
|
|
|
Future reports inherit these permissions.
|
|
|
|
---
|
|
|
|
# Scope K1.12 Documentation
|
|
|
|
Create:
|
|
|
|
```txt
|
|
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:
|
|
|
|
```txt
|
|
K.2
|
|
K.3
|
|
K.4
|
|
K.5
|
|
K.6
|
|
```
|
|
|
|
---
|
|
|
|
# Deliverables
|
|
|
|
1. Report Registry
|
|
2. Report Catalog
|
|
3. Shared Filters
|
|
4. Dataset Layer
|
|
5. Export Foundation
|
|
6. Security Foundation
|
|
7. Report Navigation
|
|
8. Audit Logging
|
|
9. 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:
|
|
|
|
```txt
|
|
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
|
|
```
|