LTV Phase 1

Version: 1.2 Date: 21/04/2026 Author: PO/BA Type: New Feature Complexity: M Module: report analytics, customer revenue, source attribution

File này dùng để làm gì: chốt bức tranh business, phạm vi phase 1, decision, FR và formula cho LTV Phase 1. Nên đọc trước: Executive Summary → A0) Feature Overview → Z) Decision Log → A5) Functional Requirements → A10) Business Formulas.

Changelog

Version	Date	Author	Thay đổi
1.2	21/04/2026	PO/BA	Khóa 4 implementation defaults còn mở: report-role, seed raw source v1, confidence model, refresh strategy hybrid
1.1	21/04/2026	PO/BA	Sửa lại SCR mapping, bổ sung lifecycle contract cho mapping/backfill, nâng chất lượng Decision Log và đồng bộ traceability
1.0	20/04/2026	PO/BA	Initial từ design đã chốt và canonical files

Hướng dẫn đọc (RACI)

Audience	Đọc sections	Trách nhiệm
PO/BA	A0 → Z → A5 → A10	Approve scope, business rule, formula
Sếp / Business lead	Executive Summary → A0 → Z → A3	Chốt định hướng và giá trị business
Tech Lead	A0 → Z → A5 → A10	Chốt hướng triển khai và reuse strategy
FE Dev	A0 → A5	Hiểu report outputs và semantics filter
BE Dev	Z → A5 → A10	Implement metric, snapshot, mapping, backfill
QA	A5 → A10	Derive test matrix và sanity checks

Executive Summary (TL;DR)

DIVA cần một định nghĩa LTV chuẩn để mọi bài toán về quảng cáo, giữ chân khách, chi nhánh và nhóm dịch vụ cùng nhìn chung một con số.

Phase 1 chốt LTV chuẩn theo hướng payment-based, actual revenue, all-time, toàn hệ thống, đồng thời tạo một lớp Nguồn gốc LTV chuẩn ổn định theo khách để phục vụ CAC/LTV theo nguồn.

Scope phase 1 dừng ở mức metric + bảng phân tích, chưa làm attribution đa chạm và chưa hứa dashboard chiến lược đầy đủ.

Milestones

Milestone	Target	Owner	Điều kiện
Canonical files locked	T+0	PO/BA	`EVIDENCE_PACK.md` + `SOURCE_OF_TRUTH.md` complete
PRD approved	T+1 ngày	Business + Tech	Chốt formula + scope
UI/Dev spec generation	T+3 ngày	PO/BA + TL	PRD approved
Implementation plan	T+4 ngày	PO/BA + TL	UI/Dev scope locked

Trạng thái Sign-off

Domain	Người	Status
Business	PO / Sếp	Pending
Tech	Tech Lead	Pending
QA	QA Lead	Pending

Pending Decisions

PD	Question	Options / Assumption	Owner	Deadline	Status	Resolution
PD-001	Ma trận mapping chi tiết cho toàn bộ raw source hiện hữu sẽ do ai duyệt cuối?	Mapping được cấu hình trên hệ thống bởi role `Admin/IT` theo quyền được phân	PO/BA + Admin/IT	20/04/2026	Closed	Chốt: `Admin/IT` là role thao tác cấu hình mapping trên hệ thống
PD-002	Màn report LTV Phase 1 sẽ đặt trong group report nào?	Đặt trong nhóm báo cáo `customer_cycle_report_group`	PO + TL	20/04/2026	Closed	Chốt: `customer_cycle_report_group` (`Chu kỳ khách hàng`)
PD-003	Report role seed mặc định cho tab `LTV Phase 1` là gì?	Reuse role set của `customer_cycle_report_group` hiện có	TL + Admin/IT	21/04/2026	Closed	Chốt: seed `bod`, `hr_leader`, `it_leader` cho v1
PD-004	Raw source nào được dùng làm baseline cho mapping version đầu tiên?	Freeze toàn bộ `master_data(type = customer_source)` active tại thời điểm cutover	PO/BA + Admin/IT	21/04/2026	Closed	Chốt: dùng full active catalog và lưu `raw_source_name_snapshot`
PD-005	Confidence `high/medium/unknown` được chốt thế nào?	Rubric explicit trong PRD + Dev Spec	TL + PO/BA	21/04/2026	Closed	Chốt: direct evidence gần `first_paid` = `high`; 1 raw source rõ, không mâu thuẫn = `medium`; còn lại = `unknown`
PD-006	Refresh incremental nên dùng cron hay event?	Hybrid event-driven + scheduled reconcile + manual rerun	TL	21/04/2026	Closed	Chốt: hybrid

Backlog Phase 2 (Out-of-scope)

#	Tính năng	Lý do defer
1	Multi-touch attribution	Chưa phù hợp phase 1
2	Last-touch / assisted-touch analysis	Không phải canonical metric
3	LTV forecast / predictive scoring	Cần data nền ổn định trước
4	Dashboard chiến lược đầy đủ cho 6 bài toán	Phase 1 chỉ làm metric + bảng phân tích
5	Extended customer value gồm referral downstream	Chưa phải lớp LTV gốc

Z) Decision Log

