URD: Khách hàng

Module	CORE-09	Phiên bản	v0.6
Trạng thái	In-progress	Ngày	2026-06-04

Tài liệu nghiệp vụ. URD này là danh sách tính năng của Khách hàng - mỗi tính năng bên dưới là một Khu vực chức năng (<AREA>). Cùng <AREA> đó định danh cho PRD của tính năng (PRD-<AREA>-NNN) và test (TC-<AREA>-NNN), và mỗi tính năng được liệt kê trong danh mục tính năng Delivery. Xem quy ước Feature Spine.

1. Mục đích

Định nghĩa các yêu cầu hướng người dùng cho Quản lý quan hệ khách hàng - lưu giữ hồ sơ khách hàng dưới một thương hiệu, tặng điểm thưởng cho khách mua lại, phát triển danh sách gửi bản tin, và thu thập yêu cầu kinh doanh để theo dõi. Mục tiêu là một nơi duy nhất để biết khách hàng của một doanh nghiệp là ai và để tương tác với họ.

2. Phạm vi

Bao gồm	Loại trừ
Hồ sơ khách hàng theo phạm vi thương hiệu	Phân khúc khách hàng (Planned)
Liên kết tài khoản khách hàng-người dùng	Bộ máy chiến dịch Email / SMS (Planned)
Tích điểm thưởng trên đơn hàng đã hoàn tất	Đổi điểm trên đơn hàng (Planned)
Đăng ký / hủy đăng ký / thống kê bản tin	Hạng thành viên (Planned)
Thu thập và vòng đời yêu cầu kinh doanh	Phân tích giá trị vòng đời (Planned)
	Đặc tả API kỹ thuật (xem tài liệu nhà phát triển)

3. Định nghĩa

Thuật ngữ	Định nghĩa
Khách hàng	Một người được thương hiệu biết đến; mô hình hóa như một User với vai trò customer cố định, mặc định không có thông tin đăng nhập
Thương hiệu (Organization)	Tầng thương hiệu ảo mà khách hàng thuộc về; khách hàng theo phạm vi này, không theo một đơn vị điểm bán cụ thể
Điểm thưởng	Số dư điểm mà khách hàng tích lũy khi đơn hàng hoàn tất thanh toán
Tỷ lệ quy đổi	Hệ số chi-tiêu-trên-điểm theo từng merchant - bao nhiêu tổng đơn hàng bằng một điểm (tổng đơn chia cho nó)
Người đăng ký	Một địa chỉ email đã chọn nhận bản tin, kèm chủ đề, ngôn ngữ, và token hủy đăng ký duy nhất
Yêu cầu	Một lead thu thập từ trang công khai, theo dõi qua vòng đời NEW → đã phân công → đã trả lời → đã chuyển đổi/thất bại

4. Mô hình khái niệm

Chỉ mang tính khái niệm. Schema đầy đủ nằm trong tài liệu nhà phát triển: Mô hình miền Identity, Sale - Customer Points, và Mô hình miền Outreach.

5. Danh mục tính năng

Danh sách tính năng của module này. Mỗi hàng là một tính năng (một Khu vực chức năng). Chi tiết tại §6. Được phản chiếu trong danh mục tính năng Delivery.

Feature ID	Tính năng	Phase	Trạng thái	Ưu tiên
CUS	Hồ sơ khách hàng	P1	Built	High
PNT	Điểm thưởng	P2	Built	Medium
SUB	Người đăng ký bản tin	P2	Built	Medium
INQ	Yêu cầu kinh doanh	P2	Built	Medium
BIZ	KH doanh nghiệp & nhóm khách	P2	Planned	High

Trạng thái: live từ Plane nếu có map, còn lại do registry khai báo. Vocabulary đồng nhất với Plane (state-group / phase).

6. Tính năng

