PRD: Phân tích sức khỏe Merchant

Module	Báo cáo	PRD ID	PRD-MAN-002
Trạng thái	Sẵn sàng dev	FEAT	MAN · BANA-1440
Epic	BANA-1337	Plane	BANA-1736
Ngày	2026-07-07	Phiên bản	v1.2
Gói	@nx/sale	URD	MAN
Surface	BO · Vận hành
Phụ trách	Phát Nguyễn

TL;DR

Cho đội vận hành (NEXPANDO & VNPAY) một góc nhìn sức khỏe xuyên merchant trong Back Office: bao nhiêu merchant Active vs Inactive (kèm so sánh với kỳ liền trước), tổng giá trị bán (GMV) và giá trị đơn trung bình (AOV) của nền tảng, GMV biến động theo mốc thời gian tự nhiên của kỳ, và một bảng từng merchant với doanh thu, số đơn và mức hoạt động của mỗi merchant - lọc được về đúng một merchant qua ô tìm kiếm dạng dropdown. Một bộ lọc kỳ calendar-based + tỉnh + merchant điều khiển mọi panel. Đây là màn đi cùng Phân tích tăng trưởng Merchant; màn tăng trưởng trả lời "bao nhiêu và từ đâu", màn này trả lời "đang làm ăn ra sao".

1. Bối cảnh & Vấn đề

Phân tích tăng trưởng Merchant (PRD-MAN-001) cho thấy quy mô và hình dạng cơ sở merchant - số lượng, ngành, tỉnh. Nó không cho thấy các merchant đó có đang giao dịch hay không: ai đang hoạt động, ai đã nguội, bao nhiêu giá trị chảy qua nền tảng, và merchant nào đang đóng góp.

Đội vận hành của chúng ta cần điều đó để điều hướng rollout - phát hiện merchant đang trượt vào trạng thái ngưng, báo cáo GMV nền tảng, và xem bức tranh giao dịch theo từng merchant mà không phải truy vấn thủ công. Tăng tiến này là màn thứ hai thuộc Phân tích Merchant (MAN); nó lo phần sức khỏe vận hành và góc nhìn giao dịch-theo-cửa-hàng.

2. Mục tiêu / Ngoài phạm vi

Mục tiêu

• Thấy KPI sức khỏe trong một cái nhìn: merchant Active, merchant Inactive, tổng GMV, giá trị đơn trung bình (AOV) - mỗi KPI kèm so sánh với kỳ liền trước và nhãn ngữ cảnh "trong kỳ".
• Thấy tỷ lệ Active vs Inactive của cơ sở merchant.
• Thấy xu hướng GMV theo mốc thời gian tự nhiên của kỳ đã chọn (ngày/tuần/tháng tùy độ dài kỳ).
• Thấy một bảng từng merchant - doanh thu, số đơn, mức hoạt động của mỗi merchant - có phân trang, sort, và lọc bắt buộc theo một merchant cụ thể qua ô tìm kiếm dạng dropdown (tìm theo mã hoặc tên merchant).
• Điều khiển mọi panel từ một bộ lọc: kỳ calendar-based (4 preset + khoảng ngày tự chọn), tỉnh, và (tùy chọn) một merchant cụ thể.

Ngoài phạm vi

• Số lượng/độ phủ merchant, phân bố theo ngành / tỉnh - thuộc PRD-MAN-001.
• Báo cáo doanh thu/ca của riêng một merchant (SLS, SHF - surface = client).
• Công thức "điểm sức khỏe" tổng hợp - màn này hiển thị trực tiếp mức hoạt động và giá trị; mô hình chấm điểm, nếu muốn, là một tăng tiến riêng (xem Câu hỏi mở).
• Trang chủ vận hành gộp (chưa dựng).

3. Success Metrics

Chỉ số	Mục tiêu / tín hiệu
Thấy được mức Inactive	Ops biết được trong một kỳ có bao nhiêu merchant Inactive, và mức đó tăng/giảm bao nhiêu % so kỳ trước
Báo cáo GMV	GMV và AOV nền tảng theo kỳ đọc thẳng từ màn, không phải truy vấn thủ công
Tra cứu nhanh một merchant	CSKH/Kinh doanh gõ mã hoặc tên một merchant vào ô tìm kiếm dropdown là ra ngay doanh thu/số đơn/mức hoạt động, không phải dò qua nhiều trang bảng
Nhất quán một bộ lọc	Đổi kỳ, tỉnh hoặc merchant thì đọc lại đồng thời mọi panel; cùng preset mở lại trong cùng kỳ luôn ra cùng khoảng ngày (calendar-based, không rolling)

