PRD: Xác thực & xác minh tài khoản

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

Xác thực & xác minh tài khoản là gì

Quản lý Người dùng là nền móng của cả hệ thống - mọi module khác đều tin vào danh tính và phạm vi mà nó cấp. Đăng ký và đăng nhập bằng mật khẩu đã chạy từ trước; PRD này khép ba khoảng trống còn lại trên nền đó: xác minh danh tính trước khi vào việc, đặt mật khẩu lần đầu cho tài khoản được tạo hộ, và chặn đăng nhập chéo giữa ba trang Client, Sale và Back Office.

Ba khoảng trống được khép lại

Trước đợt này, một tài khoản mới chưa chứng minh mình sở hữu số điện thoại hay email trước khi bắt tay vào dùng app. Người quên mật khẩu ở Client tự lo được, nhưng nhân viên được tạo tài khoản hộ ở Back Office thì không có lối tự đặt mật khẩu lần đầu. Và ba trang Client, Sale, Back Office phục vụ ba nhóm người dùng khác hẳn nhau, nhưng chưa có gì ngăn một tài khoản quản trị đăng nhập lẫn vào trang khách hàng, hay ngược lại.

Đợt này khép cả ba khoảng trống trên nền sign-up/sign-in/băm mật khẩu sẵn có: một wizard onboarding lấy xác minh số điện thoại làm cổng bắt buộc, một route riêng để chủ hoặc quản lý đặt mật khẩu cho tài khoản tạo hộ, và chặn đăng nhập chéo trang theo tầng role - tất cả từ phía server, không chỉ ở giao diện.

Một tài khoản, từ đăng ký tới vào việc

Bước	Việc xảy ra
1. Đăng ký	Tại Client, nhập họ, tên, username, mật khẩu, tick đồng ý điều khoản → tài khoản, hồ sơ, định danh username và cấu hình mặc định được tạo cùng lúc, vào app ngay
2. Onboarding	Wizard 4 bước chạy kế tiếp: xác minh số điện thoại (cổng bắt buộc) → tạo doanh nghiệp → chọn gói → chào mừng
3. Đăng nhập hằng ngày	Cùng một ô định danh (username, hoặc email/SĐT đã xác minh) kèm mật khẩu dùng chung ở cả Client, Sale, Back Office
4. Quên mật khẩu	Tại Client, tự đặt lại qua đúng một kênh khôi phục (email gộp mã 6 số và link, hoặc SMS OTP)
5. Nhân viên tạo hộ	Chủ hoặc quản lý gửi một link riêng để nhân viên tự đặt mật khẩu lần đầu

Chỗ dễ sai nhất

Chặn đăng nhập theo tầng role nằm ở server, không phải giao diện

Tài khoản có role hệ thống trên Owner (Super Admin, Admin, Operator) không đăng nhập được vào Client hay Sale; tài khoản có role từ Owner trở xuống không đăng nhập được vào Back Office.

Việc từ chối cấp token xảy ra ngay tại server. Gọi thẳng API cũng bị chặn, không chỉ ẩn nút trên giao diện.

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

Mục tiêu

• Đăng ký tài khoản tại Client trong một thao tác tất-cả-hoặc-không - tài khoản, hồ sơ, định danh username và cấu hình mặc định được tạo cùng nhau; người dùng vào app ngay, việc xác minh xử lý ở bước onboard kế tiếp.
• Wizard onboarding 4 bước ngay sau đăng ký, với bước xác minh số điện thoại là cổng bắt buộc - chưa xong thì không đi tiếp.
• Username là định danh chính của hệ thống; số điện thoại bắt buộc xác minh sau onboard cho người dùng từ vai trò Owner trở xuống; email luôn là định danh tùy chọn.
• Đăng nhập thống nhất tại cả 3 trang bằng username (hoặc email/SĐT đã xác minh) kèm mật khẩu, trả về một token phiên có phạm vi; phiên hết hạn thì đăng nhập lại.
• Chặn đăng nhập chéo tầng role: role hệ thống trên Owner (Super Admin, Admin, Operator) không vào được Client hay Sale; role từ Owner trở xuống không vào được Back Office - chặn từ server.
• Đổi mật khẩu khi đang đăng nhập, và quên mật khẩu tự phục vụ tại Client qua đúng một kênh khôi phục (email hoặc SMS OTP, không bao giờ song song).
• Một route riêng để chủ sở hữu hoặc quản lý đặt mật khẩu cho tài khoản nhân viên do mình tạo hộ.
• Quản lý định danh sau onboard tại Account Settings - xem danh sách, thêm mới, xác minh email hoặc số điện thoại chưa xác minh.
• Nền cho đăng nhập bằng OTP điện thoại không cần mật khẩu, và bắt buộc xác thực hai yếu tố khi người dùng bật.

