PRD: Seam điểm thưởng khách hàng (tích điểm)
| Module | Khách hàng (CORE-09) | PRD ID | PRD-PNT-001 |
| Status | Shipped | Owner | Nhóm Sale |
| Date | 2026-06-15 | Version | v1.0 |
| Packages | @nx/sale · @nx/core | URD | PNT |
TL;DR
Khép kín vòng lặp giữa một giao dịch bán và số dư điểm của người mua. Khi một đơn hàng hoàn tất thanh toán và có khách hàng gắn kèm, hệ thống tích cho khách hàng đó điểm - tính từ tổng đơn hàng theo một tỷ lệ quy đổi theo merchant - ghi lần tặng như một mục sổ cái bất biến, và cộng số dư điểm lũy kế của khách hàng trong cùng một bước nguyên tử. Lần tặng là idempotent theo đơn: một sự kiện thanh toán gửi lại không bao giờ cộng kép. Tỷ lệ quy đổi là hệ số chi-tiêu-trên-điểm (bao nhiêu giá trị đơn hàng bằng một điểm), nên điểm được làm tròn xuống số nguyên. PRD này chỉ bao gồm tích điểm - quy đổi (tiêu điểm) là phi-mục-tiêu có chủ đích và chưa được xây dựng.
1. Bối cảnh & Vấn đề
Module Khách hàng đã lưu hồ sơ khách hàng (CUS) và gắn khách hàng vào đơn khi thanh toán, và module Sale đã đưa một đơn tới trạng thái đã-thanh-toán-đầy-đủ. Cái còn thiếu là seam giữa chúng: không gì biến một lần thanh toán hoàn tất thành giá trị thưởng cho người mua.
Thiếu seam đó, merchant không thể tưởng thưởng khách hàng quay lại. Không có tích điểm tự động, không có số dư theo từng khách để đọc, và không có bản ghi kiểm tra được lý do số dư thay đổi. Một đường tích điểm ngây thơ còn có nguy cơ cộng kép khi webhook thanh toán gửi lại, hoặc tích điểm với tỷ lệ chưa cấu hình hay bằng không. Bước tăng này bổ sung seam tích điểm trên nền các nguyên thủy hồ sơ và thanh toán sẵn có: một lần tặng, tính một lần, ghi một lần, cho mỗi đơn đã thanh toán.
2. Mục tiêu & Phi-mục-tiêu
Mục tiêu
- Tích điểm tự động khi đơn hoàn tất thanh toán và có khách hàng gắn kèm (URD-PNT-001).
- Tính điểm tặng từ tổng đơn hàng và một tỷ lệ quy đổi theo merchant (chi-tiêu-trên-điểm), làm tròn xuống số nguyên (URD-PNT-002).
- Theo dõi số dư điểm lũy kế theo từng khách, cộng nguyên tử (URD-PNT-003).
- Idempotent theo đơn - tặng tối đa một lần kể cả khi sự kiện thanh toán gửi lại (URD-PNT-004).
- Không tặng gì khi không có khách hàng gắn kèm, tỷ lệ chưa đặt, hoặc tỷ lệ / điểm tính được không dương (URD-PNT-005).
- Ghi mỗi lần tặng như một mục sổ cái bất biến liên kết khách hàng, đơn, merchant, số điểm, và tỷ lệ đã áp (URD-PNT-006).
- Cung cấp sổ cái chỉ-đọc, theo phạm vi merchant để duyệt lịch sử điểm của khách (URD-PNT-007).
Phi-mục-tiêu
- Quy đổi điểm (tiêu điểm) - tiêu điểm cho một đơn. Chưa xây dựng; sổ cái chỉ ghi mục tích điểm và số dư chỉ luôn tăng. Theo dõi như mục phạm vi bị loại trừ (URD - Phi-mục-tiêu).
- Hạng thành viên (Đồng / Bạc / Vàng) và hệ số tích theo hạng.
- Điều chỉnh điểm thủ công hay quyền ghi sổ cái từ bên ngoài - mục được ghi chỉ bởi seam tích điểm.
- Hết hạn điểm đã tích, và sao kê / thông báo điểm cho khách hàng.
3. Chỉ số thành công
| Chỉ số | Mục tiêu / tín hiệu |
|---|---|
| Phủ tích điểm | Mỗi đơn đã thanh toán đầy đủ có khách hàng gắn kèm và tỷ lệ đã cấu hình tạo đúng một lần tặng |
| Không cộng kép | Một sự kiện thanh toán gửi lại không bao giờ thêm lần tặng thứ hai cho cùng đơn |
| Toàn vẹn số dư | Số dư của một khách bằng tổng số điểm các mục sổ cái của họ |
| Đầy đủ kiểm tra | Không có lần cộng số dư nào mà thiếu một mục sổ cái bất biến tương ứng |
| Mặc định an toàn | Đơn không có khách, không có tỷ lệ, hay tỷ lệ không dương thì không tặng gì - không phải lỗi |
4. Đối tượng & Trường hợp dùng
| Đối tượng | Mục tiêu trong tính năng này |
|---|---|
| Chủ / Quản lý | Cấu hình tỷ lệ quy đổi; đọc số dư và lịch sử điểm của một khách |
| Thu ngân | Gắn khách khi thanh toán để giao dịch tích điểm cho họ lúc thanh toán |
| Khách hàng | Tích lũy số dư điểm từ mua sắm, kiểm tra được từng mục |
Kịch bản chính: một thu ngân gắn khách vào đơn và nhận thanh toán. Khi đơn thành đã-thanh-toán-đầy-đủ, seam đọc tỷ lệ quy đổi của merchant, tính điểm từ tổng đơn, ghi một mục sổ cái, và cộng số dư của khách - tất cả nguyên tử. Nếu cùng sự kiện thanh toán được gửi lại, seam phát hiện đơn đã tích điểm và không làm gì.
5. Câu chuyện người dùng
- Là chủ, tôi muốn khách tự động tích điểm khi đơn của họ được thanh toán, để thưởng không cần bước thủ công.
- Là chủ, tôi đặt một tỷ lệ quy đổi duy nhất theo merchant, để việc tích điểm nhất quán trên mọi giao dịch.
- Là chủ, tôi muốn mỗi lần tặng được ghi như một mục bất biến, để tôi luôn giải thích được một số dư.
- Là chủ, tôi muốn một sự kiện thanh toán gửi lại không bao giờ cộng kép, để số dư đáng tin cậy.
- Là thu ngân, tôi gắn khách khi thanh toán và không làm gì khác, để điểm tự theo giao dịch.
- Là chủ, tôi duyệt lịch sử điểm của một khách trong một danh sách chỉ-đọc, để kiểm tra số dư của họ tăng thế nào.
6. Yêu cầu chức năng
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Khi một đơn hoàn tất thanh toán và có khách hàng gắn kèm, tích điểm cho khách đó | URD-PNT-001 |
| FR-2 | Tính điểm tặng = floor(tổng đơn ÷ tỷ lệ quy đổi theo merchant) - tỷ lệ là chi-tiêu-trên-điểm | URD-PNT-002 |
| FR-3 | Duy trì số dư điểm lũy kế theo từng khách, cộng theo mỗi lần tặng | URD-PNT-003 |
| FR-4 | Tặng tối đa một lần cho mỗi đơn; sự kiện thanh toán gửi lại là no-op (idempotent theo đơn) | URD-PNT-004 |
| FR-5 | Không tặng gì khi không có khách, tỷ lệ chưa đặt, hoặc tỷ lệ / điểm tính được ≤ 0 | URD-PNT-005 |
| FR-6 | Ghi mỗi lần tặng như một mục sổ cái bất biến: loại, điểm, tỷ lệ đã áp, liên kết khách / đơn / merchant | URD-PNT-006 |
| FR-7 | Mục sổ cái và lần cộng số dư được ghi trong một giao dịch nguyên tử | URD-PNT-003 · URD-PNT-006 |
| FR-8 | Cung cấp sổ cái chỉ-đọc, theo phạm vi merchant để duyệt lịch sử điểm của một khách | URD-PNT-007 |
Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong URD Khách hàng - PNT. PRD này tham chiếu chúng thay vì lặp lại.
7. Yêu cầu phi chức năng
| Lĩnh vực | Yêu cầu |
|---|---|
| Idempotency | Tối đa một lần tặng cho mỗi đơn; seam kiểm tra mục đã tồn tại trước khi cộng |
| Nguyên tử | Mục sổ cái + lần cộng số dư commit cùng nhau; lỗi một phần thì rollback toàn bộ |
| Toàn vẹn dữ liệu | Không có lần cộng số dư nào thiếu một mục sổ cái bất biến tương ứng; mục chỉ-thêm |
| Phạm vi & phân quyền | API đọc sổ cái theo phạm vi merchant (x-merchant-id) và được kiểm soát bằng quyền đọc giao dịch điểm |
| Độ chính xác | Tổng đơn và tỷ lệ dùng độ chính xác thập phân (4 chữ số); điểm làm tròn xuống số nguyên |
| Bền bỉ | Thiếu khách, thiếu tỷ lệ, hay tỷ lệ / kết quả điểm không dương là no-op an toàn, không phải lỗi |
| i18n | Nhãn hiển thị cho người dùng song ngữ ({ en, vi }) |
8. UX & Luồng
Đường tích điểm không có UI riêng - nó chạy khi thanh toán hoàn tất. Các bề mặt hướng chủ là thiết lập tỷ lệ quy đổi theo merchant và sổ cái điểm chỉ-đọc của một khách.
9. Dữ liệu & Miền
| Thực thể | Vai trò trong seam |
|---|---|
PointTransaction | Một mục sổ cái bất biến cho mỗi lần tặng - loại (EARN), điểm, tỷ lệ quy đổi đã áp, liên kết khách / đơn / merchant. Một mục mỗi đơn |
Customer | Mang số dư pointBalance lũy kế, cộng nguyên tử theo mỗi lần tặng |
Configuration | Giữ tỷ lệ quy đổi điểm theo merchant đọc lúc tặng |
SaleOrder | Đơn đã thanh toán có tổng tiền dẫn dắt lần tặng |
Chỉ mang tính khái niệm - schema và bất biến đầy đủ nằm trong tài liệu nhà phát triển Sale - Customer Points. Quan hệ là tham chiếu mềm; toàn vẹn được thực thi trong seam, không bằng ràng buộc cơ sở dữ liệu.
10. Phụ thuộc & Giả định
Phụ thuộc vào
- Hồ sơ khách hàng (CUS) - lần tặng cộng cho khách gắn vào đơn.
- Hoàn tất thanh toán đơn (Đơn hàng) - seam kích hoạt khi đơn thành đã thanh toán đầy đủ.
- Cấu hình theo merchant - tỷ lệ quy đổi đọc từ thiết lập quy đổi điểm của merchant; một mặc định hợp lý áp dụng khi thiết lập tồn tại nhưng không có giá trị rõ ràng.
@nx/core- mô hình sổ cái giao dịch điểm, số dư khách, đơn, và cấu hình.
Giả định
- Một khách được gắn vào đơn khi thanh toán; nếu không seam không tặng gì.
- Merchant đã cấu hình một tỷ lệ quy đổi dương; tỷ lệ chưa đặt hay không dương thì không tặng.
- Seam thanh toán có thể gửi lại sự kiện hoàn tất, nên đường tích điểm phải idempotent.
11. Rủi ro & Câu hỏi mở
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Sự kiện thanh toán gửi lại cộng kép | Lần tặng idempotent theo đơn - mục đã tồn tại sẽ ngắt mạch seam |
| Mục sổ cái và số dư lệch nhau khi lỗi một phần | Cả hai ghi trong một giao dịch nguyên tử; lỗi một phần rollback toàn bộ |
| Merchant chưa cấu hình tỷ lệ | No-op an toàn - không tặng, không lỗi; có log để theo dõi |
| Tỷ lệ bằng không hoặc âm | No-op an toàn - chặn trước mọi lần ghi |
| Đơn nhỏ tích không điểm | Đúng kỳ vọng - điểm làm tròn xuống; tổng dưới một điểm không tặng gì |
| Khách kỳ vọng tiêu điểm | Ngoài phạm vi - quy đổi (tiêu điểm) là phi-mục-tiêu có chủ đích trong bước này |
12. Kế hoạch phát hành & Tiêu chí ra mắt
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P2 - PNT trong danh mục tính năng URD |
| Triển khai | Mọi merchant; không feature flag. Tích điểm hoạt động khi merchant đặt một tỷ lệ quy đổi |
| Di trú | Không - seam chạy trên đường hoàn tất thanh toán sẵn có; cột số dư đã có |
| Tiêu chí ra mắt | Một đơn đã thanh toán đầy đủ có khách và tỷ lệ đã cấu hình tích floor(tổng ÷ tỷ lệ) điểm; lần tặng ghi một mục sổ cái bất biến và cộng số dư nguyên tử; sự kiện gửi lại không tặng gì; không khách / không tỷ lệ / tỷ lệ không dương không tặng gì |
| Giám sát | Số lần tặng theo merchant, kiểm tra số-dư-so-sổ-cái, lý do no-op (không khách, không tỷ lệ, không dương), số lần bỏ qua idempotent |
13. FAQ
Điểm được tính thế nào? Điểm = floor(tổng đơn ÷ tỷ lệ quy đổi). Tỷ lệ là hệ số chi-tiêu-trên-điểm - bao nhiêu giá trị đơn bằng một điểm - nên tỷ lệ 1000 tích một điểm cho mỗi 1000 tổng đơn.
Điều gì xảy ra nếu sự kiện thanh toán gửi lại? Không gì được cộng hai lần. Seam kiểm tra đơn đã tích điểm chưa và nếu rồi thì không làm gì.
Nếu merchant chưa đặt tỷ lệ? Không tặng điểm - đó là no-op an toàn, không phải lỗi. Tương tự khi không có khách gắn kèm hoặc tỷ lệ không dương.
Khách có thể tiêu điểm không? Chưa. Bước này chỉ phát hành tích điểm; quy đổi (tiêu điểm) là phi-mục-tiêu có chủ đích - sổ cái chỉ ghi mục tích điểm và số dư chỉ tăng.
Mọi thay đổi số dư có kiểm tra được không? Có - mỗi lần tặng ghi một mục sổ cái bất biến (điểm, tỷ lệ đã áp, khách / đơn / merchant) trong cùng giao dịch với lần cộng số dư, và sổ cái duyệt được chỉ-đọc theo merchant.
Nhân viên có sửa được sổ cái không? Không - mục được ghi chỉ bởi seam tích điểm. API sổ cái là chỉ-đọc và theo phạm vi merchant.
Tham chiếu
- URD: Khách hàng - PNT
- PRD liên quan: Hồ sơ khách hàng · KH doanh nghiệp & nhóm
- Module: Khách hàng - tổng quan + truy vết
- Nhà phát triển: @nx/sale - Customer Points · @nx/core