PRD: Tài khoản & cấu hình người dùng

Module	Quản lý User	PRD ID	PRD-USR-001
Trạng thái	Sẵn sàng dev	FEAT	USR
Epic	—	Plane	BANA-1527
Ngày	2026-05-27	Phiên bản	v1.0
Gói	@nx/identity	URD	USR
Surface	Client · Chủ/QLBO · Vận hành
Phụ trách	Phát Nguyễn

Tài khoản & cấu hình người dùng là gì

Mỗi người dùng trên BANA sở hữu đúng một tài khoản (User Account) bền vững: một ID do hệ thống sinh ra, không bao giờ bị xóa vật lý dù tài khoản có bị gỡ. Một tài khoản giữ được nhiều định danh đăng nhập (Login Identifier) - username, email, số điện thoại - và không bao giờ tồn tại hai tài khoản dùng chung một username, một email hay một số điện thoại đã xác minh.

Mọi module khác đều tin vào danh tính và phạm vi do Quản lý Người dùng cấp, nên bản thân tài khoản - cùng các định danh, hồ sơ (Profile), trạng thái và thiết lập cá nhân - phải tồn tại trước khi gắn được vai trò, nhân viên hay khách hàng lên trên. Thiếu một tài khoản hạng nhất thì không có chủ thể ổn định để gắn vai trò, không có cách biết chắc một email hay số điện thoại thực sự thuộc về ai, không có chỗ lưu tùy chọn riêng như ngôn ngữ, và không gì đảm bảo dữ liệu tài khoản còn sống sau một lần "xóa". PRD này dựng nền móng đó cho toàn bộ nền tảng.

Một người dùng, từ lúc đăng ký tới lúc dùng hằng ngày

Một người đăng ký bằng username - tài khoản, hồ sơ, định danh và một bộ cấu hình (User Configuration) mặc định được tạo cùng lúc. Người dùng mở trang hồ sơ, sửa họ tên và ngày sinh, tải lên ảnh đại diện. Ở góc trên header, người dùng bấm đổi ngôn ngữ - giao diện đổi và lưu ngay, lần đăng nhập sau vẫn giữ đúng lựa chọn đó. Người dùng thêm một email mới; định danh đó bắt đầu ở trạng thái chưa xác minh, cần một mã OTP mới xác minh được. Về sau, người được gán quyền quản lý tài khoản khóa tài khoản này vì lý do vận hành - người dùng không đăng nhập được nữa cho tới khi được mở khóa, nhưng toàn bộ dữ liệu tài khoản vẫn còn nguyên, không mất gì.

Chỗ dễ sai nhất

Lưu trữ là trạng thái kết thúc, không có đường quay lại

Vòng đời trạng thái của một tài khoản đi qua kích hoạt, vô hiệu hóa, chặn, và cuối cùng là lưu trữ. Ba trạng thái đầu chuyển qua lại được với nhau, nhưng lưu trữ thì không - một khi đã lưu trữ, tài khoản không có đường quay lại bất kỳ trạng thái nào khác.

Người được gán quyền quản lý tài khoản cần phân biệt rõ: muốn tạm khóa thì chọn vô hiệu hóa hoặc chặn, chỉ chọn lưu trữ khi thật sự muốn kết thúc tài khoản đó.

1. Mục tiêu & Loại trừ

Mục tiêu

• Một tài khoản người dùng với một ID do hệ thống sinh ra duy nhất, xóa mềm được và không bao giờ bị xóa vật lý.
• Nhiều định danh đăng nhập cho mỗi người dùng (username, email, số điện thoại); không bao giờ tồn tại hai tài khoản cùng một username, email hay số điện thoại đã xác minh. Username bắt buộc và mặc nhiên được coi là đã xác minh; email và số điện thoại bắt đầu ở trạng thái chưa xác minh, cần một mã OTP mới xác minh được.
• Một trang hồ sơ chỉnh sửa được: họ tên, ngày sinh, thông tin liên hệ, ảnh đại diện (xem, tải lên, xóa), cùng tùy chọn ngôn ngữ đặt ở nút góc trên header - đổi là áp dụng và lưu ngay, giữ nguyên ở lần đăng nhập sau.
• Một vòng đời trạng thái (kích hoạt, vô hiệu hóa, chặn, lưu trữ) cho người được gán quyền quản lý tài khoản thao tác - ở trang Client hay Back Office - trong phạm vi của họ; trạng thái kiểm soát việc đăng nhập, Lưu trữ là trạng thái kết thúc.
• Một bộ cấu hình cá nhân mặc định được tạo tự động khi đăng ký, nhóm và đánh khóa duy nhất theo code cho từng người dùng.
• Người dùng tự đọc và cập nhật cấu hình của chính mình.

