Work in Progress

Feature details in this document may change during investigation, discussion, design, and implementation phases.

User Management / Quản lý User

Manage internal operators, business owners, and staff accounts.

Overview

Attribute	Value
Module ID	`CORE-01`
Phase	Phase 1 (Internal + Owner), Phase 2 (Staff + Custom Roles)
Priority	HIGH
Dependencies	None (Foundation module)

The User Management module provides comprehensive account management for three user types: Internal Users (system operators), Owners (business owners/Chủ hộ), and Staff (employees). It supports hierarchical user structures with clear separation between internal operations and merchant-facing functionality.

User Types

Type	Description	Scope
Internal	VNPAY employees who operate and manage the system	System-wide
External	Business owners and their employees	Per Organization

┌─────────────────────────────────────────────────────────────────────────────┐
│                           USER HIERARCHY                                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                    INTERNAL USERS (System)                          │    │
│  │                                                                     │    │
│  │    ┌───────────────┐                                                │    │
│  │    │  SUPER ADMIN  │  ← Full system access, user management         │    │
│  │    └───────┬───────┘                                                │    │
│  │            │                                                        │    │
│  │    ┌───────┴───────┐                                                │    │
│  │    ▼               ▼                                                │    │
│  │  ┌─────────┐  ┌─────────┐                                           │    │
│  │  │  ADMIN  │  │  ADMIN  │  ← Manage merchants, support operations   │    │
│  │  └────┬────┘  └────┬────┘                                           │    │
│  │       │            │                                                │    │
│  │  ┌────┴────┐  ┌────┴────┐                                           │    │
│  │  │OPERATOR │  │OPERATOR │  ← Day-to-day operations, reports         │    │
│  │  └─────────┘  └─────────┘                                           │    │
│  │                                                                     │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                    │                                        │
│                                    │ manages                                │
│                                    ▼                                        │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                    EXTERNAL USERS (Merchants)                       │    │
│  │                                                                     │    │
│  │    ┌──────────────┐                                                 │    │
│  │    │    OWNER     │  ← Business owner (Chủ hộ kinh doanh)           │    │
│  │    └──────┬───────┘    Can create custom roles                      │    │
│  │           │                                                         │    │
│  │    ┌──────┴───────┬─────────────┐                                   │    │
│  │    ▼              ▼             ▼                                   │    │
│  │  ┌─────────┐  ┌─────────┐  ┌──────────┐                             │    │
│  │  │  STAFF  │  │  STAFF  │  │ CUSTOM   │  ← Dynamically created      │    │
│  │  │ (Store1)│  │ (Store2)│  │  ROLES   │    by Owner                 │    │
│  │  └─────────┘  └─────────┘  └──────────┘                             │    │
│  │                                                                     │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Internal User Roles

Role	Description	Capabilities
Super Admin	Highest privilege level	Full system access, manage all internal users, system configuration
Admin	Operations administrator	Manage merchants, handle escalations, configure features
Operator	Operations staff	Day-to-day support, view reports, assist merchants

External User Roles

Default Roles

When an Organization is created, two default roles are automatically provisioned:

Role	Description	Configurable
Owner	Business owner with full access to their organization	No (system role)
Staff	Default employee role with basic POS access	Yes

Custom Roles

Owners can create additional custom roles with configurable permissions to match their business structure:

Example Role	Use Case
Store Manager	Full store access, staff management, reports
Cashier	POS only, limited reports
Inventory Manager	Stock management, no sales access
Accountant	Reports and transactions, no POS

User Stories

Internal Users

ID	As a...	I want to...	So that...
US-INT-01	Super Admin	Create and manage Admin accounts	I can delegate system management
US-INT-02	Super Admin	Configure system-wide settings	The platform operates correctly
US-INT-03	Super Admin	View all merchant data	I can oversee platform operations
US-INT-04	Admin	Create and manage Operator accounts	Day-to-day tasks are handled
US-INT-05	Admin	Manage merchant accounts	I can support business owners
US-INT-06	Admin	Handle support escalations	Issues are resolved promptly
US-INT-07	Operator	View merchant reports	I can assist with inquiries
US-INT-08	Operator	Access support tools	I can help merchants effectively

