Quản lý Người dùng & Xác thực Phase 1 Built
Tài liệu nghiệp vụ (BA)
UC — Use Case · SRS — Đặc tả yêu cầu · UI — Đặc tả giao diện
Module này là cổng vào duy nhất của toàn bộ hệ thống NexPickle dành cho chủ sân: từ landing page và onboarding sân đầu tiên, qua đăng nhập Admin Portal (email/SĐT + mật khẩu, Google/Zalo SSO), xác thực OTP 2 lớp và phiên JWT, đến quản lý đội ngũ nhân viên theo ca làm việc và chấm công. Mọi chủ sân và nhân viên đều đi qua đây trước khi chạm tới bất kỳ tính năng vận hành nào.
1. Định danh
| Thuộc tính | Giá trị |
|---|---|
| Module ID | F-01 / F-02 / OW-08 |
| Hạng | Core |
| Trạng thái | Built (P1) · In-progress (SSO · 2FA · ca làm việc) |
| Giai đoạn | P1 (đăng nhập, OTP, onboarding, nhân viên) · P2 (SSO, 2FA, lịch ca, lương) |
| Ưu tiên | HIGH |
| Người dùng chính | Chủ sân · Quản lý ca · Thu ngân · Xem báo cáo |
2. Mục đích & Phạm vi
| Bao gồm | Loại trừ |
|---|---|
| Landing page + onboarding chủ sân (đăng ký, thiết lập sân đầu tiên) | Phân quyền RBAC chi tiết (do Phân quyền sở hữu) |
| Đăng nhập Admin Portal (email/SĐT + mật khẩu, Google/Zalo SSO) | Cấu hình cơ sở · tích hợp (do Nền tảng sở hữu) |
| Xác thực OTP 2 lớp (đăng ký · quên mật khẩu · 2FA) | Đặt sân của khách chơi (luồng CB System riêng) |
| Phiên JWT, refresh token, "Ghi nhớ đăng nhập", đăng xuất | Ghi nhật ký bảo mật (do Audit Log lưu) |
| Quên / đổi mật khẩu, khoá tài khoản, brute-force protection | Báo cáo doanh thu nhân viên (do Báo cáo sở hữu) |
| Quản lý nhân viên: danh sách, hồ sơ, tạo tài khoản | Tính thuế và hoá đơn |
| Ca làm việc, lịch tuần, chấm công, lương cơ bản |
3. Năng lực
| Năng lực | Người dùng làm được gì |
|---|---|
| Onboarding chủ sân | Đăng ký, xác thực OTP, thiết lập sân đầu tiên (tên sân · số lượng sân · QR), vào Welcome Dashboard |
| Landing page | Khách xem giá trị sản phẩm, tính năng, số liệu; CTA "Dùng thử miễn phí 14 ngày" |
| Đăng nhập | Email hoặc SĐT + mật khẩu (toggle ẩn/hiện); tick "Ghi nhớ đăng nhập" |
| SSO Google / Zalo | Đăng nhập nhanh qua OAuth 2.0, map với tài khoản đã đăng ký |
| OTP 2 lớp | Mã 6 số gửi SMS/email, hết hạn 5 phút, dùng cho đăng ký · quên mật khẩu · 2FA |
| Phiên JWT | Token ES256 chứa role + branch scope; tự refresh khi còn < 15 phút |
| Quên / đổi mật khẩu | Đặt lại qua OTP; revoke toàn bộ phiên cũ |
| Khoá tài khoản | Tự khoá 15 phút sau 5 lần sai; Owner khoá thủ công khi nhân viên nghỉ việc |
| Danh sách nhân viên | Xem table nhân viên: tên · vai trò · chi nhánh · trạng thái |
| Tạo tài khoản nhân viên | Thêm NV với mật khẩu tạm, gửi email kích hoạt |
| Ca làm việc | Tạo ca, lập lịch tuần, nhân viên xem lịch của mình |
| Chấm công | Check-in/check-out ca, điều chỉnh thủ công, báo cáo giờ làm tháng |
4. Phụ thuộc Module
| Phụ thuộc vào | Vì sao |
|---|---|
| Phân quyền | Tài khoản tạo ở đây được gán vai trò Owner/Manager/Cashier/Viewer; JWT mang role + branch scope |
| Nền tảng | Gửi OTP/cảnh báo qua kênh thông báo; ghi mọi sự kiện bảo mật vào audit log |
| SMS / Email Gateway | Gửi OTP xác minh và email kích hoạt nhân viên (VNPT/Viettel · SendGrid) |
| Google / Zalo OAuth | Đăng nhập nhanh qua SSO (P2) |
5. Backend Packages
Chi tiết triển khai nằm trong tài liệu lập trình viên - mục này chỉ ánh xạ module tới các service vận hành nó.
| Package | Vai trò | Tài liệu lập trình viên |
|---|---|---|
@nx/auth | Xác thực, JWT/refresh token, OTP, quên/đổi mật khẩu, khoá tài khoản | auth |
@nx/onboarding | Landing, đăng ký chủ sân, thiết lập sân đầu tiên, Welcome Dashboard | onboarding |
@nx/staff | Hồ sơ nhân viên, ca làm việc, lịch tuần, chấm công, lương cơ bản | staff |
6. Luồng người dùng chính
Đăng nhập Admin Portal + 2FA
Onboarding chủ sân mới
Tạo & khoá tài khoản nhân viên
7. Vai trò & Phân quyền
| Vai trò | Được phép | Không được phép |
|---|---|---|
| Owner (Chủ sân) | Onboarding sân, tạo/khoá/gán vai trò nhân viên, cấu hình lương, xem chấm công | - |
| Manager (Quản lý ca) | Thêm/sửa nhân viên chi nhánh, lập lịch ca, chấm công, xem bảng lương chi nhánh | Gán vai trò RBAC, onboarding sân mới |
| Cashier (Thu ngân) | Đăng nhập/đăng xuất, đổi mật khẩu, xem lịch ca và lương cá nhân, check-in/out ca | Xem danh sách nhân viên, sửa hồ sơ người khác |
| Viewer (Xem báo cáo) | Đăng nhập read-only, xem lịch ca cá nhân | Truy cập quản lý nhân sự, đổi cài đặt bảo mật |
8. Trạng thái & Lộ trình
| Giai đoạn | Năng lực |
|---|---|
| P1 | Landing, đăng ký + OTP, đăng nhập email/SĐT, JWT/refresh, "Ghi nhớ", quên/đổi mật khẩu, khoá tài khoản, thiết lập sân, danh sách & tạo nhân viên, ca cơ bản, chấm công |
| P2 | Google/Zalo SSO, 2FA OTP SMS/Email (bắt buộc Owner), thiết bị tin cậy, cảnh báo đăng nhập lạ, lịch ca nâng cao, đổi ca/xin nghỉ, lương & bảng lương |
| P3 | Passkey/WebAuthn, đăng nhập sinh trắc học, IP allowlist per chi nhánh, app nhân viên, AI tối ưu lịch ca, tích hợp payroll |
9. Trang liên quan
- Phân quyền (RBAC)
- Nền tảng (Thông báo · Cài đặt · Audit)
- Tài liệu lập trình viên: Auth Service