Loại trừ

• Bản thân xác thực, gửi mã OTP và các luồng mật khẩu - vùng AUTH / Xác thực & xác minh tài khoản.
• Tạo vai trò tùy biến và quản lý quyền động - Quyền hạn.
• Mời người dùng, quản lý session/thu hồi từ xa, lịch sử đăng nhập/audit.
• Quản lý định danh dạng tài nguyên (liệt kê, tìm kiếm, gỡ theo phạm vi) và custom view riêng cho bảng dữ liệu - thuộc Định danh & cấu hình người dùng (USR-002).
• Bắt buộc MFA.

2. Thước đo thành công

Thước đo	Mục tiêu / tín hiệu
Độ bền tài khoản	Không có xóa vật lý; mọi tài khoản bị gỡ vẫn còn dưới dạng bản ghi đã xóa mềm
Lời hứa duy nhất	Không tài khoản nào dùng trùng username, hoặc trùng một email hay số điện thoại đã xác minh với tài khoản khác
Tính đúng đắn xác minh	Email/số điện thoại chỉ dùng được sau khi xác minh bằng OTP; người bị vô hiệu hóa hoặc bị chặn không đăng nhập được
Tự phục vụ hồ sơ	Người dùng tự xem, sửa hồ sơ, ảnh đại diện và ngôn ngữ mà không cần ai hỗ trợ
Khởi tạo cấu hình	Mọi lượt đăng ký đều có sẵn bộ cấu hình mặc định, nhóm và đánh khóa theo code

3. Persona & Tình huống

Persona	Mục tiêu trong tính năng này
Chủ sở hữu / người dùng cuối	Sở hữu một tài khoản, tự sửa hồ sơ, ảnh đại diện và ngôn ngữ, quản lý định danh của mình, tinh chỉnh cấu hình cá nhân
Người được gán quyền quản lý tài khoản	Khóa, mở khóa hoặc lưu trữ tài khoản người khác trong phạm vi của mình, ở trang Client hoặc Back Office
Các module khác	Dựa vào một tài khoản ổn định để gắn vai trò, nhân viên và khách hàng lên trên

Kịch bản cốt lõi: một người đăng ký, tài khoản, hồ sơ, định danh và bộ cấu hình mặc định được tạo cùng lúc → người dùng sửa hồ sơ, đổi ảnh đại diện, chọn ngôn ngữ ở header, thêm và xác minh email hoặc số điện thoại bằng OTP, đọc và cập nhật cấu hình của mình → người được gán quyền quản lý tài khoản đổi trạng thái một người dùng khác trong phạm vi của họ, thao tác này kiểm soát việc đăng nhập; dữ liệu tài khoản luôn được giữ lại qua xóa mềm.

4. User Stories

#	Là một	Tôi muốn	Để
01	người dùng	một tài khoản duy nhất giữ được một username cùng nhiều email và số điện thoại	tôi đăng nhập bằng định danh nào mình có
02	người dùng	chắc chắn không ai khác dùng trùng email hay số điện thoại đã xác minh của tôi	định danh của tôi luôn là của riêng tôi
03	người dùng	sửa hồ sơ, đổi ảnh đại diện và chọn ngôn ngữ ngay ở góc trên	sản phẩm hiển thị đúng với tôi
04	người được gán quyền quản lý tài khoản	khóa, mở khóa hoặc lưu trữ một tài khoản trong phạm vi của mình, dù đang ở trang Client hay Back Office	truy cập phản ánh đúng tình trạng tài khoản đó
05	người dùng	tài khoản được giữ lại ngay cả khi bị "xóa"	dữ liệu không bao giờ mất âm thầm
06	người dùng	cấu hình mặc định được tạo sẵn và tôi tự chỉnh sửa được	các tùy chọn của tôi luôn được lưu lại

