| Phiên bản | 1.0 |
| Hệ thống | Hệ thống Xác thực |
| Module | AUTH - Xác thực |
| Cơ sở dữ liệu | auth_db |
| Ngày | 2026-08-05 |
| Tác giả | Nam Nguyen |
| Trạng thái | Bản nháp |
Tài liệu này định nghĩa các yêu cầu phần mềm cho module Xác thực của Hệ thống Xác thực.
Module Xác thực xử lý:
| Module | Loại phụ thuộc | Mô tả |
|---|---|---|
| SMS | Async (RabbitMQ) | SMS queue worker chạy trong AUTH service, consume từ queue password.reset.sms, gọi SMS module để gửi OTP đặt lại mật khẩu |
| Async (RabbitMQ) | EMAIL queue worker chạy trong AUTH service, consume từ queue verification.email, password.reset.email và invitation.email, gọi EMAIL module để gửi email | |
| LOG | Async (RabbitMQ) | Gửi sự kiện xác thực đến module Logger |
| Thuật ngữ | Định nghĩa |
|---|---|
| FR | Yêu cầu Chức năng |
| NFR | Non-Yêu cầu Chức năng |
| UC | Trường hợp Sử dụng |
| JWT | JSON Web Token |
| OTP | One-Time Password |
| RBAC | Role-Based Access Control |
| Khía cạnh | Value |
|---|---|
| Module Code | AUTH |
| Module Name | Authentication |
| Mô tả | Tài khoản người dùng, đăng nhập, vai trò, phiên, xác minh |
| Cơ sở dữ liệu | auth_db |
| Tables | auth_users, auth_sessions, auth_accounts, auth_verification, auth_roles, auth_user_roles, auth_organizations, auth_members, auth_teams, auth_team_members, auth_invitations |
| Tech Stack | NestJS, Better Auth, Drizzle ORM, PostgreSQL |
| Mã YC | Module | Yêu cầu | Trường hợp | Ưu tiên | Mô tả |
|---|---|---|---|---|---|
| FR-001 | AUTH | Đăng ký Người dùng | UC-01 | Cao | Hệ thống cho phép người dùng đăng ký bằng email + mật khẩu + tên. Người dùng đăng ký nhận vai trò hệ thống user mặc định. Sau khi tạo tài khoản, AUTH publish sự kiện verification.email.requested lên RabbitMQ (queue: verification.email). Email queue worker bên trong AUTH service consume sự kiện và gọi EMAIL module để gửi email xác minh. |
| FR-002 | AUTH | Đăng nhập | UC-02 | Cao | Hệ thống xác thực người dùng qua email hoặc số điện thoại + mật khẩu và trả về JWT token |
| FR-003 | AUTH | Đăng xuất | UC-03 | Cao | Hệ thống hủy phiên làm việc của người dùng khi đăng xuất |
| FR-004 | AUTH | Làm mới Token | UC-04 | Cao | Hệ thống cấp access token mới bằng refresh token |
| FR-005 | AUTH | Đặt lại Mật khẩu (Email) | UC-05 | Cao | Hệ thống gửi liên kết đặt lại mật khẩu đến email người dùng. AUTH publish sự kiện password.reset.email.requested lên RabbitMQ (queue: password.reset.email). Email queue worker trong AUTH consume và gọi EMAIL module để gửi email đặt lại. |
| FR-006 | AUTH | Đặt lại Mật khẩu (Điện thoại) | UC-06 | Cao | Hệ thống gửi OTP đặt lại mật khẩu đến số điện thoại người dùng. AUTH publish sự kiện password.reset.sms.requested lên RabbitMQ (queue: password.reset.sms). SMS queue worker trong AUTH consume và gọi SMS module để gửi OTP. |
| FR-007 | AUTH | Đổi Mật khẩu | UC-07 | Cao | Hệ thống cho phép người dùng đã xác thực đổi mật khẩu |
| FR-008 | AUTH | Xác minh Email | UC-08 | Cao | Hệ thống gửi email xác minh qua module EMAIL và xác minh qua liên kết |
| FR-010 | AUTH | Quản lý Người dùng | UC-10 | Trung bình | Admin có thể liệt kê, xem, cập nhật và xóa người dùng |
| FR-011 | AUTH | Quản lý Vai trò Hệ thống | UC-11 | Trung bình | Admin có thể quản lý các vai trò cấp hệ thống và gán cho người dùng |
| FR-012 | AUTH | Xác thực Xã hội | UC-12 | Cao | Hệ thống cho phép người dùng đăng nhập qua các nhà cung cấp xã hội và liên kết/hủy liên kết tài khoản xã hội |
| FR-013 | AUTH | Quản lý Phiên làm việc | UC-13 | Cao | Hệ thống cho phép người dùng xem, thu hồi và quản lý các phiên làm việc đang hoạt động trên nhiều thiết bị |
| FR-014 | AUTH | Khóa Tài khoản & Đăng nhập giả danh | UC-14 | Trung bình | Admin có thể khóa/mở khóa tài khoản người dùng và đăng nhập giả danh để hỗ trợ |
| FR-015 | AUTH | Quản lý Tổ chức | UC-15 | Cao | Hệ thống cho phép người dùng tạo, cập nhật, xóa tổ chức, quản lý thành viên, và tạo/quản lý các vai trò cấp tổ chức với quyền chi tiết |
| FR-016 | AUTH | Quản lý Nhóm | UC-16 | Trung bình | Hệ thống cho phép tạo nhóm trong tổ chức và quản lý thành viên nhóm |
| FR-017 | AUTH | Quản lý Lời mời | UC-17 | Cao | Hệ thống cho phép mời thành viên vào tổ chức qua email với xác minh dựa trên token. AUTH publish sự kiện invitation.email.requested lên RabbitMQ (queue: invitation.email). Email queue worker trong AUTH consume và gọi EMAIL module để gửi email lời mời. |
| FR-018 | AUTH | Gửi lại Lời mời | UC-18 | Trung bình | Hệ thống cho phép người mời gửi lại lời mời, tạo token mới và hủy token trước đó. AUTH publish sự kiện invitation.email.resent lên RabbitMQ (queue: invitation.email). |
| FR-019 | AUTH | Thu hồi Lời mời | UC-19 | Trung bình | Hệ thống cho phép người mời (chủ sở hữu) thu hồi lời mời đang chờ. |
| FR-020 | AUTH | Xác minh Token Lời mời | UC-20 | Cao | Hệ thống cung cấp đầu nối công khai để xác minh tính hợp lệ của token lời mời. |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Khách (chưa xác thực) |
| Điều kiện tiên quyết | Người dùng chưa đăng nhập; user does not have an existing account |
| Luồng Chính | 1. Người dùng điều hướng đến trang đăng ký 2. Nhập tên, email và mật khẩu 3. Hệ thống kiểm tra dữ liệu đầu vào (email format, password strength) 4. Hệ thống tạo tài khoản người dùng with hashed password and assigns user system role5. AUTH publish sự kiện verification.email.requested lên RabbitMQ (queue: verification.email)6. Email queue worker (trong AUTH service) consume sự kiện và gọi EMAIL module để gửi email xác minh 7. Hệ thống trả về phản hồi thành công with user ID and JWT token |
| Luồng Thay thế | 3a. Email đã tồn tại → Hệ thống trả về 409 Conflict 3b. Mật khẩu quá yếu → Hệ thống trả về 400 Lỗi Validation 6a. EMAIL module không khả dụng → Event vẫn được publish, worker retry exponential backoff (tối đa 5 lần); tài khoản vẫn được tạo |
| Hậu điều kiện | Tài khoản người dùng đã tạo với vai trò user (chưa xác minh); sự kiện verification.email.requested đã publish lên RabbitMQ; email xác minh đã gửi qua EMAIL module; JWT token đã cấp |
| FR Liên quan | FR-001 |
Các vai trò có thể tự đăng ký:
| Role | Mô tả |
|---|---|
user | Tài khoản người dùng tiêu chuẩn (mặc định). Người dùng có thể tạo tổ chức và nhận các vai trò cấp tổ chức (HR, Ứng viên, Nhà tuyển dụng). |
Lưu ý: Tài khoản super_admin không thể tự đăng ký. Chúng phải được tạo bởi admin qua POST /admin/create-user.
| Khía cạnh | Mô tả |
|---|---|
| Actor | Người dùng đã đăng ký |
| Điều kiện tiên quyết | Người dùng có tài khoản đã đăng ký; tài khoản đang hoạt động |
| Luồng Chính | 1. Người dùng điều hướng đến trang đăng nhập 2. Nhập email/phone và mật khẩu 3. Hệ thống kiểm tra thông tin đăng nhập trong database 4. Hệ thống tạo JWT access token (15 phút) và refresh token (7 ngày) 5. Hệ thống tạo bản ghi phiên làm việc 6. Hệ thống trả về token và thông tin người dùng |
| Luồng Thay thế | 3a. Thông tin đăng nhập không hợp lệ → Hệ thống trả về 401 Unauthorized 3b. Tài khoản bị khóa → Hệ thống trả về 403 Forbidden 3c. Tài khoản không hoạt động → Hệ thống trả về 403 Forbidden |
| Hậu điều kiện | Người dùng đã xác thực; phiên đã tạo; token đã cấp |
| FR Liên quan | FR-002 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Người dùng đã xác thực |
| Điều kiện tiên quyết | Người dùng đã đăng nhập với phiên hợp lệ |
| Luồng Chính | 1. Người dùng nhấp nút đăng xuất 2. Hệ thống nhận yêu cầu đăng xuất với access token 3. Hệ thống hủy phiên làm việc hiện tại (xóa bản ghi phiên) 4. Hệ thống trả về phản hồi thành công |
| Luồng Thay thế | 2a. Token hết hạn → Phiên đã không hợp lệ, trả về thành công |
| Hậu điều kiện | Phiên đã hủy; token không còn hiệu lực |
| FR Liên quan | FR-003 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Người dùng đã xác thực (access token hết hạn) |
| Điều kiện tiên quyết | Người dùng có refresh token hợp lệ; access token đã hết hạn |
| Luồng Chính | 1. Client phát hiện access token hết hạn 2. Client gửi refresh token đến /auth/refresh 3. Hệ thống kiểm tra refresh token và phiên 4. Hệ thống tạo access token mới 5. Hệ thống trả về access token mới |
| Luồng Thay thế | 3a. Refresh token hết hạn → Hệ thống trả về 401, người dùng phải đăng nhập lại 3b. Không tìm thấy phiên → Hệ thống trả về 401 |
| Hậu điều kiện | Access token mới đã cấp; phiên vẫn hợp lệ |
| FR Liên quan | FR-004 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Người dùng đã đăng ký (forgot password) |
| Điều kiện tiên quyết | Người dùng có email đã đăng ký; user is not logged in |
| Luồng Chính | 1. Người dùng nhấp "Forgot Password" 2. Nhập email address 3. Hệ thống kiểm tra email tồn tại, tạo token đặt lại mật khẩu, lưu vào auth_verification4. AUTH publish sự kiện password.reset.email.requested lên RabbitMQ (queue: password.reset.email)5. Email queue worker (trong AUTH) consume sự kiện và gọi EMAIL module để gửi email chứa liên kết đặt lại 6. User clicks link in email 7. Nhập mật khẩu mới 8. Hệ thống xác minh token, cập nhật mật khẩu 9. Hệ thống hủy tất cả phiên |
| Luồng Thay thế | 2a. Không tìm thấy email → Hệ thống trả về success (không tiết lộ nếu email tồn tại) 5a. EMAIL module không khả dụng → Event vẫn được publish, worker retry exponential backoff (tối đa 5 lần); user có thể yêu cầu gửi lại 8a. Token hết hạn → Hệ thống trả về 400, user yêu cầu gửi lại 8b. Token không hợp lệ → Hệ thống trả về 400 |
| Hậu điều kiện | Mật khẩu đã cập nhật; all sessions invalidated; event password.reset.email.requested đã publish |
| FR Liên quan | FR-005 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Người dùng đã đăng ký (forgot password) |
| Điều kiện tiên quyết | Người dùng có số điện thoại đã đăng ký; user is not logged in |
| Luồng Chính | 1. Người dùng nhấp "Forgot Password" 2. Chọn tùy chọn điện thoại và nhập số điện thoại 3. Hệ thống kiểm tra SĐT tồn tại, tạo mã OTP, lưu vào auth_verification4. AUTH publish sự kiện password.reset.sms.requested lên RabbitMQ (queue: password.reset.sms)5. SMS queue worker (trong AUTH) consume sự kiện và gọi SMS module để gửi OTP 6. Nhập OTP và mật khẩu mới 7. Hệ thống xác minh OTP 8. Hệ thống cập nhật mật khẩu 9. Hệ thống hủy tất cả phiên |
| Luồng Thay thế | 2a. Không tìm thấy số điện thoại → Hệ thống trả về success (không tiết lộ nếu SĐT tồn tại) 5a. SMS module không khả dụng → Event vẫn được publish, worker retry exponential backoff (tối đa 5 lần); user có thể yêu cầu gửi lại 7a. OTP hết hạn → Hệ thống trả về 422, user có thể yêu cầu OTP mới 7b. OTP không hợp lệ → Hệ thống trả về 422 |
| Hậu điều kiện | Mật khẩu đã cập nhật; all sessions invalidated; event password.reset.sms.requested đã publish |
| FR Liên quan | FR-006 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Người dùng đã xác thực |
| Điều kiện tiên quyết | Người dùng đã đăng nhập |
| Luồng Chính | 1. Người dùng điều hướng đến trang đổi mật khẩu 2. Nhập mật khẩu hiện tại và mật khẩu mới 3. Hệ thống xác minh mật khẩu hiện tại 4. Hệ thống cập nhật mật khẩu 5. Hệ thống trả về phản hồi thành công |
| Luồng Thay thế | 3a. Mật khẩu hiện tại không đúng → Hệ thống trả về 401 4a. Mật khẩu mới giống mật khẩu hiện tại → Hệ thống trả về 400 |
| Hậu điều kiện | Mật khẩu đã cập nhật; các phiên hiện tại vẫn hợp lệ |
| FR Liên quan | FR-007 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Người dùng đã đăng ký |
| Điều kiện tiên quyết | Người dùng có email đã đăng ký; email chưa xác minh |
| Luồng Chính | 1. Đăng ký hoặc yêu cầu xác minh email 2. Hệ thống tạo mã xác minh (token/OTP), lưu vào auth_verification3. AUTH publish sự kiện verification.email.requested lên RabbitMQ (queue: verification.email)4. Email queue worker (trong AUTH) consume sự kiện và gọi EMAIL module để gửi email xác minh 5. Người dùng nhấp verification link 6. Hệ thống xác minh token 7. Hệ thống đánh dấu email_verified = true8. Hệ thống trả về phản hồi thành công |
| Luồng Thay thế | 4a. EMAIL module không khả dụng → Event vẫn được publish, worker retry exponential backoff (tối đa 5 lần); user có thể yêu cầu gửi lại 6a. Token hết hạn → Hệ thống trả về 400, user yêu cầu gửi lại 6b. Token không hợp lệ → Hệ thống trả về 400 |
| Hậu điều kiện | Email đã xác minh; event verification.email.requested đã publish |
| FR Liên quan | FR-008 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Admin |
| Điều kiện tiên quyết | Người dùng đã đăng nhập với vai trò admin |
| Luồng Chính | 1. Admin điều hướng đến quản lý người dùng 2. Hiển thị danh sách người dùng (có phân trang, tìm kiếm) 3. Xem chi tiết, cập nhật hoặc xóa người dùng 4. Hệ thống thực hiện thao tác yêu cầu 5. Hệ thống trả về phản hồi thành công |
| Luồng Thay thế | 3a. Không tìm thấy người dùng → Hệ thống trả về 404 3b. Không được ủy quyền → Hệ thống trả về 403 |
| Hậu điều kiện | Bản ghi người dùng đã cập nhật hoặc xóa |
| FR Liên quan | FR-010 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Admin |
| Điều kiện tiên quyết | Người dùng đã đăng nhập với vai trò admin |
| Luồng Chính | 1. Admin điều hướng đến quản lý vai trò 2. Hiển thị danh sách vai trò 3. Tạo vai trò mới, gán vai trò hoặc xóa vai trò 4. Hệ thống thực hiện thao tác yêu cầu 5. Hệ thống trả về phản hồi thành công |
| Luồng Thay thế | 3a. Tên vai trò đã tồn tại → Hệ thống trả về 409 3b. Không tìm thấy người dùng → Hệ thống trả về 404 |
| Hậu điều kiện | Vai trò đã tạo/gán/xóa; quyền hạn đã cập nhật |
| FR Liên quan | FR-011 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Khách hoặc người dùng đã xác thực |
| Điều kiện tiên quyết | Nhà cung cấp xã hội đã cấu hình (Google, GitHub, v.v.) |
| Luồng Chính | 1. Người dùng nhấp "Đăng nhập với Google" (hoặc nhà cung cấp khác) 2. Hệ thống chuyển hướng đến trang OAuth 3. Xác thực với nhà cung cấp 4. Nhà cung cấp chuyển hướng lại với authorization code 5. Đổi code lấy token 6. Tạo/liên kết tài khoản 7. Hệ thống trả về token phiên |
| Luồng Thay thế | 6a. Email đã tồn tại → Hệ thống liên kết tài khoản xã hội với người dùng hiện có 6b. Nhà cung cấp không khả dụng → Hệ thống trả về 503 |
| Hậu điều kiện | Người dùng đã xác thực qua nhà cung cấp xã hội; phiên đã tạo |
| FR Liên quan | FR-012 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Người dùng đã xác thực |
| Điều kiện tiên quyết | Người dùng đã đăng nhập |
| Luồng Chính | 1. Điều hướng đến cài đặt phiên 2. Hiển thị danh sách phiên đang hoạt động (thiết bị, IP, lần hoạt động cuối) 3. Thu hồi phiên cụ thể hoặc tất cả phiên khác 4. Hệ thống vô hiệu hóa các phiên đã chọn 5. Hệ thống trả về phản hồi thành công |
| Luồng Thay thế | 3a. Phiên đã hết hạn → Hệ thống xóa khỏi danh sách |
| Hậu điều kiện | Các phiên đã chọn bị hủy; người dùng vẫn đăng nhập trên thiết bị hiện tại |
| FR Liên quan | FR-013 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Admin |
| Điều kiện tiên quyết | Admin đã đăng nhập với vai trò admin |
| Luồng Chính | 1. Admin điều hướng đến quản lý người dùng 2. Chọn người dùng để khóa/giả danh 3. Khóa: Cung cấp lý do và thời hạn (tùy chọn) → Khóa người dùng, hủy tất cả phiên 4. Giả danh: Tạo phiên admin với tư cách người dùng 5. Dừng đăng nhập giả danh để quay lại phiên admin |
| Luồng Thay thế | 3a. Người dùng đã bị khóa → Hệ thống trả về 409 4a. Không tìm thấy người dùng → Hệ thống trả về 404 |
| Hậu điều kiện | Người dùng bị khóa (phiên bị thu hồi) hoặc admin đang đăng nhập giả danh người dùng |
| FR Liên quan | FR-014 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Người dùng đã xác thực (chủ sở hữu/admin cho quản lý vai trò) |
| Điều kiện tiên quyết | Người dùng đã đăng nhập |
| Luồng Chính | 1. Tạo tổ chức với tên và slug 2. Kiểm tra slug duy nhất 3. Tạo tổ chức, người dùng trở thành chủ với vai trò Employer4. Cập nhật thông tin, quản lý thành viên 5. Gán vai trò tổ chức (HR, Candidate, Employer) cho thành viên 6. Tạo thêm vai trò tùy chỉnh với quyền chi tiết 7. Xóa tổ chức |
| Luồng Thay thế | 2a. Slug đã được sử dụng → Hệ thống trả về 409 5a. Quyền không hợp lệ → Hệ thống trả về 400 5b. Tên vai trò đã tồn tại → Hệ thống trả về 409 6a. Không được ủy quyền → Hệ thống trả về 403 |
| Hậu điều kiện | Tổ chức đã tạo/cập nhật/xóa; thành viên đã quản lý; vai trò tổ chức (HR, Candidate, Employer) đã gán |
| FR Liên quan | FR-015 |
Vai trò Tổ chức:
Mỗi tổ chức có thể định nghĩa vai trò với quyền chi tiết.
| Vai trò | Mô tả |
|---|---|
Employer | Chủ sở hữu tổ chức/admin. Quản lý hồ sơ công ty và tin tuyển dụng. Được gán tự động khi tạo tổ chức. |
HR | Nhóm tuyển dụng nội bộ. Quản lý quy trình tuyển dụng, đơn ứng tuyển và phỏng vấn. |
Candidate | Người tìm việc. Duyệt tin và nộp đơn ứng tuyển trong tổ chức. |
Quyền có sẵn:
| Permission | Mô tả |
|---|---|
member:read/update/delete | Quản lý thành viên tổ chức |
job:read/create/update/delete | Quản lý tin tuyển dụng |
application:read/update/delete | Quản lý đơn ứng tuyển |
interview:read/create/update/delete | Quản lý phỏng vấn |
report:read/create | Xem và tạo báo cáo |
settings:read/update | Quản lý cài đặt tổ chức |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Admin tổ chức |
| Điều kiện tiên quyết | Người dùng là admin/chủ sở hữu tổ chức |
| Luồng Chính | 1. Tạo nhóm trong tổ chức 2. Thêm/xóa thành viên nhóm 3. Cập nhật tên nhóm hoặc xóa nhóm 4. Hệ thống quản lý thành viên nhóm và chọn nhóm đang hoạt động |
| Luồng Thay thế | 1a. Tên nhóm đã tồn tại → Hệ thống trả về 409 2a. Người dùng không thuộc tổ chức → Hệ thống trả về 400 |
| Hậu điều kiện | Nhóm đã tạo/cập nhật/xóa; thành viên đã quản lý |
| FR Liên quan | FR-016 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Admin tổ chức / Người dùng được mời |
| Điều kiện tiên quyết | Admin đã đăng nhập; người được mời có email |
| Luồng Chính | 1. Mời người dùng qua email với vai trò và nhóm (tùy chọn) 2. Hệ thống tạo token ngẫu nhiên ( crypto.randomBytes(32)), tính SHA-256 hash3. Chỉ lưu hash vào auth_invitations (cột token_hash)4. Tạo URL lời mời: {FRONTEND_DOMAIN}/invitations/verify?token={raw_token}5. AUTH publish sự kiện invitation.email.requested lên RabbitMQ (queue: invitation.email)6. Email queue worker (trong AUTH) consume sự kiện và gọi EMAIL module để gửi email lời mời 7. Người được mời nhận email, nhấp liên kết 8. Frontend gọi GET /organization/verify-invitation?token={raw_token} (công khai)9. Hệ thống hash token, tìm kiếm theo hash, trả về trạng thái 10. Chấp nhận hoặc từ chối lời mời |
| Luồng Thay thế | 2a. Lời mời đang chờ trùng lặp (cùng email + role) → Hệ thống trả về 409 Conflict 6a. EMAIL module không khả dụng → Event vẫn được publish, worker retry exponential backoff (tối đa 5 lần) 9a. Token hết hạn → Hệ thống tự cập nhật thành EXPIRED, trả về 410 9b. Lời mời đã được chấp nhận → Hệ thống trả về trạng thái "accepted" 9c. Lời mời đã thu hồi → Hệ thống trả về trạng thái "revoked" |
| Hậu điều kiện | Lời mời đã gửi với token bảo mật; user added to organization (if accepted); event invitation.email.requested đã publish |
| FR Liên quan | FR-017, FR-020 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Admin tổ chức (người mời ban đầu) |
| Điều kiện tiên quyết | Admin đã đăng nhập; lời mời tồn tại và đang chờ |
| Luồng Chính | 1. Chọn lời mời để gửi lại 2. Tạo token mới (token cũ bị hủy) 3. Đặt lại trạng thái thành ĐANG CHỜ, gia hạn 72 giờ 4. AUTH publish sự kiện invitation.email.resent lên RabbitMQ (queue: invitation.email)5. Email queue worker (trong AUTH) consume sự kiện và gọi EMAIL module để gửi email lời mời mới 6. Hệ thống trả về phản hồi thành công |
| Luồng Thay thế | 1a. Lời mời đã được chấp nhận → Hệ thống trả về 409 1b. Không tìm thấy lời mời → Hệ thống trả về 404 1c. Người yêu cầu không phải người mời ban đầu → Hệ thống trả về 403 5a. EMAIL module không khả dụng → Event vẫn được publish, worker retry exponential backoff (tối đa 5 lần) |
| Hậu điều kiện | Token mới đã tạo; token cũ bị hủy; event invitation.email.resent đã publish |
| FR Liên quan | FR-018 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Admin tổ chức (người mời ban đầu) |
| Điều kiện tiên quyết | Admin đã đăng nhập; lời mời tồn tại và đang chờ |
| Luồng Chính | 1. Chọn lời mời để thu hồi 2. Xác minh quyền sở hữu (chỉ người mời ban đầu mới thu hồi được) 3. Cập nhật trạng thái thành ĐÃ THU HỒI 4. Gửi sự kiện invitation.revoked 5. Hệ thống trả về phản hồi thành công |
| Luồng Thay thế | 2a. Lời mời đã được chấp nhận → Hệ thống trả về 409 2b. Lời mời đã thu hồi → Hệ thống trả về 409 2c. Người yêu cầu không phải người mời ban đầu → Hệ thống trả về 403 |
| Hậu điều kiện | Lời mời đã thu hồi; token không còn hiệu lực |
| FR Liên quan | FR-019 |
| Khía cạnh | Mô tả |
|---|---|
| Actor | Người dùng được mời (chưa xác thực) |
| Điều kiện tiên quyết | Người dùng nhận email lời mời với URL chứa token |
| Luồng Chính | 1. Người dùng nhấp liên kết lời mời trong email 2. Frontend gọi GET /organization/verify-invitation?token={raw_token}3. Tính hash SHA-256 của token 4. Tìm kiếm lời mời theo token_hash5. Kiểm tra trạng thái và thời hạn 6. Nếu hết hạn: tự động cập nhật thành EXPIRED 7. Trả về trạng thái hợp lệ và chi tiết lời mời |
| Luồng Thay thế | 4a. Không tìm thấy token → Hệ thống trả về 404 4b. Đã chấp nhận → Hệ thống trả về { valid: false, reason: "accepted" } 4c. Đã hết hạn → Hệ thống trả về { valid: false, reason: "expired" } 4d. Đã thu hồi → Hệ thống trả về { valid: false, reason: "revoked" } |
| Hậu điều kiện | Xác nhận token hợp lệ; người dùng có thể tiến hành chấp nhận/từ chối |
| FR Liên quan | FR-020 |
| Sự kiện | Hướng | Hàng đợi | Mô tả |
|---|---|---|---|
verification.email.requested |
AUTH → RabbitMQ → AUTH worker | verification.email |
publish khi người dùng đăng ký hoặc yêu cầu xác minh email. Email queue worker trong AUTH consume và gọi EMAIL module |
verification.email.resent |
AUTH → RabbitMQ → AUTH worker | verification.email |
publish khi người dùng gửi lại xác minh email (rate-limited) |
password.reset.email.requested |
AUTH → RabbitMQ → AUTH worker | password.reset.email |
publish khi người dùng yêu cầu đặt lại mật khẩu qua email. Email worker consume và gọi EMAIL module |
password.reset.sms.requested |
AUTH → RabbitMQ → AUTH worker | password.reset.sms |
publish khi người dùng yêu cầu đặt lại mật khẩu qua SMS. SMS worker consume và gọi SMS module |
auth.event.logged |
AUTH → RabbitMQ | log.events |
Gửi sự kiện xác thực (đăng nhập, đăng ký, v.v.) đến Logger |
user.registered |
AUTH → RabbitMQ | wallet.user |
publish khi người dùng đăng ký mới, WALLET tạo ví |
invitation.email.requested |
AUTH → RabbitMQ → AUTH worker | invitation.email |
publish khi admin mời thành viên vào tổ chức. Email worker consume và gọi EMAIL module |
invitation.email.resent |
AUTH → RabbitMQ → AUTH worker | invitation.email |
publish khi admin gửi lại lời mời. Email worker consume và gọi EMAIL module |
| Sự kiện | Hướng | Giao thức | Mô tả |
|---|---|---|---|
verification.email.delivered |
EMAIL → AUTH | HTTP Webhook | EMAIL callback xác nhận trạng thái giao email về AUTH |
| Mã YC | Danh mục | Yêu cầu | Mục tiêu |
|---|---|---|---|
| NFR-001 | Hiệu suất | Thời gian phản hồi đăng nhập | < 500ms (p95) |
| NFR-002 | Hiệu suất | Thời gian phản hồi đăng ký | < 1s (p95) |
| NFR-003 | Bảo mật | Mã hóa mật khẩu | bcrypt with 12 rounds |
| NFR-004 | Bảo mật | Hạn sử dụng token | Access: 15min, Refresh: 7 days |
| NFR-005 | Bảo mật | Giới hạn tốc độ | 10 req/min cho các endpoint xác thực |
| NFR-006 | Khả dụng | Thời gian hoạt động | 99.9% |
| NFR-007 | Khả năng mở rộng | Người dùng đồng thời | 1000+ simultaneous logins |
| Mã YC | Yêu cầu | Bảng CSDL | Đầu nối API |
|---|---|---|---|
| FR-001 | Đăng ký Người dùng | auth_users, auth_accounts | POST /auth/register → RabbitMQ (verification.email) → EMAIL module |
| FR-002 | Đăng nhập | auth_users, auth_sessions | POST /auth/login |
| FR-003 | Đăng xuất | auth_sessions | POST /auth/logout |
| FR-004 | Làm mới Token | auth_sessions | POST /auth/refresh |
| FR-005 | Đặt lại Mật khẩu (Email) | auth_verification | POST /auth/forgot-password → RabbitMQ (password.reset.email) → Email Queue Worker → EMAIL module |
| FR-006 | Đặt lại Mật khẩu (Điện thoại) | auth_verification | POST /auth/forgot-password-phone → RabbitMQ (password.reset.sms) → SMS Queue Worker → SMS module |
| FR-007 | Đổi Mật khẩu | auth_users | POST /auth/change-password |
| FR-008 | Xác minh Email | auth_verification, auth_users | POST /send-verification-email → RabbitMQ (verification.email) → Email Queue Worker → EMAIL module |
| FR-010 | Quản lý Người dùng | auth_users | GET/PUT/DELETE /users/:id |
| FR-011 | Quản lý Vai trò | auth_roles, auth_user_roles | POST /admin/set-role, POST /organization/create-role |
| FR-012 | Xác thực Xã hội | auth_accounts | POST /sign-in/social, POST /link-social, POST /unlink-account |
| FR-013 | Quản lý Phiên làm việc | auth_sessions | GET /list-sessions, POST /revoke-session, POST /revoke-sessions |
| FR-014 | Khóa Tài khoản & Đăng nhập giả danh | auth_users, auth_sessions | POST /admin/ban-user, POST /admin/impersonate-user |
| FR-015 | Quản lý Tổ chức | auth_organizations, auth_members | POST /organization/create, GET /organization/list |
| FR-016 | Quản lý Nhóm | auth_teams, auth_team_members | POST /organization/create-team, POST /organization/add-team-member |
| FR-017 | Quản lý Lời mời | auth_invitations | POST /organization/invite-member → RabbitMQ (invitation.email) → Email Queue Worker → EMAIL module |
| FR-018 | Gửi lại Lời mời | auth_invitations | POST /organization/resend-invitation → RabbitMQ (invitation.email) → Email Queue Worker → EMAIL module |
| FR-019 | Thu hồi Lời mời | auth_invitations | DELETE /organization/cancel-invitation |
| FR-020 | Xác minh Token Lời mời | auth_invitations | GET /organization/verify-invitation |