Một mục con cho mỗi tính năng, theo thứ tự danh mục. Mỗi tính năng giữ mô tả, yêu cầu, và tiêu chí chấp nhận cùng nhau. Ưu tiên = MoSCoW (Must / Should / Could / Won't).

CUS - Hồ sơ khách hàng Built

Feature ID: crm/CUS · Phase: P1 · PRDs: - · Dev: @nx/identity

Người dùng làm được gì: nhân viên lưu giữ danh bạ khách hàng dưới thương hiệu của mình - tên, email, số điện thoại, ngày sinh, ngôn ngữ - theo phạm vi Organization, gắn được vào đơn hàng, và xóa-mềm trong khi giữ lại lịch sử.

Yêu cầu

ID	P	Yêu cầu
URD-CUS-001	M	Tạo khách hàng với tên, ít nhất một email và một số điện thoại
URD-CUS-002	M	Gán mọi khách hàng vào phạm vi thương hiệu (Organization)
URD-CUS-003	M	Cập nhật hồ sơ khách hàng (tên, email, điện thoại, ngày sinh, ngôn ngữ)
URD-CUS-004	M	Xóa-mềm một khách hàng, giữ lại lịch sử
URD-CUS-005	S	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-006	S	Gắn một khách hàng vào đơn hàng khi thanh toán
URD-CUS-007	C	Nâng cấp một khách hàng thành tài khoản người dùng đăng nhập đầy đủ

Tiêu chí chấp nhận

AC-CUS-01: Vòng đời hồ sơ khách hàng

Cho	Khi	Thì
Một nhân viên của một thương hiệu	Tạo khách hàng với tên + điện thoại + email	Khách hàng được tạo và gán vào phạm vi thương hiệu đó
Một khách hàng của thương hiệu khác	Nhân viên tìm/mở nó	Không hiển thị (cô lập thương hiệu)
Một khách hàng có đơn hàng liên kết	Nhân viên xóa-mềm	Khách hàng rời khỏi danh sách hoạt động; bản ghi và đơn hàng được giữ lại

PNT - Điểm thưởng Built

Feature ID: crm/PNT · Phase: P2 · PRDs: PRD-PNT-001 · Dev: @nx/sale

Người dùng làm được gì: khách hàng tự động tích số dư điểm khi đơn hàng hoàn tất thanh toán, tính bằng cách lấy tổng đơn hàng chia cho tỷ lệ quy đổi theo merchant (chi-tiêu-trên-điểm) và làm tròn xuống số nguyên, tặng tối đa một lần cho mỗi đơn, với mỗi lần tặng được ghi như một mục sổ cái bất biến.

Yêu cầu

ID	P	Yêu cầu
URD-PNT-001	S	Tặng điểm khi đơn hàng hoàn tất thanh toán và có khách hàng gắn kèm
URD-PNT-002	S	Tính điểm tặng = floor(tổng đơn hàng ÷ tỷ lệ quy đổi theo merchant) - tỷ lệ là chi-tiêu-trên-điểm
URD-PNT-003	S	Theo dõi số dư điểm lũy kế theo từng khách hàng, cộng nguyên tử
URD-PNT-004	S	Tặng điểm tối đa một lần cho mỗi đơn, kể cả khi thử lại (idempotent theo đơn)
URD-PNT-005	C	Không tặng điểm khi tỷ lệ chưa đặt / không dương, điểm tính được ≤ 0, hoặc không có khách hàng gắn kèm
URD-PNT-006	S	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), ghi nguyên tử cùng lần cộng số dư
URD-PNT-007	C	Duyệt lịch sử điểm của một khách qua sổ cái chỉ-đọc, theo phạm vi merchant

Tiêu chí chấp nhận

AC-PNT-01: Tích điểm thưởng

