alla-allaos-fullstack/plans/task-d.2.1.md

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:

Italian Thai

Project Parties:

PTT            -> End Customer
Italian Thai   -> Contractor
AEC            -> Consultant
ALLA           -> Billing Customer

Quotation:

5,000,000 THB

คำถาม:

Revenue นี้เป็นของใคร?

ถ้าไม่ Freeze ตอนนี้

Dashboard และ Report จะให้คำตอบไม่ตรงกัน

---

Scope D2.1.1 Revenue Attribution Rule

Revenue Owner

Freeze:

Revenue Owner = End Customer

Rules:

• ใช้ Project Party role = end_customer
• ถ้าไม่มี end_customer ให้ใช้ billing_customer fallback
• Dashboard ต้องใช้ Revenue Owner ในการจัดอันดับลูกค้า

Example:

Quotation = 5,000,000

Billing Customer:
Italian Thai

End Customer:
PTT

Revenue Attribution:

PTT = 5,000,000

---

Scope D2.1.2 Billing Customer Revenue

Freeze:

Billing Revenue

Definition:

Sum quotation value
where party role = billing_customer

Purpose:

Commercial relationship reporting

Example:

Italian Thai

ได้รับ Billing Revenue

---

Scope D2.1.3 Contractor Revenue

Freeze:

Contractor Revenue

Definition:

Sum quotation value
where party role = contractor

Purpose:

Contractor relationship reporting

---

Scope D2.1.4 Consultant Revenue

Freeze:

Consultant Revenue

Definition:

Sum quotation value
where party role = consultant

Purpose:

Consultant relationship reporting

---

Scope D2.1.5 Multiple Party Rule

Example:

Contractor A
Contractor B

Rules:

Both receive full attribution

Meaning:

Revenue = 5,000,000

Contractor A = 5,000,000
Contractor B = 5,000,000

Reason:

CRM relationship analytics
Not accounting allocation

Do NOT prorate.

---

Scope D2.1.6 Dashboard Reporting Rule

Dashboard must use:

crm_project_parties
crm_enquiry_customers
crm_quotation_customers

Dashboard must NOT use:

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

Top End Customers
Revenue by End Customer
Won Revenue by End Customer
Lost Revenue by End Customer

---

Contractor

Top Contractors
Revenue by Contractor
Won Revenue by Contractor

---

Consultant

Top Consultants
Revenue by Consultant
Won Revenue by Consultant

---

Billing Customer

Top Billing Customers
Revenue by Billing Customer

---

Scope D2.1.8 Service Layer

Create reporting helpers:

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:

Revenue Attribution Governance

Document:

Revenue Owner Rule
Project Party Reporting Rule
Fallback Rule
Multiple Party Rule

Update:

docs/implementation/technical-debt.md

if any unresolved reporting edge cases are discovered.

---

Explicit Non-Scope

Do NOT implement:

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