4. Personas & Tình huống

Persona	Mục tiêu ở tính năng này
Đội vận hành (NEXPANDO & VNPAY)	Theo dõi hoạt động và giá trị của merchant; tìm merchant đang nguội hoặc giá trị cao
Lãnh đạo / đối tác	Báo cáo GMV nền tảng và xu hướng hoạt động/ngưng

Tình huống chính: ops mở Phân tích sức khỏe Merchant, chọn một kỳ và (tùy chọn) một tỉnh; 4 thẻ KPI hiện số Active/Inactive, GMV và AOV kèm mũi tên tăng/giảm so kỳ trước; donut hiện tỷ lệ Active vs Inactive; biểu đồ GMV hiện giá trị theo mốc thời gian tự nhiên của kỳ; và khi cần soi một merchant cụ thể (vd. CSKH nhận yêu cầu hỗ trợ), ops gõ mã hoặc tên merchant vào ô tìm kiếm dropdown - mọi panel thu hẹp về đúng merchant đó.

5. User Stories

• Là ops, tôi muốn số Active vs Inactive cùng GMV và AOV trên một hàng, kèm % thay đổi so kỳ trước, để đánh giá sức khỏe nền tảng trong một cái nhìn.
• Là ops, tôi muốn tỷ lệ Active/Inactive được trực quan hóa bằng donut kèm %, để thấy bao nhiêu phần cơ sở đang nằm im.
• Là ops, tôi muốn xu hướng GMV theo mốc thời gian tự nhiên của kỳ, để thấy giá trị đang tăng hay giảm mà không bị rối mắt với kỳ dài.
• Là ops, tôi muốn một bảng từng merchant về doanh thu và số đơn, để soi bất kỳ merchant nào.
• Là CSKH/Kinh doanh, tôi muốn gõ mã hoặc tên để tìm đúng một merchant qua dropdown, để tra cứu tình hình merchant đó ngay lập tức mà không phải dò từng trang bảng.
• Là ops, tôi muốn một bộ lọc kỳ + tỉnh + merchant điều khiển mọi panel, để cả màn kể một câu chuyện nhất quán.

6. Functional Requirements

Định nghĩa chốt: một merchant có nhãn "Active" trong kỳ = có ít nhất 1 giao dịch hoàn tất trong kỳ đã chọn; ngược lại là "Inactive". Nhãn hiển thị đúng "Active" / "Inactive" theo mockup - không dịch sang "đang hoạt động"/"ngưng". Định nghĩa này áp thống nhất cho KPI (FR-1), donut (FR-2) và cột Trạng thái của bảng (FR-4). Lưu ý: đây là mức độ giao dịch trong kỳ, khác với trạng thái license/vòng đời của merchant (xem tooltip thẻ Tổng ở Phân tích tăng trưởng Merchant) - một merchant còn hạn license vẫn có thể Inactive nếu không phát sinh giao dịch nào trong kỳ.

#	Yêu cầu	Trạng thái	URD ref
FR-1	KPI sức khỏe - 4 thẻ (Active · Inactive · GMV · AOV) kèm so sánh kỳ liền trước + nhãn "trong kỳ"	✅ đã dựng, 🚧 bổ sung nhãn ngày	URD-MAN-004
FR-2	Phân bố Active vs Inactive - donut 2 lát kèm % ở chú giải	✅ đã dựng, 🚧 đổi nhãn	URD-MAN-004
FR-3	Xu hướng GMV - biểu đồ vùng (area), chia mốc tự nhiên theo độ dài kỳ	🚧 cần dựng lại phần chia mốc	URD-MAN-004
FR-4	Bảng từng merchant - 7 cột, phân trang server-side, badge Active/Inactive	✅ đã dựng, 🚧 đổi nhãn	URD-MAN-002
FR-5	Tìm kiếm merchant - searchable dropdown trong bộ lọc chung, theo mã/tên, bắt buộc	🚧 chưa dựng	URD-MAN-002
FR-6	Bộ lọc chung - 4 preset kỳ calendar-based + tỉnh + merchant, reset khi rời màn	🚧 cần rà soát lại phần tính kỳ	URD-MAN-006
FR-7	Phạm vi ops & trạng thái rỗng - xuyên merchant, gác quyền, empty state	✅ đã dựng	URD-MAN-005

