PRD: User account & configuration

Module	User Management	PRD ID	PRD-USR-001
Status	Ready to dev	FEAT	USR
Epic	—	Plane	BANA-1527
Date	2026-05-27	Version	v1.0
Packages	@nx/identity	URD	USR
Surface	Client · Owner/MgrBO · Ops
Owner	Phát Nguyễn

What user account & configuration is

Every person on BANA owns exactly one durable user account: a system-generated ID that is never physically removed, even if the account is later dropped. One account can hold several login identifiers - username, email, phone - and no two accounts ever share the same username, or the same verified email or phone.

Every other module trusts the identity and scope User Management issues, so the account itself - along with its identifiers, profile, status, and personal settings - must exist before any role, employee, or customer can sit on top of it. Without a first-class account there is no stable subject to attach a role to, no way to be sure an email or phone truly belongs to whoever claims it, nowhere to keep a person's own preferences like language, and no guarantee account data survives a "delete". This PRD builds that foundation for the whole platform.

One user, from registration to daily use

A person registers with a username - the account, profile, identifiers, and a default user configuration set are created together. The user opens the profile page, edits their name and birthday, and uploads an avatar. In the top-right corner of the header, they click to change language - the interface switches and saves right away, and the choice carries over the next time they sign in. They add a new email; that identifier starts unverified and needs an OTP code before it verifies. Later, whoever is assigned account-management permission locks this account for an operational reason - the user can no longer sign in until unlocked, but all of the account's data is still there, nothing is lost.

The easiest thing to get wrong

Archived is terminal - there is no way back

An account's status lifecycle moves through activate, deactivate, block, and finally archive. The first three transition freely between each other, but archive does not - once archived, an account has no path back to any other status.

Whoever holds account-management permission needs to be clear on the distinction: deactivate or block for a temporary lock, and reach for archive only when the account is truly meant to end.

1. Goals & Non-Goals

Goals

• A user account with a unique system-generated ID, soft-deletable and never physically removed.
• Multiple login identifiers per user (username, email, phone); no two accounts ever share the same username, or the same verified email or phone. Username is required and automatically treated as verified; email and phone start unverified and need an OTP code before they count as verified.
• An editable profile page: name, birthday, contact details, avatar (view, upload, delete), plus a language preference set from a button in the top-right corner of the header - changing it applies and saves right away, and holds across the next sign-in.
• A status lifecycle (activate, deactivate, block, archive) that whoever is assigned account-management permission can act on - from the Client site or the Back Office - within their scope; status gates sign-in, and Archived is terminal.
• A default set of personal configurations created automatically at registration, grouped and uniquely keyed by code per user.
• Users can read and update their own configuration.

Non-Goals

• Authentication itself, OTP delivery, and password flows - the AUTH area / Authentication.
• Custom role creation and dynamic permission management - Permissions.
• User invitation, session management / remote revocation, login history / audit.
• Managing identifiers as a resource (listing, searching, scoped removal) and per-table custom views - covered by User identifiers & configuration (USR-002).
• Enforced MFA.

2. Success Metrics

Metric	Target / signal
Account durability	Zero physical deletes; every removed account remains as a soft-deleted record
Uniqueness promise	No account ever shares a username, or a verified email or phone, with another account
Verification correctness	Email/phone usable only after OTP verification; deactivated or blocked users cannot sign in
Profile self-service	Users view and edit their own profile, avatar, and language without any help
Config bootstrap	Every registration comes with the default configuration set already grouped and keyed by code

3. Personas & Scenarios

Persona	Goal in this feature
Owner / end user	Own an account, edit their own profile, avatar, and language, manage their identifiers, tune their personal configuration
Whoever holds account-management permission	Lock, unlock, or archive another account within their scope, from the Client site or the Back Office
Other modules	Rely on a stable account to attach roles, employees, and customers to

Core scenario: a person registers, and an account, profile, identifiers, and default configuration are created together → the user edits their profile, changes their avatar, picks a language from the header, adds and verifies an email or phone via OTP, and reads and updates their own configuration → whoever holds account-management permission changes another user's status within their scope, which gates that user's sign-in; account data is always preserved through soft-delete.

4. User Stories

#	As a	I want	So that
01	user	a single account that can hold a username plus several emails and phones	I can sign in with whichever identifier I have
02	user	to be sure no one else can claim my verified email or phone	my identifiers stay mine
03	user	to edit my profile, change my avatar, and pick my language right from the top corner	the product speaks to me correctly
04	whoever holds account-management permission	to lock, unlock, or archive an account within my scope, whether I'm on the Client site or in the Back Office	access reflects that account's real standing
05	user	my account preserved even when "deleted"	data is never silently lost
06	user	default settings created for me and editable by me	my preferences always persist

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	Each user has a unique system-generated ID. The account is soft-deletable and never physically removed.	✅	URD-USR-001 · URD-USR-009
FR-002	A user can hold multiple login identifiers: username, email, phone. No two accounts ever share the same username, or the same verified email or phone.	✅	URD-USR-002 · URD-USR-003
FR-003	Username is required and automatically treated as verified. Email and phone identifiers start unverified and need an OTP code to verify.	✅	URD-USR-004 · URD-USR-005
FR-004	Users view and update their own profile. • Name, birthday, contact details. • On the same profile page, they also view, upload, or delete their own avatar.	✅	URD-USR-006
FR-005	Users set their display language from a button in the top-right corner of the header. Changing it applies and saves right away, and the choice holds across the next sign-in.	✅	URD-USR-010
FR-006	Whoever is assigned account-management permission - on the Client site or in the Back Office - can lock, unlock, or archive another account within their scope.	🔶	URD-USR-007
FR-007	Deactivated and blocked users cannot sign in.	✅	URD-USR-008
FR-008	Archived is a terminal status for an account and cannot be reactivated.	🔶	URD-USR-011
FR-009	A default set of personal configurations is created automatically the moment a user registers.	✅	URD-USR-022
FR-010	Users read and update their own personal configuration.	✅	URD-USR-019 · URD-USR-021