ID	Category	Quyết định đã khóa	Phương án đã cân nhắc	Trade-off / lý do chọn	Status
DEC-001	Business	`LTV chuẩn` = actual revenue hợp lệ đã thanh toán, sau khi trừ giao dịch đảo chiều	`order total`; cash-in tại thời điểm bán prepaid/top-up	Bỏ khả năng nhìn cash-in sớm để giữ metric sát câu hỏi business “khách thực mang về bao nhiêu tiền”	Locked
DEC-002	Technical	Mốc chuẩn dùng `invoice.paid_at`	`order.created_at`; `order.paid_at`	`invoice.paid_at` bám payment-based semantics và khớp nền code hiện có	Locked
DEC-003	Business	Không tính top-up/prepaid/gói ở thời điểm nạp hoặc mua	Tính cash-in ngay khi bán gói; tính top-up như revenue	Giảm cảm giác “đẹp số” ngắn hạn để tránh thổi phồng LTV trước khi tiêu dùng vào giao dịch hợp lệ	Locked
DEC-004	Business	Ví chính được tính khi dùng để thanh toán; ví khuyến mãi không tính	Tính mọi wallet usage; loại cả ví chính	Chấp nhận phức tạp hơn ở rule payment method để giữ đúng actual revenue hợp lệ	Locked
DEC-005	Business	`LTV chuẩn` là all-time và toàn hệ thống	Rolling 30/90 ngày; theo từng chi nhánh phát sinh	Hy sinh sự linh hoạt của nhiều góc nhìn để có một canonical metric duy nhất cho quản trị	Locked
DEC-006	Business	Doanh thu referral downstream không cộng vào LTV gốc của khách giới thiệu	Gộp downstream revenue vào khách giới thiệu	Giữ định nghĩa sạch, tránh double count; extended value sẽ defer phase sau	Locked
DEC-007	Business	`1 khách = 1 LTV = 1 Nguồn gốc LTV chuẩn = 1 Kênh nguồn chi tiết`	Nhiều nguồn canonical trên 1 khách; weighted attribution	Đơn giản hóa phase 1 để CAC/LTV đọc được ngay, chấp nhận chưa cover multi-touch	Locked
DEC-008	Technical	Tách `Nguồn khách gốc` khỏi `Nhóm nguồn LTV chuẩn`	Dùng raw source hiện tại làm canonical luôn	Thêm một lớp chuẩn hóa để tránh raw source động rewrite lịch sử	Locked
DEC-009	Technical	Mapping raw source -> normalized source phải có versioning	Overwrite trực tiếp 1 bảng mapping hiện hành	Tăng ceremony cấu hình để đổi taxonomy mà không làm vỡ lịch sử snapshot	Locked
DEC-010	Business	Khách cũ được backfill tối đa theo first paid, nhưng không suy diễn quá mức	Chỉ tính khách mới; cố gán 100% từ raw source hiện tại	Chấp nhận tỷ lệ `Chưa xác định` cao hơn để đổi lấy độ tin cậy số liệu	Locked
DEC-011	QA	Không đủ chắc chắn thì vào `Chưa xác định`	Bắt buộc map vào một nhóm; hidden khỏi report	Giữ `Unknown` như output hợp lệ để business thấy chất lượng dữ liệu thật	Locked
DEC-012	Business	Bộ lọc thời gian phase 1 áp vào `cohort first paid`	Cắt revenue theo kỳ; dùng last paid cohort	Giữ đúng nghĩa all-time LTV nhưng vẫn cho phép cohort analysis	Locked
DEC-013	Business	`LTV theo chi nhánh` phase 1 = theo `chi nhánh first paid`	Phân bổ đa chi nhánh; branch gần nhất	Chấp nhận mất góc nhìn allocation để tránh tranh cãi và sai nghĩa phase 1	Locked
DEC-014	Business	`LTV theo nhóm dịch vụ` phase 1 = theo `nhóm dịch vụ khởi đầu`	Phân bổ toàn bộ vòng đời theo nhiều nhóm dịch vụ	Dùng 1 anchor đơn giản, đủ đọc cohort quality mà không over-model	Locked
DEC-015	Scope	Phase 1 chỉ làm `metric + bảng phân tích`	Dashboard chiến lược đầy đủ; attribution đa chạm ngay từ đầu	Ưu tiên nền metric đúng và khả năng go-live sớm thay vì ôm full strategy suite	Locked
DEC-016	Governance	Ma trận mapping raw source được cấu hình trên hệ thống bởi role `Admin/IT`	PO tự chỉnh trực tiếp; giao toàn quyền cho mọi role report	Tăng kiểm soát thay đổi, chấp nhận thêm bước phối hợp với Admin/IT	Locked
DEC-017	UX / IA	Màn report LTV Phase 1 đặt trong `customer_cycle_report_group`	Tạo report group mới; đặt trong nhóm doanh thu	Giữ discoverability theo mental model `Chu kỳ khách hàng`, tránh đọc sai như báo cáo doanh thu kỳ	Locked
DEC-018	Governance	Report role seed v1 của `customer_cycle_ltv_report` reuse role set hiện có của nhóm: `bod`, `hr_leader`, `it_leader`	Seed role mới rộng hơn; chỉ `bod`; chờ config tay sau go-live	Bám pattern migration hiện tại của `customer_cycle_report_group`, giảm rủi ro permission mismatch ở phase 1	Locked
DEC-019	Data governance	Version mapping đầu tiên freeze toàn bộ `master_data(type = customer_source)` active tại thời điểm cutover thành rule v1	Chỉ map các raw source đang có customer dùng; đọc live master data mỗi lần backfill	Freeze toàn bộ catalog active giúp BE/QA/audit cùng nhìn một baseline cố định, tránh “hôm nay thêm raw source mới thì lịch sử đổi nghĩa”	Locked
DEC-020	Data quality	Confidence model v1 = `high`, `medium`, `unknown` theo rubric explicit	Chỉ `high/unknown`; để BE tự suy luận `medium`	Giữ đủ độ phân biệt cho business đọc và QA test, nhưng vẫn đơn giản hơn scoring chi tiết	Locked
DEC-021	Technical	Refresh strategy phase 1 dùng hybrid: event-driven incremental refresh + scheduled reconcile + manual backfill explicit	Chỉ cron; chỉ event-driven	Dùng event-driven để số liệu gần realtime, cron để tự hàn lệch, manual backfill cho lịch sử và rerun có kiểm soát	Locked

