# 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
```