👥 Users, Roles & Permissions

Users vs POS Staff (different identities)

Solvexa maintains two separate identity concepts:

• User (AppUser table): logs into the back-office web app. Owner, accountant, purchase manager.
• Staff (Staff table): logs into POS terminals with a 4-digit PIN. Cashiers, waiters.

Same person can be BOTH — e.g. shop owner has a User login for finance + a Staff PIN for occasional cashier duty. Linked by UserID.

Add a new User (back-office login) — different from POS Staff

Use this if you want someone to log into the back-office web app (owner, accountant, purchase manager, admin). For a cashier who only rings bills on the POS terminal, use "Add a POS Staff" below instead.

1. Admin → User Management → + New User
2. Fill: Login Name (e.g. rahul), Display Name, Email, Phone, Role (see below), Initial Password
3. Optional: WhatsApp Phone + Opt-In — lets user chat with Saathi via WA
4. Optional: Secondary Role for combined permissions
5. Click Save. User gets password reset link via email (SignupMailer). Must change password on first login.

Add a new POS Staff (cashier / waiter / kitchen)

Use this if you want someone to log into a POS terminal with a 4-digit PIN — cashiers, waiters, KDS kitchen operators. This is a SEPARATE identity from a back-office User (see the "Users vs POS Staff" section above). The same person can have BOTH — e.g. a store manager might be both a User (for reports) and a Staff (for occasional cashier duty).

1. Admin → Staff Management → + New Staff
2. Fill: Staff Code (short id, e.g. C01), First Name, Last Name, Role (POS-side role, e.g. Cashier / Manager)
3. Go to the Security tab: set a Password (required for new staff) + optional POS PIN (4–6 digits, used at the till)
4. Go to the Store Access tab: pick which stores this staff can log into. Toggle Cashier / Manager / Default per store. Only the stores in the dropdown are your own tenant's stores.
5. Go to the Permissions tab: uncheck any permission you want to deny (defaults come from the role).
6. Click Save Staff. Staff can now log into POS terminals in the assigned stores using either the password OR the POS PIN.

Common confusion: if someone asks "how do I create a staff", they almost always mean this cashier flow (Admin → Staff). If they need to log into the back-office web app instead, they need a User (Admin → User Management, section above).

Fun fact: SolvexaRetail keeps User and Staff as two separate tables because the trust boundaries are very different — a POS Staff PIN is a shared-device authenticator, a User password is a personal-device one.

Built-in Roles

Fine-grained per-user permissions

Roles set the default. Override per-user for specific overrides.

1. Open a user → Permissions tab
2. List of all 200+ permissions grouped by module. Each has Allow / Deny / Inherit-from-role
3. Common overrides: give a Cashier Report.SalesRegister.View to check own sales; deny a Manager Vendor.Edit to prevent unauthorized vendor changes
4. Save. Takes effect on next login (session-cached).

Change password

• User self-service: click your name (top-right) → Change Password
• Admin reset: User Management → user → Reset Password. New password emailed to user + forced change on next login.
• Forgot password: from Login screen → Forgot Password? → enter email → reset link mailed
• Password strength: min 8 chars, ideally mix of case + digit + symbol. Bcrypt-hashed at rest.

Two-Factor Authentication (2FA)

Add a second lock: after password, prompt for a 6-digit code from Google Authenticator / Authy / 1Password.

1. Enable: Account → Security → Enable 2FA
2. Scan the QR code with your authenticator app
3. Type the current 6-digit code to confirm
4. Save 8 backup codes — each works ONCE if you lose your phone. Store somewhere safe.
5. Next login: password → 2FA prompt → in.
6. Disable: Account → Security → Turn Off 2FA (requires current 6-digit code to disable — prevents attacker from turning it off)

Lock or deactivate a user

• 5 wrong passwords → auto-locked for 15 min (no admin action needed)
• Admin manual lock: User Management → user → toggle Active. Blocks login immediately.
• Delete a user: NOT possible after they've posted transactions. Instead, deactivate.
• Sessions kill: Admin → Sessions → tick user's active sessions → Revoke. Forces re-login.

Login + activity audit

• Admin → Sessions: who's logged in right now (IP, browser, since when)
• Admin → LoginLog: last 30 days of login attempts (success/fail, IP)
• Admin → AuditFeed: sensitive events — POS Manager Override, Cost Change, Permission Grant. AI-narrated by Saathi.
• Failed login spikes = brute force attempt. IP auto-added to rate-limit block list.

Store-level scoping

Multi-store businesses: restrict a user to see only their store.

1. Open user → Allowed Stores tab
2. Tick stores this user can access. Untick to hide.
3. Save. User's default filter across all reports scoped to allowed stores.
4. Manager overrides: still needs the permission (e.g. Store.Switch) to change stores at all.