# 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