mirror of
https://github.com/Tria-plc/edr-platform.git
synced 2026-08-26 12:41:04 +00:00
143 lines
4.4 KiB
Markdown
143 lines
4.4 KiB
Markdown
# IAM Org Structure
|
|
|
|
## Core Model
|
|
|
|
### Organization
|
|
- Top-level tenant or company.
|
|
- Entity: `Organization`
|
|
- Has: `units`, `positions`, `employees`
|
|
- Supports hierarchy through `parent` and `branches`
|
|
|
|
### Unit
|
|
- Organizational subdivision under an organization.
|
|
- Entity: `Unit`
|
|
- Belongs to `organizationId`
|
|
- Supports hierarchy through `parentUnit` and `subUnits`
|
|
- Has: `positions`, `positionTypes`, `employees`, `employeePositions`
|
|
|
|
### Department
|
|
- In the IAM UI, a department is effectively a `Position`.
|
|
- There is no separate backend `Department` entity in this package.
|
|
- In the org tree UI:
|
|
- Organization -> Unit -> Department ~= Position
|
|
- Sub-department ~= subPosition
|
|
|
|
### Position
|
|
- The actual backend model behind the UI's department concept.
|
|
- Entity: `Position`
|
|
- Belongs to: `unitId`, `organizationId`
|
|
- Supports hierarchy through `parentPositionId` and `subPositions`
|
|
- Has assigned people through `employeePositions`
|
|
- Can have direct permissions through `positionPermission`
|
|
- Also linked to a `positionType`
|
|
|
|
### Position Type
|
|
- Template or category for positions.
|
|
- Entity: `PositionType`
|
|
- Example seeded concepts include things like employee, team leader, director, deputy.
|
|
- Can carry permissions through `position_type_permissions`
|
|
|
|
### Employee
|
|
- Org-scoped representation of a person inside an organization and unit.
|
|
- Entity: `Employee`
|
|
- Links a `User` into `organizationId` and `unitId`
|
|
- Has `employeePositions[]` for actual assignments
|
|
- Uses `isCurrent` and `status` to indicate active records
|
|
|
|
### EmployeePosition
|
|
- Assignment join between `Employee` and `Position`.
|
|
- Entity: `EmployeePosition`
|
|
- Holds the active working context:
|
|
- `isCurrent`
|
|
- `status`
|
|
- `isDelegate`
|
|
- `delegatorId`
|
|
- `startDate` and `endDate`
|
|
- This is the position context the auth layer ultimately uses
|
|
|
|
### User
|
|
- Global identity record.
|
|
- Entity: `User`
|
|
- Has login/account fields like `username`, `email`, `phoneNumber`
|
|
- Has:
|
|
- `userRoles[]`
|
|
- `employee[]`
|
|
- A single user can have multiple employee records and multiple org assignments
|
|
|
|
### Role
|
|
- RBAC grouping of permissions.
|
|
- Entity: `Role`
|
|
- Assigned to users via `UserRole`
|
|
- Has permissions via `RolePermission`
|
|
|
|
### Permission
|
|
- Atomic authorization capability.
|
|
- Entity: `Permission`
|
|
- Main fields include `key`, `name`, and optional `applicationKey`
|
|
- Can be granted through:
|
|
1. `role_permissions`
|
|
2. `position_permissions`
|
|
3. `position_type_permissions`
|
|
|
|
## Relationship Summary
|
|
|
|
1. `Organization` contains many `Unit` records.
|
|
2. `Unit` contains many `Position` records.
|
|
3. The UI calls those positions departments.
|
|
4. `User` is the identity.
|
|
5. `Employee` links that user to an organization and unit.
|
|
6. `EmployeePosition` links the employee to one or more positions.
|
|
7. `Role` is assigned directly to the user via `UserRole`.
|
|
8. `Permission` can come from the user's roles, the position itself, or the position type.
|
|
|
|
## Runtime Permission Model
|
|
|
|
At login, IAM builds a session `userInfo` payload that includes:
|
|
|
|
- `roles`: from `userRoles`
|
|
- `permissions`: flattened from role permissions
|
|
- `employee.positions[].permissions`: combined from:
|
|
- direct `positionPermission`
|
|
- inherited `positionTypePermissions`
|
|
|
|
This means authorization has two practical layers:
|
|
|
|
1. User-level permissions from roles
|
|
2. Position-context permissions from the active position and its type
|
|
|
|
## Active Context During Requests
|
|
|
|
The auth guard uses request headers to decide which employee position is the current working context.
|
|
|
|
Important headers include:
|
|
|
|
- `x-current-position-id`
|
|
- `x-delegator-position-id`
|
|
- `x-current-project-id`
|
|
- `x-organization-unit-id`
|
|
|
|
That selected context becomes the active `request.user.employee.position` and is also used for auditing.
|
|
|
|
## Practical Mental Model
|
|
|
|
Use this simplified model when reasoning about IAM:
|
|
|
|
1. A `User` is the account.
|
|
2. An `Employee` is that user inside an organization.
|
|
3. A `Position` is the department-like slot in the org tree.
|
|
4. An `EmployeePosition` says which employee occupies which position.
|
|
5. A `Role` gives broad user-level permissions.
|
|
6. A `Position` and `PositionType` give contextual working permissions.
|
|
|
|
## UI Mapping
|
|
|
|
In `@tria-plc/iamui-common` user management:
|
|
|
|
- Organizations -> `Organization`
|
|
- Units -> `Unit`
|
|
- Departments -> `Position`
|
|
- Sub-departments -> child `Position`
|
|
- Team members/employees -> `Employee` plus `EmployeePosition`
|
|
- Roles -> `Role`
|
|
- Permissions -> `Permission`
|