PRD: Quản lý nhân viên
| Module | Quản lý Người dùng (CORE-01) | PRD ID | PRD-EMP-001 |
| Status | In-progress | Owner | Nhóm Quản lý Người dùng |
| Date | 2026-05-25 | Version | v0.1 |
| Packages | @nx/identity · @nx/commerce (quyền sở hữu Organizer/Merchant) | URD | EMP |
TL;DR
Cho phép chủ doanh nghiệp tạo tài khoản nhân viên và gắn họ với các merchant cụ thể trong tổ chức của mình, để nhân viên đăng nhập bằng credential riêng và chỉ thấy những merchant được gán. Chủ sở hữu có thể gán lại hoặc vô hiệu hóa nhân viên bất cứ lúc nào, và hệ thống gửi mail đặt/đặt lại mật khẩu để nhân viên tự kích hoạt đăng nhập. Kết quả: một vòng đời nhân viên có kiểm soát, đã được xác thực quyền sở hữu, tái dùng cơ chế role/scope sẵn có - không còn đăng nhập chung của chủ, không còn truy cập nhân viên không giới hạn phạm vi.
1. Bối cảnh & Vấn đề
Chủ sở hữu đưa doanh nghiệp lên hệ thống rồi cần nhân sự để vận hành. Hiện tại việc quản lý nhân viên còn sơ sài - chưa có luồng chính thức để chủ sở hữu tạo tài khoản nhân viên, gắn họ với các merchant cụ thể trong tổ chức, và gán lại hoặc thu hồi quyền truy cập đó. Thiếu nó, chủ sở hữu phải dùng chung một đăng nhập hoặc cấp quyền quá rộng, làm hỏng việc giới hạn phạm vi theo từng merchant và không có cách sạch để off-board ai đó.
Quản lý nhân viên hiện thực hóa nửa phần tài-khoản-nhân-viên trong mục đích của URD - "cách chủ doanh nghiệp quản lý nhân viên trong tổ chức của họ" - và tái dùng cơ chế role/scope sẵn có để nhân viên chỉ luôn thấy các merchant được gán.
2. Mục tiêu & Không phải mục tiêu
Mục tiêu
- Chủ sở hữu tạo tài khoản nhân viên với role Employee, liên kết tới một tổ chức và một hoặc nhiều merchant.
- Xác thực quyền sở hữu: chủ sở hữu thao tác phải sở hữu tổ chức và mọi merchant được liệt kê trước khi ghi bất kỳ grant nào.
- Find/count nhân viên theo phạm vi (scope) cùng ánh xạ role-merchant, với system role bị loại khỏi ánh xạ.
- Cập nhật: thay toàn bộ phần gán merchant, thêm/sửa username, và thu hồi hoặc cấp quyền đăng nhập.
- Vô hiệu hóa / gỡ bỏ một tài khoản nhân viên bằng soft-delete.
- Luồng mail đặt mật khẩu và đặt lại mật khẩu, với cấu hình mail đọc từ database.
Không phải mục tiêu
- Tạo role tùy biến / quản lý permission động → Permissions.
- Hệ thống mời người dùng (mời qua email/điện thoại) - bị loại theo phạm vi URD.
- Truy cập đa tổ chức cho một người dùng.
- Audit / lịch sử đăng nhập cho các thao tác của nhân viên.
3. Success Metrics
| Metric | Mục tiêu / tín hiệu |
|---|---|
| Đúng phạm vi | Nhân viên chỉ đọc/vận hành các merchant được gán; không rò rỉ chéo merchant |
| An toàn quyền sở hữu | 100% lời gọi create/update bị từ chối khi chủ sở hữu không sở hữu tổ chức hoặc một merchant được liệt kê |
| Tự kích hoạt | Mail đặt mật khẩu được gửi khi tạo; nhân viên tự kích hoạt đăng nhập |
| Off-boarding | Nhân viên đã vô hiệu hóa/gỡ bỏ không còn đăng nhập được |
4. Personas & Use Cases
| Persona | Mục tiêu trong tính năng này |
|---|---|
| Owner | Tạo nhân viên, giới hạn họ theo các merchant, gán lại hoặc off-board |
| Employee | Đăng nhập bằng credential riêng và chỉ vận hành các merchant được gán |
Core scenarios: chủ sở hữu tạo một nhân viên kèm danh sách merchant (đã xác thực theo quyền sở hữu) → mail đặt mật khẩu được gửi đi → nhân viên đăng nhập với phạm vi giới hạn ở các merchant đó → sau này chủ sở hữu thay phần gán merchant hoặc vô hiệu hóa tài khoản.
5. User Stories
- Là một owner, tôi muốn tạo một tài khoản nhân viên giới hạn ở một hoặc nhiều merchant của mình, để nhân sự chỉ vận hành các cửa hàng tôi gán.
- Là một owner, tôi muốn hệ thống từ chối bất kỳ merchant hoặc tổ chức nào tôi không sở hữu, để tôi không vô tình cấp quyền ra ngoài doanh nghiệp của mình.
- Là một owner, tôi muốn thay phần gán merchant của một nhân viên, để chuyển nhân sự giữa các cửa hàng trong một lần cập nhật.
- Là một owner, tôi muốn thêm username và (gửi lại) mail đặt/đặt lại mật khẩu, để nhân viên có thể tự kích hoạt hoặc khôi phục đăng nhập của họ.
- Là một owner, tôi muốn vô hiệu hóa hoặc gỡ bỏ một nhân viên, để nhân sự off-board mất quyền truy cập trong khi dữ liệu của họ được giữ lại.
- Là một employee, tôi muốn đăng nhập bằng credential riêng và chỉ thấy các merchant của mình, để góc nhìn khớp với trách nhiệm của tôi.
6. Functional Requirements
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Chủ sở hữu tạo một tài khoản nhân viên với role Employee | URD-EMP-001 |
| FR-2 | Nhân viên được liên kết tới một tổ chức và một hoặc nhiều merchant | URD-EMP-002 |
| FR-3 | Nhân viên chỉ có thể truy cập các merchant được gán | URD-EMP-003 |
| FR-4 | Nhân viên có thể đăng nhập bằng credential riêng | URD-EMP-004 |
| FR-5 | Truy vấn dữ liệu của một nhân viên được lọc theo phần gán merchant; system role bị loại khỏi ánh xạ role-merchant | URD-EMP-005 |
| FR-6 | Chủ sở hữu có thể cập nhật phần gán merchant (thay toàn bộ phần gán trước đó), thêm/sửa username, và thu hồi/cấp quyền đăng nhập | URD-EMP-006 |
| FR-7 | Chủ sở hữu có thể vô hiệu hóa hoặc gỡ bỏ một tài khoản nhân viên (soft-delete) | URD-EMP-007 |
| FR-8 | Hệ thống xác thực rằng chủ sở hữu sở hữu tổ chức và mọi merchant được liệt kê trước khi cấp grant | URD-EMP-008 |
| FR-9 | Mail đặt mật khẩu được gửi khi tạo (và khi thêm username lúc cập nhật); mail đặt lại mật khẩu được gửi khi có yêu cầu, với cấu hình mail đọc từ database | URD-EMP-001 · URD-EMP-004 |
Toàn văn yêu cầu và tiêu chí chấp nhận nằm trong URD Quản lý Người dùng. PRD này tham chiếu chúng thay vì lặp lại.
7. Non-Functional Requirements
| Khía cạnh | Yêu cầu |
|---|---|
| Toàn vẹn dữ liệu | Tài khoản, role Employee, và các grant tổ chức/merchant được tạo cùng nhau - tạo một phần thì bị từ chối |
| Tenancy & authz | Mọi thao tác đều được xác thực quyền sở hữu dựa trên tổ chức và các merchant của chủ sở hữu thao tác; chủ sở hữu không thể quản lý một role bằng hoặc cao hơn priority của mình |
| Phạm vi (scoping) | Find/count được lọc theo phạm vi của caller; system role bị loại khỏi ánh xạ role-merchant |
| Soft-delete | Tài khoản nhân viên không bao giờ bị xóa vật lý; gỡ bỏ là một soft-delete |
| Bảo mật | Mật khẩu được hash và không bao giờ trả về; session token bị loại khỏi response đặt lại mật khẩu |
| i18n | Nhãn/trạng thái hướng người dùng song ngữ ({ en, vi }) |
8. UX & Flows
Các luồng chính nằm trong @nx/identity (create/find/count/update/delete nhân viên và đường mail đặt/đặt lại mật khẩu). UI hướng chủ sở hữu để quản lý nhân sự nằm trong ứng dụng client.
9. Data & Domain
| Entity | Vai trò |
|---|---|
User | Tài khoản của nhân viên - danh tính, trạng thái, soft-delete |
Credential | Mật khẩu đã hash; đặt/đặt lại qua luồng mail mật khẩu |
Identifier | Giá trị đăng nhập username/email/điện thoại được thêm khi create/update |
Role (Employee) | Phân loại tài khoản và điều khiển scoping; system role bị loại khỏi ánh xạ |
| Grant role-merchant | Gắn nhân viên với một tổ chức và các merchant được gán |
Organizer / Merchant (commerce) | Nguồn quyền sở hữu - được dùng để xác thực chủ sở hữu sở hữu tổ chức và merchant |
Chỉ mang tính khái niệm - schema đầy đủ trong developer domain model.
10. Dependencies & Assumptions
Phụ thuộc vào
- Roles & Scoping (URD-ROLE) - role Employee và cơ chế lọc phạm vi mà vòng đời nhân viên tái dùng.
- Authentication (URD-AUTH) - nhân viên đăng nhập bằng credential riêng.
- Commerce (
@nx/commerce) - quyền sở hữuOrganizer/Merchantlà nguồn sự thật cho việc xác thực. - Cấu hình mail lưu trong database cho đường đặt/đặt lại mật khẩu.
Giả định
- Chủ sở hữu thao tác đã sở hữu một tổ chức với ít nhất một merchant.
- Tồn tại một dòng cấu hình mail để có thể gửi mail đặt/đặt lại mật khẩu.
11. Risks & Open Questions
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Cấp quyền truy cập tới một merchant mà chủ sở hữu không sở hữu | Quyền sở hữu được xác thực dựa trên OrganizerRepository / MerchantRepository trước khi cấp bất kỳ grant nào |
| System role rò rỉ vào ánh xạ role-merchant | System role bị lọc bỏ khi count/list ánh xạ |
| Lộ session token khi đặt lại mật khẩu | Session token bị loại khỏi response đặt lại mật khẩu |
| Chưa có audit/lịch sử đăng nhập cho thao tác nhân viên | Ngoài phạm vi increment này; xem lại khi audit được ưu tiên |
| Giả định một tổ chức | Truy cập đa tổ chức cho một người dùng là một non-goal rõ ràng |
12. Release Plan & Launch Criteria
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P2 của tính năng EMP - xem catalog tính năng URD |
| Rollout | Mọi merchant; không feature flag |
| Migration | Thêm seed cấu hình mail; không có migration dữ liệu phá hủy |
| Launch criteria | Tạo→giới hạn phạm vi→đăng nhập được kiểm chứng đầu-cuối; xác thực quyền sở hữu từ chối tổ chức/merchant không sở hữu; mail đặt/đặt lại mật khẩu được gửi; nhân viên đã soft-delete không đăng nhập được |
| Monitoring | Tỷ lệ lỗi create/update nhân viên, tỷ lệ từ chối do quyền sở hữu, tỷ lệ gửi mail đặt/đặt lại mật khẩu |
13. FAQ
Một nhân viên có thuộc nhiều tổ chức được không? Không - truy cập đa tổ chức cho một người dùng nằm ngoài phạm vi; một nhân viên được liên kết tới một tổ chức và một hoặc nhiều merchant của tổ chức đó.
Điều gì xảy ra với phần gán khi chủ sở hữu cập nhật? Cập nhật thay toàn bộ phần gán merchant trước đó bằng danh sách mới; nhân viên sau đó chỉ thấy các merchant mới.
Chủ sở hữu có gán được merchant mà họ không sở hữu không? Không - hệ thống xác thực rằng chủ sở hữu sở hữu tổ chức và mọi merchant được liệt kê trước khi ghi bất kỳ grant nào.
Nhân viên lấy mật khẩu bằng cách nào? Mail đặt mật khẩu được gửi khi tạo (và khi thêm username lúc cập nhật); nhân viên tự đặt mật khẩu. Mail đặt lại mật khẩu có sẵn khi có yêu cầu.
Nhân viên bị gỡ bỏ có bị xóa vĩnh viễn không? Không - gỡ bỏ là một soft-delete; tài khoản bị vô hiệu hóa và dữ liệu được giữ lại.
References
- URD: Quản lý Người dùng - EMP
- Liên quan: Roles & Scoping · Authentication
- Module: Quản lý Người dùng - tổng quan + truy vết
- Developer: @nx/identity · domain model