Appearance
EVIDENCE PACK — LTV Phase 1
Version: 1.0
Date: 20/04/2026
Author: PO/BA
Purpose: Bằng chứng đối chiếu code/screen/config trước khi khóa Solution Lock và sinh PRD
File này dùng để làm gì: gom bằng chứng từ codebase và tài liệu design đã chốt để tránh tự suy diễn solution cho
LTV Phase 1. Nên đọc trước:Stakeholder Ask→Current DB / Config Facts→Reuse Candidates.
1) Stakeholder Ask
| Ask | Business reason | Priority |
|---|---|---|
Chuẩn hóa chỉ số LTV cho 1 khách hàng | Có nền số liệu chung cho CAC/LTV, retention, chi nhánh, nhóm dịch vụ | Must |
Chốt cách gắn Nguồn gốc LTV chuẩn cho từng khách | Đọc đúng hiệu quả nguồn khách, không bị raw source động làm vỡ lịch sử | Must |
| Backfill tối đa cho khách cũ | Sếp cần nhìn bức tranh lịch sử, không chỉ khách mới sau ngày bật tính năng | Must |
| Có bảng phân tích để business tự đọc | Phase 1 dừng ở mức metric + bảng phân tích, chưa cần dashboard chiến lược | Must |
| Không suy diễn quá mức khi dữ liệu thiếu rõ | Giữ độ tin cậy của số liệu, chấp nhận Chưa xác định | Must |
2) Existing UI Layout
| SCR / Screen | Current component / route | Layout summary | Screenshot / code ref |
|---|---|---|---|
| Report shell hiện có | diva-admin/src/modules/report/pages/Reports.tsx và các pages trong src/modules/report/pages | Module report đang theo pattern filter + table/cards + export, phù hợp để thêm report analytics mới | Codebase discovery |
| Customer Cycle Report | diva-admin/src/modules/report/pages/CustomerCycleReport.tsx | Có shell tab report và pattern split theo nhiều góc nhìn (Tổng quan, Chu kỳ mua hàng, Chu kỳ khách hàng) | CustomerCycleReport.tsx |
| Rank / Customer Revenue report | diva-admin/src/modules/report/components/rank/CustomerRevenueReportTable.tsx | Đã có pattern bảng khách hàng + pagination + export client-side | CustomerRevenueReportTable.tsx |
| HTML brief cho sếp | docs/guides/ltv-phase1-proposal.html | Tài liệu business-facing để chốt phương án và giải thích scope phase 1 | ltv-phase1-proposal.html |
3) As-Is UI Inventory
| SCR | Section / Tab | Current fields / columns / CTA | Order | Notes |
|---|---|---|---|---|
| LTV Report | Chưa có màn chuyên biệt | Chưa có danh sách khách theo LTV, chưa có bảng tổng hợp LTV theo nguồn/chi nhánh/dịch vụ | N/A | Đây là feature mới |
| Customer source maintenance | Master data nguồn khách | Danh mục nguồn khách đang là cấu hình động, dùng cho nhập liệu và filter | N/A | Không phải canonical source cho LTV |
4) Current DB / Config / Master Data Facts
| Area | Current fact | Ref | Keep / Extend / Replace |
|---|---|---|---|
| Customer revenue | Đã có customer_revenue để ghi nhận doanh thu theo khách, có action type cho payment/refund | diva-backend/pkg/store/customer_revenue.go | Keep + Extend |
| Aggregation | Đã có materialized view customer_revenue_stats tổng hợp total_sales, total_revenue, total_debt theo customer_id | 1706669141375_customer_revenue_stats/up.sql | Keep + Extend |
| First paid logic | Codebase đã có dấu hiệu dùng invoice.paid_at làm mốc order đầu tiên | diva-backend/pkg/store/kpi_metric.go | Keep |
| Customer source | ecommerce_user.customer_source đang là mảng raw source trên hồ sơ khách | diva-backend/pkg/store/ecommerce_user.go | Keep as raw source |
| Source dashboard | Dashboard source hiện đọc trực tiếp từ master_data + ecommerce_user.customer_source | 1695093908449_run_sql_migration/up.sql | Keep for ops, not for LTV canonical |
| Refund logic | Có refund_wallet, refund_cash ở lớp customer revenue | customer_revenue.go | Keep |
| Source history | Chưa tìm thấy bằng chứng có bảng lịch sử customer_source theo thời gian | Codebase discovery | Gap to respect |
5) Reuse Candidates
| Candidate | Current asset | Classification | Delta needed |
|---|---|---|---|
| Nền doanh thu theo khách | customer_revenue + customer_revenue_stats | 🔧 Extend | Thêm lớp chuẩn hóa đúng business rule của LTV Phase 1 |
| Mốc first paid | GetFirstOrderAt dùng invoice.paid_at | ✅ Reuse | Dùng cùng nguyên tắc cho LTV |
| Report shell FE | Các report table/filter/pagination/export hiện có trong diva-admin/src/modules/report | 🔧 Extend | Dựng report LTV theo pattern cũ |
| Raw source master data | customer_source trên ecommerce_user + master data | ✅ Reuse | Chỉ dùng như raw input, không dùng trực tiếp làm canonical |
| Snapshot nguồn gốc LTV | Chưa có | 🆕 Build mới | Cần storage + audit + manual override flow |
| Mapping version | Chưa có | 🆕 Build mới | Cần versioning để khóa logic map theo thời gian |
6) Affected Screens / Routes / Files
| Type | Item | Why affected |
|---|---|---|
| FE module | diva-admin/src/modules/report/* | Cần thêm report LTV Phase 1 |
| FE component | Report filter / table patterns | Reuse pattern cho customer-level analytics |
| BE store | customer_revenue.go, kpi_metric.go | Là nền logic doanh thu theo khách và first paid |
| DB | customer_revenue_stats và bảng mới cho snapshot/mapping | Cần làm lớp canonical cho LTV/source |
| Master data | customer_source | Cần map từ raw source sang normalized source |
| Docs | docs/superpowers/specs/2026-04-20-ltv-phase1-design.md | Là design intent đã chốt |
7) Risks Of Speculative Design
| Risk | What could be wrongly assumed | How Evidence Pack prevents it |
|---|---|---|
| Dùng raw source hiện tại làm lịch sử chuẩn | Sẽ rewrite lịch sử khách cũ khi user sửa hồ sơ | Ghi rõ codebase chưa chứng minh có source history |
Gọi tất cả view là LTV theo ... | Dễ nhầm giữa all-time LTV và revenue phát sinh trong kỳ | Khóa semantics ngay từ design/PRD |
| Phân bổ LTV toàn vòng đời cho nhiều nhóm dịch vụ | Sai nghĩa customer-level metric | Chốt phase 1 chỉ dùng nhóm dịch vụ khởi đầu |
| Remap source tùy ý theo thời gian | Số liệu giữa các tháng sẽ không so sánh được | Bắt buộc mapping_version + snapshot lưu version |