URD: Quản lý Người dùng

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

Tài liệu nghiệp vụ. URD này là danh sách tính năng của Quản lý Người dùng - mỗi tính năng bên dưới là một Vùng Chức năng (<AREA>). Cùng mã <AREA> đó là khóa cho PRD (PRD-<AREA>-NNN) và test (TC-<AREA>-NNN) của tính năng, 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 Quản lý Người dùng phải làm gì cho người dùng: cách họ tạo tài khoản, xác thực và quản lý hồ sơ, và cách chủ doanh nghiệp quản lý nhân viên và khách hàng trong tổ chức của mình. Đây là nền tảng của nền tảng - mọi module khác đều tin cậy danh tính và phạm vi được cấp ở đây.

2. Phạm vi

Bao gồm	Loại trừ
Tạo tài khoản (đăng ký) và xác thực (đăng nhập)	Tạo vai trò tùy chỉnh → Quyền hạn
Quản lý mật khẩu (đổi, quên / đặt lại)	Luồng đăng nhập OAuth / OAuth2
Xác minh OTP cho email và điện thoại; liên kết tài khoản	Quản lý phiên và thu hồi từ xa
Tám vai trò hệ thống cố định và truy cập theo vai trò	Hệ thống mời người dùng
Vòng đời nhân viên (tạo, gán, vô hiệu hóa, gỡ)	Lịch sử kiểm toán / đăng nhập
Vòng đời khách hàng (tạo, cập nhật, soft-delete, nâng cấp)	Truy cập nhiều tổ chức cho một người dùng
Quản lý hồ sơ, định danh và cấu hình theo từng người dùng	Bắt buộc xác thực hai yếu tố

3. Định nghĩa

Thuật ngữ	Định nghĩa
User	Một danh tính đã xác thực - nội bộ (operator) hoặc bên ngoài (owner, employee, customer).
Credential	Một bí mật dùng để xác thực - hiện là mật khẩu băm; scheme 2FA / OAuth đã định nghĩa nhưng chưa bắt buộc.
Identifier	Một giá trị đăng nhập gắn với người dùng - username, email hoặc điện thoại. Mỗi giá trị duy nhất toàn cục trong loại của nó.
User Profile	Thông tin cá nhân gắn với người dùng - tên, ngày sinh, locale, thông tin liên hệ. Một cho mỗi người dùng.
User Configuration	Một cài đặt khóa-giá trị theo từng người dùng, nhóm theo code. Bộ mặc định được tạo khi đăng ký.
Role	Một phân loại xác định mức truy cập và phạm vi dữ liệu. Có tám vai trò cố định.
Owner	Người dùng tạo doanh nghiệp khi onboarding; có toàn quyền truy cập tổ chức của mình.
Cashier	Vai trò nhân sự cấp merchant cho thu ngân, giới hạn theo các merchant cụ thể (cùng tier với Employee).
Employee	Một nhân viên giới hạn theo các merchant cụ thể trong một tổ chức.
Customer	Một khách hàng cuối liên kết với một tổ chức; có thể được nâng cấp từ dữ liệu cấp bán hàng thành người dùng đầy đủ.
Guest	Một vai trò toàn cục kiểu chưa xác thực, không có quyền backend; ưu tiên thấp nhất.
OTP	Mã dùng một lần gửi qua email hoặc SMS để xác minh định danh hoặc đặt lại mật khẩu.
Session Token (JWT)	Cấp khi đăng nhập; mang user ID, vai trò, ID tổ chức và ID merchant để phân quyền phi trạng thái.

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

Chỉ mang tính khái niệm - schema đầy đủ nằm trong mô hình miền developer.

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 Vùng Chức năng). Chi tiết ở §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
AUTH	Xác thực	P1	Built	High
USR	Tài khoản Người dùng	P1	Built	High
ROLE	Vai trò & Phân phạm vi	P1	Built	High
EMP	Quản lý Nhân viên	P2	In-progress	High
CUS	Quản lý Khách hàng	P2	In-progress	High
CFG	Cấu hình Người dùng	P1	Built	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ỗi tính năng một mục con, 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).