Cho	Khi	Thì
Một khách hàng gắn với đơn; tỷ lệ đã cấu hình	Đơn hàng hoàn tất thanh toán	Điểm = floor(tổng đơn ÷ tỷ lệ) được cộng vào số dư và một mục sổ cái được ghi
Cùng sự kiện thanh toán đơn được gửi lại	Điểm lẽ ra được tặng lại	Không tặng kép - số dư và sổ cái không đổi
Không có khách hàng gắn kèm, hoặc tỷ lệ không dương / chưa đặt	Đơn hàng hoàn tất thanh toán	Không tặng điểm; không ghi mục (no-op an toàn, không phải lỗi)
Tổng đơn nhỏ hơn tỷ lệ	Đơn hàng hoàn tất thanh toán	Điểm tính được làm tròn về không, nên không tặng gì

AC-PNT-02: Sổ cái điểm là chỉ-đọc và theo phạm vi merchant

Cho	Khi	Thì
Các mục điểm đã tặng cho một merchant	Nhân viên mở sổ cái điểm với phạm vi merchant	Họ thấy các mục tích của khách (loại, điểm, tỷ lệ đã áp, liên kết đơn)
Một nhân viên không có phạm vi merchant	Họ yêu cầu sổ cái	Các mục của merchant đó không được trả về
Bất kỳ client bên ngoài	Nó thử tạo / sửa / xóa một mục	Sổ cái không phơi bày thao tác như vậy - mục được ghi chỉ bởi seam tích điểm

SUB - Người đăng ký bản tin Built

Feature ID: crm/SUB · Phase: P2 · PRDs: - · Dev: @nx/outreach

Người dùng làm được gì: khách truy cập chọn nhận bản tin bằng email kèm chủ đề và ngôn ngữ; việc đăng ký là idempotent, hủy đăng ký một-chạm hoạt động qua token duy nhất, và quản trị viên xem được thống kê người đăng ký.

Yêu cầu

ID	P	Yêu cầu
URD-SUB-001	S	Đăng ký bằng email với chủ đề và ngôn ngữ
URD-SUB-002	S	Giữ email duy nhất toàn cục giữa các người đăng ký
URD-SUB-003	S	Hủy đăng ký qua link token một-chạm duy nhất
URD-SUB-004	S	Đăng ký lại kích hoạt lại người đăng ký đã bị vô hiệu hóa (idempotent)
URD-SUB-005	S	Xem thống kê người đăng ký - tổng số, số mới theo tháng, số lượng theo trạng thái

Tiêu chí chấp nhận

AC-SUB-01: Đăng ký / hủy đăng ký bản tin

Cho	Khi	Thì
Một email mới	Đăng ký	Người đăng ký được tạo với chủ đề, ngôn ngữ, và một token hủy đăng ký
Một email đang hoạt động	Đăng ký lại	Trả về người đăng ký hiện có (idempotent)
Một người đăng ký đã vô hiệu hóa	Đăng ký lại	Người đăng ký được kích hoạt lại
Một token hủy đăng ký hợp lệ	Link được nhấp	Người đăng ký bị vô hiệu hóa

INQ - Yêu cầu kinh doanh Built

Feature ID: crm/INQ · Phase: P2 · PRDs: - · Dev: @nx/outreach

Người dùng làm được gì: lead từ trang công khai gửi yêu cầu kèm thông tin liên hệ, thông tin doanh nghiệp, và lời nhắn; quản trị viên được thông báo theo thời gian thực, và nhân viên sales đưa mỗi yêu cầu qua vòng đời NEW → đã phân công → đã trả lời → đã chuyển đổi/thất bại.

Yêu cầu

ID	P	Yêu cầu
URD-INQ-001	S	Thu thập một yêu cầu với thông tin liên hệ, thông tin doanh nghiệp, và lời nhắn
URD-INQ-002	S	Thông báo quản trị viên theo thời gian thực khi có yêu cầu mới được gửi
URD-INQ-003	S	Theo dõi phân công, trả lời, chuyển đổi, và lý do thất bại
URD-INQ-004	S	Đưa một yêu cầu qua NEW → đã phân công → đã trả lời → đã chuyển đổi/thất bại

Tiêu chí chấp nhận

AC-INQ-01: Yêu cầu kinh doanh

