PRD: Operations Staff & Access Administration (Back Office)

Module	User Management	PRD ID	PRD-OPS-001
Status	Ready to dev	FEAT	OPS · BANA-1435
Epic	BANA-1336	Plane	BANA-1738
Date	2026-06-26	Version	v1.0
Packages	@nx/identity	URD	OPS
Surface	BO · Ops
Owner	Phát Nguyễn · Hải Cao

What operations staff administration is

The Back Office is the operations team's internal admin portal. It carries one dedicated screen to administer internal accounts (system users): create an account, assign the right internal fixed role (SYSTEM), reset a password, deactivate an account. Internal accounts stay strictly separate from a merchant's own staff (EMP) and from end customers (CUS) - never mixed into the same list.

The Back Office already had the Access Control area, and the User Management backend already supported the full user / role / permission lifecycle. This increment closes the remaining gap: naming that surface as operations-staff administration, tying it to the fixed-role hierarchy, and specifying the safety rule for granting access.

Three fixed roles and the priority ceiling

Three internal fixed roles, seeded ahead of time with a descending priority hierarchy:

Role	Priority
Super Admin	999
Admin	900
Operator	600

These roles are defined in ROLE - Permissions URD. The platform-wide priority-ceiling rule applies to internal accounts too: "to create, edit, delete, or grant a role, that role's priority must be STRICTLY LOWER than the caller's own highest priority. Equal does not qualify either." An Admin (900) cannot grant the Admin or Super Admin role to anyone, not even to themselves; only a Super Admin can grant the Admin tier.

One internal account, from creation to daily use

The first Super Admin is bootstrapped outside this UI. From there, that Super Admin creates an account for the operations team's first Admin → that Admin signs in, opens the internal-staff admin screen, and creates an account for a new Operator with sign-in credentials and the Operator role → the Operator signs in right away with the issued username and password. One day the Admin tries to grant the Admin role to that Operator to widen their access: the role picker shows neither Admin nor Super Admin, only Operator - the priority ceiling blocks it right at the UI. Weeks later the Operator forgets their password; the Admin uses the "Reset password" row action to issue a new one, no database access needed. Before handing over more work, the Admin opens "View effective access" on that Operator to review exactly what they can do.

The easiest thing to get wrong

A pre-filled password on account creation is a vulnerability, not a convenience

The internal-account creation form used to pre-fill a fixed sample password. If an operator saved it as-is, many internal accounts ended up sharing one guessable password - a security hole that silently spreads across the operations team.

The password field must always start empty on the create form; the person filling it in is required to type a fresh password for every account.

1. Goals & Non-Goals

Goals

• A dedicated, documented internal-staff administration surface in the Back Office: list (internal accounts only), create, edit, status, delete, password reset.
• Privilege safety: nobody can grant a role at or above their own priority.
• Effective-access visibility per internal account for review.
• Every internal-account operation is permission-gated.

Non-Goals

• Merchant-owned staff management (that is EMP, surface Client) and customer management (CUS).
• The global permission catalog editor and policy-definition authoring (covered by permissions/PERM and permissions/ROLE, the BO-side of those split PRDs).
• Per-merchant role grants for merchant users - the merchant-facing grant flow, see PRD-EMP-002.
• SSO / 2FA for internal staff (tracked under AUTH Could-haves).

2. Success Metrics

Metric	Target / signal
Internal role coverage	100% of internal accounts created through the Back Office carry at least one internal fixed role and the internal-staff flag
Escalation blocked	0 privilege-escalation paths: a request to assign a role at or above the caller's priority is always rejected
Provisioning speed	An operator can provision a new internal account end-to-end in one screen, no direct database access

3. Personas & Scenarios

Persona	Goal in this feature
Operator (operations team)	Admin / Operator role - onboards and maintains other internal staff
Super Admin	Bootstraps the first Operator; the only role that can manage Admin-tier accounts

Core scenario: a Super Admin creates the operations team's first Admin account → that Admin signs in, opens the internal-staff admin screen, creates an account for a new Operator, and assigns the Operator role → the Operator signs in right away with the issued credentials → the Admin tries to grant the Admin role to that Operator, but the role picker hides Admin and Super Admin so the grant cannot happen → later the Admin resets that Operator's password and views their effective access when a review is needed.

4. User Stories

