PRD: Quản lý khách hàng
| Module | Quản lý Người dùng (CORE-01) | PRD ID | PRD-CUS-001 |
| Status | In-progress | Owner | Identity squad |
| Date | 2026-03-15 | Version | v0.1 |
| Packages | @nx/identity · @nx/sale · @nx/core | URD | CUS |
TL;DR
Mang đến cho merchant một Customer hạng nhất để sale order gắn vào, cùng một đường nâng cấp khách hàng được ghi nhận lúc bán thành tài khoản user đầy đủ mang role Customer. Kết quả: đơn hàng ghi nhận được khách là ai, và người đứng sau đơn có thể trở thành user đã xác thực, gắn với organization, mà không sinh ra danh tính trùng lặp.
1. Bối cảnh & Vấn đề
Sale order cần một khách hàng thực để gắn vào. Trước đợt này chưa có thực thể Customer do một organization sở hữu, nên đơn hàng không thể ghi nhận khách là ai, và một khách hàng được ghi nhận tại điểm bán không bao giờ trở thành user đã xác thực được. Merchant mất đi mối liên kết giữa đơn hàng và người đứng sau nó, và cùng một khách hàng có thể bị nhập lại qua nhiều lần bán mà không có danh tính dùng chung.
Đợt này giới thiệu một thực thể Customer được tập trung trong @nx/core, đấu nối quản lý khách hàng vào package sale cho sale order, và thêm một đường registration trong identity để nâng cấp một khách hàng cấp sale đang tồn tại thành tài khoản user đầy đủ mang role Customer - được bảo vệ bằng kiểm tra trùng identifier để cùng một email/phone/username không bao giờ bị chiếm hai lần. Nó hiện thực vùng tính năng CUS được định nghĩa trong URD Quản lý Người dùng.
2. Mục tiêu & Không phải mục tiêu
Mục tiêu
- Một thực thể
Customer(model + schema + repository) cho khách hàng gắn với organization, dùng lại xuyên suốtsalevàidentity. - CRUD khách hàng theo phạm vi sale order trong package
sale, kèm việc gắn khách hàng vào mộtSaleOrder. - Nâng cấp một khách hàng cấp sale thành tài khoản user đầy đủ mang role Customer, qua một
CustomerRegistrationServicechuyên trách trongidentity. - Kiểm tra trùng identifier (username / email / phone) trước khi việc nâng cấp tạo ra user.
Không phải mục tiêu
- Tạo role tùy biến hay quản lý permission động → Permissions.
- Khách hàng tự đăng ký / đăng nhập OAuth.
- Truy cập khách hàng đa organization cho một user duy nhất.
- Tích điểm loyalty và gắn kết khách hàng (thuộc về sau, nằm ngoài đợt này).
3. Success Metrics
| Metric | Mục tiêu / tín hiệu |
|---|---|
| Gán đơn cho khách | Sale order mang tham chiếu Customer khi đã biết khách |
| Khử trùng danh tính | Việc nâng cấp không bao giờ tạo identifier trùng; xung đột bị chặn, không âm thầm gộp |
| Nâng cấp thành công | Khách đã nâng cấp đăng nhập được (sau khi có credential) và phân giải đúng role Customer + scope organization |
| Tái sử dụng | Một model Customer duy nhất phục vụ cả sale và identity - không có bảng khách hàng song song |
4. Personas & Use Cases
| Persona | Mục tiêu |
|---|---|
| Owner | Tạo và duy trì khách hàng dưới organization của mình; nâng cấp một người mua đã biết thành tài khoản đầy đủ |
| Cashier / Employee | Gắn một khách hàng vào sale order tại điểm bán |
| Customer | Được gắn với một organization và (sau khi nâng cấp) giữ một tài khoản mang role Customer |
Kịch bản cốt lõi: tạo một khách hàng dưới một organization → gắn khách hàng vào một sale order → về sau, nâng cấp khách hàng cấp sale đó thành user mang role Customer, với kiểm tra trùng identifier chặn các bản trùng.
5. User Stories
- Là một owner, tôi muốn tạo tài khoản khách hàng dưới organization của mình, để đơn hàng được gán cho một người mua đã biết.
- Là một owner, tôi muốn một khách hàng vừa tạo tự động nhận role Customer và được gắn với organization của tôi, để scope đúng mà không cần bước thừa.
- Là một cashier, tôi muốn gắn một khách hàng vào sale order, để đơn ghi nhận được khách là ai.
- Là một owner, tôi muốn cập nhật hoặc soft-delete thông tin khách hàng, để dữ liệu luôn chính xác và không mất gì vĩnh viễn.
- Là một owner, tôi muốn nâng cấp một khách hàng cấp sale thành tài khoản user đầy đủ, để một người mua thường xuyên trở thành user đã xác thực.
- Là một owner, tôi muốn việc nâng cấp kiểm tra trùng identifier trước, để cùng một email / phone / username không bao giờ bị chiếm hai lần.
6. Functional Requirements
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Owner có thể tạo tài khoản khách hàng theo phạm vi một organization | URD-CUS-001 |
| FR-2 | Một khách hàng được gắn với một organization và tự động nhận role Customer | URD-CUS-002 |
| FR-3 | Hồ sơ khách hàng giữ tên và thông tin liên hệ | URD-CUS-003 |
| FR-4 | Thông tin khách hàng có thể được cập nhật và soft-delete | URD-CUS-004 |
| FR-5 | Một khách hàng có thể được gắn vào một SaleOrder (CRUD khách hàng nằm trong package sale) | URD-CUS-001..004 |
| FR-6 | Một khách hàng cấp sale có thể được nâng cấp thành tài khoản user đầy đủ qua CustomerRegistrationService | URD-CUS-005 |
| FR-7 | Việc nâng cấp kiểm tra trùng identifier (username / email / phone) trước khi tạo user | URD-CUS-006 |
Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong URD Quản lý Người dùng. PRD này tham chiếu 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 | Tạo / nâng cấp khách hàng là một thao tác duy nhất - nâng cấp dở dang không bao giờ để lại một user tạo nửa chừng |
| Tính duy nhất danh tính | Mỗi loại identifier là duy nhất toàn cục; nâng cấp ép kiểm tra xung đột trước khi ghi |
| Tái sử dụng | Một model Customer duy nhất trong @nx/core được sale và identity dùng chung - không có schema trùng |
| Tenancy & authz | Khách hàng được scope theo một organization; các thao tác được gác bằng permission |
| Soft-delete | Bản ghi khách hàng dùng soft-delete; dữ liệu không bao giờ bị xóa vật lý |
| i18n | Nhãn hiển thị cho người dùng là song ngữ ({ en, vi }) |
8. UX & Flows
Màn hình chính (trong apps/client): quản lý khách hàng trên sale order, tạo/sửa khách hàng, và điều khiển gắn-vào-đơn.
9. Data & Domain
| Thực thể | Vai trò |
|---|---|
Customer | Khách hàng gắn với organization (model + schema + repository) trong @nx/core, dùng lại bởi sale và identity |
SaleOrder | Mang tham chiếu khách hàng; việc gắn khách hàng nằm trong aggregate sale |
User + role Customer | Tài khoản đầy đủ được tạo bởi CustomerRegistrationService |
Identifier | Username / email / phone được kiểm tra xung đột trước khi nâng cấp |
Chỉ ở mức khái niệm - schema đầy đủ và các bất biến nằm trong domain model của identity.
10. Dependencies & Assumptions
Phụ thuộc vào
- User Account & Roles (URD-USR · URD-ROLE) - việc nâng cấp tạo một user và gán role Customer.
- Organization (
@nx/core/ Commerce) - một khách hàng được gắn với một organization. - Sale order (
@nx/sale) - CRUD khách hàng được scope theo sale order, và một khách hàng gắn vào mộtSaleOrder.
Giả định
- Merchant vận hành dưới một organization sở hữu khách hàng.
- Tám role cố định (gồm Customer) được seed sẵn và sẵn sàng để gán.
11. Risks & Open Questions
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Nâng cấp có thể tạo một danh tính trùng | Kiểm tra trùng identifier chặn trước khi tạo user |
| Khách đã nâng cấp chưa có credential | Khoảng trống đã biết - tài khoản khách hàng được tạo không kèm credential, nên chưa thể đăng nhập |
| Nâng cấp dở dang khi lỗi | Tạo / nâng cấp là một thao tác duy nhất; không có user ghi nửa chừng |
| Khách hàng đa organization | Ngoài phạm vi; một khách hàng gắn với một organization |
12. Release Plan & Launch Criteria
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P2 - xem catalog tính năng URD (CUS đang In-progress; giao một phần của vùng này) |
| Rollout | Mọi merchant; không feature flag |
| Migration | Thực thể mới (Customer); không migration dữ liệu |
| Launch criteria | Tạo khách hàng → gắn vào sale order đã kiểm; nâng cấp tạo một user mang role Customer kèm kiểm tra xung đột; một model Customer dùng chung giữa sale + identity |
| Monitoring | Tỷ lệ lỗi tạo / nâng cấp khách hàng, số lần từ chối do trùng identifier, tỷ lệ đơn có khách hàng |
13. FAQ
Thực thể Customer nằm ở đâu? Trong @nx/core (models/schemas/sale/customer), nên cả sale và identity dùng lại một model - không có bảng khách hàng song song.
Tạo một khách hàng có tạo một tài khoản đăng nhập không? Không - một khách hàng vừa tạo là một bản ghi gắn với organization. Việc nâng cấp biến một khách hàng cấp sale thành một user đầy đủ mang role Customer; credential (và đăng nhập) là một mối quan tâm riêng, đến sau.
Chuyện gì xảy ra nếu email hoặc phone đã bị dùng? Việc nâng cấp bị chặn với lỗi xung đột. Identifier là duy nhất toàn cục theo từng loại và được kiểm tra trước khi user được tạo.
Một khách hàng có thể thuộc nhiều organization không? Không - truy cập đa organization cho một khách hàng duy nhất nằm ngoài phạm vi.
Loyalty / tích điểm có nằm trong phần này không? Không - gắn kết khách hàng và loyalty được xử lý sau, ngoài đợt này.
References
- URD: Quản lý Người dùng - Customer Management - yêu cầu (vùng
CUS) - Liên quan: URD - User Account · Roles & Scoping
- Module: Quản lý Người dùng - tổng quan + truy vết
- Developer: @nx/identity · @nx/sale