taks-d.2.1

plans/task-d.2.1.md

@@ -0,0 +1,370 @@
+# Task D.2.1: Revenue Attribution & Party Governance
+
+## Goal
+
+Freeze Revenue Attribution Rules และ Project Party Reporting Rules สำหรับ ALLA OS CRM
+
+หลัง Task D.2.1 ผ่านแล้ว:
+
+* Dashboard KPI
+* Report Center
+* Export
+* Sales Analytics
+
+ต้องใช้กติกาชุดเดียวกัน
+
+ห้ามแต่ละ module ตีความ Revenue Owner เอง
+
+---
+
+# Business Problem
+
+ตัวอย่าง:
+
+Billing Customer:
+
+```txt
+Italian Thai
+```
+
+Project Parties:
+
+```txt
+PTT            -> End Customer
+Italian Thai   -> Contractor
+AEC            -> Consultant
+ALLA           -> Billing Customer
+```
+
+Quotation:
+
+```txt
+5,000,000 THB
+```
+
+คำถาม:
+
+```txt
+Revenue นี้เป็นของใคร?
+```
+
+ถ้าไม่ Freeze ตอนนี้
+
+Dashboard และ Report จะให้คำตอบไม่ตรงกัน
+
+---
+
+# Scope D2.1.1 Revenue Attribution Rule
+
+## Revenue Owner
+
+Freeze:
+
+```txt
+Revenue Owner = End Customer
+```
+
+Rules:
+
+* ใช้ Project Party role = `end_customer`
+* ถ้าไม่มี end_customer ให้ใช้ billing_customer fallback
+* Dashboard ต้องใช้ Revenue Owner ในการจัดอันดับลูกค้า
+
+Example:
+
+```txt
+Quotation = 5,000,000
+
+Billing Customer:
+Italian Thai
+
+End Customer:
+PTT
+```
+
+Revenue Attribution:
+
+```txt
+PTT = 5,000,000
+```
+
+---
+
+# Scope D2.1.2 Billing Customer Revenue
+
+Freeze:
+
+```txt
+Billing Revenue
+```
+
+Definition:
+
+```txt
+Sum quotation value
+where party role = billing_customer
+```
+
+Purpose:
+
+```txt
+Commercial relationship reporting
+```
+
+Example:
+
+```txt
+Italian Thai
+```
+
+ได้รับ Billing Revenue
+
+---
+
+# Scope D2.1.3 Contractor Revenue
+
+Freeze:
+
+```txt
+Contractor Revenue
+```
+
+Definition:
+
+```txt
+Sum quotation value
+where party role = contractor
+```
+
+Purpose:
+
+```txt
+Contractor relationship reporting
+```
+
+---
+
+# Scope D2.1.4 Consultant Revenue
+
+Freeze:
+
+```txt
+Consultant Revenue
+```
+
+Definition:
+
+```txt
+Sum quotation value
+where party role = consultant
+```
+
+Purpose:
+
+```txt
+Consultant relationship reporting
+```
+
+---
+
+# Scope D2.1.5 Multiple Party Rule
+
+Example:
+
+```txt
+Contractor A
+Contractor B
+```
+
+Rules:
+
+```txt
+Both receive full attribution
+```
+
+Meaning:
+
+```txt
+Revenue = 5,000,000
+
+Contractor A = 5,000,000
+Contractor B = 5,000,000
+```
+
+Reason:
+
+```txt
+CRM relationship analytics
+Not accounting allocation
+```
+
+Do NOT prorate.
+
+---
+
+# Scope D2.1.6 Dashboard Reporting Rule
+
+Dashboard must use:
+
+```txt
+crm_project_parties
+crm_enquiry_customers
+crm_quotation_customers
+```
+
+Dashboard must NOT use:
+
+```txt
+crm_customers only
+```
+
+as revenue source.
+
+Project Party role is the reporting authority.
+
+---
+
+# Scope D2.1.7 KPI Extension
+
+Freeze new KPI dimensions:
+
+## End Customer
+
+```txt
+Top End Customers
+Revenue by End Customer
+Won Revenue by End Customer
+Lost Revenue by End Customer
+```
+
+---
+
+## Contractor
+
+```txt
+Top Contractors
+Revenue by Contractor
+Won Revenue by Contractor
+```
+
+---
+
+## Consultant
+
+```txt
+Top Consultants
+Revenue by Consultant
+Won Revenue by Consultant
+```
+
+---
+
+## Billing Customer
+
+```txt
+Top Billing Customers
+Revenue by Billing Customer
+```
+
+---
+
+# Scope D2.1.8 Service Layer
+
+Create reporting helpers:
+
+```ts
+getRevenueByEndCustomer()
+getRevenueByBillingCustomer()
+getRevenueByContractor()
+getRevenueByConsultant()
+```
+
+Rules:
+
+* organization scoped
+* respect active filters
+* reusable by Dashboard and Reports
+
+No UI required.
+
+---
+
+# Scope D2.1.9 Governance Documentation
+
+Create ADR:
+
+```txt
+Revenue Attribution Governance
+```
+
+Document:
+
+```txt
+Revenue Owner Rule
+Project Party Reporting Rule
+Fallback Rule
+Multiple Party Rule
+```
+
+Update:
+
+```txt
+docs/implementation/technical-debt.md
+```
+
+if any unresolved reporting edge cases are discovered.
+
+---
+
+# Explicit Non-Scope
+
+Do NOT implement:
+
+```txt
+Dashboard UI
+Charts
+Export
+Forecasting
+Commission calculation
+Accounting allocation
+Profitability reporting
+```
+
+This task is governance only.
+
+---
+
+# Output
+
+1. Revenue Attribution Rules Frozen
+2. Revenue Owner Frozen
+3. Project Party Reporting Rules Frozen
+4. KPI Dimensions Frozen
+5. Service Layer Added
+6. ADR Added
+7. Remaining Risks
+8. Task J Readiness
+
+---
+
+# Definition of Done
+
+✔ Revenue Owner frozen
+
+✔ End Customer attribution frozen
+
+✔ Billing attribution frozen
+
+✔ Contractor attribution frozen
+
+✔ Consultant attribution frozen
+
+✔ Multiple party rule frozen
+
+✔ Dashboard reporting rule frozen
+
+✔ KPI dimensions frozen
+
+✔ ADR created
+
+✔ Ready for Task J Dashboard KPI