AUTH - Xác thực Built

Feature ID: user-management/AUTH · Phase: P1 · PRDs: - · Dev: @nx/identity

Tính năng làm gì cho người dùng: người dùng tạo tài khoản và đăng nhập bằng username, email hoặc điện thoại kèm mật khẩu; họ đổi hoặc đặt lại mật khẩu và xác minh email và điện thoại qua mã dùng một lần.

Yêu cầu

ID	P	Yêu cầu
URD-AUTH-001	M	Người dùng có thể đăng ký với username và mật khẩu
URD-AUTH-002	M	Đăng ký tạo tài khoản, hồ sơ, định danh và cài đặt mặc định trong một thao tác
URD-AUTH-003	M	Nếu bất kỳ phần nào của đăng ký thất bại, không có gì được tạo (tất-cả-hoặc-không)
URD-AUTH-004	M	Người dùng có thể đăng nhập bằng bất kỳ định danh đã xác minh (username / email / phone) + mật khẩu
URD-AUTH-005	M	Đăng nhập thành công trả về token phiên mang vai trò và phạm vi tổ chức / merchant
URD-AUTH-006	M	Mật khẩu được băm an toàn trước khi lưu và không bao giờ lưu dạng văn bản thuần
URD-AUTH-007	M	Người dùng có thể đổi mật khẩu (xác minh mật khẩu hiện tại trước)
URD-AUTH-008	M	Người dùng có thể xác minh email qua OTP (yêu cầu → nhận mã → gửi)
URD-AUTH-009	M	Người dùng có thể xác minh điện thoại qua OTP (cùng luồng)
URD-AUTH-010	M	Người dùng có thể đặt lại mật khẩu đã quên (yêu cầu → xác minh mã → đặt mật khẩu mới)
URD-AUTH-011	S	Người dùng có thể thêm (liên kết) một email hoặc điện thoại đã xác minh vào tài khoản đã xác thực
URD-AUTH-012	S	Hệ thống ghi lại dấu thời gian đăng nhập gần nhất
URD-AUTH-013	C	Bắt buộc xác thực hai yếu tố Planned
URD-AUTH-014	C	Hỗ trợ đăng nhập OAuth / bên thứ ba Planned

Chấp nhận

AC-AUTH-01: Đăng nhập

Cho	Khi	Thì
Thông tin xác thực hợp lệ, định danh đã xác minh	Người dùng đăng nhập	Token phiên được cấp với vai trò và phạm vi
Mật khẩu sai	Người dùng đăng nhập	Xác thực bị từ chối
Định danh chưa xác minh	Người dùng đăng nhập	Đăng nhập bị từ chối - định danh chưa xác minh
Người dùng bị vô hiệu hóa / bị chặn	Người dùng đăng nhập	Từ chối truy cập
Đăng nhập thành công	-	Dấu thời gian đăng nhập gần nhất được cập nhật

AC-AUTH-02: Đăng ký

Cho	Khi	Thì
Username + mật khẩu + hồ sơ mới	Người dùng đăng ký	Tài khoản được tạo với vai trò Owner
Username đã tồn tại	Người dùng đăng ký	Lỗi xung đột
Đăng ký thành công	-	Cài đặt mặc định tự tạo
Bất kỳ bước nào thất bại	-	Toàn bộ đăng ký roll back

AC-AUTH-03: Xác minh OTP

Cho	Khi	Thì
Email hoặc điện thoại chưa xác minh	Người dùng yêu cầu OTP	Mã được gửi, token phiên trả về
Phiên hợp lệ + mã đúng	Người dùng gửi	Định danh được đánh dấu đã xác minh
Mã hết hạn	Người dùng gửi	Lỗi - mã đã hết hạn
Quá nhiều lần thử	Người dùng thử lại	Lỗi - vượt quá số lần thử tối đa

