PRD: Phân tích tăng trưởng Merchant

Module	Báo cáo	PRD ID	PRD-MAN-001
Trạng thái	Sẵn sàng dev	FEAT	MAN · BANA-1440
Epic	BANA-1337	Plane	BANA-1707
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 độ phủ xuyên merchant duy nhất trong Back Office: quy mô cơ sở merchant và store (tổng đã đăng ký, mới phát sinh trong kỳ), merchant mới đến ra sao theo mốc thời gian tự nhiên của kỳ đã chọn (chia theo ngành), và merchant phân bố thế nào theo ngành (hộ kinh doanh vs doanh nghiệp) và theo tỉnh (top 5 + nhóm "Khác"). Một bộ lọc kỳ theo lịch (calendar-based, 4 preset + khoảng ngày tự chọn) + tỉnh điều khiển mọi panel.

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

Mỗi merchant đã có báo cáo doanh thu riêng (SLS, surface = client) - nhưng nó trả lời "merchant này đang ra sao", phạm vi một merchant. Đội vận hành của chúng ta có một câu hỏi khác khi onboarding tăng tốc: toàn nền tảng đang tăng trưởng thế nào - có bao nhiêu merchant, đang ở trạng thái gì, merchant mới đến nhanh ra sao, thuộc ngành nào, ở tỉnh nào.

Tới giờ câu trả lời đó chỉ lấy được bằng truy vấn dữ liệu thủ công. Tăng tiến này biến nó thành một màn dành cho ops: một dashboard độ phủ trình bày bức tranh xuyên merchant ở một nơi. Đây là màn đầu trong hai màn thuộc Phân tích Merchant (MAN); màn thứ hai, Phân tích sức khỏe Merchant, lo phần giao dịch-theo-cửa-hàng và sức khỏe vận hành.

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

Mục tiêu

• Thấy quy mô cơ sở merchant và store trong một cái nhìn: tổng số đã đăng ký trên hệ thống và số mới phát sinh trong kỳ, tách riêng cho merchant và store.
• Thấy xu hướng merchant mới 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ỳ), chia theo ngành.
• Thấy phân bố theo ngành, mỗi ngành tách thành hộ kinh doanh (HKD) vs doanh nghiệp (DN).
• Thấy phân bố theo tỉnh - 5 tỉnh đứng đầu cộng một nhóm "Khác" - kèm tỷ trọng % trên tổng.
• Điều khiển mọi panel từ một bộ lọc: kỳ theo lịch (calendar-based, 4 preset + khoảng ngày tự chọn) và tỉnh.

Ngoài phạm vi

• Báo cáo doanh thu/ca của riêng một merchant (SLS, SHF - surface = client).
• Giao dịch-theo-cửa-hàng và sức khỏe vận hành - thuộc PRD-MAN-002.
• Trang chủ vận hành gộp mọi phân tích (chưa dựng).
• Sửa merchant - màn này chỉ đọc; CRUD merchant nằm ở Commerce.

3. Success Metrics

Chỉ số	Mục tiêu / tín hiệu
Tự lấy báo cáo độ phủ	Ops trả lời "merchant onboard theo ngành / tỉnh trong kỳ" mà không cần truy vấn thủ công
Nhất quán một bộ lọc	Đổi kỳ hoặc tỉnh thì đọc lại đồng thời cả bốn panel; không panel nào bị cũ; cùng preset mở lại trong cùng kỳ luôn ra cùng khoảng ngày (calendar-based, không rolling)
Đọc xu hướng nhanh	Tăng trưởng merchant mới nắm được theo mốc thời gian tự nhiên của kỳ, có chia theo ngành
Đọc đúng ý nghĩa số Tổng	Ops không nhầm "Tổng merchant/store" với số đang thực sự hoạt động - tooltip trên thẻ Tổng dẫn rõ sang Sức khỏe merchant
Toàn vẹn phân bố	Mỗi tổng ngành khớp với phần tách HKD + DN; tỷ trọng tỉnh cộng lại bằng 100% (kể cả "Khác")

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 độ phủ nền tảng - số lượng, cơ cấu trạng thái, tăng trưởng đến từ đâu
Lãnh đạo / đối tác	Báo cáo tiến độ onboarding theo ngành và theo vùng