A) PRD

A0) Feature Overview

Ý tưởng cốt lõi

LTV Phase 1 tạo ra một chỉ số gốc duy nhất để DIVA biết mỗi khách hàng thực sự đáng giá bao nhiêu tiền, đồng thời gắn chỉ số này với một nguồn gốc chuẩn đủ ổn định để dùng cho CAC/LTV, retention và phân tích chi nhánh.

Feature không cố giải hết mọi bài toán nâng cao ngay trong lần đầu. Mục tiêu của phase 1 là dựng đúng nền metric, dựng đúng lớp attribution chuẩn, và dựng đủ các bảng để business đọc được số mà không cần suy diễn bằng tay.

Kiến trúc tổng thể

text

Business view
  ├─ LTV chuẩn theo khách
  ├─ Nguồn gốc LTV chuẩn
  ├─ Kênh nguồn chi tiết
  └─ Các bảng phân tích phase 1

Data layer
  ├─ customer_revenue / customer_revenue_stats (existing)
  ├─ nguồn khách gốc / master data (existing raw source)
  ├─ mapping raw source -> normalized source (new, versioned)
  ├─ snapshot nguồn gốc LTV theo khách (new)
  └─ backfill + confidence model (new)

Report layer
  ├─ Bảng khách hàng
  ├─ Bảng tổng hợp theo nguồn
  ├─ Bảng tổng hợp theo chi nhánh first paid
  ├─ Bảng tổng hợp theo nhóm dịch vụ khởi đầu
  └─ Bảng kiểm soát chất lượng dữ liệu

Mapping sang tài liệu chi tiết:

Khối	PRD (FR)	UI Spec (SCR)	Dev Spec (Section)
Metric nền LTV	FR-001	SCR-01	C3, C4
Snapshot nguồn gốc	FR-002	SCR-01, SCR-03	C4, C5
Mapping version	FR-003	SCR-02	C4, C5
Backfill lịch sử	FR-004	SCR-01	C6, C7
Report phase 1	FR-005, FR-006, FR-007	SCR-01	C5, C6
Manual override + audit	FR-008	SCR-03	C5, C8

Quyết định chính (tóm tắt theo nhóm)

Nhóm	Quyết định	Ref
LTV core	Payment-based, actual revenue, all-time, system-wide	DEC-001 → DEC-005
Attribution	Tách raw source khỏi normalized source, 1 khách chỉ có 1 canonical source	DEC-007 → DEC-009
Data history	Backfill tối đa nhưng không suy diễn quá mức	DEC-010, DEC-011
View semantics	Time = cohort first paid, branch = first paid branch, service = initial service group	DEC-012 → DEC-014
Delivery scope	Phase 1 chỉ làm metric + bảng phân tích	DEC-015
Governance & placement	Mapping do `Admin/IT` cấu hình; report đặt ở `customer_cycle_report_group`	DEC-016, DEC-017
Access & rollout	Report role seed v1 reuse `bod`, `hr_leader`, `it_leader`	DEC-018
Data baseline	Freeze toàn bộ active `customer_source` vào version v1; confidence rubric 3 mức	DEC-019, DEC-020
Refresh strategy	Event-driven cho increment + cron reconcile + manual backfill explicit	DEC-021

Logic kế toán / nghiệp vụ đặc biệt

Khái niệm	Có tính vào LTV không?	Ghi chú
Thanh toán dịch vụ/sản phẩm hợp lệ	Có	Base revenue event
Ví chính dùng để thanh toán	Có	Chỉ khi thực sự tiêu vào giao dịch hợp lệ
Ví khuyến mãi	Không	Không phản ánh actual revenue hợp lệ
Nạp ví / top-up	Không	Không tính ở thời điểm nạp
Mua thẻ trả trước / prepaid / gói	Không tính ở thời điểm mua	Chỉ tính khi được tiêu vào giao dịch hợp lệ nếu future flow hỗ trợ
Refund / hoàn ví / partial refund	Trừ	Là giao dịch đảo chiều

Bảng FR tóm tắt

FR	Mô tả	Priority	Phase
FR-001	Chuẩn hóa `LTV chuẩn` ở cấp customer	Must	1
FR-002	Snapshot `Nguồn gốc LTV chuẩn` theo khách	Must	1
FR-003	Quản lý mapping raw source -> normalized source có versioning	Must	1
FR-004	Backfill tối đa khách cũ theo first paid + confidence	Must	1
FR-005	Bảng khách hàng LTV	Must	1
FR-006	Bảng tổng hợp quản trị	Must	1
FR-007	Bảng kiểm soát chất lượng dữ liệu	Must	1
FR-008	Chỉnh tay nguồn gốc LTV chuẩn có kiểm soát	Should	1
FR-009	Khóa semantics cho time/branch/service views	Must	1
FR-010	Scope guard phase 1	Must	1

