User Management & Access ControlCore Module

Regional Scopes

1. Overview & Purpose

What are Regional Scopes?

Regional Scopes establishes territorial access boundaries across physical store branches and storage locations. It ensures staff accounts can only view, transact, and audit data belonging strictly to their authorized branches (user_branches) and outlet locations (user_locations).

Menu Location:User Management > User Scopes

2. When to Use Regional Scopes

Single Store Outlet Binding for Frontline Staff (Cashier Scope)

A retail cashier at the "Kelapa Gading Retail Store" must only open register shifts on counters located in that specific store and access local store inventory.

Recommended Action:Create a User Branch scope mapping the user strictly to that branch and set isDefault = true. The global context switcher is hidden to prevent accidental cross-branch data corruption.

Multi-Outlet Territory Scoping for Roaming Supervisors

A regional area supervisor oversees 3 mall boutiques (Grand Indonesia, Senayan City, and Pondok Indah Mall) and needs to toggle between them.

Recommended Action:Assign all 3 branches in User Scopes, designating Grand Indonesia as isDefault = true. The UI context bar displays a dropdown restricted exclusively to those 3 authorized outlets.

Storage Room Physical Security Boundary (User Locations)

A warehouse clerk is permitted in the General Receiving Dock but restricted from entering high-value electronics vaults or chemical storage rooms.

Recommended Action:Navigate to the User Locations tab and bind the employee account strictly to permitted storage locations, preventing unauthorized inventory stock deductions elsewhere.

Default Branch Initialization for Seamless Authentication

Preventing staff from encountering "Branch Not Selected" runtime errors upon initial web login or POS register boot-up.

Recommended Action:Every active employee must possess exactly one primary branch marked as isDefault = true, which automatically establishes the initial operational context upon token exchange.

3. Data Dictionary & Fields

Schema structure for the user_branches and user_locations territory boundary tables:

Field / Column	Input Type	Requirement	Description & Operational Guide
userId	BIGINT (FK)	Required	Reference to users table identifying the scoped employee.
branchId	BIGINT (FK)	Required	Reference to branches table designating the authorized physical business unit.
isDefault	BOOLEAN	Required	Flags the primary branch auto-selected upon user login context initialization.
locationId	BIGINT (FK)	Required	Reference to locations table defining authorized warehouse or outlet rooms.
createdBy	BIGINT (FK)	Required	Administrator user who granted the branch or location territory scope.
createdAt	DATETIME	Required	Audit timestamp when the territorial binding was provisioned.

4. Interface Preview

User Scopes tabbed view providing independent management of branch assignments and storage location boundaries.

inventories-web

Menu Location:Route: /admin/user-management/user-scopes

Screen Preview: User Scopes Management Interface

Visual interface illustration and control layout for menu Route: /admin/user-management/user-scopes

1User Branches & Locations Tabs2Assign Branch Scope Modal3Default Branch Indicator4Revoke Territory Access

User Scopes console featuring User Branches and User Locations tabs, primary default indicators, and assignment dialogues.

5. Assigning Branch Scopes

Open User Scopes Dashboard

Navigate to User Management > User Scopes from the sidebar navigation.

Select Scope Tab

Choose either the User Branches tab or the User Locations tab.

Launch Scope Assignment Modal

Click Add User Branch or Add User Location button in the top toolbar.

Select User & Branch Territory

Pick the target user and the physical branch or location they are assigned to.

Set Default Status & Commit

Toggle isDefault if this is the staff member primary branch, then click Submit.

Only one branch per user can be designated as the active default branch.

6. Assigning Location Scopes

Search Scoped Staff

Filter scope table by staff name, username, or branch name.

Switch Primary Default Branch

Edit the user branch record to toggle the default flag when staff transfers base branches.

Save Scope Modification

Confirm the update; the new default branch takes effect upon their next session login.

7. Scope Revocation Rules

Primary Branch Reassignment Required

Before deleting a user default branch scope, you must first designate another assigned branch as default. An account with no default branch cannot establish initial login context.

Verify No Pending Documents

Confirm staff member has no unposted stock transfers or open shifts in the target branch.

Revoke Territory Scope

Click Delete on the user branch/location row to immediately withdraw operational access.

8. Cross-Module Impact

Target Subsystem	Relational & Transactional Effect
Global Application Context Guard	Restricts the branch switcher bar exclusively to branches assigned in the user scope.
Point of Sale (POS)	Cashiers can only open POS shifts on counters located inside their authorized branches.
Inventories & Stock Management	Stock transfers and adjustments filter origin/destination locations to scoped facilities.

Operational Best Practices

Always assign at least one default branch to every new user account before issuing credentials.
For strict audit compliance, remove location scopes immediately when an employee transfers departments.