AC-AUTH-04: Quên mật khẩu

Cho	Khi	Thì
Người dùng quên mật khẩu	Yêu cầu đặt lại	Phiên đặt lại được tạo
Mã đặt lại hợp lệ	Người dùng xác minh	Phiên được xác nhận
Phiên đã xác minh	Người dùng đặt mật khẩu mới	Mật khẩu được cập nhật (đã băm)

USR - Tài khoản Người dùng Built

Feature ID: user-management/USR · Phase: P1 · PRDs: PRD-USR-001 · PRD-USR-002 · Dev: @nx/identity

Tính năng làm gì cho người dùng: mỗi người dùng có một tài khoản duy nhất có thể giữ nhiều định danh (username, email, điện thoại), một hồ sơ chỉnh sửa được, tùy chọn ngôn ngữ và một vòng đời trạng thái - và dữ liệu tài khoản luôn được bảo toàn qua soft-delete. Bản thân định danh là một tài nguyên có quản lý: người dùng có thể liệt kê và thêm định danh của mình, mỗi cái phân loại bằng một scheme, và bất kỳ định danh nào được thêm đều bắt đầu chưa xác minh.

Yêu cầu

ID	P	Yêu cầu
URD-USR-001	M	Mỗi người dùng có một ID duy nhất do hệ thống sinh
URD-USR-002	M	Một người dùng có thể có nhiều định danh (username, email, điện thoại)
URD-USR-003	M	Mỗi định danh duy nhất toàn cục trong loại của nó
URD-USR-004	M	Username là bắt buộc và tự động được xem là đã xác minh
URD-USR-005	M	Định danh email và điện thoại bắt đầu chưa xác minh và cần OTP để xác minh
URD-USR-006	M	Người dùng có thể xem và cập nhật hồ sơ của mình (tên, ngày sinh, locale, liên hệ)
URD-USR-007	M	Người dùng được ủy quyền có thể đổi trạng thái người dùng (kích hoạt, vô hiệu hóa, chặn, lưu trữ)
URD-USR-008	M	Người dùng bị vô hiệu hóa và bị chặn không thể đăng nhập
URD-USR-009	M	Dữ liệu người dùng luôn được bảo toàn - tài khoản không bao giờ bị xóa vĩnh viễn (soft-delete)
URD-USR-010	S	Người dùng có thể đặt tùy chọn ngôn ngữ / locale
URD-USR-011	C	ARCHIVED là trạng thái cuối và không thể kích hoạt lại
URD-USR-012	M	Mỗi định danh khai báo một scheme phân loại nó - username, email, điện thoại - lấy từ một tập cố định, đã kiểm chứng (cùng các scheme do hệ thống cấp)
URD-USR-013	M	Định danh là một tài nguyên có quản lý: liệt kê, tìm kiếm, đếm và đọc đơn lẻ, giới hạn theo quyền truy cập của người gọi
URD-USR-014	M	Thêm một định danh luôn gắn nó với người dùng yêu cầu và tạo nó chưa xác minh; tham chiếu người dùng hoặc cờ xác minh cung cấp không thể ghi đè điều này
URD-USR-015	S	Định danh có thể được cập nhật và gỡ (đơn lẻ hoặc theo bộ lọc) qua soft-delete; dữ liệu định danh được bảo toàn
URD-USR-016	M	Mọi thao tác định danh (đọc / tạo / cập nhật / xóa) được kiểm soát quyền riêng lẻ và giới hạn theo merchant

Chấp nhận

AC-USR-01: Danh tính & vòng đời tài khoản

Cho	Khi	Thì
Một tài khoản mới	Được tạo	Một ID duy nhất do hệ thống sinh được gán; dữ liệu dùng soft-delete, không bao giờ xóa vĩnh viễn
Người dùng bị vô hiệu hóa hoặc bị chặn	Thử đăng nhập	Truy cập bị từ chối