5. Yêu cầu chức năng

#	Yêu cầu	Trạng thái	URD ref
FR-001	Mỗi người dùng có một ID do hệ thống sinh ra, duy nhất. Tài khoản có thể xóa mềm và không bao giờ bị xóa vật lý.	✅	URD-USR-001 · URD-USR-009
FR-002	Một người dùng giữ được nhiều định danh đăng nhập: username, email, số điện thoại. Không bao giờ tồn tại hai tài khoản cùng một username, hoặc cùng một email hay số điện thoại đã xác minh.	✅	URD-USR-002 · URD-USR-003
FR-003	Username bắt buộc và mặc nhiên được coi là đã xác minh. Định danh email và số điện thoại bắt đầu chưa xác minh, cần một mã OTP để xác minh.	✅	URD-USR-004 · URD-USR-005
FR-004	Người dùng xem và cập nhật hồ sơ của chính mình. • Họ tên, ngày sinh, thông tin liên hệ. • Ngay trên trang hồ sơ, người dùng cũng xem, tải lên hoặc xóa ảnh đại diện của mình.	✅	URD-USR-006
FR-005	Người dùng đặt ngôn ngữ hiển thị bằng nút ở góc trên header. Đổi ngôn ngữ là áp dụng và lưu ngay, lần đăng nhập sau vẫn giữ đúng lựa chọn đó.	✅	URD-USR-010
FR-006	Người dùng được gán quyền quản lý tài khoản - ở trang Client hay Back Office - khóa, mở khóa hoặc lưu trữ tài khoản người khác trong phạm vi của mình.	🔶	URD-USR-007
FR-007	Người dùng bị vô hiệu hóa hoặc bị chặn không đăng nhập được.	✅	URD-USR-008
FR-008	Lưu trữ là trạng thái kết thúc của một tài khoản, không kích hoạt lại được.	🔶	URD-USR-011
FR-009	Một bộ cấu hình cá nhân mặc định được tạo tự động ngay khi người dùng đăng ký.	✅	URD-USR-022
FR-010	Người dùng tự đọc và cập nhật cấu hình cá nhân của mình.	✅	URD-USR-019 · URD-USR-021

5.1 Tiêu chí nghiệm thu

• Một người đăng ký tài khoản mới → nhận một ID duy nhất do hệ thống sinh ra; dữ liệu tài khoản không bao giờ bị xóa vật lý dù sau này bị gỡ.
• Đăng ký với một username đã có người dùng khác dùng → bị từ chối, không tài khoản nào được tạo.
• Đăng ký với một email hoặc số điện thoại đang là định danh đã xác minh của một tài khoản khác → bị từ chối, giữ đúng lời hứa không trùng.
• Đăng ký xong → username tự động ở trạng thái đã xác minh; thêm một email hoặc số điện thoại mới → định danh đó ở trạng thái chưa xác minh, cần một mã OTP mới xác minh được.
• Mở trang hồ sơ → thấy và sửa được họ tên, ngày sinh, thông tin liên hệ của mình.
• Trên trang hồ sơ, tải lên một ảnh đại diện → ảnh hiển thị ngay trên hồ sơ; bấm xóa ảnh đại diện → ảnh bị gỡ khỏi hồ sơ.
• Bấm nút đổi ngôn ngữ ở góc trên header, chọn một ngôn ngữ khác → giao diện đổi ngay và được lưu; đăng xuất rồi đăng nhập lại → vẫn đúng ngôn ngữ vừa chọn.
• Một người được gán quyền quản lý tài khoản, ở trang Client hoặc Back Office, khóa một tài khoản trong phạm vi của mình → tài khoản đó không đăng nhập được nữa.
• Một người không được gán quyền quản lý tài khoản thử khóa một tài khoản khác → bị từ chối.
• Mở khóa một tài khoản đang bị chặn → tài khoản đăng nhập lại được bình thường.
• Lưu trữ một tài khoản → tài khoản đó không đăng nhập được; thử kích hoạt lại một tài khoản đã lưu trữ → không có lối quay lại các trạng thái khác.
• Một người dùng mới hoàn tất đăng ký → một bộ cấu hình cá nhân mặc định đã sẵn sàng ngay, không cần thao tác gì thêm.
• Người dùng mở cấu hình cá nhân của mình → thấy đúng các tùy chọn đã lưu (ví dụ cờ đã xem hướng dẫn); sửa một tùy chọn rồi lưu → lần sau mở lại vẫn thấy giá trị mới.