Loại trừ

• Quản lý phiên từ xa và thu hồi thủ công.
• Hệ thống mời người dùng qua email hoặc điện thoại.
• Lịch sử đăng nhập / nhật ký kiểm toán chi tiết.
• Quên mật khẩu tự phục vụ tại Back Office hoặc Sale - hai trang này không có màn quên mật khẩu; nhân viên quên mật khẩu ở đây cần chủ sở hữu hoặc quản lý gửi yêu cầu đặt mật khẩu qua route đặt mật khẩu tài khoản tạo hộ (FR-015).

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

Thước đo	Mục tiêu / tín hiệu
Hoàn tất onboarding	Tỷ lệ tài khoản mới vượt cổng xác minh SĐT và hoàn tất cả 4 bước wizard tăng dần
Tự khôi phục	Số lượt quên mật khẩu tự xử lý qua email hoặc SMS OTP, không cần đội vận hành can thiệp, tăng dần
Toàn vẹn đăng nhập theo trang	Không ca đăng nhập nào lọt qua chặn tầng role - admin vào được Client/Sale, hoặc Owner trở xuống vào được Back Office
An toàn credential	100% mật khẩu lưu dạng băm; không phát hiện bản rõ trong log
Độ tin cậy mã	Tỷ lệ gửi OTP (SMS/email) thành công; ca hết hạn hoặc quá số lần thử được xử lý mượt mà
Nhớ đăng nhập	Tỷ lệ phiên dài hạn (đã tick nhớ đăng nhập) không phải đăng nhập lại giữa các lần mở app tăng dần

3. Persona & Tình huống

Persona	Mục tiêu trong tính năng này
Owner	Đăng ký, hoàn tất wizard onboarding, bảo vệ và tự khôi phục tài khoản của mình
Cashier / Employee	Đăng nhập bằng thông tin riêng tại Sale hoặc Client, đổi mật khẩu, được chủ hoặc quản lý đặt mật khẩu hộ khi cần
Chủ / Quản lý	Gửi yêu cầu đặt mật khẩu cho tài khoản nhân viên tạo hộ; quản lý định danh của chính mình tại Account Settings
Super Admin / Admin / Operator	Đăng nhập vào Back Office; không đăng nhập được vào Client hay Sale bằng tài khoản quản trị
Customer	Đăng ký, xác minh SĐT bắt buộc qua wizard, tự khôi phục mật khẩu khi quên

Kịch bản chính: đăng ký tại Client (tài khoản + hồ sơ + username, vào app ngay) → wizard onboarding 4 bước, xác minh SĐT là cổng bắt buộc → tạo doanh nghiệp, gán vai trò Owner → đăng nhập tại Client/Sale/Back Office bằng định danh đã xác minh, nhận token phiên có phạm vi → đổi mật khẩu, hoặc nếu quên thì tự đặt lại qua email/SMS OTP → nếu là nhân viên được tạo hộ và chưa từng đặt mật khẩu, mở link do chủ/quản lý gửi để đặt mật khẩu lần đầu → sau onboard, thêm và xác minh thêm định danh tại Account Settings.

4. User Stories