External Users - Owner (Chủ hộ)

ID	As a...	I want to...	So that...
US-OWN-01	Business owner	Register my account with business info	I can start using the POS system
US-OWN-02	Business owner	Verify my phone/email	My account is secure
US-OWN-03	Business owner	Configure my business profile (name, MST)	Tax invoices are correct
US-OWN-04	Business owner	Enable two-factor authentication	My account is protected
US-OWN-05	Business owner	View my login history	I can detect unauthorized access
US-OWN-06	Business owner	Create custom roles	I can match my business structure
US-OWN-07	Business owner	Configure role permissions	Each role has appropriate access

External Users - Staff & Custom Roles

ID	As a...	I want to...	So that...
US-STF-01	Business owner	Create staff accounts	Employees can use the system
US-STF-02	Business owner	Assign staff to specific stores	Each staff works at correct location
US-STF-03	Business owner	Assign roles to staff	Staff have appropriate permissions
US-STF-04	Business owner	Deactivate staff accounts	Former employees lose access
US-STF-05	Staff member	Login with my credentials	I can perform my work tasks
US-STF-06	Staff member	Access features based on my role	I can do my assigned tasks

Feature Matrix

Internal User Features

Feature	P1	Description
Super Admin account	✓	Initial system administrator
Admin account management	✓	Create/manage Admin users
Operator account management	✓	Create/manage Operator users
System configuration	✓	Platform-wide settings
Merchant management	✓	View/manage all merchants
Internal audit logs	✓	Track internal user actions

External User Features (Owner)

Feature	P1	Description
Owner registration	✓	Register with phone/email
Business profile setup	✓	Name, MST, address, hours
Phone/Email verification	✓	OTP verification
Password management	✓	Set/reset password
Two-factor auth (2FA)	✓	Optional SMS/Authenticator
Login history	✓	Track login attempts
Session management	✓	Active sessions control

External User Features (Staff & Roles)

Feature	P2	P3	Description
Staff account creation	✓		Create employee accounts
Staff store assignment	✓		Assign to Merchant/POS
Role assignment	✓		Assign roles to staff
Staff deactivation	✓		Suspend/remove access
Custom role creation	✓		Owner creates custom roles
Permission configuration	✓		Configure role permissions
Staff activity tracking		✓	Performance metrics

Key Flows

Internal User Management Flow

Owner Registration Flow

Custom Role Creation Flow

Staff Account Creation Flow

User Session State

Business Rules

Internal Users

Rule ID	Rule	Description
BR-INT-01	Super Admin minimum	At least 1 Super Admin must exist
BR-INT-02	Role hierarchy	Super Admin > Admin > Operator
BR-INT-03	Self-demotion	Users cannot demote themselves
BR-INT-04	Audit logging	All internal actions must be logged

External Users (Owner)

Rule ID	Rule	Description
BR-OWN-01	Phone required	Phone number is mandatory for registration
BR-OWN-02	Unique phone	Each phone number can only register once
BR-OWN-03	MST format	Tax ID must follow Vietnam MST format (10 or 13 digits)
BR-OWN-04	Password policy	Min 8 chars, 1 uppercase, 1 number
BR-OWN-05	OTP expiry	OTP valid for 5 minutes
BR-OWN-06	Login attempts	Lock after 5 failed attempts (30 min)
BR-OWN-07	Session timeout	Auto logout after 30 min inactive
BR-OWN-08	Owner unique	Each organization has exactly 1 owner account

External Users (Staff & Roles)