Cho	Khi	Thì
Một khách truy cập	Gửi một yêu cầu	Trạng thái là NEW và quản trị viên được thông báo theo thời gian thực
Một nhân viên sales	Tự phân công cho mình	Yêu cầu hiển thị người được phân công
Một nhân viên sales	Trả lời	Tác giả phản hồi và thời điểm được ghi nhận
Một nhân viên sales	Đánh dấu đã chuyển đổi (hoặc thất bại kèm lý do)	Kết quả và thời điểm được ghi nhận

BIZ - Khách Doanh nghiệp & Nhóm khách Planned

Mã tính năng: customer/BIZ · Phase: P2 (T7) · PRDs: PRD-BIZ-001 · Dev: @nx/identity

Mang lại gì cho người dùng: merchant quản lý khách hàng công ty - có mã số thuế (MST) - để HĐ VAT công ty mang đúng MST người mua, và xếp khách vào nhóm (VIP, member) phục vụ định giá và chăm sóc.

Yêu cầu

ID	P	Yêu cầu
URD-BIZ-001	M	Hồ sơ khách mang được trường doanh nghiệp: MST, tên công ty
URD-BIZ-002	M	Khách doanh nghiệp và cá nhân phân biệt rõ
URD-BIZ-003	M	MST của công ty chảy lên HĐ VAT của nó
URD-BIZ-004	M	Nhóm khách: tạo nhóm, gán khách
URD-BIZ-005	S	Nhóm của khách dùng được làm điều kiện giá (Pricing tiêu thụ ở T8)
URD-BIZ-006	S	Màn quản lý khách có ở client và BO
URD-BIZ-007	C	Quy tắc nhóm (gán tự động)

Nghiệm thu

AC-BIZ-01: HĐ VAT công ty

Given	When	Then
KH doanh nghiệp có MST hợp lệ	Đơn B2B xuất HĐ VAT	Hóa đơn mang MST + tên công ty người mua
Khách thuộc nhóm "VIP"	Liệt kê/lọc	Thành viên nhóm hiển thị và lọc được

7. Ràng buộc & Phi mục tiêu

Ràng buộc

ID	Ràng buộc
C-01	Khách hàng theo phạm vi thương hiệu (Organization), không theo một đơn vị điểm bán cụ thể
C-02	Khách hàng có vai trò customer cố định và mặc định không có thông tin đăng nhập
C-03	Tặng điểm là idempotent - tối đa một lần tặng cho mỗi đơn
C-04	Email người đăng ký duy nhất toàn cục; token hủy đăng ký duy nhất toàn cục
C-05	Đăng ký là idempotent (trả về cái hiện có hoặc kích hoạt lại)
C-06	Mọi bản ghi dùng xóa-mềm

Phi mục tiêu

• Phân khúc và nhắm khách hàng
• Bộ máy chiến dịch Email / SMS
• Đổi điểm trên đơn hàng, và hạng thành viên
• Phân tích giá trị vòng đời khách hàng

8. Lịch sử phiên bản

Ngày	Tác giả	Mô tả	Ver
2026-02-26	P. Do - Product Owner	Hồ sơ khách hàng, điểm, người đăng ký, yêu cầu ban đầu	v0.1
2026-04-16	P. Do - Product Owner	Tái cấu trúc quanh người đăng ký và yêu cầu	v0.3
2026-05-30	Chuyển đổi tài liệu	Tái cấu trúc theo quy ước module; các khu vực CUS/PNT/SUB/INQ căn theo hành vi đã build; ưu tiên trung thực với trạng thái	v0.4
2026-06-04	Claude (AI pair)	Tái tổ chức theo tính năng (Feature Spine)	v0.5
2026-06-15	Nhóm Sale	PNT cập nhật đúng theo code (tỷ lệ chia chi-tiêu-trên-điểm); thêm yêu cầu sổ cái PNT-006/007 + AC-PNT-02; liên kết PRD-PNT-001	v0.6