URD: CRM

Module	CORE-09	Phiên bản	v0.4
Trạng thái	In-progress	Ngày	2026-05-30

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	Engine 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ố theo từng merchant biến tổng đơn hàng thành điểm
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. Yêu cầu chức năng

Một bảng cho mỗi khu vực chức năng. Mã <AREA> khớp với ID của test case. Ưu tiên = MoSCoW (Must / Should / Could / Won't).

5.1 Hồ sơ khách hàng (CUS)

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 đủ

5.2 Điểm thưởng (PNT)

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
URD-PNT-002	S	Tính điểm tặng = tổng đơn hàng × tỷ lệ quy đổi theo merchant
URD-PNT-003	S	Theo dõi số dư điểm lũy kế theo từng khách hàng
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)
URD-PNT-005	C	Không tặng điểm khi tỷ lệ chưa đặt/bằng không hoặc không có khách hàng gắn kèm

5.3 Người đăng ký bản tin (SUB)

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

5.4 Yêu cầu kinh doanh (INQ)

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

6. 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

AC-PNT-01: Đ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 = tổng đơn × tỷ lệ được cộng vào số dư
Cùng sự kiện thanh toán đơn được gửi lại	Điểm được tặng lại	Không tặng kép — số dư không đổi
Không có khách hàng gắn kèm, hoặc tỷ lệ bằng không/chưa đặt	Đơn hàng hoàn tất thanh toán	Không tặng điểm

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

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

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
• Engine 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	Di trú 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