Rule ID	Rule	Description
BR-STF-01	Staff limit	Max 100 staff per organization (configurable)
BR-STF-02	Staff requires store	Staff must be assigned to at least 1 Merchant
BR-STF-03	Staff requires role	Staff must have at least 1 role assigned
BR-STF-04	Multiple roles	Staff can have multiple roles assigned
BR-STF-05	Direct permissions	Staff can have direct permissions via PermissionMapping
BR-STF-06	Default roles immutable	Owner role cannot be modified or deleted
BR-STF-07	Role limit	Max 20 custom roles per organization
BR-STF-08	Role in use	Cannot delete role if assigned to staff
BR-STF-09	Effective permissions	Staff effective perms = Union(role perms) + direct perms

Acceptance Criteria

AC-INT-01: Internal User Creation

GIVEN   a Super Admin or Admin logged into Admin Portal
WHEN    they create a new internal user (Admin/Operator)
THEN    - Account is created with specified role
        - Credentials are generated securely
        - User can login to Admin Portal
        - Action is logged in audit trail

AC-OWN-01: Owner Registration

GIVEN   a new user with valid phone number
WHEN    they complete registration with business info
THEN    - Account is created with OWNER role
        - Organization is created
        - Default roles (Owner, Staff) are created
        - Business profile is saved
        - User can login immediately
        - MST is validated (format check)

AC-OWN-02: Phone Verification

GIVEN   a user entering phone number
WHEN    OTP is sent
THEN    - OTP is 6 digits
        - OTP expires in 5 minutes
        - Max 3 OTP requests per 15 minutes
        - User cannot proceed without verification

AC-OWN-03: Two-Factor Authentication

GIVEN   an owner with 2FA enabled
WHEN    they login with correct password
THEN    - 2FA prompt appears
        - Login only succeeds after 2FA verification
        - Trusted devices can skip 2FA (optional)

AC-ROLE-01: Custom Role Creation

GIVEN   an owner logged into the system
WHEN    they create a custom role
THEN    - Role is created with specified name
        - Permissions are assigned to role
        - Role is available for staff assignment
        - Role count does not exceed limit (20)

AC-ROLE-02: Role Permission Configuration

GIVEN   an owner with an existing custom role
WHEN    they modify role permissions
THEN    - Permissions are updated
        - All staff with this role inherit new permissions
        - Changes take effect immediately

AC-STF-01: Staff Account Creation

GIVEN   an owner logged into the system
WHEN    they create a staff account
THEN    - Staff receives login credentials
        - Staff is assigned to selected store(s)
        - Staff is assigned at least one role
        - Staff can login and work

AC-STF-02: Staff Role Assignment

GIVEN   an owner with existing staff and roles
WHEN    they assign roles to a staff member
THEN    - Selected roles are assigned (can be multiple)
        - Staff inherits union of all role permissions
        - Changes take effect immediately

AC-STF-03: Direct Permission Assignment

GIVEN   an owner managing a staff member's permissions
WHEN    they add a direct permission
THEN    - Permission is added via PermissionMapping
        - Staff receives permission independent of roles
        - Effective permissions updated immediately

AC-STF-04: Account Deactivation

GIVEN   a staff account that needs to be disabled
WHEN    owner deactivates the account
THEN    - Staff is immediately logged out
        - Staff cannot login
        - Staff data is retained (soft delete)
        - Can be reactivated later

Dependencies

User Management
├── Required by: Permissions, Organization, Merchant
├── Requires: None (Foundation)
├── Contains: Role Management (embedded)
└── Integrates: VNPAY MO (Merchant Onboarding)

Module	Relationship
Permissions	Roles contain permissions, Users inherit via Role
Organization	Owner belongs to Organization, Roles scoped to Organization
Merchant	Staff assigned to Merchants

Integration Points

Admin Portal (Internal Users)