Tình huống chính: ops mở Phân tích tăng trưởng Merchant, chọn Tháng này (mặc định) và (tùy chọn) một tỉnh; snapshot hiện tổng merchant/store đã đăng ký và số mới trong kỳ (kèm nhãn ngày rõ ràng cho từng loại), panel tăng trưởng hiện merchant mới theo mốc thời gian tự nhiên của kỳ, chia theo ngành, và hai panel phân bố hiện ngành nào (HKD vs DN) cùng tỉnh nào đang đóng góp vào cơ sở.

5. User Stories

• Là ops, tôi muốn thấy tổng merchant/store đã đăng ký và số mới trong kỳ trên một hàng, để nắm quy mô và tốc độ onboarding nền tảng trong một cái nhìn.
• Là ops, tôi muốn xu hướng merchant mới chia theo ngành, để thấy không chỉ tăng nhanh ra sao mà còn ở ngành nào.
• Là ops, tôi muốn merchant tách theo ngành thành hộ kinh doanh vs doanh nghiệp, để hiểu cơ cấu khách.
• Là ops, tôi muốn 5 tỉnh đứng đầu (cộng nhóm "Khác") kèm tỷ trọng %, để thấy mức tập trung địa lý.
• Là ops, tôi muốn một bộ lọc kỳ + tỉnh điều khiển mọi panel, để cả màn kể một câu chuyện nhất quán.

6. Functional Requirements

#	Yêu cầu	Trạng thái	URD ref
FR-1	Snapshot - 4 thẻ số: tổng/mới cho merchant và store	🚧 cần dựng lại	URD-MAN-003
FR-2	Xu hướng merchant mới - cột chồng dọc, mốc theo kỳ tự nhiên, chồng theo ngành	🚧 cần dựng lại phần chia mốc	URD-MAN-003
FR-3	Phân bố theo ngành - cột chồng ngang, tách HKD vs DN, sort giảm dần	✅ đã dựng	URD-MAN-001
FR-4	Phân bố theo tỉnh - cột ngang, top 5 + nhóm "Khác", kèm tỷ trọng %	✅ đã dựng	URD-MAN-001
FR-5	Bộ lọc chung - 4 preset kỳ calendar-based + chọn 1 tỉnh, reset khi rời màn	🚧 cần rà soát lại phần tính kỳ	URD-MAN-006
FR-6	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-7	Khoảng ngày tự chọn (từ ngày - đến ngày) bên cạnh preset	🚧 chưa dựng	URD-MAN-006

FR-1 - Snapshot quy mô merchant & store (🚧 cần dựng lại)

• Bốn thẻ số trên một hàng: Tổng merchant · Merchant mới · Tổng store · Store mới. Bốn thẻ này thay thế hoàn toàn ba thẻ trạng thái cũ (Đang hoạt động / Tạm ngưng / Hết hạn) - trạng thái vòng đời merchant không còn hiển thị ở panel này; xem Phân tích sức khỏe Merchant (PRD-MAN-002) để biết merchant nào đang thực sự hoạt động.

• Cách tính, trong phạm vi bộ lọc tỉnh (kỳ chỉ áp dụng cho hai thẻ "mới"):

  Thẻ	Công thức	Loại chỉ số
  Tổng merchant	COUNT(Organization) WHERE deleted_at IS NULL	Snapshot - thời điểm hiện tại
  Merchant mới	COUNT(Organization) WHERE created_at BETWEEN [kỳ đã chọn]	Flow - trong kỳ
  Tổng store	COUNT(Store) WHERE deleted_at IS NULL	Snapshot - thời điểm hiện tại
  Store mới	COUNT(Store) WHERE created_at BETWEEN [kỳ đã chọn], tính độc lập với Merchant mới (một store mới có thể thuộc merchant đã có từ trước)	Flow - trong kỳ

• Nhãn ngữ cảnh ngày (date context label) hiển thị ngay dưới mỗi giá trị: thẻ snapshot (Tổng merchant, Tổng store) hiện "tính đến DD/MM/YYYY" (ngày hiện tại); thẻ flow (Merchant mới, Store mới) hiện "trong kỳ DD/MM/YYYY - DD/MM/YYYY" (đúng ranh giới kỳ đã chọn).