AC-USR-02: Quản lý định danh

Cho	Khi	Thì
Một người dùng đã đăng nhập	Liệt kê định danh của mình	Chỉ các định danh trong phạm vi của người gọi được trả về, mỗi cái gắn nhãn theo scheme
Người dùng thêm một định danh	Gửi yêu cầu tạo	Định danh thuộc về người dùng yêu cầu và được lưu chưa xác minh
Một yêu cầu tạo nêu người dùng khác hoặc đặt sẵn đã xác minh	Được gửi	Chủ sở hữu vẫn là người gọi và định danh vẫn chưa xác minh - các giá trị request bị bỏ qua
Một định danh được gỡ	Gửi yêu cầu xóa	Bản ghi được soft-delete và bảo toàn, không bao giờ xóa vật lý

ROLE - Vai trò & Phân phạm vi Built

Feature ID: user-management/ROLE · Phase: P1 · PRDs: - · Dev: @nx/identity

Tính năng làm gì cho người dùng: tám vai trò hệ thống cố định đặt mức truy cập và phạm vi dữ liệu của mỗi người dùng; vai trò ưu tiên cao hơn thấy nhiều hơn, kết quả list/count được lọc theo phạm vi của người gọi, và không ai có thể quản lý vai trò ở mức của mình hoặc cao hơn.

Yêu cầu

ID	P	Yêu cầu
URD-ROLE-001	M	Hệ thống cung cấp tám vai trò cố định: Super Admin, Admin, Operator, Owner, Cashier, Employee, Customer, Guest
URD-ROLE-002	M	Vai trò có một hệ thống ưu tiên; ưu tiên cao hơn nghĩa là truy cập rộng hơn
URD-ROLE-003	M	Super Admin và Admin bỏ qua mọi lọc dữ liệu
URD-ROLE-004	M	Owner chỉ thấy tổ chức của mình và các merchant của nó
URD-ROLE-005	M	Employee / Cashier chỉ thấy merchant mà họ được gán
URD-ROLE-006	M	Thao tác list và count được lọc theo phạm vi của người dùng yêu cầu
URD-ROLE-007	M	Người dùng không thể quản lý vai trò bằng hoặc cao hơn ưu tiên của chính mình
URD-ROLE-008	M	Vai trò Owner được tự gán khi đăng ký

Chấp nhận

AC-ROLE-01: Truy cập theo phạm vi vai trò

Cho	Khi	Thì
Một Owner	List hoặc count bản ghi	Chỉ tổ chức của mình và các merchant của nó được trả về
Một người dùng	Thử quản lý vai trò ở mức của mình hoặc cao hơn	Thao tác bị từ chối

EMP - Quản lý Nhân viên In-progress

Feature ID: user-management/EMP · Phase: P2 · PRDs: - · Dev: @nx/identity

Tính năng làm gì cho người dùng: chủ sở hữu tạo tài khoản nhân viên, gán họ vào một hoặc nhiều merchant trong tổ chức của mình, và cập nhật hoặc vô hiệu hóa các gán đó; mỗi nhân viên đăng nhập bằng thông tin xác thực riêng và chỉ thấy các merchant được gán.

Yêu cầu

ID	P	Yêu cầu
URD-EMP-001	M	Chủ sở hữu có thể tạo tài khoản nhân viên
URD-EMP-002	M	Nhân viên được liên kết với một tổ chức và một hoặc nhiều merchant
URD-EMP-003	M	Nhân viên chỉ có thể truy cập merchant mà họ được gán
URD-EMP-004	M	Nhân viên có thể đăng nhập bằng thông tin xác thực riêng
URD-EMP-005	M	Truy vấn dữ liệu cho một nhân viên được lọc theo các merchant họ được gán
URD-EMP-006	M	Chủ sở hữu có thể cập nhật gán merchant của nhân viên (thay thế mọi gán trước đó)
URD-EMP-007	M	Chủ sở hữu có thể vô hiệu hóa hoặc gỡ một tài khoản nhân viên
URD-EMP-008	M	Hệ thống xác thực rằng chủ sở hữu thực sự sở hữu tổ chức và mọi merchant được liệt kê