#	Là một	Tôi muốn	Để
01	người dùng mới	đăng ký bằng username và mật khẩu tại Client trong một bước	tài khoản, hồ sơ và định danh username được tạo cùng nhau và tôi vào app được ngay
02	người dùng mới	wizard onboarding dẫn tôi qua xác minh số điện thoại trước khi tạo doanh nghiệp	tài khoản của tôi có một số điện thoại đáng tin ngay từ đầu
03	người dùng	đăng nhập bằng username kèm mật khẩu ở bất kỳ trang nào (Client, Sale, Back Office) mà tài khoản mình được phép	nhận một token phiên mang đúng vai trò và phạm vi của mình
04	người dùng	tick Nhớ đăng nhập	không phải đăng nhập lại mỗi lần mở app
05	người dùng	đổi mật khẩu sau khi xác nhận mật khẩu hiện tại	xoay vòng credential an toàn
06	người dùng quên mật khẩu tại Client	tự yêu cầu đặt lại, xác minh mã hoặc bấm link, và đặt mật khẩu mới	khôi phục quyền truy cập mà không cần hỗ trợ
07	chủ merchant	gửi yêu cầu đặt mật khẩu cho một tài khoản nhân viên tôi vừa tạo	nhân viên đó tự đặt mật khẩu lần đầu qua một link riêng
08	quản trị viên nội bộ	tài khoản Back Office của mình không đăng nhập được vào Client hay Sale	vai trò quản trị tách bạch khỏi vai trò khách hàng hay nhân viên bán hàng
09	người dùng đã đăng nhập	thêm và xác minh một email hoặc số điện thoại mới tại Account Settings	có thêm cách đăng nhập và khôi phục

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

#	Yêu cầu	Trạng thái	URD ref
FR-001	Đăng ký tại Client bằng Họ, Tên, username và mật khẩu. • Mã giới thiệu là tùy chọn, tick đồng ý điều khoản là bắt buộc. • Đăng ký là một bước duy nhất tạo xong tài khoản và hồ sơ; lỗi giữa chừng thì không có gì được tạo.	✅	URD-AUTH-001..003
FR-002	Đăng ký xong vào app ngay, wizard onboarding 4 bước chạy kế tiếp. • Thứ tự 4 bước: xác minh số điện thoại → tạo doanh nghiệp → chọn gói → chào mừng. • Bước xác minh số điện thoại là cổng bắt buộc: nhập số, nhận mã OTP qua SMS, nhập mã. • Có nút sửa số và nút gửi lại mã ở bước này.	✅	URD-AUTH-009
FR-003	Trong wizard onboarding, người dùng khai thêm được một email tùy chọn. • Xác minh email bằng cách bấm link gửi trong mail. • Bỏ qua bước này không chặn tiến trình onboarding.	✅	URD-AUTH-008
FR-004	Username là định danh chính của hệ thống. • Đăng ký và đăng nhập bằng username luôn dùng được, không phụ thuộc email hay số điện thoại. • Sau khi hoàn tất onboarding, người dùng từ vai trò Owner trở xuống bắt buộc giữ ít nhất một số điện thoại đã xác minh (SMS qua nhà cung cấp VNPAY). • Email luôn là định danh tùy chọn.	✅	URD-AUTH-015..016
FR-005	Đăng nhập tại Client, Sale và Back Office dùng chung một kiểu form: ô định danh (username, hoặc email/số điện thoại đã xác minh) và ô mật khẩu. Đăng nhập xong, người dùng thấy đúng phần việc theo vai trò và organizer/merchant của mình.	✅	URD-AUTH-004..005
FR-006	Phiên đăng nhập chuẩn kéo dài 24 giờ. • Hết hạn thì app tự đăng xuất về màn đăng nhập, người dùng phải đăng nhập lại. • Không có cơ chế gia hạn ngầm.	✅	URD-AUTH-005
FR-007	Màn đăng nhập có ô tick Nhớ đăng nhập: tick thì phiên giữ 30 ngày, không tick thì 24 giờ chuẩn.	🚧	URD-AUTH-005
FR-008	Tài khoản vai trò hệ thống trên Owner (Super Admin, Admin, Operator) không đăng nhập được vào Client và Sale. • Hệ thống từ chối ngay khi đăng nhập, không chỉ ẩn trên giao diện, kèm thông báo rõ lý do. • Muốn dùng như một khách hàng thì phải tạo một tài khoản riêng.	🚧	URD-AUTH-020
FR-009	Tài khoản vai trò từ Owner trở xuống không đăng nhập được vào Back Office. Hệ thống từ chối ngay khi đăng nhập, kèm thông báo rõ lý do.	🚧	URD-AUTH-021
FR-010	Hệ thống ghi lại thời điểm đăng nhập gần nhất của mỗi tài khoản.	✅	URD-AUTH-012
FR-011	Người dùng đang đăng nhập đổi mật khẩu bằng cách nhập mật khẩu hiện tại, mật khẩu mới và xác nhận. Đổi xong, app tự đăng xuất và người dùng đăng nhập lại bằng mật khẩu mới.	✅	URD-AUTH-007
FR-012	Mật khẩu chỉ được lưu dưới dạng băm một chiều bằng thuật toán chuyên cho mật khẩu. Bản rõ của mật khẩu không bao giờ được lưu hay ghi log.	✅	URD-AUTH-006
FR-013	Tại Account Settings, mục Hồ sơ quản lý các định danh của người dùng. • Xem danh sách email và số điện thoại của mình kèm trạng thái xác minh. • Thêm một định danh mới. • Bấm vào một định danh chưa xác minh để xác minh: email qua link hoặc mã, điện thoại qua OTP SMS.	🚧	URD-AUTH-011
FR-014	Tại Client, người dùng tự đặt lại được mật khẩu đã quên. • Hệ thống gửi MỘT email chứa cả mã 6 số lẫn link đặt lại. • Nhập mã hoặc bấm link đều dẫn tới cùng bước đặt mật khẩu mới. • Đặt mật khẩu mới xong, người dùng phải đăng nhập lại.	✅	URD-AUTH-010 · URD-AUTH-017
FR-015	Chủ hoặc quản lý gửi được yêu cầu đặt mật khẩu cho tài khoản nhân viên do mình tạo hộ. • Người nhận bấm link trong tin gửi tới để tự đặt mật khẩu lần đầu. • Khác với luồng quên mật khẩu tự phục vụ ở FR-014.	✅	URD-AUTH-010
FR-016	Mỗi lần gửi mã khôi phục hay kích hoạt chỉ đi qua MỘT kênh. • Tài khoản có email đã xác minh thì gửi qua email, không có thì gửi OTP SMS tới số đã xác minh. • Không bao giờ gửi cả hai kênh cùng lúc.	🔶	URD-AUTH-018
FR-017	Đăng nhập bằng mã OTP gửi qua SMS thay cho mật khẩu, dành cho tài khoản có số điện thoại đã xác minh.	🚧	URD-AUTH-019
FR-018	Người dùng bật được xác thực hai lớp cho tài khoản của mình. Khi bật, đăng nhập bằng mật khẩu phải qua thêm một bước xác thực nữa.	🚧	URD-AUTH-013