• Tooltip/help text bắt buộc trên hai thẻ Tổng (Tổng merchant, Tổng store): "Tổng merchant/store = tổng số đã đăng ký trên hệ thống, không phân biệt còn hoạt động hay đã ngưng dùng. Muốn xem merchant nào đang thực sự active, tham khảo Sức khỏe merchant." Lý do cần tooltip: số Tổng tính cả merchant/store đã ngưng hoạt động nhưng chưa bị xóa (deleted_at IS NULL), dễ gây hiểu lầm nếu không giải thích.

• Mỗi thẻ có nền màu phân biệt (Tổng = xanh dương, Mới = xanh lá).

• Giá trị thiếu hiển thị dấu gạch "-"; đang tải hiển thị placeholder.

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

• Loại biểu đồ: cột chồng dọc (không đổi).

• Trục ngang không còn chia đều 6 mốc cố định - chia theo mốc thời gian tự nhiên của kỳ đã chọn:

  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 cột, mỗi cột 1 tháng trong quý)
  Năm nay	Theo tháng, từ tháng 1 đến tháng hiện tại (không vẽ tháng tương lai)
  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

  Số cột trên biểu đồ vì vậy không cố định - thay đổi theo độ dài kỳ và bảng quy tắc trên (vd. Quý này luôn ra đúng 3 cột; Tháng này thường ra 4-5 cột tùy số tuần rơi vào tháng).

• Trục dọc: số merchant mới trong mỗi mốc, tính theo ngày merchant gia nhập nền tảng (created_at).

• Mỗi cột chồng theo ngành / loại hình, có chú giải màu theo ngành; tổng merchant mới của mốc hiển thị trên đỉnh cột.

• Rê chuột vào một cột: tooltip hiện khoảng ngày thực của mốc và số merchant mới của từng ngành trong mốc đó.

FR-3 - Phân bố theo ngành (✅ đã dựng)

• Loại biểu đồ: cột chồng ngang, mỗi ngành một hàng, sort giảm dần theo tổng số merchant.
• Mỗi hàng tách hai đoạn: Hộ kinh doanh (HKD) và Doanh nghiệp (DN); số đếm HKD và DN hiển thị ngay dưới tên ngành; tổng của ngành hiển thị bên phải thanh.
• Tổng mỗi ngành luôn bằng HKD + DN. Merchant chưa xác định ngành gom về nhãn dấu gạch "-".
• Tooltip và chú giải phân biệt rõ HKD vs DN.

FR-4 - Phân bố theo tỉnh (✅ đã dựng)

• Loại biểu đồ: cột ngang, hiển thị đúng 5 tỉnh có nhiều merchant nhất (sort giảm dần) cộng một hàng "Khác" gộp toàn bộ tỉnh còn lại.
• Mỗi hàng: tên tỉnh (theo ngôn ngữ người xem) + số merchant + tỷ trọng % làm tròn về số nguyên trên tổng.
• Hàng "Khác" hiển thị màu nhạt hơn để phân biệt với 5 tỉnh đứng đầu.
• Tổng tỷ trọng mọi hàng (kể cả "Khác") bằng 100%.

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

• Bộ lọc kỳ dùng logic calendar-based: mỗi kỳ có ranh giới cố định theo lịch dương. Không còn logic rolling (vd. không tính kiểu "30 ngày qua" lùi từ thời điểm mở màn) - đảm bảo mở lại cùng preset trong cùng kỳ luôn ra cùng khoảng ngày, và so sánh giữa các kỳ không lệch theo giờ truy cập.
• 4 preset cố định: Tháng này (mặc định) · Tháng trước · Quý này · Năm nay, cộng tùy chọn khoảng ngày tự chọn (xem FR-7). Preset của kỳ đang chạy (Tháng này / Quý này / Năm nay) có ngày bắt đầu cố định theo lịch (ngày 1 của tháng/quý/năm); ranh giới kết thúc là hôm nay vì dữ liệu tương lai chưa tồn tại - đây là giới hạn dữ liệu, không phải một cửa sổ rolling.
• Chọn tỉnh single-select, mặc định "Tất cả tỉnh thành"; danh sách tỉnh hiển thị theo ngôn ngữ người xem.
• Mặc định khi vào màn: Tháng này + tất cả tỉnh thành.
• Đổi preset/khoảng ngày hoặc tỉnh → cả bốn panel đọc lại đồng thời.
• Rời màn → bộ lọc reset về mặc định; mỗi lần vào đều bắt đầu sạch.