FR-1 - KPI sức khỏe (✅ đã dựng, 🚧 bổ sung nhãn ngày)

Bốn thẻ trên một hàng, mỗi thẻ gồm tên chỉ số, giá trị, phần so sánh kỳ trước và một dòng mô tả ngắn:

KPI	Cách tính	Định dạng
Merchant Active	Số merchant có ≥ 1 giao dịch hoàn tất trong kỳ đã chọn	Số nguyên, chữ xanh lá
Merchant Inactive	Số merchant trong cơ sở không có giao dịch nào trong kỳ	Số nguyên, chữ đỏ; thẻ có nền màu cảnh báo (hổ phách) để nổi bật
GMV	Tổng giá trị bán của mọi giao dịch hoàn tất trong kỳ, xuyên merchant	Tiền tệ
AOV	GMV ÷ tổng số đơn trong kỳ	Tiền tệ

• So sánh kỳ liền trước trên cả 4 thẻ: kỳ so sánh là kỳ ngay trước kỳ đã chọn, cùng độ dài; thẻ hiện mũi tên tăng/giảm + % thay đổi (tăng = xanh lá, giảm = đỏ) kèm chú thích "so với kỳ trước".
• Cả 4 thẻ là flow metric - luôn kèm nhãn ngữ cảnh ngày "trong kỳ DD/MM/YYYY - DD/MM/YYYY" ngay dưới phần so sánh kỳ trước, để phân biệt rõ với các thẻ snapshot ở Phân tích tăng trưởng Merchant.
• Giá trị thiếu hiển thị dấu gạch "-"; đang tải hiển thị khung chờ (skeleton).

FR-2 - Phân bố Active vs Inactive (✅ đã dựng, 🚧 đổi nhãn)

• Loại biểu đồ: donut 2 lát - Active (xanh lá) và Inactive (đỏ).
• Chú giải dưới biểu đồ liệt kê 2 nhãn "Active" / "Inactive" kèm tỷ lệ % (1 chữ số thập phân); hai tỷ lệ cộng lại bằng 100%.
• Dùng đúng hai con số Active/Inactive của FR-1 - donut và KPI không bao giờ lệch nhau.

FR-3 - Xu hướng GMV (🚧 cần dựng lại phần chia mốc)

• Loại biểu đồ: biểu đồ vùng (area) (không đổi).

• Trục ngang không còn cố định 1 điểm/ngày - chia theo mốc thời gian tự nhiên của kỳ đã chọn, cùng bảng quy tắc với panel tăng trưởng (PRD-MAN-001 FR-2):

  Kỳ	Cách chia mốc
  Tháng này / Tháng trước	Theo tuần
  Quý này	Theo tháng (đúng 3 điểm)
  Năm nay	Theo tháng, từ tháng 1 đến tháng hiện tại
  Khoảng tự chọn < 31 ngày	Theo ngày
  Khoảng tự chọn 31-90 ngày	Theo tuần
  Khoảng tự chọn > 90 ngày	Theo tháng

• Trục dọc: GMV của mỗi mốc.

• Rê chuột vào một điểm: tooltip hiện khoảng ngày thực của mốc + GMV định dạng tiền tệ.

• Quy tắc chia mốc này thay thế hoàn toàn cách làm cũ (1 điểm/ngày cố định, tới ~365 điểm với "Năm nay") - xem Risks.

FR-4 - Bảng từng merchant (✅ đã dựng, 🚧 đổi nhãn)

Bảng "giao dịch theo merchant", mỗi merchant một dòng, gồm 7 cột:

Cột	Nội dung
Organizer	Tên organizer sở hữu merchant, theo ngôn ngữ người xem
Merchant	Tên merchant, theo ngôn ngữ người xem
Loại hình	Loại hình kinh doanh của merchant (badge)
Số đơn	Số giao dịch hoàn tất của merchant trong kỳ
GMV	Tổng giá trị bán của merchant trong kỳ
Giao dịch gần nhất	Ngày giờ của giao dịch gần nhất
Trạng thái	Active / Inactive - theo định nghĩa chốt ở đầu §6 (badge)

• Phân trang server-side: 25 / 50 / 75 / 100 dòng mỗi trang, mặc định 50; hiển thị tổng số dòng.
• Sort server-side theo cột; không có bộ lọc riêng theo từng cột.
• Bảng tuân theo cùng bộ lọc kỳ + tỉnh + merchant với các panel còn lại.

FR-5 - Tìm kiếm merchant (🚧 chưa dựng, bắt buộc trước khi ra mắt)

• Bộ lọc merchant dạng searchable dropdown, đặt trong thanh bộ lọc chung cạnh kỳ + tỉnh (không phải ô tìm kiếm riêng trên bảng) - gõ để tìm theo mã merchant hoặc tên merchant.
• Chọn 1 merchant → mọi panel (4 thẻ KPI, donut, biểu đồ GMV, bảng) thu hẹp về đúng merchant đó; để trống = tất cả merchant trong phạm vi kỳ + tỉnh đã chọn.
• Xóa lựa chọn → toàn bộ panel trở lại phạm vi đầy đủ.
• Đây là bộ lọc bắt buộc, không phải tính năng phụ có thì tốt: CSKH/Kinh doanh cần tra cứu ngay tình hình một merchant cụ thể (khi có yêu cầu hỗ trợ hoặc theo dõi khách hàng) mà không dò qua nhiều trang bảng.

FR-6 - Bộ lọc chung (🚧 cần rà soát lại phần tính kỳ)

• Dùng chung logic calendar-based với PRD-MAN-001: mỗi kỳ có ranh giới cố định theo lịch, không dùng logic rolling. 4 preset cố định (Tháng này - mặc định · Tháng trước · Quý này · Năm nay; preset đang chạy có ngày bắt đầu cố định theo lịch, kết thúc tại hôm nay do giới hạn dữ liệu) cộng khoảng ngày tự chọn (dùng chung yêu cầu FR-7 🚧 bên PRD-MAN-001).
• Chọn tỉnh single-select mặc định "Tất cả tỉnh thành".
• Chọn merchant qua searchable dropdown (FR-5) - dimension thứ ba của bộ lọc, mặc định để trống (tất cả merchant).
• Mặc định khi vào màn: Tháng này + tất cả tỉnh thành + không chọn merchant; rời màn → bộ lọc reset về mặc định.

FR-7 - Phạm vi ops & trạng thái rỗng (✅ đã dựng)

• Màn xuyên merchant, nằm trong mục "Báo cáo & Phân tích" của Back Office cạnh màn tăng trưởng, gác quyền cho đội vận hành; user của một merchant không bao giờ tới được.
• Không có dữ liệu → empty state từng panel, không phải lỗi; đang tải → placeholder.

Tiêu chí nghiệm thu

