PRD: User identifiers & configuration management

Module	User Management	PRD ID	PRD-USR-002
Status	Ready to dev	FEAT	USR
Epic	—	Plane	BANA-1525
Date	2026-06-15	Version	v1.0
Packages	@nx/identity	URD	USR
Surface	Client · Owner/Mgr
Owner	Phát Nguyễn

What identifiers & configuration management is

PRD-USR-001 established the account: a user can hold several login identifiers, and a default set of configurations is seeded at registration. That PRD defined what those records are - this PRD defines how a user manages them afterwards as standalone, permission-gated resources: list, add, remove identifiers; read and write user configuration.

Every identifier carries a scheme that types it - username, email, phone, plus system-issued schemes - drawn from a fixed set. Adding an identifier always binds it to the caller and always starts unverified, whatever the request claims. Configurations are grouped under system or table, uniquely keyed by code per user, and readable right after sign-in - before a merchant or organizer is even chosen - so the app can hydrate preferences from the first screen.

Why a dedicated management surface is needed

Without a managed surface a signed-in user cannot add a second phone, list the identifiers they already hold, or save their own table layout - and nothing guards the two ways an identifier-create goes wrong: attaching it to another user, or attaching one pre-marked verified to skip the one-time code. Removing an identifier is missing a similar guard: nothing stops a user from removing their own last verified email, or - at the Owner role or below - their own last verified phone, losing a trustworthy way to sign back in.

Configurations have a subtler gap: they must be readable before a merchant or organizer is chosen - the very first thing the client needs to render preferences - yet the standard resource pattern gates reads behind a merchant scope. This increment closes these gaps, and adds a per-user custom table view, built by cloning a base table layout.

One identifier, from add to removal

On the Profile screen in Account Settings (specified in PRD-AUTH-001), a user adds a new phone number. It is stored under their own account and marked unverified, awaiting a one-time code - regardless of any user reference or verified flag the request sends along. That same user tries to remove their last verified phone → the removal is refused, keeping at least one trustworthy way to sign back in. Separately, the app loads the user's configurations the moment they sign in - before an organizer or merchant is chosen - and the user saves a custom "Products" table view; the system clones the base product table layout into a new per-user view, refusing a second view that reuses the same code.

The easiest thing to get wrong

The last-verified-identifier rule applies to EVERY removal path, not just the profile screen

It is easy to assume that blocking the removal of the last verified email or phone is just a form validation on the profile screen. It is not - the rule applies to every identifier-removal path, including inside the verification flow.

Enforce it in only one place, and a user can still lock themselves out of signing back in through a different removal path the profile-screen validation never covers.

1. Goals & Non-Goals

Goals

• Expose identifiers as a managed resource - list, search, count, single read, update, remove - scoped to the caller.
• Make adding an identifier safe by construction: it is always bound to the requesting user and always created unverified.
• Type every identifier with a scheme (username, email, phone number, plus system-issued schemes) drawn from a fixed set.
• Guard identifier removal: keep at least one verified email in place if it is the last one, and for a user at the Owner role or below, keep at least one verified phone in place.
• Expose configurations as a managed resource, grouped under system or table and uniquely keyed by code per user.
• Allow configuration reads right after sign-in, before a merchant or organizer is chosen (user-level resource), while gating create / update / delete.
• Let a user save a custom table view from a code + display name, auto-saved on every edit, cloned from the base table layout, rejecting duplicates.

Non-Goals

• The account-bootstrap path itself (registration creating account, profile, identifiers, default configs) - specified in PRD-USR-001.
• One-time-code request / delivery / verification flows - they live in the AUTH area (Authentication); this PRD only sets an identifier's initial unverified state, and the removal rule that keeps the last verified identifier in place.
• Password and credential schemes (URD-AUTH).
• Custom role / permission definition → Permissions.
• The contents of any specific configuration (SMS provider config, search pipeline, finance defaults) - this PRD governs the management surface, not each configuration's structure.

2. Success Metrics

Metric	Target / signal
Identifier ownership safety	100% of created identifiers are owned by the requesting user; no cross-user attachment is possible
Verification safety	100% of created email / phone identifiers start unverified; none bypass the one-time code via a pre-set flag
Sign-back-in safety	No account can remove all of its verified identifiers - at least 1 verified email (if it is the last) and 1 verified phone (for Owner and below) always stay in place
Readable before choosing an organizer/merchant	A signed-in user can read their configurations before selecting an organizer or merchant
Config key integrity	A configuration is uniquely resolvable by code within a user
Custom-view correctness	A saved view is rejected on duplicate code, and refused when its base table layout is missing

3. Personas & Scenarios

Persona	Goal in this feature
Owner / end user	Add and manage their own emails / phones, and save personal table layouts
Authorized operator	Browse and maintain identifiers within their scope under explicit permissions
Client app	Read a user's configurations at launch, before an organizer or merchant is chosen, to hydrate preferences

