PRD: Employee management
| Module | User Management (CORE-01) | PRD ID | PRD-EMP-001 |
| Status | In-progress | Owner | User Management squad |
| Date | 2026-05-25 | Version | v0.1 |
| Packages | @nx/identity · @nx/commerce (Organizer/Merchant ownership) | URD | EMP |
TL;DR
Lets a business owner create staff accounts and bind them to specific merchants within their organization, so employees sign in with their own credentials and see only the merchants they are assigned to. Owners can reassign or deactivate staff at any time, and the system sends set/reset-password mail so employees activate their own login. The result: a controlled, ownership-validated employee lifecycle that reuses the existing role/scoping machinery - no shared owner logins, no unscoped staff access.
1. Context & Problem
Owners onboard a business and then need staff who can operate it. Today employee management is thin - there is no first-class flow for an owner to create staff accounts, bind them to specific merchants in their organization, and reassign or revoke that access. Without it, owners share a single login or hand out broad access, which breaks per-merchant scoping and leaves no clean way to off-board someone.
Employee management grounds the staff-account half of the URD's purpose - "how business owners manage employees within their organizations" - and reuses the existing role/scoping machinery so an employee only ever sees the merchants they are assigned to.
2. Goals & Non-Goals
Goals
- Owner-driven employee account creation with the Employee role, linked to an organization and one or more merchants.
- Ownership validation: the acting owner must own the organization and every listed merchant before any grant is written.
- Scope-filtered find/count of employees and their role-merchant mappings, with system roles excluded from the mapping.
- Update: replace merchant assignments, add/update a username, and revoke or grant login access.
- Deactivate / remove an employee account via soft-delete.
- Set-password and reset-password mail flow, with mail configuration read from the database.
Non-Goals
- Custom role creation / dynamic permission management → Permissions.
- A user invitation system (email/phone invites) - excluded by the URD scope.
- Multi-organization access for a single user.
- Audit / login history for employee actions.
3. Success Metrics
| Metric | Target / signal |
|---|---|
| Scoping correctness | Employees can read/operate only their assigned merchants; zero cross-merchant leakage |
| Ownership safety | 100% of create/update calls reject when the owner does not own the org or a listed merchant |
| Self-activation | Set-password mail delivered on creation; employees activate their own login |
| Off-boarding | Deactivated/removed employees can no longer sign in |
4. Personas & Use Cases
| Persona | Goal in this feature |
|---|---|
| Owner | Create staff, scope them to merchants, reassign or off-board them |
| Employee | Sign in with own credentials and operate only assigned merchants |
Core scenarios: an owner creates an employee with a merchant list (validated against ownership) → set-password mail goes out → the employee signs in scoped to those merchants → the owner later replaces the merchant assignments or deactivates the account.
5. User Stories
- As an owner, I want to create an employee account scoped to one or more of my merchants, so staff can operate only the stores I assign.
- As an owner, I want the system to reject any merchant or organization I do not own, so I cannot accidentally grant access outside my business.
- As an owner, I want to replace an employee's merchant assignments, so I can move staff between stores in one update.
- As an owner, I want to add a username and (re)send set/reset-password mail, so an employee can activate or recover their own login.
- As an owner, I want to deactivate or remove an employee, so off-boarded staff lose access while their data is preserved.
- As an employee, I want to sign in with my own credentials and see only my merchants, so my view matches my responsibilities.
6. Functional Requirements
| # | Requirement | URD ref |
|---|---|---|
| FR-1 | Owner creates an employee account with the Employee role | URD-EMP-001 |
| FR-2 | Employee is linked to an organization and one or more merchants | URD-EMP-002 |
| FR-3 | Employee can access only the merchants they are assigned to | URD-EMP-003 |
| FR-4 | Employee can sign in with their own credentials | URD-EMP-004 |
| FR-5 | Data queries for an employee are filtered by their merchant assignments; system roles are excluded from the role-merchant mapping | URD-EMP-005 |
| FR-6 | Owner can update merchant assignments (replaces all previous assignments), add/update a username, and revoke/grant login access | URD-EMP-006 |
| FR-7 | Owner can deactivate or remove an employee account (soft-delete) | URD-EMP-007 |
| FR-8 | System validates that the owner owns the organization and every listed merchant before granting | URD-EMP-008 |
| FR-9 | Set-password mail is sent on creation (and when a username is added on update); reset-password mail is sent on request, with mail configuration read from the database | URD-EMP-001 · URD-EMP-004 |
Full requirement text and acceptance criteria live in the User Management URD. This PRD references them rather than restating them.
7. Non-Functional Requirements
| Area | Requirement |
|---|---|
| Data integrity | Account, Employee role, and organization/merchant grants are created together - partial creation is rejected |
| Tenancy & authz | Every operation is ownership-validated against the acting owner's organization and merchants; an owner cannot manage a role at or above their own priority |
| Scoping | Find/count is filtered to the caller's scope; system roles are excluded from the role-merchant mapping |
| Soft-delete | Employee accounts are never physically deleted; removal is a soft-delete |
| Security | Passwords are hashed and never returned; the session token is removed from the reset-password response |
| i18n | User-facing labels/statuses are bilingual ({ en, vi }) |
8. UX & Flows
Key flows live in @nx/identity (employee create/find/count/update/delete and the set/reset-password mail path). The owner-facing UI for staff management lives in the client app.
9. Data & Domain
| Entity | Role |
|---|---|
User | The employee's account - identity, status, soft-delete |
Credential | Hashed password; set/reset via the password-mail flow |
Identifier | Username/email/phone login values added on create/update |
Role (Employee) | Classifies the account and drives scoping; system roles excluded from the mapping |
| Role-merchant grant | Binds the employee to an organization and its assigned merchants |
Organizer / Merchant (commerce) | Ownership source - consumed to validate the owner owns the org and merchants |
Conceptual only - full schema in the developer domain model.
10. Dependencies & Assumptions
Depends on
- Roles & Scoping (URD-ROLE) - the Employee role and the scope-filtering machinery employee lifecycle reuses.
- Authentication (URD-AUTH) - employees sign in with their own credentials.
- Commerce (
@nx/commerce) -Organizer/Merchantownership is the source of truth for validation. - Mail configuration stored in the database for the set/reset-password path.
Assumptions
- The acting owner already owns an organization with at least one merchant.
- A mail configuration row exists so set/reset-password mail can be sent.
11. Risks & Open Questions
| Risk / question | Mitigation / status |
|---|---|
| Granting access to a merchant the owner does not own | Ownership validated against OrganizerRepository / MerchantRepository before any grant |
| System roles leaking into the role-merchant mapping | System roles filtered out when counting/listing the mapping |
| Session token exposure on password reset | Session token removed from the reset-password response |
| No audit/login history for employee actions | Out of scope for this increment; revisit when audit is prioritized |
| Single-organization assumption | Multi-organization access for one user is an explicit non-goal |
12. Release Plan & Launch Criteria
| Aspect | Plan |
|---|---|
| Phase | P2 of the EMP feature - see URD feature catalog |
| Rollout | All merchants; no feature flag |
| Migration | Mail-configuration seed added; no destructive data migration |
| Launch criteria | Create→scope→sign-in verified end-to-end; ownership validation rejects non-owned org/merchants; set/reset-password mail delivered; soft-deleted employees cannot sign in |
| Monitoring | Employee create/update error rate, ownership-rejection rate, set/reset-password mail delivery |
13. FAQ
Can an employee belong to more than one organization? No - multi-organization access for a single user is out of scope; an employee is linked to one organization and one or more of its merchants.
What happens to assignments when an owner updates them? The update replaces all previous merchant assignments with the new list; the employee then sees only the new merchants.
Can an owner assign a merchant they don't own? No - the system validates that the owner owns the organization and every listed merchant before any grant is written.
How does an employee get a password? Set-password mail is sent on creation (and when a username is added on update); employees set their own password. Reset-password mail is available on request.
Is a removed employee deleted permanently? No - removal is a soft-delete; the account is deactivated and data is preserved.
References
- URD: User Management - EMP
- Related: Roles & Scoping · Authentication
- Module: User Management - overview + traceability
- Developer: @nx/identity · domain model