5.1 Tiêu chí nghiệm thu

• Đăng ký tại Client với Họ, Tên, username, mật khẩu và tick đồng ý điều khoản → tài khoản, hồ sơ, định danh username và cấu hình mặc định được tạo cùng lúc, người dùng vào thẳng app.
• Đăng ký thiếu tick đồng ý điều khoản, hoặc username đã tồn tại → bị từ chối, không tạo gì.
• Ngay sau đăng ký, bước 1 của wizard onboarding yêu cầu nhập số điện thoại và mã OTP SMS → chưa xác minh xong thì không bấm qua được bước 2 tạo doanh nghiệp.
• Ở bước xác minh số điện thoại, nhập sai số rồi bấm sửa số → số cũ bị gỡ, nhập lại số mới và xác minh lại từ đầu.
• Ở bước xác minh số điện thoại, bấm gửi lại mã → một mã OTP SMS mới được gửi.
• Ở bước xác minh số điện thoại, khai thêm một email tùy chọn rồi bỏ qua xác minh email → wizard vẫn cho đi tiếp sang bước tạo doanh nghiệp.
• Bấm link xác minh email gửi trong mail ở bước onboard → email được đánh dấu đã xác minh.
• Hoàn tất cả 4 bước wizard → doanh nghiệp được tạo, người dùng được gán vai trò Owner, vào màn chào mừng.
• Đăng nhập tại Client, Sale hoặc Back Office bằng username và mật khẩu đúng, định danh đã xác minh → nhận token phiên mang vai trò và phạm vi organizer/merchant.
• Đăng nhập bằng một email hoặc số điện thoại đã xác minh (thay vì username) kèm mật khẩu đúng → vẫn đăng nhập thành công.
• Đăng nhập với mật khẩu sai, hoặc định danh chưa xác minh → bị từ chối kèm lý do.
• Token phiên hết hạn trong lúc dùng app → app tự đăng xuất, đưa về màn đăng nhập; đăng nhập lại thì dùng tiếp.
• Tạo thêm một merchant mới → merchant mới dùng được ngay, không phải đăng xuất đăng nhập lại.
• Đăng nhập có tick Nhớ đăng nhập, đóng app rồi mở lại trong thời hạn dài → vẫn còn phiên, không phải đăng nhập lại.
• Đăng nhập không tick Nhớ đăng nhập → phiên hết theo thời hạn chuẩn.
• Một tài khoản Super Admin, Admin hoặc Operator thử đăng nhập vào Client hoặc Sale → bị server từ chối cấp token, màn đăng nhập báo rõ lý do.
• Một tài khoản Owner, Cashier, Employee hoặc Customer thử đăng nhập vào Back Office → bị server từ chối cấp token, kèm thông báo rõ.
• Người nội bộ muốn thao tác như một khách hàng → phải tạo một tài khoản riêng cho việc đó, không dùng chung tài khoản quản trị.
• Đăng nhập thành công → dấu thời gian đăng nhập gần nhất trên tài khoản được cập nhật.
• Đang đăng nhập, đổi mật khẩu với mật khẩu hiện tại đúng, mật khẩu mới và xác nhận khớp nhau → mật khẩu đổi thành công, tài khoản tự đăng xuất, phải đăng nhập lại bằng mật khẩu mới.
• Đổi mật khẩu nhưng nhập sai mật khẩu hiện tại → bị từ chối, mật khẩu cũ không đổi.
• Xem log hoặc response bất kỳ liên quan đến mật khẩu → không bao giờ thấy mật khẩu dạng bản rõ, chỉ thấy giá trị đã băm ở tầng lưu trữ.
• Tại Account Settings, mở mục Hồ sơ → thấy danh sách định danh hiện có kèm nhãn trạng thái xác minh; thêm một email hoặc số điện thoại mới → định danh mới xuất hiện ở trạng thái chưa xác minh, bấm vào để mở luồng xác minh và hoàn tất.
• Tại Client, yêu cầu quên mật khẩu cho một tài khoản có email đã xác minh → nhận một email duy nhất chứa cả mã 6 số và link đặt lại; nhập mã hoặc bấm link đều dẫn tới cùng màn đặt mật khẩu mới.
• Đặt mật khẩu mới xong ở luồng quên mật khẩu → mật khẩu được lưu dạng băm, response không mang token phiên, phải đăng nhập lại bằng mật khẩu mới.
• Chủ sở hữu tạo một tài khoản nhân viên rồi gửi yêu cầu đặt mật khẩu cho tài khoản đó → nhân viên nhận được một link riêng, bấm vào để đặt mật khẩu lần đầu tại route đặt mật khẩu tài khoản tạo hộ.
• Một tài khoản có email đã xác minh yêu cầu khôi phục hoặc kích hoạt đăng nhập → chỉ nhận email, không nhận thêm SMS song song.
• Một tài khoản không có email đã xác minh yêu cầu khôi phục hoặc kích hoạt đăng nhập → nhận một OTP qua SMS tới số điện thoại đã xác minh.
• Một người dùng có số điện thoại đã xác minh yêu cầu đăng nhập bằng OTP → nhận mã qua SMS, nhập đúng mã còn hạn → nhận token phiên mà không cần nhập mật khẩu.
• Yêu cầu OTP đăng nhập nhưng nhập mã sai hoặc mã đã hết hạn → bị từ chối kèm lý do.
• Bật bắt buộc xác thực hai yếu tố cho tài khoản → lần đăng nhập kế tiếp bằng mật khẩu phải qua thêm bước xác thực thứ hai mới nhận được token phiên.

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	Đăng ký là một thao tác tất-cả-hoặc-không - nếu bất kỳ bước nào thất bại, không tạo gì (tài khoản, hồ sơ, định danh, cấu hình)
An toàn credential	Mật khẩu băm trước khi lưu; đặt lại/đặt mới đều ghi mật khẩu đã băm; response quên-mật-khẩu và đặt-mật-khẩu-tạo-hộ không bao giờ mang token phiên
Tenancy & authz	Token phiên mang vai trò và phạm vi organizer/merchant; mọi thao tác trừ đăng ký/đăng nhập/OTP đều cần xác thực
Chặn theo tầng role	Việc từ chối cấp token theo ngữ cảnh app (Client/Sale/Back Office) nằm ở server, không chỉ ở giao diện - gọi thẳng API cũng bị chặn
Độ bền OTP	Mọi mã OTP (email, SMS) có thời hạn và giới hạn số lần thử; ca hết hạn hoặc quá số lần trả lỗi rõ ràng
Kênh khôi phục	Một luồng khôi phục hoặc kích hoạt đăng nhập chỉ gửi đúng một kênh (email hoặc SMS OTP), không bao giờ gửi song song
Phiên	Đúng một token phiên, không refresh token; hết hạn buộc đăng xuất; thời hạn 24 giờ chuẩn / 30 ngày khi tick Nhớ đăng nhập
Khả năng cấu hình	Nội dung mail và mẫu SMS điều khiển bởi cấu hình lưu tập trung, có thể cấu hình, không phải chuỗi cố định
i18n	Nhãn, trạng thái và nội dung mail/SMS ở phần hiển thị là song ngữ (Anh / Việt)