Data Model tóm tắt

Table / Artifact	Loại	Mục đích
`customer_revenue`	Existing	Nền giao dịch doanh thu theo khách
`customer_revenue_stats`	Existing	Aggregate hiện tại theo khách
`ltv_customer_snapshot`	New	Lưu LTV chuẩn và metadata nền theo khách
`ltv_source_mapping_version`	New	Version của rule map raw source
`ltv_source_mapping_rule`	New	Chi tiết raw source -> normalized source
`ltv_customer_source_snapshot`	New	Snapshot nguồn gốc LTV theo khách
`ltv_customer_source_audit`	New	Audit log cho manual override

Impact lên code hiện tại

BE: reuse và extend customer_revenue, customer_revenue_stats, invoice.paid_at logic
DB: thêm bảng mapping version, source snapshot, audit
FE: thêm report phase 1 trong group customer_cycle_report_group của module report analytics
Ops: cần quy trình review ma trận mapping raw source hiện hữu

Timeline

Phase	Nội dung	Target
Phase 1A	Canonical docs + mapping matrix lock	T+1 tuần
Phase 1B	Metric nền + snapshot + backfill	T+1 sprint
Phase 1C	Report tables + QA sanity check	T+1 sprint

A1) Blueprint

Field	Value
Feature	LTV Phase 1
Type	New Feature
Platform	Web Admin (diva-admin)
Module ảnh hưởng	Report analytics, customer revenue, source attribution

A2) Context

As-Is

DIVA đã có doanh thu theo khách và một số report về khách mới/khách cũ/khách quay lại.
Nguồn khách gốc hiện là danh mục động và có thể bị thay đổi trên hồ sơ khách.
Chưa có một chỉ số LTV canonical để mọi bài toán business cùng dùng.
Chưa có một lớp Nguồn gốc LTV chuẩn đủ ổn định để dùng cho CAC/LTV.

To-Be

DIVA có một định nghĩa LTV chuẩn duy nhất ở cấp customer.
Mỗi khách có Nguồn gốc LTV chuẩn và Kênh nguồn chi tiết được snapshot cố định.
Khách cũ được backfill tối đa nhưng không suy diễn quá mức.
Business có thể xem các bảng theo khách, theo nguồn, theo chi nhánh first paid, theo nhóm dịch vụ khởi đầu.

Non-goals / Explicit Out-of-scope

#	Item	Lý do không thuộc scope
1	Multi-touch attribution	Chưa phù hợp phase 1
2	LTV phát sinh trong kỳ	Dễ mâu thuẫn với canonical all-time LTV
3	Phân bổ LTV theo nhiều chi nhánh	Chưa đủ dữ liệu và chưa cần cho phase 1
4	Phân bổ LTV theo toàn bộ nhóm dịch vụ khách đã mua	Chưa phù hợp customer-level metric phase 1
5	Dashboard chiến lược đầy đủ cho 6 bài toán	Scope quá lớn cho phase 1

A3) Goals & Success Metrics

Goal	Metric	Target
Có 1 định nghĩa LTV duy nhất trong hệ thống	Không còn 2 cách hiểu khác nhau giữa marketing/ops/report	100%
Có lớp source chuẩn cho CAC/LTV	Mỗi khách có `Nguồn gốc LTV chuẩn` hoặc `Chưa xác định`	100%
Hạn chế suy diễn lịch sử	Tỷ lệ case backfill “không đủ chắc chắn” được tách riêng	100% case ambiguous
Business tự đọc được dữ liệu	Có report bảng khách hàng + bảng tổng hợp + bảng data quality	100% scope phase 1

A4) Personas

Persona	Vai trò	JTBD	Frequency
Marketing Manager	Quản lý acquisition	Biết nguồn nào đem về khách có giá trị vòng đời tốt hơn	Hàng tuần
CRM / CSKH Lead	Quản lý retention	Đánh giá nhóm khách nào nên ưu tiên giữ chân	Hàng tuần
Regional / Branch Director	Quản lý chi nhánh	Biết cohort first paid của chi nhánh mình có chất lượng tốt không	Hàng tháng
PO/BA	Điều phối chiến lược	Có nền số liệu thống nhất cho các quyết định sau này	Liên tục

A5) Functional Requirements

FR-001 — Chuẩn hóa `LTV chuẩn` ở cấp customer

Ref: DEC-001, DEC-002, DEC-003, DEC-004, DEC-005 | Priority: Must | SCR: SCR-01

AC:

[ ] Hệ thống tính được LTV chuẩn cho từng khách ở cấp customer.
[ ] LTV chuẩn dùng invoice.paid_at làm mốc thời gian chuẩn.
[ ] LTV chuẩn cộng dần theo từng lần thanh toán hợp lệ.
[ ] LTV chuẩn trừ đúng các giao dịch đảo chiều như refund/hoàn ví/partial refund.
[ ] Nạp ví, prepaid, top-up, ví khuyến mãi không được cộng sai vào LTV chuẩn.
[ ] LTV chuẩn là all-time và toàn hệ thống.

FR-002 — Snapshot `Nguồn gốc LTV chuẩn` theo khách

Ref: DEC-007, DEC-008 | Priority: Must | SCR: SCR-01, SCR-03

AC:

[ ] Mỗi khách có đúng 1 Nguồn gốc LTV chuẩn.
[ ] Mỗi khách có đúng 1 Kênh nguồn chi tiết.
[ ] Snapshot được chốt tại thời điểm first paid.
[ ] Snapshot lưu được thời điểm chốt, cách chốt và bằng chứng chốt.
[ ] Raw source thay đổi sau này không làm rewrite snapshot đã chốt.

FR-003 — Mapping raw source -> normalized source có versioning

Ref: DEC-009 | Priority: Must | SCR: SCR-02

AC:

[ ] Hệ thống quản lý được mapping_version.
[ ] Mỗi version có effective_from, effective_to, status.
[ ] Snapshot nguồn gốc của khách phải lưu mapping_version đã dùng.
[ ] Khi business thay đổi taxonomy/rule map thì tạo version mới, không overwrite version cũ.
[ ] Rerun backfill tương lai không được tự remap lịch sử theo version mới.

FR-004 — Backfill tối đa khách cũ theo first paid + confidence

Ref: DEC-010, DEC-011 | Priority: Must | SCR: SCR-01

AC:

[ ] Backfill dùng lần thanh toán hợp lệ đầu tiên làm mốc chuẩn.
[ ] Hệ thống ưu tiên bằng chứng lịch sử/khó sửa trước raw source hiện tại.
[ ] Raw source hiện tại chỉ được dùng khi đủ điều kiện an toàn để suy ra.
[ ] Nếu không đủ chắc chắn thì khách vào Chưa xác định.
[ ] Kết quả backfill lưu được mức độ tin cậy: Cao, Trung bình, Chưa xác định.

FR-005 — Bảng khách hàng LTV

Ref: DEC-015 | Priority: Must | SCR: SCR-01

AC:

[ ] Có danh sách khách hàng kèm LTV chuẩn, first paid, last paid, Nguồn gốc LTV chuẩn, Kênh nguồn chi tiết, trạng thái xác định nguồn.
[ ] Có filter theo cohort first paid.
[ ] Có filter theo chi nhánh first paid.
[ ] Có filter theo Nhóm nguồn LTV chuẩn, Kênh nguồn chi tiết.
[ ] Có filter theo nhóm dịch vụ khởi đầu.
[ ] Có filter theo trạng thái xác định nguồn.

FR-006 — Bảng tổng hợp quản trị

Ref: DEC-012, DEC-013, DEC-014, DEC-015 | Priority: Must | SCR: SCR-01

AC:

[ ] Có bảng/tổng hợp LTV trung bình theo Nhóm nguồn LTV chuẩn.
[ ] Có bảng/tổng hợp LTV trung bình theo Kênh nguồn chi tiết.
[ ] Có bảng/tổng hợp LTV trung bình theo chi nhánh first paid.
[ ] Có bảng/tổng hợp LTV trung bình theo nhóm dịch vụ khởi đầu.
[ ] Không được gắn nhãn mơ hồ kiểu LTV theo chi nhánh nếu thực chất là revenue phát sinh trong kỳ hoặc multi-branch allocation.

FR-007 — Bảng kiểm soát chất lượng dữ liệu

Ref: DEC-011, DEC-015 | Priority: Must | SCR: SCR-01

AC:

[ ] Có chỉ số số khách đã chốt nguồn.
[ ] Có chỉ số số khách backfill được.
[ ] Có chỉ số số khách Chưa xác định.
[ ] Có chỉ số số case chỉnh tay.
[ ] Có danh sách/top raw source chưa map được.

FR-008 — Chỉnh tay `Nguồn gốc LTV chuẩn` có kiểm soát

Ref: DEC-008, DEC-016 | Priority: Should | SCR: SCR-03

AC:

[ ] Chỉ role được phân quyền mới được chỉnh tay.
[ ] Phase 1 cho phép role Admin/IT thao tác cấu hình mapping và chỉnh tay các case đặc biệt trên hệ thống.
[ ] Bắt buộc nhập lý do chỉnh.
[ ] Lưu được audit log: ai sửa, sửa lúc nào, từ gì sang gì, lý do gì.
[ ] Khi chỉnh tay xong, hệ thống phân biệt được source đó là Chỉnh tay.

FR-009 — Khóa semantics cho các view phase 1

Ref: DEC-012, DEC-013, DEC-014 | Priority: Must | SCR: SCR-01

AC:

[ ] Bộ lọc thời gian được diễn giải là cohort theo ngày thanh toán hợp lệ đầu tiên.
[ ] LTV theo chi nhánh được diễn giải là chi nhánh first paid.
[ ] LTV theo nhóm dịch vụ được diễn giải là nhóm dịch vụ khởi đầu.
[ ] UI/help text/tooltip/report label không được dùng wording gây hiểu nhầm với LTV phát sinh trong kỳ hoặc LTV phân bổ đa chiều.

FR-010 — Scope guard phase 1

Ref: DEC-015 | Priority: Must | SCR: N/A

AC:

[ ] Phase 1 không bao gồm multi-touch attribution.
[ ] Phase 1 không bao gồm forecast/predictive LTV.
[ ] Phase 1 không bao gồm dashboard chiến lược đầy đủ cho 6 bài toán.
[ ] Phase 1 không bao gồm extended customer value tính downstream referral revenue.

A5.1) Lifecycle Contracts

LIFECYCLE-001 — Mapping Version

text

Tạo version mới
    │
    ▼
[draft] --Publish version--> [published] --Archive--> [archived]
   │                              │
   └------Clone from published----┘

