# 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