7. UX & Luồng

Màn hình chính: màn đăng ký và wizard onboarding 4 bước tại Client; màn đăng nhập dùng chung layout ở cả Client, Sale và Back Office (khác thông báo chặn theo tầng role); mục Hồ sơ trong Account Settings cho quản lý định danh sau onboard; màn quên mật khẩu tại Client; route riêng đặt mật khẩu tài khoản tạo hộ.

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

Entity	Vai trò
Tài khoản người dùng	Danh tính đã xác thực, sở hữu credential, định danh, hồ sơ và vai trò
Credential mật khẩu	Bí mật mật khẩu băm dùng để xác thực
Định danh đăng nhập	Một giá trị đăng nhập (username / email / điện thoại), trùng lặp toàn cục theo từng loại, mang cờ verified
Phiên đăng nhập	Một token phiên duy nhất; cờ Nhớ đăng nhập quyết định thời hạn (24 giờ / 30 ngày)
Phiên mã một lần	Trạng thái ngắn hạn hỗ trợ xác minh, khôi phục và đăng nhập OTP (yêu cầu → gửi, có thời hạn và giới hạn số lần, gắn một kênh - email hoặc SMS)
Yêu cầu khôi phục	Một yêu cầu đặt lại mật khẩu, tự khởi xướng (quên mật khẩu) hoặc khởi xướng hộ (chủ/quản lý gửi cho tài khoản nhân viên tạo hộ)
Tầng role	Phân nhóm vai trò quyết định trang nào được đăng nhập - trên Owner (Super Admin, Admin, Operator) chỉ vào Back Office; Owner trở xuống (Owner, Cashier, Employee, Customer) chỉ vào Client/Sale

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

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