Chấp nhận

AC-EMP-01: Tạo nhân viên

Cho	Khi	Thì
Chủ sở hữu	Tạo nhân viên với danh sách merchant	Tài khoản được tạo với vai trò Employee, liên kết tới tổ chức + merchant
Chủ sở hữu không sở hữu tổ chức	Tạo nhân viên	Bị cấm
Merchant không thuộc tổ chức của chủ sở hữu	Có trong danh sách	Lỗi xác thực

AC-EMP-02: Gán lại merchant

Cho	Khi	Thì
Nhân viên hiện có	Chủ sở hữu cập nhật gán	Gán trước đó được thay bằng gán mới
-	-	Nhân viên chỉ thấy merchant mới

CUS - Quản lý Khách hàng In-progress

Feature ID: user-management/CUS · Phase: P2 · PRDs: - · Dev: @nx/identity

Tính năng làm gì cho người dùng: chủ sở hữu tạo và duy trì tài khoản khách hàng liên kết với tổ chức của mình, và có thể nâng cấp một khách hàng cấp bán hàng hiện có thành tài khoản người dùng đầy đủ, kèm kiểm tra xung đột định danh.

Yêu cầu

ID	P	Yêu cầu
URD-CUS-001	M	Chủ sở hữu có thể tạo tài khoản khách hàng
URD-CUS-002	M	Khách hàng được liên kết với một tổ chức và nhận vai trò Customer tự động
URD-CUS-003	M	Hồ sơ khách hàng gồm tên và thông tin liên hệ
URD-CUS-004	M	Thông tin khách hàng có thể được cập nhật và soft-delete
URD-CUS-005	S	Một khách hàng cấp bán hàng có thể được nâng cấp thành tài khoản người dùng đầy đủ
URD-CUS-006	S	Việc nâng cấp kiểm tra xung đột định danh trước khi tạo người dùng

Chấp nhận

AC-CUS-01: Nâng cấp khách hàng

Cho	Khi	Thì
Khách hàng cấp bán hàng	Kích hoạt nâng cấp	Người dùng đầy đủ được tạo với vai trò Customer
Xung đột định danh	Thử nâng cấp	Bị chặn với lỗi xung đột

CFG - Cấu hình Người dùng Built

Feature ID: user-management/CFG · Phase: P1 · PRDs: PRD-USR-001 · PRD-USR-002 · Dev: @nx/identity

Tính năng làm gì cho người dùng: mỗi người dùng nhận một bộ cài đặt cá nhân mặc định khi đăng ký, nhóm và định danh duy nhất theo code, và có thể đọc và cập nhật cài đặt của mình - bao gồm lưu một chế độ xem bảng tùy chỉnh với cột và bộ lọc của riêng mình. Cài đặt đọc được ngay khi người dùng đăng nhập, trước khi chọn merchant.

Yêu cầu

ID	P	Yêu cầu
URD-CFG-001	M	Cấu hình mặc định được tạo tự động khi người dùng đăng ký
URD-CFG-002	M	Cấu hình được nhóm và định danh duy nhất theo code cho mỗi người dùng
URD-CFG-003	S	Người dùng có thể xem và cập nhật cấu hình của mình
URD-CFG-004	M	Cấu hình thuộc một tập nhóm cố định (system, table, integration) và được định danh duy nhất bằng code cho từng người dùng
URD-CFG-005	M	Việc đọc cấu hình khả dụng cho bất kỳ người dùng đã xác thực trước khi chọn merchant; tạo / cập nhật / xóa được kiểm soát quyền
URD-CFG-006	S	Người dùng có thể tạo một chế độ xem bảng tùy chỉnh từ code + tên hiển thị; hệ thống nhân bản layout đã lưu của cấu hình bảng gốc thành một view mới theo từng người dùng trong nhóm table
URD-CFG-007	M	Việc tạo view tùy chỉnh từ chối một view trùng (người dùng + code + tên) và yêu cầu cấu hình bảng gốc được tham chiếu phải tồn tại