FR-6 - 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, gác quyền cho đội vận hành; user của một merchant không bao giờ tới được.
• Panel không có dữ liệu hiện empty state riêng của panel đó, không phải lỗi; dữ liệu thiếu một phần không làm vỡ màn.

FR-7 - Khoảng ngày tự chọn (🚧 chưa dựng)

• Bên cạnh 4 preset, ops chọn được một khoảng ngày bất kỳ (từ ngày - đến ngày, hai đầu bao gồm); cả bốn panel phản ứng y hệt như với preset, kể cả quy tắc chia mốc ở FR-2 (dựa theo độ dài khoảng đã chọn: <31 ngày / 31-90 ngày / >90 ngày).
• Khoảng tự chọn cũng dùng logic calendar-based (không tính lùi theo giờ hiện tại) và reset khi rời màn, như FR-5.

Tiêu chí nghiệm thu

• Chọn preset "Tháng trước": snapshot và cả 3 biểu đồ đọc lại; không panel nào còn giữ số của kỳ trước đó.
• Snapshot hiện đủ 4 thẻ: Tổng merchant · Merchant mới · Tổng store · Store mới; thẻ Tổng luôn kèm nhãn "tính đến DD/MM/YYYY", thẻ Mới luôn kèm nhãn "trong kỳ DD/MM/YYYY-DD/MM/YYYY"; một thẻ không có dữ liệu → hiện "-", các thẻ còn lại vẫn hiển thị bình thường.
• Rê/chạm vào biểu tượng tooltip ở thẻ Tổng merchant hoặc Tổng store → hiện đúng nội dung giải thích "không phân biệt hoạt động hay ngưng" kèm liên kết sang Sức khỏe merchant.
• Biểu đồ tăng trưởng chia mốc đúng theo bảng quy tắc ở FR-2 (vd. Quý này luôn ra đúng 3 cột theo tháng; Tháng này ra cột theo tuần); tổng mọi cột bằng tổng merchant mới trong kỳ; tooltip mỗi cột hiện đúng khoảng ngày con của mốc.
• Mở lại cùng preset vào hai ngày khác nhau trong cùng kỳ (vd. "Tháng này" mở ngày 5 rồi ngày 20) → 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".
• Ở panel ngành, với mọi hàng: số HKD + số DN = tổng hiển thị bên phải thanh; các hàng xếp giảm dần theo tổng.
• Ở panel tỉnh: tối đa 6 hàng (5 tỉnh + "Khác"); tổng % các hàng = 100%.
• Chọn một tỉnh ở bộ lọc → cả bốn panel chỉ tính merchant thuộc tỉnh đó.
• Rời màn rồi quay lại → bộ lọc về "Tháng này + tất cả tỉnh thành".
• Đăng nhập bằng user của một merchant → không mở được màn.
• Kỳ không có merchant mới → panel tăng trưởng hiện empty state, không hiện lỗi.

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 cơ sở merchant
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	Mọi panel phản ánh cùng một bộ lọc tại cùng thời điểm
i18n	Nhãn song ngữ (EN/VI); tên tỉnh theo ngôn ngữ người xem
Rỗng & đang tải	Không dữ liệu → empty state cho từng panel; đ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 nằm trong mục "Báo cáo & Phân tích" của Back Office. Bộ lọc được nhớ trong lúc ops làm việc và reset khi rời màn, nên mỗi lần vào đều bắt đầu sạch.

9. Data & Domain

Khái niệm	Vai trò trong màn này
Merchant	Đơn vị được đếm - mang một ngành / loại hình và một tỉnh; trạng thái vòng đời (đang hoạt động / tạm ngưng / hết hạn) không còn hiển thị ở màn này, xem Phân tích sức khỏe Merchant
Ngành / loại hình	Gom merchant cho phần tăng trưởng và phân bố theo ngành; cũng phân biệt hộ kinh doanh vs doanh nghiệp
Tỉnh	Gom merchant cho phân bố địa lý
Kỳ	Khoảng ngày calendar-based (theo preset hoặc khoảng tự chọn) để đo tăng trưởng merchant mới; chia theo mốc tự nhiên (ngày/tuần/tháng tùy độ dài kỳ) trên biểu đồ tăng trưởng - xem FR-2

