taks-d.2.1

docs/implementation/task-d21-revenue-attribution-governance.md

@@ -0,0 +1,76 @@
+# Task D.2.1: Revenue Attribution and Party Governance
+
+## Scope delivered
+
+- Froze the revenue attribution rules for CRM reporting.
+- Froze project-party reporting authority so dashboard and reports use the same source of truth.
+- Added reusable server-side helpers for grouped revenue analytics by party role.
+- Added ADR governance so future reporting changes require an explicit decision trail.
+
+## Frozen rules
+
+### Revenue owner
+
+- `Revenue Owner = End Customer`
+- Authority: project-party role code `end_customer`
+- Fallback: if no `end_customer` exists, use `billing_customer`
+
+### Relationship revenue dimensions
+
+- `Billing Revenue` = quotation revenue grouped by project-party role `billing_customer`
+- `Contractor Revenue` = quotation revenue grouped by project-party role `contractor`
+- `Consultant Revenue` = quotation revenue grouped by project-party role `consultant`
+
+### Multiple party behavior
+
+- When multiple parties share the same role on a quotation, each party receives full quotation attribution.
+- This is intentional CRM relationship analytics behavior.
+- No proration is applied.
+
+### Reporting authority
+
+- Reporting must use project-party relationships, not raw customer references by themselves.
+- Service logic prefers `crm_quotation_customers`.
+- If quotation parties are missing, service logic falls back to `crm_enquiry_customers` on the linked enquiry.
+- Cancelled quotations are excluded by default from revenue attribution.
+
+## Service layer added
+
+Added server-only reporting helpers under `src/features/crm/reporting/server/`:
+
+- `getRevenueByEndCustomer()`
+- `getRevenueByBillingCustomer()`
+- `getRevenueByContractor()`
+- `getRevenueByConsultant()`
+
+Shared behavior:
+
+- organization scoped
+- supports active quotation/report filters
+- groups revenue by customer
+- counts quotation coverage per attributed customer
+- respects end-customer fallback to billing-customer for revenue-owner attribution
+
+## Governance added
+
+- Added ADR [0010-revenue-attribution-governance.md](/c:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/adr/0010-revenue-attribution-governance.md)
+- This ADR freezes:
+  - revenue owner rule
+  - project-party reporting rule
+  - fallback rule
+  - multiple-party rule
+
+## Remaining risks
+
+- quotations and enquiries still use separate party tables, so analytics currently depends on a precedence rule rather than a unified reporting projection
+- legacy records without synchronized project-party rows may not attribute revenue until backfill or edit/save normalization happens
+- historical analytics still reflects current project-party state, not an effective-dated party snapshot
+
+## Task J readiness
+
+- revenue attribution rules frozen
+- revenue owner frozen
+- project-party reporting rules frozen
+- KPI dimensions frozen for reporting by end customer, billing customer, contractor, and consultant
+- reusable service layer added for dashboard/report reuse
+- ADR added