Initial commit
This commit is contained in:
Igor Martyniuk
@@ -0,0 +1,53 @@
|
||||
# Access Control Module
|
||||
|
||||
The Access Control module manages admin accounts, roles, and permissions in the admin app. It is the UI boundary for deciding who can access which admin features.
|
||||
|
||||
## Source Map
|
||||
|
||||
| Area | Path |
|
||||
| ------------------------- | ------------------------------------------------------- |
|
||||
| Frontend module | `apps/admin/src/core/AccessControl/` |
|
||||
| Frontend routes | `apps/admin/src/core/AccessControl/config/routing.tsx` |
|
||||
| Frontend translations | `apps/admin/src/core/AccessControl/config/translation/` |
|
||||
| Backend admin module | `backend/app/base_modules/Admin/` |
|
||||
| Backend role module | `backend/app/base_modules/Role/` |
|
||||
| Backend permission module | `backend/app/base_modules/Permission/` |
|
||||
| Permission loader | `backend/app/services/permission_service.ts` |
|
||||
|
||||
## Documentation
|
||||
|
||||
| Page | Purpose |
|
||||
| ------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| [Frontend](./frontend.md) | Routes, UI structure, data layer, forms, translations, and cache invalidation. |
|
||||
| [Backend](./backend.md) | Admin, role, and permission API routes, policies, validators, and permission loading. |
|
||||
|
||||
## Main Capabilities
|
||||
|
||||
- List, search, sort, paginate, create, edit, and delete admin accounts.
|
||||
- Assign roles to admin accounts.
|
||||
- List, create, edit, and delete roles.
|
||||
- Assign permissions to roles.
|
||||
- Load available permission definitions from backend module permission configs.
|
||||
- Gate access to screens and actions through the Permission core module.
|
||||
|
||||
## Ownership Rules
|
||||
|
||||
- AccessControl owns management UI for admins, roles, and role permissions.
|
||||
- Backend Admin owns account persistence and profile update endpoint.
|
||||
- Backend Role owns role persistence and role-permission sync.
|
||||
- Backend Permission owns the available permission list endpoint.
|
||||
- Permission core module owns permission checking and React gates.
|
||||
- Auth core module owns the current authenticated admin and session state.
|
||||
|
||||
## Common Change Guide
|
||||
|
||||
| Change | Start Here |
|
||||
| --------------------------- | ---------------------------------------------------------------------------------------------------- |
|
||||
| Add an admin field | `entities/AdminEntity.ts`, `data/api/dto.ts`, `data/mappers/AdminMapper.ts`, `view/forms/AdminForm/` |
|
||||
| Change admin list columns | `view/widgets/AdminTable.tsx` |
|
||||
| Change role form behavior | `view/forms/RoleForm/` |
|
||||
| Add a new permission source | Backend module `config/permissions.ts` and `backend/app/services/permission_service.ts` |
|
||||
| Change cache invalidation | `data/queries/cache.ts` |
|
||||
| Change translations | `config/translation/en.json` and `config/translation/uk.json` |
|
||||
| Change backend admin API | `backend/app/base_modules/Admin/controller/admin_controller.ts` |
|
||||
| Change backend role API | `backend/app/base_modules/Role/controller/role_controller.ts` |
|
||||
@@ -0,0 +1,89 @@
|
||||
# Access Control Backend
|
||||
|
||||
Access Control frontend uses three backend base modules:
|
||||
|
||||
```txt
|
||||
backend/app/base_modules/Admin/
|
||||
backend/app/base_modules/Role/
|
||||
backend/app/base_modules/Permission/
|
||||
```
|
||||
|
||||
## Routes
|
||||
|
||||
| Method | Route | Backend | Purpose |
|
||||
| -------- | ----------------------- | ---------- | ------------------------------------------- |
|
||||
| `GET` | `/admin` | Admin | Paginated admin list. |
|
||||
| `GET` | `/admin/:id` | Admin | Admin details with roles. |
|
||||
| `POST` | `/admin` | Admin | Create admin and sync roles. |
|
||||
| `PUT` | `/admin/:id` | Admin | Update admin and sync roles. |
|
||||
| `DELETE` | `/admin/:id` | Admin | Delete admin. |
|
||||
| `PUT` | `/admin/update-profile` | Admin | Update current authenticated admin profile. |
|
||||
| `GET` | `/role` | Role | Paginated role list. |
|
||||
| `GET` | `/role/:id` | Role | Role details with permissions. |
|
||||
| `POST` | `/role` | Role | Create role and role-permission rows. |
|
||||
| `PUT` | `/role/:id` | Role | Update role and role-permission rows. |
|
||||
| `DELETE` | `/role/:id` | Role | Delete role. |
|
||||
| `GET` | `/permission` | Permission | List all available permission definitions. |
|
||||
|
||||
All routes use `middleware.auth()` except login routes owned by Auth.
|
||||
|
||||
## Authorization
|
||||
|
||||
Policies:
|
||||
|
||||
```txt
|
||||
backend/app/base_modules/Admin/policy/admin_policy.ts
|
||||
backend/app/base_modules/Role/policy/role_policy.ts
|
||||
backend/app/base_modules/Permission/policy/permission_policy.ts
|
||||
```
|
||||
|
||||
Permission slugs are defined in:
|
||||
|
||||
```txt
|
||||
backend/app/base_modules/Admin/config/permissions.ts
|
||||
backend/app/base_modules/Role/config/permissions.ts
|
||||
```
|
||||
|
||||
Current AccessControl slugs:
|
||||
|
||||
```txt
|
||||
admins.view
|
||||
admins.create
|
||||
admins.update
|
||||
admins.delete
|
||||
role.view
|
||||
role.create
|
||||
role.update
|
||||
role.delete
|
||||
```
|
||||
|
||||
## Permission Loading
|
||||
|
||||
Available permissions are collected by:
|
||||
|
||||
```txt
|
||||
backend/app/services/permission_service.ts
|
||||
```
|
||||
|
||||
`getAllPermissions()` scans `app/base_modules/*/config/permissions.ts` and `app/modules/*/config/permissions.ts`. Add permissions to the owning backend module config; do not hard-code them in the frontend.
|
||||
|
||||
## Validation
|
||||
|
||||
Validators:
|
||||
|
||||
```txt
|
||||
backend/app/base_modules/Admin/validators/admin_create_validator.ts
|
||||
backend/app/base_modules/Admin/validators/admin_update_validator.ts
|
||||
backend/app/base_modules/Admin/validators/admin_update_profile_validator.ts
|
||||
backend/app/base_modules/Role/validator/role_create_validator.ts
|
||||
backend/app/base_modules/Role/validator/role_update_validator.ts
|
||||
```
|
||||
|
||||
Keep frontend form rules compatible with backend validators. Backend validation is authoritative.
|
||||
|
||||
## Data Notes
|
||||
|
||||
- Admin create/update syncs assigned roles through the admin-role relation.
|
||||
- Role create/update rewrites `role_permissions` rows for the role.
|
||||
- Permission records returned by `/permission` are loaded from permission config files, not only database rows.
|
||||
- Deleting the final admin is blocked by the Admin controller.
|
||||
@@ -0,0 +1,145 @@
|
||||
# Access Control Frontend
|
||||
|
||||
The frontend module provides the admin-facing UI for managing admins, roles, and permissions.
|
||||
|
||||
Source root:
|
||||
|
||||
```txt
|
||||
apps/admin/src/core/AccessControl/
|
||||
```
|
||||
|
||||
## Directory Structure
|
||||
|
||||
```txt
|
||||
AccessControl/
|
||||
config/ Routes, menu, messages, translations.
|
||||
data/
|
||||
api/ Raw HTTP calls and DTOs.
|
||||
mappers/ DTO-to-entity mapping.
|
||||
queries/ React Query hooks, keys, and cache invalidation.
|
||||
entities/ Admin, role, permission entities and enums.
|
||||
pages/ Route-level pages.
|
||||
view/
|
||||
forms/ Admin and role forms.
|
||||
layouts/ Module layout.
|
||||
widgets/ Tables and modal triggers.
|
||||
```
|
||||
|
||||
## Routes
|
||||
|
||||
Frontend route config:
|
||||
|
||||
```txt
|
||||
config/routing.tsx
|
||||
```
|
||||
|
||||
Mounted module path:
|
||||
|
||||
```txt
|
||||
/access-control
|
||||
```
|
||||
|
||||
| Route | Page | Purpose |
|
||||
| ----------------------- | --------------- | ----------------------------------------- |
|
||||
| `/access-control/admin` | `AdminListPage` | Manage admin accounts and assigned roles. |
|
||||
| `/access-control/role` | `RoleListPage` | Manage roles and assigned permissions. |
|
||||
|
||||
## Data Layer
|
||||
|
||||
Raw API calls live in:
|
||||
|
||||
```txt
|
||||
data/api/AdminAPI.ts
|
||||
data/api/RoleAPI.ts
|
||||
data/api/PermissionAPI.ts
|
||||
data/api/dto.ts
|
||||
```
|
||||
|
||||
Query hooks live in:
|
||||
|
||||
```txt
|
||||
data/queries/admin.ts
|
||||
data/queries/role.ts
|
||||
data/queries/permission.ts
|
||||
```
|
||||
|
||||
Cache invalidation helpers live in:
|
||||
|
||||
```txt
|
||||
data/queries/cache.ts
|
||||
```
|
||||
|
||||
Current helpers:
|
||||
|
||||
```ts
|
||||
invalidateAdminList();
|
||||
invalidateAdminDetailed(id?);
|
||||
invalidateRoleList();
|
||||
invalidateRoleDetailed(id?);
|
||||
invalidatePermissionList();
|
||||
```
|
||||
|
||||
## DTO Mapping
|
||||
|
||||
The API layer returns DTOs. Query hooks map DTOs into entities before data reaches UI code.
|
||||
|
||||
```txt
|
||||
data/mappers/AdminMapper.ts
|
||||
data/mappers/RoleMapper.ts
|
||||
data/mappers/PermissionMapper.ts
|
||||
entities/AdminEntity.ts
|
||||
entities/RoleEntity.ts
|
||||
entities/PermissionEntity.ts
|
||||
```
|
||||
|
||||
Keep backend response shape in DTOs. Keep UI/domain shape in entities.
|
||||
|
||||
## Forms
|
||||
|
||||
Admin form:
|
||||
|
||||
```txt
|
||||
view/forms/AdminForm/
|
||||
```
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- Create and update admin data.
|
||||
- Select admin status.
|
||||
- Assign roles.
|
||||
- Optionally update password.
|
||||
|
||||
Role form:
|
||||
|
||||
```txt
|
||||
view/forms/RoleForm/
|
||||
```
|
||||
|
||||
Responsibilities:
|
||||
|
||||
- Create and update role name.
|
||||
- Group available permissions by module slug prefix.
|
||||
- Assign permission slugs to the role.
|
||||
|
||||
## Widgets
|
||||
|
||||
| Widget | Purpose |
|
||||
| -------------------- | -------------------------------------------- |
|
||||
| `AdminTable` | Admin list, filters, actions, create button. |
|
||||
| `RoleTable` | Role list, actions, create button. |
|
||||
| `ManageAdminTrigger` | Admin create/edit dialog orchestration. |
|
||||
| `ManageRoleTrigger` | Role create/edit dialog orchestration. |
|
||||
| `DeleteAdminTrigger` | Admin delete confirmation and mutation. |
|
||||
| `DeleteRoleTrigger` | Role delete confirmation and mutation. |
|
||||
|
||||
## Translations
|
||||
|
||||
Translations are module-local:
|
||||
|
||||
```txt
|
||||
config/messages.ts
|
||||
config/translation/en.json
|
||||
config/translation/uk.json
|
||||
```
|
||||
|
||||
Use only `ACCESS_CONTROL.*` keys inside this module.
|
||||
Reference in New Issue
Block a user