77 lines
2.9 KiB
Markdown
77 lines
2.9 KiB
Markdown
# 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
|