Core scenario: a signed-in user opens identifier management → sees the identifiers they hold, each shown by its scheme → adds a new phone; it is stored against their own account and marked unverified, awaiting a one-time code. That same user tries to remove their last verified phone → the removal is refused, keeping at least one trustworthy way to sign back in. Separately, the app loads the user's configurations the moment they sign in - before an organizer or merchant is chosen - and the user saves a custom "Products" table view; the system clones the base product table layout into a new per-user view, refusing a second view that reuses the same code.

4. User Stories

#	As a	I want	So that
01	user	to add an email or phone to my existing account	I can later verify it and use it to sign in
02	user	any identifier I add to belong to me and start unverified	no one can pre-trust a contact or attach it elsewhere
03	user	to see and manage the identifiers I already hold, each labelled by type	I know my account's login surface
04	user	the system to stop me from removing my last verified email or phone	I don't lock myself out of signing back in
05	user	my preferences to load the moment I sign in, before I pick an organizer or merchant	the app feels personalised from the first screen
06	user	to save my own table layout by name, auto-saved the instant I edit it	my columns and filters persist across sessions
07	user	a duplicate-named view refused	my saved views stay unambiguous

5. Functional Requirements

#	Requirement	Status	URD ref
FR-001	Every identifier declares a scheme that types it - username, email, phone number, plus system-issued schemes - drawn from a fixed, validated set.	✅	URD-USR-012
FR-002	Identifiers are a managed resource: list, search, count, and single-record read, scoped to the caller's access.	✅	URD-USR-013
FR-003	Adding an identifier always binds it to the requesting user and creates it unverified. A supplied user reference or verified flag cannot override this.	✅	URD-USR-014 · URD-USR-005
FR-004	Identifiers can be updated and removed, single or by filter, via soft-delete. Identifier data is preserved.	✅	URD-USR-015 · URD-USR-009
FR-005	Removing a verified email is refused if it is the account's last verified email. • A user at the Owner role or below must always keep at least one verified phone; removing the last verified phone is refused even if the account still has a verified email. • The rule applies wherever removal happens, from the profile screen or inside a verification flow.	🚧	URD-USR-017 · URD-USR-018
FR-006	Every identifier operation (read / create / update / delete) is individually permission-gated and merchant-scoped.	✅	URD-USR-016
FR-007	Configurations belong to a fixed group set (system, table) and are uniquely identified by code per user.	✅	URD-USR-019
FR-008	Configuration reads are available to any authenticated user right after sign-in, before an organizer or merchant is chosen. Create, update, and delete are permission-gated.	✅	URD-USR-021
FR-009	A user can create a custom table view from a code and display name. • The system clones the base table configuration's stored layout into a new per-user view in the table group. • After creation, every edit to the view's columns or filters is auto-saved immediately, with no Save button required.	✅	URD-USR-020
FR-010	Creating a custom view rejects a duplicate view: same user, code, and name. It requires the referenced base table configuration to exist.	✅	URD-USR-020

5.1 Acceptance Criteria

• View the list of your own identifiers → each one is shown with its scheme (username / email / phone, or a system-issued scheme).
• List, search, count, or single-read an identifier → only identifiers within your own access scope are visible.
• Add a new identifier, even if the request supplies another user's reference or a verified flag → the identifier is still stored under the caller's own account and stays unverified.
• Update or remove an identifier (single or by filter) → the identifier moves to a removed state (soft-delete); its data is preserved.
• Remove the account's last verified email → the removal is refused.
• A user at the Owner role or below removes their last verified phone, even while the account still has a verified email → the removal is refused.
• Try to read, create, update, or remove an identifier without the matching permission, or one that belongs to another merchant → refused.
• Open your own list of configurations → each configuration belongs to the system or table group and is uniquely identified by its code.
• Sign in, before choosing an organizer or merchant, and read your configurations → they are readable immediately; try to create, update, or delete a configuration without permission → refused.
• Create a custom table view with a code and display name → a new view is created, cloned from the base table configuration's layout; then edit the view's columns or filters → the change is auto-saved immediately, with no Save button needed.
• Create a view that duplicates an existing one (same user + code + name) → refused.
• Create a view that references a base table configuration that does not exist → refused.

6. Non-Functional Requirements

Area	Requirement
Ownership integrity	Identifier-create derives the owner from the authenticated caller, never from whatever the request declares
Verification integrity	A created identifier is always unverified; the verified state is reachable only through the one-time-code flow
Sign-back-in integrity	An account never loses all of its verified contact identifiers - removing the last verified email or phone is blocked, wherever removal happens
Authorization	Identifier operations are individually permission-gated; configuration reads are authenticate-only (user-level), writes permission-gated
Pre-merchant access	Configuration reads succeed before an organizer or merchant scope exists, so the client can hydrate at launch
Soft-delete	Removing an identifier or configuration preserves the record; physical deletion is never performed
i18n	User-facing labels (identifier-type and configuration labels) are bilingual (English / Vietnamese)

7. UX & Flows