Chỉ ở mức khái niệm - các con số là tổng hợp xuyên merchant trên cơ sở merchant và ngày onboarding của chúng; mô hình dữ liệu nằm ở tài liệu developer.

10. Dependencies & Assumptions

Phụ thuộc

• Commerce - merchant, trạng thái, và ngành / loại hình của chúng (Commerce).
• Ngày onboarding - thời điểm mỗi merchant gia nhập, để tính xu hướng tăng trưởng.
• Dữ liệu tỉnh thành - để gán nhãn và gom merchant theo địa lý.

Giả định

• Ops đã đăng nhập với vai trò vận hành xuyên merchant.
• Merchant/store có created_at và deleted_at đáng tin cậy, và merchant có ngành / loại hình, để snapshot và các panel phân bố có ý nghĩa.

11. Risks & Open Questions

Rủi ro / câu hỏi	Giảm thiểu / trạng thái
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-5 là calendar-based hoàn chỉnh
Khoảng tự chọn rất dài vẫn ra nhiều cột tháng trên biểu đồ tăng trưởng	Chấp nhận - số cột theo tháng tăng tuyến tính với độ dài kỳ, không giới hạn cứng
"Ngành" phụ thuộc loại hình của từng merchant có được set không	Ngành chưa set rơi về dấu gạch; đảm bảo onboarding bắt loại hình
Panel tỉnh chỉ hiện top 5 + "Khác"	Theo chủ ý; bảng đầy đủ theo tỉnh có thể bổ sung sau nếu cần
Chưa chọn được khoảng ngày tự do (FR-7)	Theo dõi riêng, không chặn các panel hiện có
Bốn thẻ Tổng/Mới thay hoàn toàn 3 thẻ trạng thái cũ - ops quen thuộc với bản cũ cần thời gian thích nghi	Tooltip trên thẻ Tổng và liên kết sang Sức khỏe merchant giúp định hướng lại

12. Release Plan & Launch Criteria

Khía cạnh	Kế hoạch
Phase	P1 - đã có cho ops trong Back Office
Rollout	Mọi user ops; không feature flag
Migration	Không - chỉ tổng hợp lại cơ sở merchant hiện có
Tiêu chí ra mắt	Bộ lọc (4 preset calendar-based + tỉnh) điều khiển cả bốn panel, không còn hành vi rolling; snapshot hiện đủ 4 thẻ Tổng merchant/Merchant mới/Tổng store/Store mới, kèm nhãn snapshot/flow và tooltip giải thích số Tổng; biểu đồ tăng trưởng chia mốc tự nhiên theo FR-2, chồng theo ngành, tổng trên đỉnh cột; panel ngành tách HKD vs DN với tổng khớp; panel tỉnh hiện top 5 + "Khác" kèm % cộng đủ 100%; không dữ liệu thì hiện empty state. Khoảng ngày tự chọn (FR-7) không chặn ra mắt - theo dõi riêng
Theo dõi	Tần suất mở báo cáo; tỷ lệ kết quả rỗng

13. FAQ

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

Vì sao Tổng merchant/Tổng store không khớp số đang hoạt động? Vì Tổng tính cả merchant/store đã ngưng dùng nhưng chưa bị xóa (deleted_at IS NULL) - xem tooltip trên thẻ, hoặc mở Phân tích sức khỏe Merchant để biết merchant nào đang thực sự hoạt động.

Giao dịch-theo-cửa-hàng và sức khỏe merchant nằm ở đâu? Ở màn anh em, Phân tích sức khỏe Merchant (PRD-MAN-002).

Vì sao panel tỉnh chỉ hiện 5 tỉnh? Để bức tranh tập trung vào nơi đóng góp lớn nhất - mọi tỉnh còn lại gom vào một hàng "Khác" kèm tỷ trọng cộng dồn, nên tổng vẫn đủ 100%.

Chọn được khoảng ngày bất kỳ không? Chưa - hiện có 4 preset kỳ; khoảng ngày tự chọn là FR-7, chưa dựng.

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-002 - Phân tích sức khỏe Merchant
• Module: Reports - URD · Lộ trình: Phase 2 - Theo tháng
• Developer: @nx/sale - Sales Report