• Với một kỳ có giao dịch: 4 thẻ KPI hiện đủ giá trị; số Active + số Inactive = tổng merchant trong phạm vi bộ lọc.
• AOV × tổng số đơn ≈ GMV (sai số làm tròn tiền tệ).
• Mỗi thẻ KPI hiện mũi tên + % so với kỳ ngay trước cùng độ dài, kèm nhãn "trong kỳ DD/MM/YYYY-DD/MM/YYYY"; thẻ "Merchant Inactive" có nền cảnh báo khác hẳn 3 thẻ còn lại.
• % hai lát donut khớp đúng hai con số Active/Inactive của KPI và cộng lại bằng 100%; nhãn hiển thị đúng "Active"/"Inactive".
• Biểu đồ GMV chia mốc đúng theo bảng quy tắc ở FR-3 (vd. Quý này ra đúng 3 điểm theo tháng, Năm nay ra điểm theo tháng chứ không phải theo ngày); tổng GMV mọi mốc bằng GMV ở thẻ KPI.
• Mở lại cùng preset vào hai ngày khác nhau trong cùng kỳ → ngày bắt đầu kỳ không đổi; không có hành vi tính lùi kiểu "30 ngày qua".
• Một merchant có ≥ 1 giao dịch hoàn tất trong kỳ → dòng của nó ở bảng hiện Trạng thái "Active"; không có giao dịch → "Inactive".
• Bảng đủ 7 cột; đổi số dòng/trang từ 50 xuống 25 → bảng tải lại từ trang 1, tổng số dòng không đổi; bấm sort một cột → thứ tự đổi phía server.
• Đổi kỳ, tỉnh hoặc merchant → KPI, donut, biểu đồ GMV và bảng đọc lại đồng thời.
• Rời màn rồi quay lại → bộ lọc về "Tháng này + tất cả tỉnh thành + không chọn merchant".
• Đăng nhập bằng user của một merchant → không mở được màn.
• Kỳ không có giao dịch → các panel hiện empty state, không hiện lỗi.
• (Khi FR-5 dựng xong) Gõ mã hoặc tên một merchant vào ô tìm kiếm dropdown và chọn → 4 thẻ KPI, donut, biểu đồ GMV và bảng đều thu hẹp về đúng merchant đó; xóa lựa chọn → toàn bộ panel trở lại phạm vi đầy đủ.

7. Non-Functional Requirements

Khía cạnh	Yêu cầu
Chỉ đọc	Màn không thay đổi dữ liệu - chỉ tổng hợp lại mức hoạt động và giá trị
Phạm vi & phân quyền	Xuyên merchant, gác quyền cho vai trò ops; không bao giờ tới được bởi user của một merchant
Nhất quán	KPI, donut, biểu đồ GMV, và bảng đều phản ánh cùng một bộ lọc (kỳ + tỉnh + merchant) và cùng định nghĩa "Active"/"Inactive"
Quy mô	Bảng từng merchant phân trang (và tìm kiếm, khi dựng) phía server để vẫn mượt khi merchant tăng
i18n	Nhãn và định dạng tiền song ngữ (EN/VI); tên organizer/merchant theo ngôn ngữ người xem; nhãn "Active"/"Inactive" giữ nguyên tiếng Anh ở cả hai ngôn ngữ theo mockup
Rỗng & đang tải	Không dữ liệu → empty state; đang tải → placeholder; dữ liệu thiếu không làm vỡ màn

8. UX & Flows

Ops dùng màn như thế nào:

Một bộ lọc điều khiển những gì:

Màn thuộc mục "Báo cáo & Phân tích" của Back Office, cạnh Phân tích tăng trưởng Merchant. Nó đã lên menu và chạy được.

9. Data & Domain

Khái niệm	Vai trò trong màn này
Merchant	Đơn vị được đo - có một mức hoạt động (Active / Inactive) và các giao dịch của nó
Mức hoạt động	Active = có ≥ 1 giao dịch hoàn tất trong kỳ đã chọn; ngược lại là Inactive - định nghĩa duy nhất, dùng chung cho KPI, donut và bảng; khác với trạng thái license/vòng đời ở Phân tích tăng trưởng Merchant
GMV	Gross merchandise value - tổng giá trị bán xuyên merchant trong kỳ
AOV	GMV ÷ tổng số đơn trong kỳ
Kỳ so sánh	Kỳ ngay trước kỳ đã chọn, cùng độ dài - nguồn của mũi tên và % thay đổi trên các thẻ KPI
Dòng merchant	Doanh thu, số đơn, giao dịch gần nhất và mức hoạt động của một merchant trong kỳ (giao dịch theo merchant)
Bộ lọc merchant	Searchable dropdown theo mã/tên merchant (FR-5); khi chọn, thu hẹp mọi panel về đúng một merchant

Chỉ ở mức khái niệm - các con số là tổng hợp xuyên merchant trên các giao dịch hoàn tất trong kỳ; mô hình dữ liệu nằm ở tài liệu developer.

10. Dependencies & Assumptions

Phụ thuộc

• Phân tích tăng trưởng Merchant (PRD-MAN-001) - dùng chung bộ lọc và bề mặt phân tích MAN.
• Bán hàng & đơn - giao dịch hoàn tất là nguồn của GMV, AOV, mức hoạt động, và bảng từng merchant.
• Commerce - cơ sở merchant, organizer sở hữu và loại hình của chúng (Commerce).