6. Yêu cầu phi chức năng

Khía cạnh	Yêu cầu
Toàn vẹn dữ liệu	Không bao giờ tồn tại hai tài khoản cùng một username, một email hay một số điện thoại đã xác minh; xóa mềm giữ lại mọi bản ghi tài khoản
Tenancy & quyền	Phạm vi tài khoản (organizer/merchant) được phân giải theo từng người dùng; thao tác trạng thái, hồ sơ, cấu hình đều được gác quyền
Quyền riêng tư	Yêu cầu OTP lại cho một định danh đã tồn tại gửi âm thầm - không lộ việc tài khoản đó đã tồn tại
Tính nhất quán	Đăng ký tạo tài khoản, hồ sơ, định danh và cấu hình mặc định cùng một lúc; không tạo dở dang
i18n	Nhãn và trạng thái hướng người dùng song ngữ Anh/Việt; ngôn ngữ người dùng chọn chi phối cách hiển thị

7. UX & Luồng

Các màn hình chính: trang hồ sơ cá nhân với ảnh đại diện tại Client, nút đổi ngôn ngữ ở header, và khu quản lý trạng thái tài khoản (kích hoạt, vô hiệu hóa, chặn, lưu trữ) cho người được gán quyền tại cả Client và Back Office.

8. Dữ liệu & Miền nghiệp vụ

Khái niệm	Vai trò
Tài khoản người dùng	Tài khoản bền vững - ID do hệ thống sinh ra, trạng thái, xóa mềm, phạm vi organizer/merchant
Định danh đăng nhập	Một giá trị đăng nhập (username, email, số điện thoại) kèm cờ xác minh, không bao giờ trùng giữa hai tài khoản
Hồ sơ người dùng	Thông tin cá nhân một-cho-mỗi-người dùng - họ tên, ngày sinh, ngôn ngữ, liên hệ, ảnh đại diện
Cấu hình người dùng	Một thiết lập cá nhân theo từng người dùng, nhóm và đánh khóa duy nhất theo code

Chỉ mang tính khái niệm - mô hình dữ liệu và quy tắc đầy đủ nằm trong domain model của identity.

9. Phụ thuộc & Giả định

Phụ thuộc vào

#	Feature	Phụ thuộc điều gì
01	AUTH Xác thực	đăng ký, gửi mã OTP và việc kiểm soát đăng nhập nằm trong vùng AUTH.
02	ROLE Vai trò & phạm vi	tài khoản là chủ thể mà vai trò và phạm vi organizer/merchant gắn vào.
03	MORG Thành viên đa organizer	một người dùng thuộc nhiều organizer cùng lúc thuộc vùng này; PRD này không mô tả lại.
04	Lõi nền tảng dùng chung	mô hình dữ liệu dùng chung, phạm vi và phần kết nối cấu hình.

Giả định

#	Giả định	Sai thì sao
01	Một người dùng đăng ký qua luồng đăng ký, việc này kích hoạt tạo tài khoản, hồ sơ, định danh và cấu hình mặc định.	Đăng ký không kích hoạt đủ bốn phần này thì một người dùng mới thiếu định danh hoặc cấu hình, và các module khác không có gì ổn định để gắn vai trò lên.
02	Kênh OTP (email/SMS) tồn tại để xác minh định danh email và số điện thoại.	Không có kênh OTP thì email và số điện thoại mới thêm mãi mãi ở trạng thái chưa xác minh, và người dùng không có cách nào xác minh định danh của mình.