Ghi chú:
- `published` là read-only
- chỉnh sửa tiếp theo phải tạo draft mới
- publish version mới không tự rewrite snapshot cũ

State definitions

State	Ý nghĩa business	User thấy gì
`draft`	Version đang soạn, chưa ảnh hưởng runtime	Có thể sửa rule, effective date, notes; có CTA `Lưu nháp`, `Publish version`
`published`	Version đang hiệu lực cho khách mới / snapshot mới	Read-only, hiển thị badge `Published`, chỉ cho `Clone thành draft`, `Archive` nếu được phép
`archived`	Version lịch sử để tra cứu, không dùng cho publish mới	Read-only, chỉ phục vụ audit / compare

Transition summary

From	Event	Guard	To	Side effect
none	Tạo version mới	Role `Admin/IT`	`draft`	Clone rule từ version cũ hoặc tạo draft rỗng
`draft`	`Publish version`	Có `effective_from`, version code hợp lệ, các rule bắt buộc đã đủ	`published`	Khoá version hiện tại, version đang publish trước đó được đóng hiệu lực theo config
`published`	`Clone thành draft`	Role `Admin/IT`	`draft` (record mới)	Copy rule sang version mới để tiếp tục chỉnh
`published`	`Archive`	Không còn là version active duy nhất cho luồng cần dùng	`archived`	Chỉ đổi trạng thái version nguồn, không đổi snapshot lịch sử

LIFECYCLE-002 — Backfill Job

text

Tạo job explicit
    │
    ▼
[queued] --> [running] --> [done]
                 │
                 └--------> [failed]

Ghi chú:
- Publish mapping version mới không tự tạo backfill job
- Mọi lần rerun phải do `Admin/IT` kích hoạt explicit

State definitions

State	Ý nghĩa business	User thấy gì
`queued`	Job đã được tạo, chờ worker nhận	Badge `Đang chờ xử lý`, chưa đổi số liệu report
`running`	Job đang tính snapshot / data quality	Badge `Đang xử lý`, hiện job progress/summary gần nhất
`done`	Job chạy xong và đã ghi `summary_payload`	Hiển thị kết quả mới, unknown count và totals
`failed`	Job lỗi, chưa tạo được kết quả cuối	Error banner + CTA `Chạy lại`

Transition summary

From	Event	Guard	To	Side effect
none	`Chạy backfill`	Role `Admin/IT`, chọn scope + mapping version	`queued`	Tạo `ltv_backfill_job` mới
`queued`	Worker nhận job	Lock thành công	`running`	Ghi `started_at`
`running`	Hoàn tất	Không có lỗi blocking	`done`	Upsert snapshot + ghi `summary_payload`, `finished_at`
`running`	Exception / validation fail	Có lỗi runtime	`failed`	Giữ snapshot hợp lệ gần nhất, ghi lỗi để retry
`failed`	`Chạy lại`	Role `Admin/IT` xác nhận rerun	`queued` (job mới)	Không reuse row failed; tạo job mới để audit rõ

A6) Assumptions

ID	Assumption	Owner xác nhận
ASM-001	`customer_revenue` và `customer_revenue_stats` đủ tin để làm nền phase 1	Tech Lead
ASM-002	Business chấp nhận có nhóm `Chưa xác định` thay vì cố gán đủ 100%	PO / Sếp
ASM-003	Nhóm nguồn chuẩn phase 1 đủ để quản trị ở mức source group, kênh chi tiết dùng cho drill-down	PO / Marketing
ASM-004	Role `Admin/IT` là role phù hợp để thao tác cấu hình mapping trên hệ thống trong phase 1	PO / Tech Lead

A6.1) Locked Implementation Defaults

Topic	Default chốt cho phase 1	Ref
Report role seed	`customer_cycle_ltv_report` seed `bod`, `hr_leader`, `it_leader` giống pattern hiện có của `customer_cycle_report_group`	DEC-018
Raw source baseline v1	Freeze toàn bộ `master_data(type = customer_source)` active tại thời điểm cutover vào `mapping_version` đầu tiên	DEC-019
Confidence model	`high` = direct evidence gần `first_paid`; `medium` = đúng 1 raw source hiện tại, không mâu thuẫn; `unknown` = còn lại	DEC-020
Refresh strategy	Event-driven incremental refresh cho payment/refund/override; cron reconcile định kỳ; backfill lịch sử/rerun vẫn là explicit job	DEC-021

A7) Risks

ID	Risk	Impact	Probability	Mitigation
RSK-001	Raw source hiện tại bị sửa nhiều lần, không phản ánh đúng lịch sử khách cũ	Cao	Cao	Không dùng raw source hiện tại như lịch sử chuẩn; áp dụng confidence model
RSK-002	Business hiểu nhầm `LTV theo chi nhánh` thành revenue phát sinh tại chi nhánh	Cao	Trung bình	Khóa semantics, label rõ `chi nhánh first paid`
RSK-003	Mapping rule đổi theo thời gian làm số liệu lịch sử bị méo	Cao	Trung bình	Áp dụng `mapping_version` + snapshot lưu version
RSK-004	Tỷ lệ `Chưa xác định` cao hơn kỳ vọng	Trung bình	Cao	Xem đây là KPI data quality và truyền thông rõ với business
RSK-005	Nhóm report đặt sai IA làm business hiểu LTV như báo cáo doanh thu kỳ	Trung bình	Trung bình	Đặt màn tại `customer_cycle_report_group` và ghi rõ semantics trên label/help text