#	As a	I want	So that
01	operator	to open a dedicated list of internal accounts only, searchable and filterable	I never mix them with a merchant's staff or customers when looking for who runs the platform
02	operator	to create a new internal account with its own sign-in credentials and at least one fixed role	a new teammate has Back Office access right away
03	operator	to edit the profile, roles, and status of an internal account	account data stays correct over time
04	operator	to delete one or more internal accounts that are no longer in use, with confirmation	the list stays clean and safe
05	Admin	to neither see nor assign a role at or above my own priority	nobody can self-escalate through the Back Office
06	operator	to reset the password of a locked-out teammate	that teammate gets back to work without anyone touching the database
07	Super Admin	to view the effective access of an internal account	I can review exactly what that person can do

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	The internal-staff list shows internal accounts only, never a merchant's staff or end customers. • 8 columns: First name · Last name · Username · Email · Phone number · Internal role · Last sign-in · Status (colored label). • A global search box over the list. • A Status filter - multiple values selectable at once; the full value set: Activated / Deactivated / Blocked / Archived. • A filter by internal role - multiple roles selectable at once. • Default sort by creation time, newest first; default pagination 50 rows/page (options 25 / 50 / 75 / 100).	🔶	URD-OPS-001 · URD-OPS-002 · URD-OPS-011 · URD-OPS-012
FR-002	Create an internal account with its own sign-in credentials and at least one internal role. • First name, Last name: required, free text. • Username: required, 4-32 characters; lowercase letters and digits only, with dots / underscores / hyphens allowed between character groups (not leading, trailing, or consecutive); uppercase is auto-lowercased and whitespace is stripped while typing. • Email: required, valid email format. • Phone numbers: required, at least one, multiple numbers can be added or removed. • Password: required, 8-80 characters, at least one uppercase letter, one lowercase letter, and one digit. • Status: defaults to Activated; the full value set: Activated / Deactivated / Blocked / Archived. • Internal roles: required, at least one; the list contains only the three internal fixed roles Super Admin / Admin / Operator; a role not in Activated status is shown but not selectable. • A live preview card next to the form mirrors the name, email, phone numbers, status, and count of selected roles.	✅	URD-OPS-003
FR-003	Edit the profile, roles, and status of an internal account, same form as create, with a few differences. • Username is shown but not editable - the sign-in identifier is immutable after creation. • No password field on the edit form - password changes happen through the dedicated reset action (FR-006). • Roles may be left empty when editing. • Leaving the page with unsaved changes triggers a confirmation warning. • Deactivating or reactivating an account is done by changing the Status field right on the edit form.	✅	URD-OPS-005 · URD-OPS-006
FR-004	Delete internal accounts, per row and in bulk, both behind confirmation. • A per-row delete action on the list; the confirmation dialog names the exact username of the account about to be deleted. • Multi-row selection with bulk delete, also behind confirmation.	✅	URD-OPS-008
FR-005	Priority ceiling - the caller can neither see nor assign a role at or above their own priority. • The role picker on the create/edit form hides every role whose priority is equal to or above the caller's highest priority (an Admin sees neither Super Admin nor Admin; only a Super Admin can grant the Admin tier). • Even if an assignment request is sent directly, bypassing the UI, the server rejects it with a clear error message.	🚧	URD-OPS-004 ⇐ URD-CROLE-003
FR-006	Password reset for another internal account, performed by an operator. • A "Reset password" row action on the list. • The new password follows the same rules as the create form (8-80 characters, uppercase, lowercase, and a digit).	🚧	URD-OPS-007
FR-007	View effective access for an internal account - from the list or the edit screen, open the merged permission list from all assigned roles, to review "what can this person do".	🚧	URD-OPS-010
FR-008	Force a new password on create - the password field starts empty by default, no pre-filled sample value.	🚧	URD-OPS-003

5.1 Acceptance Criteria

• Sign in as an Admin-role account, open the create/edit form → the role picker shows neither Super Admin nor Admin, only Operator; send a Super Admin assignment request directly to the server, bypassing the UI → the request is rejected with an error message.
• An operator creates an internal account with all valid fields → the account appears in the list; it signs in immediately with the issued username and password; it carries exactly the selected roles.
• Enter username Anh.Ba (uppercase plus whitespace) → the stored value is anh.ba; enter a 3-character username or one containing special characters other than . _ - → it is blocked with a message.
• Enter password abcdefgh (no uppercase, no digit) → it is rejected with a message naming the missing rules.
• Submit the create form with no phone number or no role selected → the save is blocked and the offending fields are highlighted.
• Open the edit form of an account → the username is not editable and there is no password field.
• Delete an account → the confirmation dialog names the exact username; after confirming, the account disappears from the list.
• Filter Status = Blocked → the list shows only Blocked accounts.
• An operator uses the "Reset password" action on another account, entering a valid new password → that account can sign in immediately with the new password.
• Open "View effective access" on an account carrying two roles → the permission list shown is the merge of both roles.
• Open the internal-account create form → the password field is empty, no sample value pre-filled.