10. Kế hoạch phát hành & Tiêu chí

Khía cạnh	Kế hoạch
Phase	P1 (nền tảng) - xem danh mục tính năng URD
Rollout	Mọi người dùng; không có feature flag
Migration	Không cần cho tài khoản mới; cấu hình mặc định được cấp cho từng người dùng khi đăng ký
Tiêu chí phát hành	Đăng ký kiểm chứng đủ tài khoản, hồ sơ, định danh và cấu hình mặc định; xác minh OTP đổi trạng thái định danh; đổi trạng thái tài khoản kiểm soát việc đăng nhập; xóa mềm giữ lại dữ liệu
Theo dõi	Tỷ lệ đăng ký thành công, tỷ lệ xác minh OTP, số ca vi phạm lời hứa duy nhất định danh, độ phủ khởi tạo cấu hình

Tham chiếu

• URD: Quản lý Người dùng - Tài khoản người dùng
• Xây trên: Xác thực · Thành viên đa organizer · Vai trò & phạm vi - URD Phân quyền
• PRD liên quan: Định danh & cấu hình người dùng
• Module: Quản lý Người dùng - URD
• Developer: @nx/identity · domain model · @nx/core

Rủi ro & Câu hỏi mở

#	Rủi ro / câu hỏi	Giảm thiểu / trạng thái
01	Hai tài khoản dùng trùng định danh	Không tài khoản nào dùng trùng username, hoặc trùng một email hay số điện thoại đã xác minh với tài khoản khác
02	Dò tài khoản qua yêu cầu mã	Yêu cầu OTP lại cho một định danh đã tồn tại gửi âm thầm
03	Tài khoản tạo dở khi đăng ký thất bại	Tài khoản, hồ sơ, định danh và cấu hình mặc định được tạo cùng một lúc; không tạo dở dang
04	Kích hoạt lại một tài khoản đã lưu trữ	Lưu trữ là trạng thái kết thúc theo thiết kế của một tài khoản

Câu hỏi thường gặp

#	Câu hỏi	Trả lời
01	Một người dùng có thể có nhiều hơn một email hoặc số điện thoại không?	Có - một tài khoản giữ được nhiều định danh (username, email, số điện thoại). Username bắt buộc và đã xác minh; email và số điện thoại bắt đầu chưa xác minh và cần một mã OTP.
02	Hai người có thể dùng chung một email hoặc số điện thoại đã xác minh không?	Không - không bao giờ tồn tại hai tài khoản cùng một username, một email hay một số điện thoại đã xác minh.
03	Điều gì xảy ra khi một tài khoản bị xóa?	Tài khoản được xóa mềm - bản ghi được giữ lại và không bao giờ bị xóa vật lý.
04	Vì sao người bị vô hiệu hóa hoặc bị chặn không đăng nhập được?	Trạng thái kiểm soát việc đăng nhập - chỉ tài khoản đang hoạt động mới xác thực được.
05	Lưu trữ có đảo ngược được không?	Theo thiết kế là không - Lưu trữ được xem là trạng thái kết thúc của một tài khoản.
06	Ai được đổi trạng thái tài khoản của người khác?	Người được gán quyền quản lý tài khoản, ở trang Client hay ở Back Office, khóa, mở khóa hoặc lưu trữ tài khoản người khác trong phạm vi của mình - không giới hạn ở một chức danh cụ thể.
07	Cấu hình mặc định đến từ đâu?	Một bộ cấu hình mặc định được tạo tự động khi đăng ký; người dùng tự đọc và cập nhật cấu hình của chính mình sau đó.
08	Yêu cầu lại một mã OTP cho một email đã tồn tại có để lộ rằng tài khoản đó tồn tại không?	Không - yêu cầu lại cho một định danh đã tồn tại gửi âm thầm để tránh lộ thông tin.