alla-allaos-fullstack/plans/task-k.1.md

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

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:

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