PRD: Hồ sơ khách hàng
| Module | Khách hàng (CORE-09) | PRD ID | PRD-CUS-001 |
| Status | Shipped | Owner | Customer squad |
| Date | 2026-03-15 | Version | v1.0 |
| Packages | @nx/identity · @nx/sale · @nx/core | URD | CUS |
TL;DR
Cung cấp cho merchant một danh sách khách hàng dưới thương hiệu của mình và cho phép nhân viên gắn một khách hàng đã biết vào sale order tại lúc thanh toán - để mọi đơn hàng đều có thể quy về một con người, chứ không phải một phiếu ẩn danh. Một khách hàng đã thu thập sau này có thể được nâng cấp thành tài khoản người dùng đăng nhập đầy đủ, biến một khách vãng lai thành một khách hàng quay lại có thể tiếp cận.
1. Context & Problem
Sale order chưa có khái niệm khách hàng: một lần thanh toán không thể quy về một con người đã biết, và không có danh sách khách hàng nào dưới một thương hiệu. Nếu không có bản ghi khách hàng, merchant không thể nhận diện khách mua lại, đối soát đơn hàng theo từng con người, hay xây dựng bất kỳ tính năng tương tác nào (điểm thưởng, phân khúc, chiến dịch) đi kèm sau đó. Đây là phần nền tảng đầu tiên của module Khách hàng - nó giới thiệu bản ghi Customer, bề mặt quản lý xung quanh nó, và liên kết từ một khách hàng đến một sale order, để các giai đoạn sau (điểm thưởng, outreach, phân tích) có một con người để gắn vào.
2. Goals & Non-Goals
Goals
- Giới thiệu entity
Customer(name, phone, email,userId,merchantId) cùng một repository và một service quản lý khách hàng. - Cho phép nhân viên tạo và quản lý khách hàng, và gắn một khách hàng vào sale order tại lúc thanh toán.
- Đặt phạm vi mọi khách hàng theo thương hiệu (merchant/Organization), với soft-delete giữ lại lịch sử.
- Nâng cấp một khách hàng đã thu thập thành tài khoản người dùng đăng nhập đầy đủ (đăng ký khách hàng + plumbing OTP).
Non-Goals
- Phân khúc và nhắm mục tiêu khách hàng (Dự kiến).
- Engine chiến dịch Email / SMS (Dự kiến).
- Điểm thưởng, đổi điểm, và hạng thành viên - thuộc về Loyalty Points.
- Phân tích giá trị vòng đời khách hàng (Dự kiến).
3. Success Metrics
| Metric | Mục tiêu / tín hiệu |
|---|---|
| Quy đơn về khách hàng | Tỷ lệ sale order có gắn khách hàng tăng dần |
| Cô lập theo thương hiệu | Không có lượt đọc khách hàng chéo thương hiệu (nhân viên chỉ thấy thương hiệu của mình) |
| Giữ lại lịch sử | Khách hàng đã soft-delete vẫn giữ các đơn hàng liên kết; không có xóa cứng |
| Nâng cấp | Khách hàng đã thu thập được nâng cấp thành tài khoản đăng nhập (khi được chọn) |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Chủ doanh nghiệp | Giữ một danh sách khách hàng theo phạm vi thương hiệu; quản lý và soft-delete hồ sơ |
| Thu ngân | Tạo một khách hàng ngay tại chỗ và gắn vào đơn hàng lúc thanh toán |
| Khách hàng | Được nâng cấp thành tài khoản đăng nhập để truy cập lịch sử của mình sau này |
Core scenarios: một thu ngân tạo một khách hàng (name + phone + email) tại lúc thanh toán → khách hàng được đặt phạm vi theo thương hiệu và gắn vào sale order → nhân viên quản lý hồ sơ trong thương hiệu của mình → một khách hàng đã thu thập tùy chọn được nâng cấp thành tài khoản người dùng đăng nhập đầy đủ.
5. User Stories
- Là một thu ngân, tôi muốn tạo một khách hàng với name, phone, và email trong một bước, để tôi có thể gắn một con người đã biết vào đơn hàng lúc thanh toán.
- Là một thu ngân, tôi muốn gắn một khách hàng hiện có vào một sale order, để đơn hàng được gắn với con người đó.
- Là một chủ doanh nghiệp, tôi muốn khách hàng được đặt phạm vi theo thương hiệu của mình, để nhân viên chỉ thấy và quản lý khách hàng của chính chúng tôi.
- Là một chủ doanh nghiệp, tôi muốn cập nhật hồ sơ một khách hàng và soft-delete nó, để danh sách luôn sạch trong khi lịch sử vẫn được giữ lại.
- Là một chủ doanh nghiệp, tôi muốn nâng cấp một khách hàng đã thu thập thành tài khoản người dùng đăng nhập, để một khách vãng lai có thể trở thành một khách hàng quay lại có thể tiếp cận.
6. Functional Requirements
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Tạo một khách hàng với name, ít nhất một email và một phone | URD-CUS-001 |
| FR-2 | Đặt phạm vi mọi khách hàng theo thương hiệu (Organization/merchant) | URD-CUS-002 |
| FR-3 | Cập nhật hồ sơ một khách hàng (name, emails, phones, ngày sinh, locale) | URD-CUS-003 |
| FR-4 | Soft-delete một khách hàng, giữ lại bản ghi và các đơn hàng liên kết | URD-CUS-004 |
| FR-5 | Nhân viên chỉ thấy và quản lý khách hàng trong thương hiệu của mình | URD-CUS-005 |
| FR-6 | Gắn một khách hàng vào sale order lúc thanh toán; khách hàng được trả về khi đơn hàng thay đổi | URD-CUS-006 |
| FR-7 | Nâng cấp một khách hàng đã thu thập thành tài khoản người dùng đăng nhập đầy đủ (đăng ký dựa trên OTP) | URD-CUS-007 |
Toàn bộ nội dung yêu cầu và tiêu chí chấp nhận nằm trong URD Khách hàng. PRD này tham chiếu đến chúng thay vì lặp lại.
7. Non-Functional Requirements
| Khía cạnh | Yêu cầu |
|---|---|
| Toàn vẹn dữ liệu | Soft-delete qua common column defs; xóa một khách hàng không bao giờ gỡ bỏ các đơn hàng liên kết |
| Tenancy & authz | Mọi khách hàng được đặt phạm vi theo từng merchant/thương hiệu; nhân viên không thể đọc hay quản lý khách hàng của thương hiệu khác |
| Hiệu năng / quy mô | Tra cứu và gắn khách hàng trong lúc thanh toán không thêm độ trễ cảm nhận được vào luồng bán hàng |
| Mô hình định danh | Một khách hàng là một User với role khách hàng cố định và mặc định không có thông tin đăng nhập |
| i18n | Nhãn hiển thị cho người dùng là song ngữ ({ en, vi }); hồ sơ mang theo một locale |
8. UX & Flows
Các màn hình chính (trong apps/client): bộ chọn/tạo khách hàng tại thanh toán, và bề mặt quản lý khách hàng theo phạm vi thương hiệu. Quản lý khách hàng do @nx/identity phục vụ; việc gắn vào sale order và endpoint nâng cấp nằm trên customer controller của sale.
9. Data & Domain
| Entity | Vai trò |
|---|---|
Customer | Bản ghi khách hàng - name, phone, email, userId, merchantId; common column defs (soft-delete) |
User | Một khách hàng là một User với role khách hàng cố định; nâng cấp thêm thông tin đăng nhập |
SaleOrder | Mang theo một khách hàng đã gắn; khách hàng được trả về khi đơn hàng thay đổi |
CustomerRegistrationService | Nâng cấp một khách hàng đã thu thập thành tài khoản người dùng đăng nhập đầy đủ qua OTP |
Chỉ ở mức khái niệm - schema và các bất biến đầy đủ nằm trong identity domain model.
10. Dependencies & Assumptions
Phụ thuộc vào
- Quản lý người dùng (Quản lý người dùng) - một khách hàng là một User; nâng cấp biến một khách hàng thành tài khoản đăng nhập.
- Commerce (Commerce) - khách hàng được đặt phạm vi theo Organization/merchant.
- Sale (
@nx/sale) - sale order gắn và trả về khách hàng lúc thanh toán.
Giả định
- Một merchant/thương hiệu (Organization) tồn tại để đặt phạm vi cho khách hàng.
- Plumbing gửi OTP sẵn sàng cho đường nâng cấp thành user.
11. Risks & Open Questions
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Rò rỉ khách hàng chéo thương hiệu | Mọi lượt đọc/ghi đều theo phạm vi từng merchant; nhân viên giới hạn trong thương hiệu của mình |
| Quyền sở hữu quản lý khách hàng bị chia giữa các package | Entity ở @nx/core, controller trải trên @nx/sale và @nx/identity; URD chỉ định @nx/identity là chủ dev của CUS - việc hợp nhất được theo dõi riêng |
| Nâng cấp thành user trùng với một tài khoản hiện có | Đăng ký dựa trên OTP bảo vệ việc tạo tài khoản; định nghĩa đường gộp nếu phone/email đã tồn tại |
| Soft-delete so với các đơn hàng tham chiếu khách hàng | Soft-delete giữ lại bản ghi và các đơn hàng liên kết của nó |
12. Release Plan & Launch Criteria
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P1 (nền tảng) - xem danh mục tính năng URD |
| Rollout | Tất cả merchant; không có feature flag |
| Migration | Không (entity Customer mới) |
| Tiêu chí ra mắt | Tạo→gắn→đơn-hàng-mang-khách-hàng được kiểm chứng đầu cuối; cô lập theo thương hiệu được kiểm chứng; nâng cấp thành user được kiểm chứng với đăng ký OTP |
| Giám sát | Lượng tạo khách hàng theo từng thương hiệu, tỷ lệ gắn vào đơn hàng, tỷ lệ nâng cấp thành công |
13. FAQ
Một khách hàng có phải là tài khoản đăng nhập không? Mặc định là không - một khách hàng là một User với role khách hàng cố định và không có thông tin đăng nhập. Nâng cấp thêm khả năng đăng nhập qua đăng ký dựa trên OTP.
Có thể gắn một khách hàng vào đơn hàng sau khi đã bắt đầu thanh toán không? Có - nhân viên gắn một khách hàng vào sale order; khách hàng được trả về khi đơn hàng thay đổi.
Điều gì xảy ra với các đơn hàng khi một khách hàng bị soft-delete? Không có gì - khách hàng rời khỏi danh sách đang hoạt động, nhưng bản ghi và các đơn hàng liên kết của nó vẫn được giữ lại.
PRD này có bao gồm điểm thưởng không? Không - điểm thưởng là một phần riêng (Loyalty Points); phần này chỉ giới thiệu bản ghi khách hàng và việc gắn nó vào đơn hàng.
Khách hàng có được chia sẻ giữa các thương hiệu không? Không - mọi khách hàng được đặt phạm vi theo thương hiệu của nó (Organization); nhân viên chỉ thấy khách hàng của thương hiệu mình.
References
- URD: Khách hàng - Hồ sơ khách hàng
- Liên quan: Loyalty Points · Newsletter Subscribers · Sales Inquiries
- Module: Khách hàng - tổng quan + truy vết
- Developer: @nx/identity · @nx/sale · domain model