5.1 Acceptance Criteria

• A person registers a new account → they get a unique system-generated ID; account data is never physically removed even if the account is later dropped.
• Registering with a username someone else already has → rejected, no account gets created.
• Registering with an email or phone that is already a verified identifier on another account → rejected, keeping the no-overlap promise.
• Right after registration → the username is automatically verified; adding a new email or phone → that identifier starts unverified and needs an OTP code before it verifies.
• Opening the profile page → the user sees and can edit their own name, birthday, and contact details.
• On the profile page, uploading an avatar → the picture shows on the profile right away; clicking delete on the avatar → the picture is removed from the profile.
• Clicking the language button in the top-right corner of the header and picking a different language → the interface switches and saves immediately; signing out and back in → the same language is still there.
• Whoever is assigned account-management permission, on the Client site or in the Back Office, locks an account within their scope → that account can no longer sign in.
• Someone without account-management permission tries to lock another account → rejected.
• Unlocking a blocked account → the account can sign in normally again.
• Archiving an account → that account can no longer sign in; trying to reactivate an archived account → there is no path back to any other status.
• A new user finishes registering → a default personal configuration set is already there, no extra step needed.
• Opening one's own configuration → the saved options show up correctly (for example a seen-the-tour flag); editing one and saving → the new value is there the next time it opens.

6. Non-Functional Requirements

Area	Requirement
Data integrity	No two accounts ever share the same username, or the same verified email or phone; soft-delete preserves every account record
Tenancy & authorization	Account scope (organizer/merchant) is resolved per user; status, profile, and configuration operations are all permission-gated
Privacy	An OTP re-request for an identifier that already exists sends silently - it never reveals that the account exists
Consistency	Registration creates the account, profile, identifiers, and default configuration together; partial creation is not allowed
i18n	User-facing labels and statuses are bilingual (English/Vietnamese); the language the user picks drives what they see

7. UX & Flows

Key screens: the profile page with avatar on the Client site, the language button in the header, and the account-status area (activate, deactivate, block, archive) for assigned managers on both the Client site and the Back Office.

8. Data & Domain

Entity	Role
User account	The durable account - system-generated ID, status, soft-delete, organizer/merchant scope
Login identifier	A login value (username, email, phone) with a verification flag, never shared between two accounts
User profile	One-per-user personal info - name, birthday, language, contacts, avatar
User configuration	A per-user personal setting, grouped and uniquely keyed by code

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

9. Dependencies & Assumptions

Depends on

#	Feature	What is depended on
01	AUTH Authentication	registration, OTP delivery, and sign-in gating live in the AUTH area.
02	ROLE Roles & scoping	the account is the subject roles and organizer/merchant scope attach to.
03	MORG Multi-organizer membership	a single user belonging to multiple organizers at once belongs to this area; this PRD does not restate it.
04	Shared platform core	shared data models, scoping, and configuration plumbing.

Assumptions

#	Assumption	What breaks if it is wrong
01	A user registers through the sign-up flow, which triggers account, profile, identifier, and default-configuration creation.	If registration does not trigger all four together, a new user ends up missing identifiers or configuration, and other modules have nothing stable to attach a role to.
02	An OTP channel (email/SMS) exists for verifying email and phone identifiers.	Without an OTP channel, newly added emails and phones stay unverified forever, and a user has no way to verify their own identifier.

10. Release Plan & Launch Criteria

Aspect	Plan
Phase	P1 (foundation) - see the URD feature catalog
Rollout	All users; no feature flag
Migration	None for new accounts; the default configuration is provisioned per user at registration
Launch criteria	Registration verified to create the account, profile, identifiers, and default configuration together; OTP verification flips identifier state; status changes gate sign-in; soft-delete preserves data
Monitoring	Registration success rate, OTP verification rate, uniqueness-promise violations, configuration-bootstrap coverage

References

• URD: User Management - User Account
• Builds on: Authentication · Multi-organizer membership · Roles & scoping - Permissions URD
• Related PRD: User identifiers & configuration
• Module: User Management - URD
• Developer: @nx/identity · domain model · @nx/core

Risks & Open Questions

#	Risk / question	Mitigation / status
01	Two accounts sharing an identifier	No account ever shares a username, or a verified email or phone, with another account
02	Account discovery via code requests	An OTP re-request for an identifier that already exists sends silently
03	Half-created accounts on registration failure	The account, profile, identifiers, and default configuration are created together; partial creation is not allowed
04	Reactivating an archived account	Archived is terminal by design for an account

Frequently asked questions

#	Question	Answer
01	Can a user have more than one email or phone?	Yes - an account holds multiple identifiers (username, email, phone). Username is required and verified; email and phone start unverified and need an OTP code.
02	Can two people share the same verified email or phone?	No - no two accounts ever share the same username, or the same verified email or phone.
03	What happens when an account is deleted?	It's soft-deleted - the record is preserved and never physically removed.
04	Why can't a deactivated or blocked user sign in?	Status gates sign-in - only an active account can authenticate.
05	Is Archived reversible?	By design, no - Archived is a terminal status for an account.
06	Who can change someone else's account status?	Whoever is assigned account-management permission, on the Client site or in the Back Office, can lock, unlock, or archive another account within their scope - it's not limited to a specific title.
07	Where do default settings come from?	A default configuration set is created automatically at registration; users read and update their own configuration from then on.
08	Does re-requesting an OTP code for an existing email reveal that the account exists?	No - re-requests for an identifier that already exists send silently to avoid leaking that information.