Phụ thuộc vào

#	Feature	Phụ thuộc điều gì
01	User Account (URD-USR)	người dùng, định danh và vòng đời verified mà tính năng này điều khiển.
02	Vai trò & phạm vi (URD-ROLE - Phân quyền)	đăng ký gán vai trò mặc định GUEST; đăng nhập phân giải vai trò và phạm vi vào token; tám vai trò cố định là cơ sở cho chặn theo tầng role.
03	Quản lý Nhân viên (URD-EMP)	tài khoản nhân viên do chủ/quản lý tạo hộ, đối tượng của luồng đặt mật khẩu tài khoản tạo hộ.
04	Commerce	tạo doanh nghiệp ở bước 2 của wizard onboarding cấp vai trò Owner.
05	Hạ tầng gửi tin	nhà cung cấp SMS VNPAY cho OTP số điện thoại; gửi mail cho mã và link email; ứng dụng Client/Sale/Back Office cho các màn đăng nhập, onboarding, verify và reset.

Giả định

#	Giả định	Sai thì sao
01	Một số điện thoại hoặc email khai báo có thể nhận được để mã hoặc link được gửi tới.	Mã hoặc link không tới nơi, người dùng bị kẹt giữa chừng ở bước xác minh, quên mật khẩu, hoặc đặt mật khẩu tài khoản tạo hộ.
02	Cấu hình mail và mẫu SMS sẵn sàng trước khi gửi các loại thông báo xác minh/khôi phục.	Gửi thông báo thất bại hoặc gửi sai nội dung, chặn toàn bộ luồng xác minh hoặc khôi phục liên quan.
03	Username là bắt buộc và mặc định được coi là đã xác minh; email và số điện thoại khởi đầu chưa xác minh.	Một định danh không đủ tin cậy bị coi là đã xác minh, mở đường cho xác thực giả mạo.

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 feature URD
Rollout	Mọi người dùng trên cả 3 trang; không feature flag
Migration	Không cần migration dữ liệu mới - tái dùng bảng tài khoản, định danh và cấu hình sẵn có
Tiêu chí phát hành	Wizard onboarding xác minh SĐT trọn vẹn; đăng nhập chặn đúng theo tầng role ở cả 3 trang; quên mật khẩu và đặt mật khẩu tài khoản tạo hộ trọn vẹn; mật khẩu luôn lưu dạng băm
Theo dõi	Tỷ lệ hoàn tất wizard, tỷ lệ gửi/hoàn tất OTP theo kênh, số ca đăng nhập bị chặn theo tầng role, lý do đăng nhập thất bại

