@flusys/ng-iam 1.1.1-beta → 1.2.0-rc.1

package/README.md

@@ -1,1078 +1,95 @@
-# @flusys/ng-iam Package Guide
+# @flusys/ng-iam
 
-## Overview
+Identity and Access Management UI for FLUSYS Angular apps — role management, permission assignment, and reactive permission checking via signals.
 
-`@flusys/ng-iam` provides Identity and Access Management (IAM) for FLUSYS applications. It includes permission state management, role-based access control (RBAC), action management with AND/OR prerequisite logic, and dynamic menu filtering based on user permissions.
-
-**Key Principle:** ng-iam is **100% independent** from ng-auth through the **Provider Interface Pattern**. No compile-time or runtime dependencies on ng-auth.
-
-## Package Information
-
-| Item | Value |
-|------|-------|
-| Package | `@flusys/ng-iam` |
-| Version | 1.0.0 |
-| Dependencies | ng-core, ng-shared, ng-layout (IMenuItem only) |
-| NO dependency on | ng-auth (fully independent via Provider Pattern) |
-| Build | `npm run build:ng-iam` |
-| Entry point | `public-api.ts` |
-
----
-
-## Table of Contents
-
-1. [Architecture](#architecture)
-2. [Provider Interfaces](#provider-interfaces)
-3. [Integration Options](#integration-options)
-4. [Permission Modes](#permission-modes)
-5. [Routes](#routes)
-6. [Services](#services)
-7. [Components](#components)
-8. [Page Components](#page-components)
-9. [Interfaces](#interfaces)
-10. [Utils & Constants](#utils--constants)
-11. [Backend Integration](#backend-integration)
-12. [Best Practices](#best-practices)
-13. [Common Issues](#common-issues)
+[![npm version](https://img.shields.io/npm/v/@flusys/ng-iam.svg)](https://www.npmjs.com/package/@flusys/ng-iam)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 ---
 
-## Architecture
-
-```
-ng-shared (defines interfaces + tokens)
-    |
-Your Auth System (implements interfaces with adapters)
-    |
-ng-iam (consumes interfaces via DI)
-```
-
-ng-iam resolves all auth-related data at runtime via DI tokens defined in ng-shared. If a required token is not provided, Angular throws a clear error at injection time.
-
----
+## Installation
 
-## Provider Interfaces
-
-ng-iam requires these provider interfaces:
-
-| Token | Source | Purpose | Required? |
-|-------|--------|---------|-----------|
-| `USER_PROVIDER` | `@flusys/ng-shared` | User list for role/action assignment | Yes |
-| `LAYOUT_AUTH_STATE` | `@flusys/ng-layout` | Current company/branch context | Yes (if company feature enabled) |
-| `COMPANY_API_PROVIDER` | `@flusys/ng-shared` | Company list for whitelisting | Optional (for CompanyActionSelector) |
-| `USER_PERMISSION_PROVIDER` | `@flusys/ng-shared` | User branch permissions | Optional (for branch-scoped permissions) |
-
-### How Components Use Providers
-
-```typescript
-// UserActionSelectorComponent / UserRoleSelectorComponent
-private readonly userProvider = inject(USER_PROVIDER);
-private readonly companyContext = inject(LAYOUT_AUTH_STATE);
-
-async loadUsers() {
-  const response = await firstValueFrom(
-    this.userProvider.getUsers({
-      page: 0,
-      pageSize: MAX_DROPDOWN_ITEMS,
-      companyId: this.companyContext.currentCompanyInfo()?.id || undefined,
-    })
-  );
-  this.users.set(response?.data ?? []);
-}
+```bash
+npm install @flusys/ng-iam @flusys/ng-core @flusys/ng-shared
 ```
 
----
-
-## Integration Options
-
-### Option 1: With FLUSYS ng-auth (Recommended)
-
-ng-auth provides pre-built adapters for all required interfaces.
+## 1. Register Providers
 
 ```typescript
 // app.config.ts
-import { provideAuthProviders } from '@flusys/ng-auth';
+import { provideIamProviders } from '@flusys/ng-iam';
 
 export const appConfig: ApplicationConfig = {
   providers: [
-    provideAuthProviders(), // Registers all adapters
+    ...provideIamProviders(), // registers PROFILE_PERMISSION_PROVIDER for ng-shared's permission directives/guards
   ],
 };
 ```
 
-**Reference adapters in ng-auth:**
-
-| Adapter | Interface | Path |
-|---------|-----------|------|
-| `AuthUserProviderAdapter` | `IUserProvider` | `projects/ng-auth/adapters/` |
-| `AuthLayoutStateAdapter` | `ILayoutAuthState` | `projects/ng-auth/adapters/` |
-| `AuthCompanyApiProviderAdapter` | `ICompanyApiProvider` | `projects/ng-auth/adapters/` |
-| `AuthUserPermissionProviderAdapter` | `IUserPermissionProvider` | `projects/ng-auth/adapters/` |
-
-### Option 2: With Custom Auth System
-
-Implement the required interfaces with your own auth system. No ng-auth dependency needed.
-
-```typescript
-// Minimum configuration (basic IAM)
-providers: [
-  { provide: USER_PROVIDER, useClass: YourUserProvider },
-  { provide: LAYOUT_AUTH_STATE, useClass: YourCompanyContextProvider },
-]
-
-// Full configuration (company + branch permissions)
-providers: [
-  { provide: USER_PROVIDER, useClass: YourUserProvider },
-  { provide: LAYOUT_AUTH_STATE, useClass: YourCompanyContextProvider },
-  { provide: COMPANY_API_PROVIDER, useClass: YourCompanyApiProvider },
-  { provide: USER_PERMISSION_PROVIDER, useClass: YourUserPermissionProvider },
-]
-```
-
-**Feature matrix:**
-
-| Feature | Providers Needed |
-|---------|-----------------|
-| Basic role assignments | USER_PROVIDER only |
-| Company-scoped permissions | + LAYOUT_AUTH_STATE, COMPANY_API_PROVIDER |
-| Branch-scoped permissions | + LAYOUT_AUTH_STATE, USER_PERMISSION_PROVIDER |
-| Direct user permissions | + USER_PERMISSION_PROVIDER |
-
-All adapters must return `IListResponse<T>` or `ISingleResponse<T>` format from `@flusys/ng-shared`.
-
----
-
-## Permission Modes
-
-FLUSYS IAM supports three permission modes configured via `APP_CONFIG.iam.permissionMode`:
-
-| Mode | Structure | Tabs Available | Use Case |
-|------|-----------|---------------|----------|
-| **DIRECT** | User -> Actions | User-Actions | Small apps, per-user permissions |
-| **RBAC** | User -> Role -> Actions | Role-Actions, User-Roles | Standard apps, role templates |
-| **FULL** | Both combined | Role-Actions, User-Roles, User-Actions | Maximum flexibility |
-
-When company feature is enabled, a **Company-Actions** tab is added for whitelisting actions per company.
-
----
-
-## Routes
-
-**Export:** `IAM_ROUTES` from `@flusys/ng-iam`
-
-```
-/iam                          (IamContainerComponent - tabbed navigation)
-  /actions                    (ActionListPageComponent - hierarchical tree)
-  /actions/new                (ActionFormPageComponent - create)
-  /actions/:id                (ActionFormPageComponent - edit)
-  /roles                      (RoleListPageComponent - paginated table)
-  /roles/new                  (RoleFormPageComponent - create)
-  /roles/:id                  (RoleFormPageComponent - edit)
-  /permissions                (PermissionPageComponent - tabbed assignment UI)
-  (default redirect -> /actions)
-```
-
-**Usage in app routes:**
+## 2. Add IAM Routes
 
 ```typescript
+// app.routes.ts
 import { IAM_ROUTES } from '@flusys/ng-iam';
 
 export const routes: Routes = [
-  { path: 'iam', children: IAM_ROUTES },
+  {
+    path: 'iam',
+    loadChildren: () => IAM_ROUTES,
+  },
 ];
 ```
 
----
-
-## Services
-
-### PermissionStateService
-
-Manages current user's permissions with signal-based state. Provided at root level.
-
-**Dependencies:** `MyPermissionsApiService`, `PermissionValidatorService` (from ng-shared)
-
-**Signals:**
-
-| Signal | Type | Description |
-|--------|------|-------------|
-| `permissions` | `Signal<IMyPermissionsResponseDto \| null>` | Current user permissions (readonly) |
-| `isLoading` | `Signal<boolean>` | Loading state (readonly) |
-
-**Methods:**
-
-| Method | Returns | Description |
-|--------|---------|-------------|
-| `loadPermissions(dto?)` | `Observable<void>` | Load permissions from `/iam/permissions/my-permissions` |
-| `isLoaded()` | `boolean` | Check if permissions have been loaded |
-
-Permission checking is delegated to `PermissionValidatorService` from ng-shared (hasAction, hasAllActions, hasAnyAction, getActionCodes).
-
-```typescript
-const permissionState = inject(PermissionStateService);
-
-// Load permissions (typically in guard)
-await firstValueFrom(permissionState.loadPermissions());
-
-// Check permissions (via PermissionValidatorService)
-const validator = inject(PermissionValidatorService);
-validator.hasAction('user.create');
-validator.hasAllActions(['user.create', 'user.update']);
-validator.hasAnyAction(['user.view', 'user.list']);
-```
-
----
-
-### ActionApiService
-
-Extends `ApiResourceService<IUpdateActionDto, IAction>` for action CRUD.
-
-**Resource:** `iam/actions`
-
-**Additional Methods:**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `getTree(search?, isActive?, withDeleted?)` | `POST /iam/actions/tree` | Get hierarchical action tree |
-| `getActionsForPermission()` | `POST /iam/actions/tree-for-permission` | Get actions filtered by company whitelist |
-
-Inherits standard CRUD from `ApiResourceService`: `getAll`, `getById`, `insert`, `update`, `delete`.
-
----
-
-### RoleApiService
-
-Extends `ApiResourceService<IUpdateRoleDto, IRole>` for role CRUD.
-
-**Resource:** `iam/roles`
-
-Inherits standard CRUD from `ApiResourceService`. Only available in RBAC/FULL mode.
-
----
-
-### PermissionApiService
-
-Extends `BaseApiService` for all permission assignment operations.
-
-**Base:** `super('iam')` - all paths resolved via `this.getUrl(...)` relative to `/iam/`
-
-**User -> Action (Direct Permissions):**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `assignUserActions(data)` | `POST /iam/permissions/user-actions/assign` | Assign/remove actions for user |
-| `getUserActions(userId, query?)` | `GET /iam/permissions/user-actions/{userId}` | Get user's direct actions |
-
-**User -> Role:**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `assignUserRoles(data)` | `POST /iam/permissions/user-roles/assign` | Assign/remove roles for user |
-| `getUserRoles(userId, query?)` | `GET /iam/permissions/user-roles/{userId}` | Get user's roles |
-
-**Role -> Action:**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `assignRoleActions(data)` | `POST /iam/permissions/role-actions/assign` | Assign/remove actions for role |
-| `getRoleActions(roleId, query?)` | `GET /iam/permissions/role-actions/{roleId}` | Get role's actions |
-
-**Company -> Action (Whitelisting):**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `assignCompanyActions(data)` | `POST /iam/permissions/company-actions/assign` | Assign/remove company whitelist |
-| `getCompanyActions(companyId)` | `GET /iam/permissions/company-actions/{companyId}` | Get company's whitelisted actions |
-
-> **Note:** Read operations use GET (exception to the POST-only RPC convention). Write operations use POST.
-
----
-
-### MyPermissionsApiService
-
-Fetches current user's permissions.
-
-**Method:**
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `getMyPermissions(dto?)` | `POST /iam/permissions/my-permissions` | Get current user's frontend actions and cached endpoint count |
-
----
-
-### ActionPermissionLogicService
-
-Manages smart prerequisite validation using AND/OR logic trees. Uses PrimeNG `ConfirmationService` and `MessageService` for dialogs.
-
-**Core Methods:**
-
-| Method | Description |
-|--------|-------------|
-| `handleCheck(action, selection, allActions, onUpdate, onCancel)` | Handle action selection with recursive prerequisite validation |
-| `handleUncheck(action, selection, allActions, onUpdate)` | Handle deselection with dependency detection |
-| `hasUnmetPrerequisites(action, selection, allActions)` | Check if action has unmet prerequisites |
-| `getActionsWithUnmetPrerequisites(selection, allActions)` | Get all selected actions with unmet prerequisites |
-| `showValidationErrorDialog(invalid, selection, allActions, onUpdate)` | Pre-save validation error dialog with auto-fix |
-| `getPrerequisiteTooltip(action, selection, allActions)` | Get tooltip text with prerequisite info |
-
-**Features:**
-- Recursive deep-scan for cascading prerequisites
-- Smart AND/OR optimization (selects minimum required actions)
-- Visual formatting with status indicators
-- Alternative suggestions for OR logic branches
-- Pre-save validation with auto-fix capability
-
----
-
-## Components
-
-### LogicBuilderComponent
-
-Visual AND/OR permission logic tree editor.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-logic-builder` |
-| Standalone | Yes |
-| Change Detection | OnPush |
-
-**Inputs:**
-
-| Input | Type | Description |
-|-------|------|-------------|
-| `logic` | `ILogicNode \| null` | Current permission logic tree |
-| `actions` | `Array<{id, name}>` | Available actions for dropdowns |
-
-**Outputs:**
-
-| Output | Type | Description |
-|--------|------|-------------|
-| `logicChange` | `ILogicNode \| null` | Emitted when logic changes |
-
-**Features:** Recursive tree builder, AND/OR operator toggling, action selector dropdowns, node add/remove.
-
----
-
-### UserActionSelectorComponent
-
-Assigns actions directly to users (DIRECT/FULL mode).
-
-| Property | Value |
-|----------|-------|
-| Selector | `flusys-user-action-selector` |
-| Standalone | Yes |
-| Change Detection | OnPush |
-
-**Dependencies:** `APP_CONFIG`, `LAYOUT_AUTH_STATE`, `USER_PROVIDER`, `USER_PERMISSION_PROVIDER`, `ActionApiService`, `ActionPermissionLogicService`, `PermissionApiService`, `MessageService`
-
-**Features:**
-- User dropdown (loaded from USER_PROVIDER)
-- Branch selector (conditional, loaded from USER_PERMISSION_PROVIDER)
-- Hierarchical TreeTable with checkboxes
-- Action type tags (backend/frontend/both)
-- Prerequisite validation with tooltips
-- Change tracking with pending add/remove summary
-- Select/deselect all
-- Pre-save validation
-
----
-
-### UserRoleSelectorComponent
-
-Assigns roles to users (RBAC/FULL mode).
-
-| Property | Value |
-|----------|-------|
-| Selector | `flusys-user-role-selector` |
-| Standalone | Yes |
-| Change Detection | OnPush |
-
-**Dependencies:** `APP_CONFIG`, `LAYOUT_AUTH_STATE`, `USER_PROVIDER`, `USER_PERMISSION_PROVIDER`, `RoleApiService`, `PermissionApiService`, `MessageService`
-
-**Features:**
-- User dropdown with branch selector
-- DataTable with pagination
-- Change tracking with pending add/remove summary
-- Select/deselect all
-- No prerequisite validation (roles are simple assignments)
-
----
-
-### RoleActionSelectorComponent
-
-Assigns actions to roles (RBAC/FULL mode).
-
-| Property | Value |
-|----------|-------|
-| Selector | `flusys-role-action-selector` |
-| Standalone | Yes |
-| Change Detection | OnPush |
-
-**Dependencies:** `RoleApiService`, `ActionApiService`, `PermissionApiService`, `MessageService`, `ActionPermissionLogicService`
-
-**Features:**
-- Role dropdown
-- Hierarchical TreeTable with checkboxes
-- Prerequisite validation with smart dependency handling
-- Request cancellation with AbortController
-- Pre-save validation with auto-fix dialog
-- Change tracking
-
----
-
-### CompanyActionSelectorComponent
-
-Manages company action whitelisting (when company feature enabled).
-
-| Property | Value |
-|----------|-------|
-| Selector | `flusys-company-action-selector` |
-| Standalone | Yes |
-| Change Detection | OnPush |
-
-**Dependencies:** `COMPANY_API_PROVIDER`, `ActionApiService`, `PermissionApiService`, `MessageService`, `ConfirmationService`, `ActionPermissionLogicService`
-
-**Features:**
-- Company dropdown (loaded from COMPANY_API_PROVIDER)
-- Full action tree (not filtered by company whitelist)
-- Prerequisite validation
-- Backend prerequisite error handling with auto-fix
-- Request cancellation with AbortController
-
----
-
-## Page Components
-
-> Page components are **not exported** from the public API. They are internal and accessed via `IAM_ROUTES` (lazy-loaded by the router).
-
-### IamContainerComponent
-
-Tabbed navigation container for IAM pages.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-iam-container` |
-| Tabs | Actions (always), Roles (RBAC/FULL), Permissions (always) |
-
-Uses `RouterLink` and `RouterLinkActive` for navigation. Tab visibility based on permission mode.
-
----
-
-### ActionListPageComponent
-
-Hierarchical action list with CRUD operations.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-action-list-page` |
-| Features | TreeTable display, create/edit/delete, read-only indicators, company context awareness |
-
-Reloads actions when company context changes via effect.
-
----
-
-### ActionFormPageComponent
-
-Action create/edit form with LogicBuilder integration.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-action-form-page` |
-| Features | Create/edit mode, parent action selector, ActionType enum, permissionLogic editor, display order, active flag |
-
-**Form fields:** name (required), description, code, actionType, permissionLogic, parentId, serial, isActive, metadata.
-
----
-
-### RoleListPageComponent
-
-Paginated role list with CRUD operations.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-role-list-page` |
-| Features | Paginated table (10/25/50), create/edit/delete, company context filtering, read-only indicators |
-
----
-
-### RoleFormPageComponent
-
-Role create/edit form.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-role-form-page` |
-| Features | Create/edit mode, company auto-assignment on create, active flag, display order |
-
-**Form fields:** name (required), description, serial, isActive. Company assigned automatically from context.
-
----
-
-### PermissionPageComponent
-
-Main permission management interface with tabbed layout.
-
-| Property | Value |
-|----------|-------|
-| Selector | `lib-permission-page` |
-| Features | Dynamic tabs based on permission mode and company feature |
-
-**Tabs:**
-- Role-Actions (RBAC/FULL) - `RoleActionSelectorComponent`
-- User-Roles (RBAC/FULL) - `UserRoleSelectorComponent`
-- User-Actions (DIRECT/FULL) - `UserActionSelectorComponent`
-- Company-Actions (if company feature enabled) - `CompanyActionSelectorComponent`
-
----
-
-## Interfaces
-
-### ActionType (Enum)
-
-```typescript
-enum ActionType {
-  BACKEND = 'backend',     // API endpoint permissions (cached by PermissionGuard)
-  FRONTEND = 'frontend',   // UI feature permissions (returned in my-permissions)
-  BOTH = 'both',           // Both backend and frontend
-}
-```
-
-### IAction (extends IBaseEntity)
-
-```typescript
-interface IAction extends IBaseEntity {
-  readOnly: boolean;
-  name: string;
-  description: string | null;
-  code: string | null;
-  actionType: ActionType;
-  permissionLogic: ILogicNode | null;  // AND/OR prerequisite rules
-  parentId: string | null;             // For hierarchy
-  serial: number | null;               // Display order
-  isActive: boolean;
-  metadata: Record<string, any> | null;
-}
-```
-
-### IActionTreeDto (extends IAction)
+All routes are protected by `permissionGuard` using constants from `ng-shared`.
 
-```typescript
-interface IActionTreeDto extends IAction {
-  children: IActionTreeDto[];
-}
-```
+## 3. Load Permissions
 
-### ICreateActionDto / IUpdateActionDto
+Call `PermissionStateService.loadPermissions()` after login (e.g., in `appInitGuard` or after session restore). It fetches the current user's effective permissions from `POST /iam/permissions/my-permissions` and populates `PermissionValidatorService` from `ng-shared`.
 
 ```typescript
-interface ICreateActionDto {
-  name: string;
-  description?: string;
-  code?: string;
-  actionType?: ActionType;
-  permissionLogic?: ILogicNode;
-  parentId?: string;
-  serial?: number;
-  isActive?: boolean;
-  metadata?: Record<string, any>;
-}
+import { PermissionStateService } from '@flusys/ng-iam';
 
-interface IUpdateActionDto extends Partial<ICreateActionDto> {
-  id: string;
-}
-```
-
-### IRole (extends IBaseEntity)
+@Component({ ... })
+export class AppShellComponent {
+  private readonly permState = inject(PermissionStateService);
 
-```typescript
-interface IRole extends IBaseEntity {
-  readOnly: boolean;
-  name: string;
-  description: string | null;
-  companyId: string | null;
-  isActive: boolean;
-  serial: number | null;
-  metadata: Record<string, any> | null;
-}
-```
-
-### ICreateRoleDto / IUpdateRoleDto / IRoleQueryDto
-
-```typescript
-interface ICreateRoleDto {
-  name: string;
-  description?: string;
-  companyId?: string;
-  isActive?: boolean;
-  serial?: number;
-  metadata?: Record<string, any>;
-}
-
-interface IUpdateRoleDto extends Partial<ICreateRoleDto> {
-  id: string;
-}
-
-interface IRoleQueryDto {
-  companyId?: string;
-  isActive?: boolean;
-}
-```
-
-### Permission Interfaces
-
-```typescript
-type PermissionAction = 'add' | 'remove';
-type PermissionMode = 'rbac' | 'direct' | 'full';
+  readonly permissions = this.permState.permissions; // Signal<IMyPermissionsResponseDto | null>
+  readonly isLoading   = this.permState.isLoading;  // Signal<boolean>
 
-interface IPermissionItemDto {
-  id: string;
-  action: PermissionAction;
-}
-
-// Assignment DTOs
-interface IAssignUserActionsDto {
-  userId: string;
-  companyId?: string;
-  branchId?: string;      // null = company-wide
-  items: IPermissionItemDto[];
-}
-
-interface IAssignCompanyActionsDto {
-  companyId: string;
-  items: IPermissionItemDto[];
-}
-
-interface IAssignRoleActionsDto {
-  roleId: string;
-  items: IPermissionItemDto[];
-}
-
-interface IAssignUserRolesDto {
-  userId: string;
-  companyId?: string;
-  branchId?: string;
-  items: IPermissionItemDto[];
-}
-```
-
-### Response DTOs
-
-```typescript
-interface IUserActionResponseDto {
-  id: string;
-  userId: string;
-  actionId: string;
-  actionCode: string;
-  actionName: string;
-  branchId: string | null;
-  createdAt: Date;
-}
-
-interface IRoleActionResponseDto {
-  id: string;
-  roleId: string;
-  actionId: string;
-  actionCode: string;
-  actionName: string;
-  createdAt: Date;
-}
-
-interface ICompanyActionResponseDto {
-  id: string;
-  companyId: string;
-  actionId: string;
-  actionCode: string;
-  actionName: string;
-  createdAt: Date;
-}
-
-interface IUserRoleResponseDto {
-  id: string;
-  userId: string;
-  roleId: string;
-  roleCode: string;
-  roleName: string;
-  branchId: string | null;  // Always null - roles are NOT branch-scoped
-  createdAt: Date;
-}
-```
-
-### My Permissions Response
-
-```typescript
-interface IMyPermissionsResponseDto {
-  frontendActions: Array<{ id: string; code: string; name: string; description: string }>;
-  cachedEndpoints: number;  // Endpoint count for backend PermissionGuard
-}
-```
-
-### Menu & Logic Interfaces
-
-```typescript
-interface IMenuAction {
-  id: string;
-  code: string;
-  name: string;
-  route: string | null;
-  icon: string | null;
-  iconType: number | null;
-  serial: number | null;
-  parentId: string | null;
-  children?: IMenuAction[];
-}
-
-// ILogicNode is imported from @flusys/ng-shared
-```
-
-### Prerequisite Interfaces
-
-```typescript
-interface IPrerequisiteActionDto {
-  actionId: string;
-  actionCode: string;
-  actionName: string;
-}
-
-interface IPrerequisiteValidationError {
-  actionId: string;
-  actionCode: string;
-  actionName: string;
-  requiredActions: IPrerequisiteActionDto[];
-}
-
-interface IPermissionOperationResultDto {
-  success: boolean;
-  added: number;
-  removed: number;
-  message: string;
-  prerequisiteErrors?: IPrerequisiteValidationError[];
-}
-```
-
-### Simple Models
-
-```typescript
-interface IUser {
-  id: string;
-  name: string;
-  email: string;
-}
-
-interface IBranch {
-  id: string;
-  name: string;
-  companyId: string;
-}
-
-interface ICompany {
-  id: string;
-  name: string;
-  slug?: string;
-}
-```
-
-### Query DTOs
-
-```typescript
-interface IGetUserActionsDto {
-  branchId?: string;
-}
-
-interface IGetRoleActionsDto {}
-
-interface IGetUserRolesDto {
-  branchId?: string;  // Ignored by backend
-}
-
-interface IGetMyPermissionsDto {
-  parentCodes?: string[];
-}
-```
-
----
-
-## Utils & Constants
-
-> Utils are **internal** (not exported from the public API). They are used by components and services within the package.
-
-### permission-logic.util.ts
-
-| Function | Description |
-|----------|-------------|
-| `validateActionPrerequisites(action, selectedIds, allActions)` | Validate prerequisites respecting AND/OR. Returns `{valid, missingActions}` |
-| `extractRequiredActionIds(logic, allActions)` | Extract all action IDs from a logic tree |
-| `describePrerequisites(logic, allActions)` | Human-readable prerequisite description |
-
-### tree-utils.ts
-
-| Function | Description |
-|----------|-------------|
-| `flattenTree<T>(tree)` | Flatten hierarchical tree into flat array |
-| `buildItemMap<T>(items)` | Build ID-to-item `Map` for O(1) lookup |
-| `buildTreeFromFlat<T>(flatList)` | Build tree from flat list using `parentId` |
-| `convertActionToTreeNode(actions)` | Convert `IActionTreeDto[]` to PrimeNG `TreeNode<IAction>[]` |
-
-### Constants
-
-```typescript
-export const MAX_DROPDOWN_ITEMS = 100;  // Max items for dropdown lists (users, companies, roles, branches)
-```
-
-Exported directly as `MAX_DROPDOWN_ITEMS` from the package.
-
----
-
-## Backend Integration
-
-### Required Endpoints
-
-**Action CRUD:**
-
-```
-POST /iam/actions/tree                    # Get hierarchical action tree
-POST /iam/actions/tree-for-permission     # Get actions filtered by company whitelist
-POST /iam/actions/get-all                 # List all actions (flat)
-POST /iam/actions/get/:id                 # Get action by ID
-POST /iam/actions/insert                  # Create action
-POST /iam/actions/update                  # Update action
-POST /iam/actions/delete                  # Delete action
-```
-
-**Role CRUD:**
-
-```
-POST /iam/roles/get-all                   # List roles (with pagination + company filter)
-POST /iam/roles/get/:id                   # Get role by ID
-POST /iam/roles/insert                    # Create role
-POST /iam/roles/update                    # Update role
-POST /iam/roles/delete                    # Delete role
-```
-
-**Permission Assignments:**
-
-```
-POST /iam/permissions/my-permissions      # Current user's permissions
-POST /iam/permissions/user-actions/assign # Assign/remove user actions
-GET  /iam/permissions/user-actions/:id    # Get user's direct actions
-POST /iam/permissions/user-roles/assign   # Assign/remove user roles
-GET  /iam/permissions/user-roles/:id      # Get user's roles
-POST /iam/permissions/role-actions/assign # Assign/remove role actions
-GET  /iam/permissions/role-actions/:id    # Get role's actions
-POST /iam/permissions/company-actions/assign  # Assign/remove company whitelist
-GET  /iam/permissions/company-actions/:id     # Get company's whitelisted actions
-```
-
-### My Permissions Response Format
-
-```json
-{
-  "success": true,
-  "data": {
-    "frontendActions": [
-      {
-        "id": "uuid",
-        "code": "user.create",
-        "name": "Create User",
-        "description": "Allows creating new users"
-      }
-    ],
-    "cachedEndpoints": 42
+  loadOnInit() {
+    this.permState.loadPermissions().subscribe();
   }
-}
-```
-
----
 
-## Best Practices
-
-### Permission Loading
-
-Load permissions in a guard to block navigation until ready:
-
-```typescript
-// appInitGuard
-if (!permissionState.isLoaded()) {
-  try {
-    await firstValueFrom(permissionState.loadPermissions());
-  } catch (error) {
-    console.error('Failed to load permissions:', error);
-    // Continue with graceful degradation - don't block the app
+  isLoaded() {
+    return this.permState.isLoaded(); // true when permissions are set in PermissionValidatorService
   }
 }
-return true;
-```
-
-- Cache permissions in memory (PermissionStateService handles this)
-- Clear permissions on logout
-- Never store permissions in localStorage (security risk)
-- Never load permissions in component `ngOnInit` (causes race conditions)
-
-### Permission Checks
-
-```typescript
-// Single action
-validator.hasAction('user.create');
-
-// ALL required
-validator.hasAllActions(['user.create', 'user.update']);
-
-// ANY required
-validator.hasAnyAction(['user.view', 'user.list']);
-```
-
-Cache check results in computed signals rather than calling in templates or tight loops.
-
-### Menu Filtering
-
-```typescript
-// Set menu with requiredAction or logicNode
-this.layoutService.setMenu(menuItems);
-
-// Set permission checker (layout handles filtering automatically)
-this.layoutService.setPermissionChecker((actionCode) =>
-  validator.hasAction(actionCode)
-);
-```
-
-Do not filter menus manually - let layout handle it.
-
-### Action Naming
-
-Format: `module.operation` or `module.entity.operation`
-
-```typescript
-// Good
-'user.create'
-'user.update'
-'report.export'
-'admin.system.config'
-
-// Bad
-'create'           // Too generic
-'userCreate'       // Not dot notation
-'users'            // Entity name, not action
-```
-
-### LogicNode Pattern
-
-Complex permission rules using AND/OR operators:
-
-```typescript
-// User needs 'user.create' AND ('user.update' OR 'user.delete')
-const logic: ILogicNode = {
-  type: 'AND',
-  children: [
-    { type: 'ACTION', value: 'user.create' },
-    {
-      type: 'OR',
-      children: [
-        { type: 'ACTION', value: 'user.update' },
-        { type: 'ACTION', value: 'user.delete' },
-      ],
-    },
-  ],
-};
-```
-
----
-
-## Common Issues
-
-| Problem | Cause | Solution |
-|---------|-------|----------|
-| `permissionState.isLoaded()` returns false | IAM not enabled or endpoint failing | Check `services.iam.enabled: true` in environment, verify `POST /iam/permissions/my-permissions` works |
-| Empty menu after login | Permissions not loaded or no matching actions | Check `permissionState.isLoaded()`, verify user has frontend actions, check `requiredAction` matches action codes |
-| Menu items not filtered | Permission checker not set | Call `layoutService.setPermissionChecker()` after loading permissions |
-| 401 on IAM endpoints with external auth | Auth token not forwarded | Ensure your auth interceptor adds `Authorization` header to IAM requests |
-| Provider not configured error | Missing DI registration | Add required providers to `app.config.ts` (USER_PROVIDER, LAYOUT_AUTH_STATE) |
-| Empty user/company dropdowns | API response format mismatch | Ensure adapters return `IListResponse<T>` format with `data` array |
-
----
-
-## Configuration
-
-### Frontend Environment
-
-```typescript
-// environment.ts
-services: {
-  iam: { baseUrl: 'http://localhost:2002/iam', enabled: true },
-}
-```
-
-### Backend Environment
-
-```bash
-# .env
-IAM_PERMISSION_MODE=FULL  # DIRECT, RBAC, or FULL
-```
-
-| Scenario | services.iam.enabled | Result |
-|----------|---------------------|--------|
-| Full IAM | `true` | Permission-based menu |
-| IAM Disabled | `false` | Static menu (all items visible) |
-| Service Down | `true` (API fails) | Graceful fallback to static menu |
-
----
-
-## Provider Functions
-
-### provideIamProviders()
-
-Registers provider adapters that enable other packages (ng-auth) to access IAM functionality without direct dependencies.
-
-```typescript
-import { provideIamProviders } from '@flusys/ng-iam';
-
-// app.config.ts
-export const appConfig: ApplicationConfig = {
-  providers: [
-    ...provideIamProviders(),  // Register IAM providers
-  ],
-};
 ```
 
-**Registers:**
+## 4. Check Permissions in Templates
 
-| Token | Adapter | Purpose |
-|-------|---------|---------|
-| `PROFILE_PERMISSION_PROVIDER` | `ProfilePermissionProviderAdapter` | User roles/actions for profile page |
+Once `provideIamProviders()` is registered and `loadPermissions()` has been called, permission directives from `ng-shared` work automatically:
 
-### ProfilePermissionProviderAdapter
+```html
+<!-- show element if user has the action code -->
+<button *hasPermission="'product.update'">Edit</button>
 
-Implements `IProfilePermissionProvider` from ng-shared. Enables ng-auth's profile page to display user permissions.
-
-```typescript
-interface IProfilePermissionProvider {
-  getUserRoles(userId: string, branchId?: string): Observable<ISingleResponse<IProfileRoleInfo[]>>;
-  getUserActions(userId: string, branchId?: string): Observable<ISingleResponse<IProfileActionInfo[]>>;
-}
+<!-- show element if user has any of these action codes -->
+<div *hasPermission="['admin.manage', 'product.delete']">Admin area</div>
 ```
 
-**Usage in ng-auth profile page:**
+Use `permissionGuard` from `ng-shared` to protect routes:
 
 ```typescript
-// Optional injection - graceful degradation when IAM disabled
-private readonly permissionProvider = inject(PROFILE_PERMISSION_PROVIDER, { optional: true });
+import { permissionGuard } from '@flusys/ng-shared';
 
-// Load user permissions
-if (this.permissionProvider) {
-  this.permissionProvider.getUserRoles(userId, branchId).subscribe(response => {
-    this.roles.set(response.data ?? []);
-  });
+{
+  path: 'admin',
+  canActivate: [permissionGuard('admin.manage')],
+  loadComponent: () => import('./admin.component'),
 }
 ```
 
----
-
-## See Also
-
-- **[CORE-GUIDE.md](./CORE-GUIDE.md)** - Configuration system (APP_CONFIG)
-- **[AUTH-GUIDE.md](./AUTH-GUIDE.md)** - Authentication and provider adapters
-- **[SHARED-GUIDE.md](./SHARED-GUIDE.md)** - Provider interface definitions
-- **[LAYOUT-GUIDE.md](./LAYOUT-GUIDE.md)** - Menu system and filtering
-
----
+## License
 
-**Last Updated:** 2026-02-16
-**Angular Version:** 21
+MIT © FLUSYS