Giả định

• Ops đã đăng nhập với vai trò vận hành xuyên merchant.
• Merchant thuộc về một organizer và có loại hình, để các cột Organizer / Loại hình của bảng có ý nghĩa.

11. Risks & Open Questions

Rủi ro / câu hỏi	Giảm thiểu / trạng thái
Sức khỏe vận hành là một điểm số hay chỉ là số liệu hoạt động/giá trị thô?	PRD này hiển thị số liệu trực tiếp; mô hình chấm điểm tổng hợp sẽ là một tăng tiến riêng
Bộ lọc tìm merchant (FR-5) chưa dựng, nhưng nay là yêu cầu bắt buộc cho CSKH/Kinh doanh	Chặn ra mắt cho tới khi dropdown tìm merchant hoạt động trên toàn bộ panel - theo dõi sát tiến độ dựng
Logic tính kỳ hiện tại (đã dựng trước bản này) có thể đang tính rolling ngầm	Rà soát tầng tính kỳ trước khi coi FR-6 là calendar-based hoàn chỉnh
Bảng có rất nhiều merchant	Phân trang (và tìm kiếm khi dựng) phía server để vẫn mượt

12. Release Plan & Launch Criteria

Khía cạnh	Kế hoạch
Phase	P2 - chạy thật trong Back Office
Rollout	Mọi user ops; không feature flag
Migration	Không - chỉ tổng hợp lại giao dịch hiện có
Tiêu chí ra mắt	Bộ lọc (kỳ calendar-based + tỉnh + merchant) điều khiển mọi panel, không còn hành vi rolling; 4 thẻ KPI hiện Active / Inactive / GMV / AOV kèm % so kỳ trước và nhãn "trong kỳ"; donut 2 lát kèm % khớp KPI, nhãn đúng "Active"/"Inactive"; biểu đồ GMV chia mốc tự nhiên theo FR-3; bảng 7 cột (badge Active/Inactive) phân trang server-side (25/50/75/100, mặc định 50); màn vào được từ menu BO; không dữ liệu thì hiện empty state. Bộ lọc tìm merchant theo mã/tên (FR-5, dropdown trong thanh bộ lọc chung) bắt buộc và chặn ra mắt - thiết yếu cho CSKH/Kinh doanh
Theo dõi	Tần suất mở báo cáo; độ trễ truy vấn bảng từng merchant

13. FAQ

Khác gì so với Phân tích tăng trưởng Merchant? Tăng trưởng trả lời "bao nhiêu merchant và từ đâu"; Sức khỏe trả lời "hoạt động và giá trị ra sao", tới tận bảng từng merchant.

"Active" nghĩa là gì? Merchant có ít nhất 1 giao dịch hoàn tất trong kỳ đã chọn. Không có giao dịch nào trong kỳ = "Inactive". Một định nghĩa duy nhất cho KPI, donut và bảng - khác với trạng thái license/vòng đời hiển thị ở Phân tích tăng trưởng Merchant.

Có một điểm sức khỏe duy nhất không? Chưa - màn hiển thị trực tiếp mức hoạt động và giá trị. Mô hình chấm điểm có thể bổ sung sau nếu vận hành cần.

Tìm được một merchant cụ thể không? Có - gõ mã hoặc tên vào ô tìm kiếm dropdown trong thanh bộ lọc chung (FR-5); chọn một merchant sẽ thu hẹp mọi panel (không chỉ riêng bảng) về đúng merchant đó. Đây là yêu cầu bắt buộc, hiện chưa dựng - bảng vẫn lật trang và sort được trong lúc chờ dựng.

Đây có phải báo cáo doanh thu của một merchant không? Không - nó xuyên merchant. Doanh thu của riêng merchant là báo cáo SLS phía client.

User của một merchant có mở được màn này không? Không - nó xuyên merchant và gác quyền cho đội vận hành.

References

• URD: Reports - MAN (Phân tích Merchant) · SLS
• Màn anh em: PRD-MAN-001 - Phân tích tăng trưởng Merchant
• Module: Reports - URD · Lộ trình: Phase 2 - Theo tháng
• Developer: @nx/sale - Sales Report