Tham chiếu

• URD: Quản lý Người dùng - Xác thực - yêu cầu và tiêu chí chấp nhận của AUTH
• Xây trên: User Account · Vai trò & phạm vi - URD Phân quyền · Quản lý Nhân viên
• PRD liên quan: Quản lý nhân viên · User Account & Configuration · Định danh & cấu hình người dùng
• Module: Quản lý Người dùng - URD
• Developer: @nx/identity · mô hình domain

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

#	Rủi ro / câu hỏi	Giảm thiểu / trạng thái
01	Đăng ký dở dang để lại tài khoản mồ côi	Đăng ký là tất-cả-hoặc-không; bất kỳ bước nào lỗi cũng rollback toàn bộ
02	Dò mã OTP / phát lại	Mã có thời hạn và giới hạn số lần thử; vượt ngưỡng trả lỗi rõ ràng
03	Response quên mật khẩu rò rỉ token phiên	Token phiên luôn bị loại khỏi response đặt-lại-mật-khẩu và đặt-mật-khẩu-tạo-hộ
04	Người dùng không có email khi quên mật khẩu	Kênh khôi phục tự chuyển sang SMS OTP tới số điện thoại đã xác minh, không chặn cứng vào email
05	Gọi thẳng API bỏ qua chặn phía giao diện	Việc từ chối cấp token theo ngữ cảnh app nằm ở server, không chỉ ở màn hình đăng nhập
06	Tài khoản nhân viên tạo hộ chưa từng đặt mật khẩu bị khóa ngoài	Route đặt mật khẩu tài khoản tạo hộ cho phép chủ/quản lý gửi lại yêu cầu bất cứ lúc nào
07	Bắt buộc 2FA và đăng nhập OTP điện thoại là hai lối đăng nhập song song với mật khẩu	Cả hai đều đi qua cùng cơ chế cấp token phiên có phạm vi, không mở thêm đường tắt quyền

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

#	Câu hỏi	Trả lời
01	Đăng ký xong tôi có phải xác minh gì ngay không?	Không - đăng ký xong bạn vào app ngay. Wizard onboarding chạy ngay sau đó và bước xác minh số điện thoại là cổng bắt buộc của wizard, không phải của đăng ký.
02	Tôi đăng nhập được bằng email hay số điện thoại không, hay chỉ username?	Cả ba - ô định danh trên màn đăng nhập nhận username, email hoặc số điện thoại, miễn là định danh đó đã xác minh.
03	Tôi quên mật khẩu thì làm sao?	Ở Client, bạn tự yêu cầu đặt lại; hệ thống gửi một email chứa cả mã 6 số và link (nếu bạn có email đã xác minh), hoặc một OTP SMS (nếu không). Ở Back Office và Sale không có màn này - nhân viên cần chủ hoặc quản lý gửi yêu cầu đặt mật khẩu hộ.
04	Route đặt mật khẩu tài khoản tạo hộ khác gì quên mật khẩu?	Quên mật khẩu do chính chủ tài khoản tự khởi xướng. Đặt mật khẩu tài khoản tạo hộ do chủ hoặc quản lý khởi xướng thay cho một nhân viên họ vừa tạo - người nhận bấm link để đặt mật khẩu lần đầu.
05	Vì sao một tài khoản quản trị không đăng nhập được vào Client?	Vì tầng role trên Owner (Super Admin, Admin, Operator) chỉ dành cho Back Office; muốn dùng như một khách hàng thì phải tạo một tài khoản riêng cho việc đó.
06	Nhớ đăng nhập hoạt động ra sao?	Tick vào ô này khi đăng nhập thì token phiên được cấp với thời hạn 30 ngày thay vì 24 giờ chuẩn.