A8) Metrics (Post-launch)

Metric	Cách đo	Target	Khi nào đo
Tỷ lệ khách có `Nguồn gốc LTV chuẩn` hoặc `Chưa xác định`	Khách có snapshot / tổng khách trong scope	100%	Sau backfill
Tỷ lệ khách `Chưa xác định`	`Unknown / total`	Theo dõi xu hướng giảm dần	Tuần 1, tháng 1
Tỷ lệ case chỉnh tay	`manual overrides / total snapshots`	Càng thấp càng tốt	Hàng tháng
Mức độ dùng report của business	Số lần truy cập / export / filter use	Theo dõi adoption	Sau go-live

A9) Glossary

Thuật ngữ (VI)	Thuật ngữ (EN)	Định nghĩa	Phân biệt với
LTV chuẩn	Base LTV	Tổng actual revenue hợp lệ khách đã thanh toán cho DIVA, sau đảo chiều	≠ doanh thu phát sinh trong kỳ
Nguồn khách gốc	Raw customer source	Nguồn đang lưu động trên hồ sơ khách	≠ Nguồn gốc LTV chuẩn
Nhóm nguồn LTV chuẩn	Normalized LTV source group	Nhóm nguồn cố định dùng cho CAC/LTV	≠ raw source động
Kênh nguồn chi tiết	Detailed source channel	Lớp chi tiết trong mỗi nhóm nguồn chuẩn	≠ multi-touch
Chi nhánh first paid	First paid branch	Chi nhánh phát sinh lần thanh toán hợp lệ đầu tiên	≠ mọi chi nhánh khách từng giao dịch
Nhóm dịch vụ khởi đầu	Initial service group	Nhóm dịch vụ của giao dịch first paid	≠ toàn bộ nhóm dịch vụ trong vòng đời
Chưa xác định	Unknown	Không đủ chắc chắn để gán nguồn gốc LTV chuẩn	≠ lỗi dữ liệu hệ thống

RACI

Deliverable	PO	TL	Admin/IT	FE Dev	BE Dev	QA
PRD (file này)	A	C	I	I	I	I
Mapping matrix raw source	C	I	A	I	I	I
UI Spec	C	C	I	R	I	I
Dev Spec	I	A	I	C	R	I
QA Test Plan	C	I	I	I	I	R

R = Responsible, A = Accountable, C = Consulted, I = Informed

A10) Business Formulas

FORMULA-001: Base LTV

Mô tả: Tổng actual revenue hợp lệ mà một khách đã thanh toán cho DIVA từ first paid đến hiện tại, sau khi trừ giao dịch đảo chiều.
Công thức: ltv = sum(valid_payment_amount) - sum(reverse_amount)
Biến số:
- valid_payment_amount: giá trị thanh toán hợp lệ của khách trên từng invoice/payment event
- reverse_amount: refund, hoàn ví, partial refund hoặc adjustment làm mất hiệu lực doanh thu đã ghi nhận
Đơn vị: VND
Ví dụ: Khách đã thanh toán 5.000.000 + 3.000.000 + 10.000.000, sau đó refund 2.000.000 → LTV = 18.000.000 - 2.000.000 = 16.000.000
Edge cases:
- top-up / nạp ví / mua prepaid nhưng chưa tiêu vào giao dịch hợp lệ → không cộng
- ví khuyến mãi → không cộng
- thanh toán nhiều lần cho cùng một đơn → cộng dần theo từng lần thanh toán hợp lệ

FORMULA-002: First Paid Date

Mô tả: Ngày thanh toán hợp lệ đầu tiên của khách, dùng làm mốc cohort và snapshot attribution.
Công thức: first_paid_at = min(valid_invoice.paid_at)
Biến số:
- valid_invoice.paid_at: thời điểm thanh toán hợp lệ đầu tiên theo rule của phase 1
Đơn vị: Datetime
Ví dụ: Khách có các lần thanh toán hợp lệ vào 05/03/2025, 19/03/2025, 04/04/2025 → first_paid_at = 05/03/2025
Edge cases:
- invoice tạo trước nhưng thanh toán sau → dùng paid_at, không dùng created_at
- nếu không có payment hợp lệ → khách ngoài scope phase 1

FORMULA-003: Average LTV By Source Group

Mô tả: LTV trung bình của nhóm khách thuộc cùng Nhóm nguồn LTV chuẩn.
Công thức: avg_ltv_by_source = sum(customer_ltv) / count(customers_in_group)
Biến số:
- customer_ltv: FORMULA-001
- customers_in_group: tập khách có cùng Nhóm nguồn LTV chuẩn
Đơn vị: VND / khách
Ví dụ: Nhóm Quảng cáo trả phí có 3 khách với LTV 8.000.000, 12.000.000, 10.000.000 → avg = 30.000.000 / 3 = 10.000.000
Edge cases:
- nếu nhóm không có khách → hiển thị —
- Chưa xác định vẫn là một nhóm hợp lệ và phải được tính riêng

FORMULA-004: Cohort Filter Semantics

