alla-allaos-fullstack/docs/implementation/task-d21-revenue-attribution-governance.md

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
• 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