Chấp nhận

AC-CFG-01: Cấu hình mặc định

Cho	Khi	Thì
Một người dùng mới	Đăng ký	Một bộ cấu hình mặc định được tạo tự động, nhóm và định danh duy nhất theo code

AC-CFG-02: Chế độ xem bảng tùy chỉnh

Cho	Khi	Thì
Một người dùng đã đăng nhập, trước khi chọn merchant	Đọc cấu hình của mình	Cấu hình được trả về (chỉ cần xác thực, cấp người dùng)
Một người dùng, một code + tên hiển thị, một layout bảng gốc đã tồn tại	Lưu một view tùy chỉnh	Một view mới theo từng người dùng được tạo trong nhóm table, nhân bản layout gốc
Một view dùng lại tổ hợp (người dùng + code + tên) hiện có	Được lưu	Từ chối - view đã tồn tại
Một code không có cấu hình bảng gốc khớp	Được lưu	Từ chối - cấu hình bảng gốc không tồn tại

7. Ràng buộc & Mục tiêu Loại trừ

Ràng buộc

ID	Ràng buộc
C-01	Mật khẩu phải được băm an toàn; cấm lưu văn bản thuần
C-02	Tám vai trò cố định được seed sẵn và không thể sửa hoặc xóa
C-03	Ưu tiên vai trò được thực thi - không người dùng nào quản lý được vai trò ở mức của mình hoặc cao hơn
C-04	Tạo tài khoản là một thao tác liền mạch - không cho phép tạo một phần
C-05	Mọi bản ghi dùng soft-delete - không bao giờ xóa vật lý
C-06	Mỗi loại định danh duy nhất toàn cục (một email chỉ thuộc một người dùng)
C-07	Nhân viên phải được liên kết với cả một tổ chức và ít nhất một merchant
C-08	Token phiên là phi trạng thái - thay đổi quyền có hiệu lực ở lần đăng nhập kế tiếp
C-09	Mọi thao tác trừ đăng nhập / đăng ký đều yêu cầu xác thực

Mục tiêu Loại trừ

• Tạo vai trò tùy chỉnh và quản lý quyền động → Quyền hạn
• Luồng đăng nhập OAuth / OAuth2 bên thứ ba
• Quản lý phiên và thu hồi từ xa
• Mời người dùng qua email hoặc điện thoại
• Lịch sử đăng nhập và ghi log kiểm toán
• Truy cập nhiều tổ chức cho một người dùng duy nhất
• Chính sách bắt buộc MFA

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

Ngày	Tác giả	Mô tả	Ver
2026-02-26	P. Do - Product Owner	User story ban đầu	v0.1
2026-04-16	Product	Tái cấu trúc thành URD với ID yêu cầu	v0.3
2026-05-29	Product	Chuyển sang quy ước module-docs; chỉnh trạng thái (BLOCKED, không IDSAFE), thêm liên kết tài khoản + khoảng trống trung thực về trạng thái	v0.4
2026-06-04	Claude (AI pair)	Tổ chức lại theo tính năng (Feature Spine); mỗi tính năng giữ yêu cầu + chấp nhận riêng; ràng buộc chuyển sang CON xuyên suốt	v0.5
2026-06-15	Product	Mở rộng USR (tài nguyên quản lý định danh) + CFG (tài nguyên cấu hình, đọc trước merchant, view tùy chỉnh); liên kết PRD-USR-002	v0.6