Mô tả: Bộ lọc thời gian của phase 1 áp vào cohort khách theo first_paid_at, không cắt phần doanh thu all-time của LTV.
Công thức: cohort_match = first_paid_at in selected_period
Biến số:
- first_paid_at: FORMULA-002
- selected_period: khoảng thời gian user chọn
Đơn vị: Boolean filter
Ví dụ: User chọn tháng 03/2025. Khách A first paid ngày 10/03/2025 và hiện có LTV all-time 18.000.000 → khách A thuộc cohort tháng 03/2025 và report vẫn hiển thị đủ 18.000.000, không chỉ doanh thu trong tháng 03/2025.
Edge cases:
- khách first paid ngoài kỳ lọc nhưng có phát sinh doanh thu trong kỳ → không nằm trong cohort phase 1
- semantics này phải được thể hiện rõ trên UI/report labels

A11) Traceability

Decision / Truth	Covered by
Payment-based canonical LTV	FR-001, FORMULA-001, FORMULA-002
1 khách = 1 canonical source	FR-002, FR-003
Backfill tối đa nhưng không suy diễn quá mức	FR-004
Mapping lifecycle / publish safety	FR-003, LIFECYCLE-001
Backfill orchestration / rerun explicit	FR-004, LIFECYCLE-002
Report role seed / rollout	DEC-018, A6.1
Raw source seed baseline + confidence rubric	DEC-019, DEC-020, A6.1
Hybrid refresh strategy	DEC-021, A6.1
Phase 1 chỉ là metric + bảng phân tích	FR-005, FR-006, FR-007, FR-010
Time/branch/service semantics	FR-006, FR-009, FORMULA-004

LTV Phase 1 ​

Changelog ​

Hướng dẫn đọc (RACI) ​

Executive Summary (TL;DR) ​

Milestones ​

Trạng thái Sign-off ​

Pending Decisions ​

Backlog Phase 2 (Out-of-scope) ​

Z) Decision Log ​

A) PRD ​

A0) Feature Overview ​

Ý tưởng cốt lõi ​

Kiến trúc tổng thể ​

Quyết định chính (tóm tắt theo nhóm) ​

Logic kế toán / nghiệp vụ đặc biệt ​

Bảng FR tóm tắt ​

Data Model tóm tắt ​

Impact lên code hiện tại ​

Timeline ​

A1) Blueprint ​

A2) Context ​

As-Is ​

To-Be ​

Non-goals / Explicit Out-of-scope ​

A3) Goals & Success Metrics ​

A4) Personas ​

A5) Functional Requirements ​

FR-001 — Chuẩn hóa LTV chuẩn ở cấp customer ​

FR-002 — Snapshot Nguồn gốc LTV chuẩn theo khách ​

FR-003 — Mapping raw source -> normalized source có versioning ​

FR-004 — Backfill tối đa khách cũ theo first paid + confidence ​

FR-005 — Bảng khách hàng LTV ​

FR-006 — Bảng tổng hợp quản trị ​

FR-007 — Bảng kiểm soát chất lượng dữ liệu ​

FR-008 — Chỉnh tay Nguồn gốc LTV chuẩn có kiểm soát ​

FR-009 — Khóa semantics cho các view phase 1 ​

FR-010 — Scope guard phase 1 ​

A5.1) Lifecycle Contracts ​

LIFECYCLE-001 — Mapping Version ​

LIFECYCLE-002 — Backfill Job ​

A6) Assumptions ​

A6.1) Locked Implementation Defaults ​

A7) Risks ​

A8) Metrics (Post-launch) ​

A9) Glossary ​

RACI ​

A10) Business Formulas ​

FORMULA-001: Base LTV ​

FORMULA-002: First Paid Date ​

FORMULA-003: Average LTV By Source Group ​

FORMULA-004: Cohort Filter Semantics ​

A11) Traceability ​

LTV Phase 1

Changelog

Hướng dẫn đọc (RACI)

Executive Summary (TL;DR)

Milestones

Trạng thái Sign-off

Pending Decisions

Backlog Phase 2 (Out-of-scope)

Z) Decision Log

A) PRD

A0) Feature Overview

Ý tưởng cốt lõi

Kiến trúc tổng thể

Quyết định chính (tóm tắt theo nhóm)

Logic kế toán / nghiệp vụ đặc biệt

Bảng FR tóm tắt

Data Model tóm tắt

Impact lên code hiện tại

Timeline

A1) Blueprint

A2) Context

As-Is

To-Be

Non-goals / Explicit Out-of-scope

A3) Goals & Success Metrics

A4) Personas

A5) Functional Requirements

FR-001 — Chuẩn hóa `LTV chuẩn` ở cấp customer

FR-002 — Snapshot `Nguồn gốc LTV chuẩn` theo khách

FR-003 — Mapping raw source -> normalized source có versioning

FR-004 — Backfill tối đa khách cũ theo first paid + confidence

FR-005 — Bảng khách hàng LTV

FR-006 — Bảng tổng hợp quản trị

FR-007 — Bảng kiểm soát chất lượng dữ liệu

FR-008 — Chỉnh tay `Nguồn gốc LTV chuẩn` có kiểm soát

FR-009 — Khóa semantics cho các view phase 1

FR-010 — Scope guard phase 1

A5.1) Lifecycle Contracts

LIFECYCLE-001 — Mapping Version

LIFECYCLE-002 — Backfill Job

A6) Assumptions

A6.1) Locked Implementation Defaults

A7) Risks

A8) Metrics (Post-launch)

A9) Glossary

RACI

A10) Business Formulas

FORMULA-001: Base LTV

FORMULA-002: First Paid Date

FORMULA-003: Average LTV By Source Group

FORMULA-004: Cohort Filter Semantics

A11) Traceability