Viewing, adding, and verifying identifiers lives in Account Settings, specified in PRD-AUTH-001 - Authentication & account verification. This PRD is the resource layer underneath that screen: list, add, remove (with the rule keeping the last verified identifier in place), and permission-gating; plus preferences hydration at sign-in and the per-table "save view" control that persists a user's columns and filters.

8. Data & Domain

Entity	Role in this increment
Login identifier	A typed login value - scheme (username / email / phone, plus system schemes), the identifier value, a verified flag, owned by a user; managed as a resource, with a removal rule keeping the last verified identifier in place
User configuration	A per-user setting - group (system / table), code, display name, stored value - uniquely keyed by code per user; the integration group is a system-wide configuration outside this personal store; a custom view is a table-group entry cloned from a base layout, auto-saved on every edit

Conceptual only - full data model and rules live in the identity domain model. Identifier ownership and uniqueness are enforced by the application's own checks, not by cross-record data-layer constraints.

9. Dependencies & Assumptions

Depends on

#	Feature	What is depended on
01	PRD-USR-001 User account & configuration	this increment manages the identifiers and configurations that account bootstrap creates.
02	AUTH Authentication	the one-time-code flow flips an identifier from unverified to verified; this PRD only sets the initial state and the removal rule that keeps the last verified identifier in place; AUTH-001's onboarding wizard already makes phone verification mandatory for users at the Owner role or below, which is the foundation this rule relies on.
03	ROLE Roles & scoping	identifier operations are permission-gated and scoped to the caller; the last-verified-phone rule needs to know the caller's role (Owner or below).
04	Shared platform core	shared identifier and configuration models, scheme / group definitions, and base table layouts.

Assumptions

#	Assumption	What breaks if it is wrong
01	A user is authenticated before managing identifiers or configurations (except where reads are intentionally open at the user level).	Without that authentication step, an anonymous request could list or edit another user's identifiers, breaking the exact promise that operations are scoped to the caller.
02	Base table layouts exist as seeded table-group configurations that a custom view can clone from.	Without a base layout, creating a custom view has nothing to clone and is refused outright, blocking the personal-layout feature entirely.

10. Release Plan & Launch Criteria

Aspect	Plan
Phase	P1 (foundation) - extends USR in the URD feature catalog
Rollout	All users; no feature flag
Migration	None - the surfaces operate on existing identifier and configuration records
Launch criteria	Identifiers are listable and addable; a created identifier is owned by the caller and unverified; removing the last verified email or phone is blocked; configurations are readable before an organizer or merchant is selected; a custom view clones the base layout, auto-saves on edit, and refuses duplicates / missing base
Monitoring	Identifier-create ownership/verified invariants, identifier-removal rejection rate by reason (last email / last phone), configuration read latency at sign-in, custom-view rejection rate by reason

References

• URD: User Management - User Account
• Builds on: PRD-USR-001 - User account & configuration
• Related: PRD-AUTH-001 - Authentication & account verification · Roles & scoping - Permissions URD
• Module: User Management - URD
• Developer: @nx/identity · domain model · @nx/core

Risks & Open Questions

#	Risk / question	Mitigation / status
01	An identifier attached to the wrong user	Owner is taken from the authenticated caller, never from whatever the request declares
02	A contact pre-marked verified to skip the one-time code	Create always forces the unverified state; verification is reachable only via the one-time-code flow
03	A user locks themselves out of signing back in by removing all verified identifiers	Removal is refused when it is the last verified email, or when a user at the Owner role or below removes their last verified phone; the rule applies wherever removal happens
04	Configuration reads blocked before an organizer or merchant is chosen	Reads are authenticate-only at the user level, so the client can hydrate at launch
05	Two custom views colliding on the same code	A duplicate (user + code + name) view is refused before anything is saved
06	A view cloned from a missing base layout	Creation requires the referenced base table configuration to exist, else it is refused

Frequently asked questions

#	Question	Answer
01	Can I add an identifier to another user's account?	No - the owner is always the authenticated caller; any user reference in the request is ignored.
02	Why does a new email I add show as unverified?	Every added identifier starts unverified by design; it becomes a usable login only after the one-time-code flow verifies it.
03	Can I remove all of my identifiers?	Not quite - you must always keep at least one verified email if it is your last one, and if you are at the Owner role or below, at least one verified phone; the system refuses any removal that would leave you without a trustworthy way to sign back in, whether you remove it from the profile screen or inside a verification flow.
04	Why can I read my settings before choosing an organizer or merchant?	Configurations are a user-level resource, so reads are open to any signed-in user - that lets the app hydrate your preferences the moment you sign in, before an organizer or merchant is selected.
05	What is a custom view?	A personal table layout (columns and filters) saved under your account, cloned from a base table layout and identified by a code and name; every time you adjust its columns or filters, it auto-saves immediately, no Save button needed.
06	What stops two views clashing?	A view reusing an existing (user + code + name) combination is refused, and a view whose base table layout does not exist is refused as well.