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

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

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. Yêu cầu Chức năng

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

5.1 Xác thực (AUTH)

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

5.2 Tài khoản Người dùng (USR)

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

5.3 Vai trò & Phân phạm vi (ROLE)

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ý

5.4 Quản lý Nhân viên (EMP)

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ê

5.5 Quản lý Khách hàng (CUS)

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

5.6 Cấu hình Người dùng (CFG)

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

6. Tiêu chí 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)

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

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

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à nguyên tử — 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