task-k.1

plans/task-k.1.md

@@ -0,0 +1,392 @@
+# 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
+```