┌─────────────────────────────────────────────────────────┐
│                    ADMIN PORTAL                         │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Internal Users (Super Admin, Admin, Operator)          │
│                                                         │
│  Access:                                                │
│  ├── Separate authentication system                     │
│  ├── Admin-specific web portal                          │
│  ├── Audit logging for all actions                      │
│  └── Role-based access to system features               │
│                                                         │
│  Capabilities:                                          │
│  ├── View/manage all merchants                          │
│  ├── System configuration                               │
│  ├── Support operations                                 │
│  └── Reports and analytics                              │
│                                                         │
└─────────────────────────────────────────────────────────┘

VNPAY Merchant Onboarding (MO)

┌─────────────────────────────────────────────────────────┐
│                    VNPAY MO SYNC                        │
├─────────────────────────────────────────────────────────┤
│                                                         │
│  Sales Connect → MO → PMBH                           │
│                                                         │
│  Sync Data:                                             │
│  ├── Business information                               │
│  ├── Owner contact details                              │
│  ├── Tax registration (MST)                             │
│  └── Store/outlet information                           │
│                                                         │
│  Trigger: When merchant is approved in MO               │
│  Direction: MO → PMBH (one-way sync)                 │
│  Result: Owner account + default roles created          │
│                                                         │
└─────────────────────────────────────────────────────────┘

Screenshots

Screenshots will be added after UI implementation.

Permissions - Role-based access control
Organization - Business entity management
Merchant - Store/outlet management
Reports - Staff performance reports

User Management / Quản lý User ​

Overview ​

User Types ​

Internal User Roles ​

External User Roles ​

Default Roles ​

Custom Roles ​

User Stories ​

Internal Users ​

External Users - Owner (Chủ hộ) ​

External Users - Staff & Custom Roles ​

Feature Matrix ​

Internal User Features ​

External User Features (Owner) ​

External User Features (Staff & Roles) ​

Key Flows ​

Internal User Management Flow ​

Owner Registration Flow ​

Custom Role Creation Flow ​

Staff Account Creation Flow ​

User Session State ​

Business Rules ​

Internal Users ​

External Users (Owner) ​

External Users (Staff & Roles) ​

Acceptance Criteria ​

AC-INT-01: Internal User Creation ​

AC-OWN-01: Owner Registration ​

AC-OWN-02: Phone Verification ​

AC-OWN-03: Two-Factor Authentication ​

AC-ROLE-01: Custom Role Creation ​

AC-ROLE-02: Role Permission Configuration ​

AC-STF-01: Staff Account Creation ​

AC-STF-02: Staff Role Assignment ​

AC-STF-03: Direct Permission Assignment ​

AC-STF-04: Account Deactivation ​

Dependencies ​

Integration Points ​

Admin Portal (Internal Users) ​

VNPAY Merchant Onboarding (MO) ​

Screenshots ​

Related Modules ​

User Management / Quản lý User

Overview

User Types

Internal User Roles

External User Roles

Default Roles

Custom Roles

User Stories

Internal Users

External Users - Owner (Chủ hộ)

External Users - Staff & Custom Roles

Feature Matrix

Internal User Features

External User Features (Owner)

External User Features (Staff & Roles)

Key Flows

Internal User Management Flow

Owner Registration Flow

Custom Role Creation Flow

Staff Account Creation Flow

User Session State

Business Rules

Internal Users

External Users (Owner)

External Users (Staff & Roles)

Acceptance Criteria

AC-INT-01: Internal User Creation

AC-OWN-01: Owner Registration

AC-OWN-02: Phone Verification

AC-OWN-03: Two-Factor Authentication

AC-ROLE-01: Custom Role Creation

AC-ROLE-02: Role Permission Configuration

AC-STF-01: Staff Account Creation

AC-STF-02: Staff Role Assignment

AC-STF-03: Direct Permission Assignment

AC-STF-04: Account Deactivation

Dependencies

Integration Points

Admin Portal (Internal Users)

VNPAY Merchant Onboarding (MO)

Screenshots

Related Modules