6. Non-Functional Requirements

Area	Requirement
Data integrity	Deleting an internal account is a soft-delete, the data is preserved, never physically removed
Authorization	Every internal-account operation (list, read, create, edit, delete, password reset) is individually permission-gated
Privilege safety	Nobody creates or assigns a role at or above their own highest priority, even when the request is sent directly, bypassing the UI
Account separation	Internal accounts stay strictly separate from a merchant's staff (EMP) and customers (CUS), never shown in the same list
i18n	Status labels and role labels display bilingually (English / Vietnamese)

7. UX & Flows

8. Data & Domain

Concept	Role
Internal account (system user)	An operations-team account, separate from a merchant's staff and customers; carries one or more internal fixed roles
Fixed role (SYSTEM)	Super Admin / Admin / Operator, each carrying a fixed priority that decides the hierarchy
Priority ceiling	The rule that blocks creating, editing, deleting, or granting a role whose priority is equal to or above the caller's own highest priority
Effective access	The merged permission list from every role currently assigned to an account

Conceptual only - the full schema and rules live in the identity domain model.

9. Dependencies & Assumptions

Depends on

#	Feature	What is depended on
01	ROLE Fixed roles	the three internal fixed roles and the priority-ceiling rule are defined here; this PRD only ties account administration to that hierarchy.
02	USR User account	internal accounts reuse the same identifier model (username / email / phone) and identifier-reuse handling.

Assumptions

#	Assumption	What breaks if it is wrong
01	The User Management backend already supports the full user / role / permission lifecycle before this surface existed.	An incomplete lifecycle means create, edit, and delete on internal accounts do not work, and the whole OPS surface has no foundation to stand on.
02	The first Super Admin is bootstrapped by a tool outside this UI.	With no Super Admin at all, nobody can grant the Admin role, and there is no valid way to unlock the system from inside the UI.
03	The operations team uses exactly the three existing fixed roles, with no need for an intermediate role for platform operations.	Needing an intermediate role means the current three-tier priority scale has no room and has to be extended.

10. Release Plan & Criteria

Aspect	Plan
Phase	P2 - see the URD feature catalog
Rollout	All operators; no feature flag; ships behind the existing Access Control nav
Migration	None - the surface operates on existing User Management capabilities
Release criteria	An operator can provision, restrict, and reset an internal account from the Back Office with the priority ceiling enforced (full acceptance in §5.1)
Monitoring	Number of internal accounts created through the Back Office, number of role-assignment requests rejected for exceeding the priority ceiling

References

• URD: Operations Staff Administration (BO)
• Related: ROLE - Fixed roles · USR - User account
• Related PRD: PRD-EMP-002 - Merchant User Administration (Back Office)
• Module: User Management - URD
• Developer: @nx/identity

Risks & Open Questions

#	Risk / question	Mitigation / status
01	The create form used to pre-fill a fixed sample password; if an operator saved it as-is, many internal accounts ended up sharing one guessable password	Addressed by FR-008 - the password field starts empty by default, forcing a new one
02	Unclear whether internal staff need an explicit invite + pending-activation state, or whether create-with-password-reset is enough	Open - the backend has no "invite" capability today
03	Unclear whether "Operator" should be allowed to create other Operators, or only Admin and above	Open - the priority ceiling answers the role math, but a further policy decision may narrow it

Frequently asked questions

#	Question	Answer
01	Why do internal accounts have to be separate from a merchant's staff and customers?	Because they are two entirely different subjects: internal accounts operate the platform, while a merchant's staff (EMP) and customers (CUS) do not operate anything. Mixing them into one list makes it impossible to tell who actually runs the system.
02	Who can create a Super Admin account?	Only a Super Admin can grant the Admin role; the priority ceiling automatically blocks Admin and Operator from creating another Super Admin.
03	Why doesn't the role picker show all three roles?	The priority ceiling hides every role whose priority is equal to or above the caller's own highest priority; an Admin sees neither Super Admin nor Admin in their own picker.
04	Does resetting a teammate's password need their confirmation first?	No. An operator performs it directly through the "Reset password" row action on the list; the new password follows the same rules as the create form.
05	Does bulk delete ask for confirmation?	Yes. Selecting multiple rows and deleting in bulk still goes through the same confirmation dialog as a single-row delete.
06	What is "view effective access" for?	To review exactly what an internal account can do, by merging the permissions from every role currently assigned to it.