Users
- Code: SET-USR
- Module: Settings
- Type: Master Data
1. Overview
Users are the accounts that can log in to the tenant-dashboard. Each user has a name, login email, active status, and one or more roles, which determine their access rights throughout the application. A user is linked to an entity, so if the same entity is also an employee, the user acts as that employee, for example as the PIC of a Purchase Order. When a user is created, the system sends an email with a link for the user to set their own password, which also proves their email. When their email is changed, the system sends a verification email. Until a new user sets a password, the account cannot be used at all; if the link expires or the email does not arrive, an admin can resend it from the user detail. A user who changes their email can still log in but cannot access the app’s features until the new email is verified.
Expected outcome: only authorized people can log in, and each user can only do what their roles allow.
2. Problem
Without individual accounts and clear access rights, staff activity cannot be traced and access to sensitive data is hard to restrict. As a result:
- One shared account for many people makes activity untraceable.
- Not every staff member may access every module; for example, cashiers must not change settings.
- A mistyped email means the user does not receive the link and cannot access the app’s features; emails must be verified.
3. Goals & Non-goals
3.1 Goals
- Everyone uses their own account, so every activity can be traced back to its actor.
- Each person’s access is restricted according to their roles, not made the same for all staff.
- The login email is confirmed to be correct and owned by its user before the user can access the app’s features.
- Access can be revoked at any time without deleting that person’s activity history.
3.2 Non-goals
- Admins setting or changing a user’s password.
- Login through third-party providers (SSO) and two-factor authentication.
- Granting permissions directly to users outside of roles.
4. Business Rules
Business rules are the set of provisions and constraints that apply to Users throughout the application, on every screen and action that involves it, whoever performs it. These rules are the single source of truth: if another part of this PRD appears to differ, the rules here prevail.
- BR-01 The user’s email is the login identity and must not be the same as another user’s.
- BR-02 Every user must have at least one role. The permissions that apply to them are the union of all their roles.
- BR-03 Every email change must go through email verification through a unique link that can only be used once. New users do not need separate verification: their email is automatically verified when they successfully set their password (see the Authentication PRD, BR-07 to BR-08).
- BR-04 One entity may only have one user account. Creating from an entity can only use an entity that does not have an account yet.
- BR-05 An inactive user cannot access the system, including through an ongoing session.
- BR-06 User passwords are not set by an admin from this page; a new user sets their own first password through a link in an email, per the Authentication PRD (BR-07 to BR-08). 🚧 Not yet: FE + BE
- BR-07 Every change to user data is recorded along with its actor and time.
- BR-08 A user who has not set a password cannot log in, cannot reset their password, and cannot do anything until the password is set. If the link expires or the email does not arrive, an admin resends a new link from the user detail; the old link stops working immediately. Resending is only available while the password has not been set (see Authentication PRD, BR-14 and BR-15). 🚧 Not yet: FE + BE
5. Flow
5.1 Main Flowchart
- Choose Source — An account can be created from scratch, or from an existing entity so that one person is not recorded twice.
- 0a. Choose Entity — An entity without an account is selected first, then its name and email are filled in automatically.
- Profile — The user name, login email, and account status are filled in.
- Roles — At least one role is selected to determine the user’s access rights.
- Review — All inputs are reviewed before saving.
- Validation — Inputs are checked before the account is saved. An account that violates the rules cannot be saved, and the errors are shown in the relevant section.
- User Saved — The account is created and an email with a set-password link is sent to the registered address.
- Set Password — The user opens the link in the email, fills in their own password, and by doing so proves that the email really belongs to them. If the link expires or the email does not arrive, an admin resends a new link from the user detail (BR-08). 🚧 Not yet: FE + BE
- Account Active — The user can log in and use the app according to their roles.
5.2 Status Lifecycle
A user has two independent statuses:
| Status | Description | Next |
|---|---|---|
Activeis_active: true | The account may be used to log in | Inactive |
Inactiveis_active: false | The account is deactivated and cannot access the system | Active |
Unverifiedemail_verified_at: null | Ownership of the login email has not been proven | Verified |
Verifiedemail_verified_at set | The login email has been verified by its owner | Unverified, when the email is changed |
6. Document Structure
6.1 General
| Field | Type | Required | Default | Rules |
|---|---|---|---|---|
| User Name | Text | Yes | Follows the entity, if created from an entity | Maximum 20 characters |
| Text | Yes | Follows the entity, if created from an entity | Used as the login email, must be unique, valid format, maximum 50 characters (BR-01) | |
| Status | Enum | Yes | Not selected | Active or Inactive |
| Roles | Ref. Role, multiple | Yes, at least 1 | — | Selected from the Role master (BR-02) |
| Email Verified | Boolean | — | — | Set by the system when the user successfully sets their password (new account) or opens the verification link (email changed) (BR-03) |
| Avatar | File | — | — | Set by the user themselves through My Account, cannot be changed from this page |
7. UI Structure
This section defines how Users are displayed and operated: the list columns, filters, and form controls along with their option sources. This section only governs display and interaction; content and value rules still follow Document Structure.
7.1 Datatable
| Column | Sortable | Sample Value | Component |
|---|---|---|---|
| User Name | Yes | Budi Santoso | Text |
| — | budi@toko.com | Text, with a verified icon | |
| Roles | — | Store Manager | Text |
| As Employee | — | EMP-0042, or empty | Link to the Employee detail |
| As Supplier | — | SUP-0012, or empty | Link to the Supplier detail |
| Status | — | Active | Badge |
| Actions | — | View · Edit · Delete | Action Menu |
7.2 Advance Filter
| Field | Control | Options Source | Default |
|---|---|---|---|
| Status | Single Select | Active or Inactive | Empty |
| Roles | Multi Select | Role master | Empty |
7.3 Form & Details
Create — The Choose Source dialog (From Scratch or From Entity) appears first. Choosing From Entity adds a Choose Entity step, which fills in User Name and Email automatically. A three-step wizard: Profile, Roles, then Review. Actions: Next, Save.
Edit — Three tabs, Profile, Email, and Roles, each saved separately.
Detail — User name and status badge at the top, followed by read-only Profile, Email, and Roles tabs. Actions: Edit Data, Delete, Activity Logs, and Resend Link. Resend Link is only shown while the user has not set a password (BR-08). 🚧 Not yet: FE + BE
Profile
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Status | Single Select | Active or Inactive | — |
| User Name | Text Input | — | Filled from the entity if created from an entity |
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Text Input | — | Filled from the entity if created from an entity; saved → a verification link is sent to the new address |
Roles
| Field | Control | Options Source | Behavior |
|---|---|---|---|
| Roles | Multi Select (cards) | Role master | Each role card can be expanded to view and search its permissions; at least one role selected |
8. User Stories
US-01 - Create a user from scratch
As an owner, I want to create accounts for staff, so that they can log in with the appropriate access rights.
| ID | Acceptance criteria |
|---|---|
| AC-01.1 | Opening Add User shows the source choice dialog; “Create from Scratch” opens the Profile → Roles → Review wizard. |
| AC-01.2 | User name is required (max 20 characters), email is required (valid format, max 50 characters), status must be selected. |
| AC-01.3 | At least one role must be selected. |
| AC-01.4 | The Review step shows info that an email with a set-password link will be sent after the data is saved (BR-06). 🚧 Not yet: FE |
| AC-01.5 | On success, a success toast appears, the user is redirected to the list, and the email with the set-password link is sent (BR-03, BR-06). |
| AC-01.6 | Error messages (for example, the email is already in use) appear in the Review step and on the related fields (BR-01). |
| AC-01.7 | The user does not receive the email or the link has expired — the admin resends it from the user detail (see US-09). 🚧 Not yet: FE + BE |
| AC-01.8 | User name longer than 20 characters — rejected while filling in; the error message currently says “max 50” and needs to be aligned. |
US-02 - Create a user from an entity
As an admin, I want to create an account from an existing entity (for example an employee), so that identities are not duplicated.
| ID | Acceptance criteria |
|---|---|
| AC-02.1 | The entity table only shows entities that do not have a user account yet. |
| AC-02.2 | After an entity is selected and Next is clicked, the name and email are filled from the entity. |
| AC-02.3 | Data is sent with the selected entity’s party_id. |
US-03 - Edit a user profile
As an admin, I want to change a user’s name and status, so that access can be enabled or revoked.
| ID | Acceptance criteria |
|---|---|
| AC-03.1 | The Edit Data button only appears for users with the update permission. |
| AC-03.2 | The Profile tab saves the name and status; the save button is only enabled when there are changes. |
| AC-03.3 | An admin deactivates their own account — not prevented while filling in; it must be rejected on save so admins do not lock themselves out. |
| AC-03.4 | A user is deactivated while logged in — the session ends at the next access check (BR-05). |
US-04 - Change a user’s email
As an admin, I want to change a user’s login email, so that a user with a wrong email can still log in.
| ID | Acceptance criteria |
|---|---|
| AC-04.1 | The Email tab only appears in edit mode. |
| AC-04.2 | The new email is required, valid format, max 50 characters. |
| AC-04.3 | After saving, the system sends a verification email to the new address; verification info is shown in the tab. |
| AC-04.4 | An admin changes a user’s email — its verification link uses the new account verification flow, unlike an email change from My Account. Needs confirmation: both flows must be accepted. |
US-05 - Change a user’s roles
As an owner, I want to add or revoke a user’s roles, so that their access rights match their duties.
| ID | Acceptance criteria |
|---|---|
| AC-05.1 | The Roles tab in view mode shows the user’s roles; in edit mode it shows all roles with checkboxes. |
| AC-05.2 | At least one role must remain selected. |
| AC-05.3 | Each role card can be expanded to view and search its permissions. |
| AC-05.4 | An admin revokes roles from their own account — not prevented while filling in; it must be rejected on save so admins do not lock themselves out (BR-02). |
| AC-05.5 | Deleting the last role that gives all admins access to Settings — Needs confirmation (see the Roles & Permissions PRD). |
US-06 - User list and filters
As an owner, I want to view and filter users, so that it is easy to check who has which access.
| ID | Acceptance criteria |
|---|---|
| AC-06.1 | Columns: name, email (with a verified icon), roles, as employee, as supplier, status. |
| AC-06.2 | Keyword search; advanced filters for status and roles; pagination. |
| AC-06.3 | Row actions: View, Edit, Delete according to permissions; bulk delete from selected rows. |
US-07 - Delete a user
As an owner, I want to delete accounts that are no longer needed.
| ID | Acceptance criteria |
|---|---|
| AC-07.1 | Single and bulk delete require confirmation and the delete permission. |
| AC-07.2 | If the deletion is rejected, the error message appears as a toast. |
| AC-07.3 | An admin deletes their own account — not prevented while filling in; it must be rejected on save so admins do not lock themselves out. |
US-08 - Resend set-password link
As an admin, I want to resend the set-password link to a new user, so the user can still activate their account when the link expires or the email does not arrive.
| ID | Acceptance criteria |
|---|---|
| AC-08.1 | The Resend Link button appears in the user detail only while the user has not set a password, and only for admins with permission (BR-08). 🚧 Not yet: FE + BE |
| AC-08.2 | After it is pressed, a new link is sent to the user’s email; a success toast appears and the previous link stops working immediately (BR-08). 🚧 Not yet: FE + BE |
| AC-08.3 | The button shows a sending state and cannot be pressed again while in progress; if it fails, an error toast appears. 🚧 Not yet: FE + BE |
| AC-08.4 | A user who has already set a password — the button is not shown (BR-08). 🚧 Not yet: FE + BE |
| AC-08.5 | The resend is recorded in the activity log (BR-07). 🚧 Not yet: FE + BE |
US-09 - Activity history
As an auditor, I want to see the user activity log.
| ID | Acceptance criteria |
|---|---|
| AC-09.1 | The log is available for all users (in the list) and per user (in the detail), with event, actor, and date range filters. |
9. User Scenarios
| Role | Scenario |
|---|---|
| Owner | Creates an account for a new store manager with the “Store Manager” role |
| Admin | Creates an account for an already registered employee, without retyping their name and email |
| Admin | Changes a mistyped user email; the user verifies the new email |
| Admin | Resends the set-password link to a new user whose link expired |
| Owner | Deactivates the account of a staff member who has left |
| Admin | Adds the “Purchasing” role to a user who takes on extra duties |
10. Permissions & Actions
10.1 Permission by Action
| Action | Permission | Condition |
|---|---|---|
| View User List | settings:user:list:any | — |
| View Activity Logs | settings:user:list:any | — |
| View User Detail | settings:user:view:any | — |
| Create User | settings:user:create:any | — |
| Edit User (Profile) | settings:user:update:any | — |
| Edit User (Email) | settings:user:update:any | — |
| Edit User (Roles) | settings:user:update:any | — |
| Resend Set-Password Link | settings:user:update:any | User has not set a password 🚧 Not yet: FE + BE |
| Delete User | settings:user:delete:any | — |
11. Notifications
This feature does not trigger any notifications.
12. Dependencies
Related PRDs
- Roles & Permissions — user roles and permissions.
- Entities — user identity and synchronization with employees/suppliers.
- Employees — users linked to an employee act as that employee on transactions.
- Authentication (Account) — login, email verification, and forgot/reset password.
- Activity Logs — the source of the activity log.
Effects on other modules
- User permissions determine which sidebar menus appear and which actions are available in every module.
- Users are the actors recorded in every activity log.