@flusys/ng-iam 4.0.1 → 4.1.0

package/README.md

@@ -1,608 +1,451 @@
-# @flusys/ng-iam Package Guide
+# @flusys/ng-iam
 
-## Overview
-
-`@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**.
+> Identity and Access Management UI library for the FLUSYS Angular platform — role management, permission assignment, permission evaluation, and logic builder.
 
-| Item | Value |
-|------|-------|
-| Package | `@flusys/ng-iam` |
-| Version | 4.0.1 |
-| Dependencies | ng-core, ng-shared, ng-layout (IMenuItem only) |
-| CSS Framework | Tailwind CSS (not PrimeFlex) |
-| Build | `npm run build:ng-iam` |
+[![npm version](https://img.shields.io/npm/v/@flusys/ng-iam.svg)](https://www.npmjs.com/package/@flusys/ng-iam)
+[![Angular](https://img.shields.io/badge/Angular-21-red.svg)](https://angular.io)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
 ---
 
-## 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.
+## Table of Contents
+
+- [Overview](#overview)
+- [Features](#features)
+- [Compatibility](#compatibility)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Permission Modes](#permission-modes)
+  - [RBAC Mode](#rbac-mode)
+  - [DIRECT Mode](#direct-mode)
+  - [FULL Mode](#full-mode)
+- [Module Registration](#module-registration)
+- [Permission State Service](#permission-state-service)
+- [IAM API Services](#iam-api-services)
+- [Components](#components)
+  - [PermissionPageComponent](#permissionpagecomponent)
+  - [LogicBuilderComponent](#logicbuildercomponent)
+- [Integration](#integration)
+- [API Endpoints](#api-endpoints)
+- [Troubleshooting](#troubleshooting)
+- [License](#license)
 
 ---
 
-## Provider Interfaces
+## Overview
 
-| Token | Source | Purpose | Required? |
-|-------|--------|---------|-----------|
-| `USER_PROVIDER` | ng-shared | User list for role/action assignment | Yes |
-| `LAYOUT_AUTH_STATE` | ng-layout | Current company/branch context | Yes (if company enabled) |
-| `COMPANY_API_PROVIDER` | ng-shared | Company list for whitelisting | Optional |
-| `USER_PERMISSION_PROVIDER` | ng-shared | User branch permissions | Optional |
+`@flusys/ng-iam` provides the complete Identity and Access Management UI for FLUSYS applications. It supports three independent permission modes (RBAC, DIRECT, FULL) and integrates with the backend `nestjs-iam` module.
 
-```typescript
-// Provider usage
-const companyId = inject(LAYOUT_AUTH_STATE).currentCompanyInfo()?.id;
-const response = await inject(USER_PERMISSION_PROVIDER).getUserBranchPermissions(userId).toPromise();
-```
+The package uses the Provider Interface Pattern — it never imports from `ng-auth` directly. Instead it injects `USER_PROVIDER` and `COMPANY_PROVIDER` from `ng-shared` to get current user and company context.
 
 ---
 
-## Integration Options
-
-### With FLUSYS ng-auth (Recommended)
-
-```typescript
-import { provideAuthProviders } from '@flusys/ng-auth';
-export const appConfig: ApplicationConfig = {
-  providers: [provideAuthProviders()],  // Registers all adapters
-};
-```
-
-### With Custom Auth System
-
-```typescript
-providers: [
-  { provide: USER_PROVIDER, useClass: YourUserProvider },
-  { provide: LAYOUT_AUTH_STATE, useClass: YourCompanyContextProvider },
-  { provide: COMPANY_API_PROVIDER, useClass: YourCompanyApiProvider },       // Optional
-  { provide: USER_PERMISSION_PROVIDER, useClass: YourUserPermissionProvider }, // Optional
-]
-```
+## Features
 
-| 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 |
+- ✅ Three permission modes: RBAC, DIRECT, FULL
+- ✅ `PermissionStateService` — signal-based permission state with 1-hour cache
+- ✅ Role management UI (create, assign users, set permissions)
+- ✅ Direct permission assignment UI (assign permissions directly to users)
+- ✅ `LogicBuilderComponent` — visual AND/OR/nested logic builder for complex permissions
+- ✅ Permission cache auto-invalidation on role/permission change
+- ✅ `provideIamProviders()` — registers permission evaluator with `ng-shared`
+- ✅ Lazy-loaded IAM pages
 
 ---
 
-## Permission Modes
-
-Configured via `APP_CONFIG.iam.permissionMode`:
+## Compatibility
 
-| Mode | Structure | Tabs Available | Use Case |
-|------|-----------|---------------|----------|
-| **DIRECT** | User -> Actions | User-Actions | Small apps |
-| **RBAC** | User -> Role -> Actions | Role-Actions, User-Roles | Standard apps |
-| **FULL** | Both combined | All tabs | Maximum flexibility |
-
-When company feature is enabled, a **Company-Actions** tab is added for whitelisting.
+| Package | Version |
+|---------|---------|
+| Angular | 21+ |
+| @flusys/ng-core | 4.x |
+| @flusys/ng-shared | 4.x |
 
 ---
 
-## Routes
-
-**Export:** `IAM_ROUTES` from `@flusys/ng-iam`
+## Installation
 
+```bash
+npm install @flusys/ng-iam @flusys/ng-core @flusys/ng-shared
 ```
-/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)
-```
-
-| Route | Guard | Permission |
-|-------|-------|------------|
-| `/actions` | permissionGuard | `ACTION_PERMISSIONS.READ` |
-| `/roles` | permissionGuard | `ROLE_PERMISSIONS.READ` |
-| `/permissions` | anyPermissionGuard | Multiple READ permissions |
 
 ---
 
-## Services
-
-### PermissionStateService
-
-**File:** `services/permission-state.service.ts` | Provided at root level
-
-Manages current user's permissions with signal-based state.
+## Quick Start
 
-| API | Type | Description |
-|-----|------|-------------|
-| `permissions` | `Signal<IMyPermissionsResponseDto \| null>` | Current user permissions (readonly) |
-| `isLoading` | `Signal<boolean>` | Loading state (readonly) |
-| `loadPermissions(dto?)` | `Observable<void>` | Load from `/iam/permissions/my-permissions` |
-| `isLoaded()` | `boolean` | Check if permissions loaded |
-
-Permission checking delegated to `PermissionValidatorService` from ng-shared.
+### 1. Enable IAM in Config
 
 ```typescript
-await firstValueFrom(permissionState.loadPermissions());  // Load in guard
-validator.hasAction('user.create');                       // Check permission
-validator.hasAllActions(['user.create', 'user.update']); // Check multiple
+// environments/environment.ts
+export const environment = {
+  permissionMode: 'FULL',  // 'RBAC' | 'DIRECT' | 'FULL'
+  services: {
+    auth: { enabled: true },
+    iam: { enabled: true },
+  },
+};
 ```
 
----
-
-### ActionApiService
-
-**File:** `services/action-api.service.ts` | Extends `ApiResourceService<IUpdateActionDto, IAction>`
-
-**Resource:** `iam/actions`
-
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `getTree(search?, isActive?, withDeleted?)` | `POST /iam/actions/tree` | Hierarchical action tree |
-| `getActionsForPermission()` | `POST /iam/actions/tree-for-permission` | Actions filtered by company whitelist |
+### 2. Register IAM Providers
 
-Inherits standard CRUD: `getAll`, `getById`, `insert`, `update`, `delete`.
-
----
+```typescript
+// app.config.ts
+import { provideIamProviders } from '@flusys/ng-iam';
 
-### RoleApiService
+export const appConfig: ApplicationConfig = {
+  providers: [
+    ...provideIamProviders(),
+    // Provides: PERMISSION_VALIDATOR (used by HasPermissionDirective, PermissionGuard)
+  ],
+};
+```
 
-**File:** `services/role-api.service.ts` | Extends `ApiResourceService<IUpdateRoleDto, IRole>`
+### 3. Add IAM Routes
 
-**Resource:** `iam/roles` | Only available in RBAC/FULL mode.
+```typescript
+// app.routes.ts
+import { IAM_ROUTES } from '@flusys/ng-iam';
+
+export const routes: Routes = [
+  {
+    path: 'iam',
+    loadChildren: () => IAM_ROUTES,
+  },
+];
+```
 
 ---
 
-### PermissionApiService
+## Permission Modes
 
-**File:** `services/permission-api.service.ts` | Extends `BaseApiService`
+### RBAC Mode
 
-All endpoints use POST (POST-only RPC convention).
+Role-Based Access Control. Users are assigned roles; roles hold permissions.
 
-| Method | Endpoint | Description |
-|--------|----------|-------------|
-| `assignUserActions(data)` | `POST /iam/permissions/user-actions/assign` | Assign/remove actions for user |
-| `getUserActions(userId, query?)` | `POST /iam/permissions/get-user-actions` | Get user's direct actions |
-| `assignUserRoles(data)` | `POST /iam/permissions/user-roles/assign` | Assign/remove roles for user |
-| `getUserRoles(userId, query?)` | `POST /iam/permissions/get-user-roles` | Get user's roles |
-| `assignRoleActions(data)` | `POST /iam/permissions/role-actions/assign` | Assign/remove actions for role |
-| `getRoleActions(roleId, query?)` | `POST /iam/permissions/get-role-actions` | Get role's actions |
-| `assignCompanyActions(data)` | `POST /iam/permissions/company-actions/assign` | Assign/remove company whitelist |
-| `getCompanyActions(companyId)` | `POST /iam/permissions/get-company-actions` | Get company's whitelisted actions |
+```
+User ──assigned──► Role ──has──► Permissions
+```
 
----
+**Active controllers:**
+- Role management (create roles, assign permissions to roles)
+- Role assignment (assign roles to users)
 
-### ActionPermissionLogicService
+**Config:**
+```typescript
+{ permissionMode: 'RBAC' }
+```
 
-**File:** `services/action-permission-logic.service.ts`
+### DIRECT Mode
 
-Manages smart prerequisite validation using AND/OR logic trees.
+Permissions assigned directly to users. No roles.
 
-| Method | Description |
-|--------|-------------|
-| `handleCheck(action, selection, allActions, onUpdate, onCancel)` | Handle selection with prerequisite validation |
-| `handleUncheck(action, selection, allActions, onUpdate)` | Handle deselection with dependency detection |
-| `hasUnmetPrerequisites(action, selection, allActions)` | Check if action has unmet prerequisites |
-| `showValidationErrorDialog(invalid, selection, allActions, onUpdate)` | Pre-save validation with auto-fix |
-| `getPrerequisiteTooltip(action, selection, allActions)` | Get tooltip text with prerequisite info |
+```
+User ──directly assigned──► Permissions
+```
 
-Features: Recursive deep-scan, smart AND/OR optimization, alternative suggestions, pre-save validation.
+**Active controllers:**
+- User permission assignment
 
----
+**Config:**
+```typescript
+{ permissionMode: 'DIRECT' }
+```
 
-## Components
+### FULL Mode
 
-### LogicBuilderComponent
+Both RBAC and DIRECT combined. User gets union of role permissions + direct permissions.
 
-**Selector:** `lib-logic-builder` | Visual AND/OR permission logic tree editor.
+```
+User ──assigned──► Role ──has──► Permissions
+     └──directly──────────────► Permissions
+```
 
-| Input/Output | Type | Description |
-|--------------|------|-------------|
-| `logic` (input) | `ILogicNode \| null` | Current permission logic tree |
-| `actions` (input) | `Array<{id, name}>` | Available actions for dropdowns |
-| `logicChange` (output) | `ILogicNode \| null` | Emitted when logic changes |
+**Config:**
+```typescript
+{ permissionMode: 'FULL' }
+```
 
 ---
 
-### Selector Components (Common Pattern)
-
-All selector components share a common pattern with these signals:
+## Module Registration
 
-| Signal | Description |
-|--------|-------------|
-| `selectedXxxId` | Selected entity ID (user/role/company) |
-| `treeNodes` / `items` | Available items (TreeNode[] or flat array) |
-| `flatActions` | Flattened action list (for action selectors) |
-| `selectedIds` | Currently selected IDs (Set) |
-| `originalSelectedIds` | Original state for change tracking |
-| `isLoading` / `isSaving` | Loading/saving states |
-| `pendingAdd` / `pendingRemove` | Computed: items to add/remove |
-| `hasChanges` | Computed: whether there are pending changes |
+### `provideIamProviders()`
 
-Common features: AbortController for request cancellation, responsive tables with `overflow-x-auto`, change tracking, select/deselect all.
-
----
-
-### UserActionSelectorComponent
+```typescript
+import { provideIamProviders } from '@flusys/ng-iam';
 
-**Selector:** `flusys-user-action-selector` | Assigns actions directly to users (DIRECT/FULL mode).
+// app.config.ts
+providers: [
+  ...provideIamProviders(),
+]
+```
 
-- User dropdown (`lib-user-select` from ng-shared)
-- Branch selector (conditional, from USER_PERMISSION_PROVIDER)
-- Hierarchical TreeTable with checkboxes
-- Prerequisite validation with tooltips
+Registers:
+- `PERMISSION_VALIDATOR` — implementation of `IPermissionValidator` used by `HasPermissionDirective` and `PermissionGuard` from `ng-shared`
 
 ---
 
-### UserRoleSelectorComponent
+## Permission State Service
 
-**Selector:** `flusys-user-role-selector` | Assigns roles to users (RBAC/FULL mode).
+`PermissionStateService` is the signal-based store for the current user's loaded permissions. It caches permissions for **1 hour** and auto-invalidates when roles or direct permissions change.
 
-- User dropdown with branch selector
-- DataTable with pagination
-- No prerequisite validation (roles are simple assignments)
-
----
-
-### RoleActionSelectorComponent
+```typescript
+import { PermissionStateService } from '@flusys/ng-iam';
+
+@Component({ ... })
+export class MyComponent {
+  private permState = inject(PermissionStateService);
+
+  // Signals
+  permissions = this.permState.permissions;       // Signal<string[]>
+  isLoaded = this.permState.isLoaded;             // Signal<boolean>
+  isLoading = this.permState.isLoading;           // Signal<boolean>
+
+  // Check permission reactively
+  canEdit = computed(() =>
+    this.permState.hasPermission('product:update')
+  );
+
+  canDelete = computed(() =>
+    this.permState.hasAnyPermission(['product:delete', 'admin:manage'])
+  );
+
+  // Load permissions (called by appInitGuard after login)
+  loadPermissions(): void {
+    this.permState.load();
+  }
+
+  // Invalidate cache (call after role/permission changes)
+  invalidate(): void {
+    this.permState.invalidate();
+  }
+}
+```
 
-**Selector:** `flusys-role-action-selector` | Assigns actions to roles (RBAC/FULL mode).
+**PermissionStateService API:**
 
-- Role dropdown with filter
-- Hierarchical TreeTable with checkboxes
-- Prerequisite validation with auto-fix dialog
+| Member | Type | Description |
+|--------|------|-------------|
+| `permissions` | `Signal<string[]>` | Current user's permission list |
+| `isLoaded` | `Signal<boolean>` | True when permissions are loaded |
+| `isLoading` | `Signal<boolean>` | True when loading is in progress |
+| `hasPermission(key)` | `boolean` | Single permission check |
+| `hasAllPermissions(keys[])` | `boolean` | AND logic — all must match |
+| `hasAnyPermission(keys[])` | `boolean` | OR logic — at least one must match |
+| `load()` | `Observable<void>` | Load permissions from backend |
+| `invalidate()` | `void` | Clear cache and force reload |
 
----
+### Permission Key Format
 
-### CompanyActionSelectorComponent
+```
+resource:action
+```
 
-**Selector:** `flusys-company-action-selector` | Manages company action whitelisting.
+Examples:
+```
+product:read
+product:create
+product:update
+product:delete
+admin:manage
+user:read
+report:export
+```
 
-- Company dropdown (from COMPANY_API_PROVIDER)
-- Full action tree (not filtered)
-- Backend prerequisite error handling with auto-fix
+Wildcard support:
+```
+*         — all permissions
+product:* — all product actions
+```
 
 ---
 
-## Page Components
+## IAM API Services
 
-Page components are **internal** (not exported). Accessed via `IAM_ROUTES`.
-
-| Component | Selector | Features |
-|-----------|----------|----------|
-| `IamContainerComponent` | `lib-iam-container` | Tabbed navigation, responsive tabs |
-| `ActionListPageComponent` | `lib-action-list-page` | TreeTable, CRUD, read-only indicators |
-| `ActionFormPageComponent` | `lib-action-form-page` | Signal forms, LogicBuilder integration |
-| `RoleListPageComponent` | `lib-role-list-page` | Paginated table (10/25/50), CRUD |
-| `RoleFormPageComponent` | `lib-role-form-page` | Signal forms, company auto-assignment |
-| `PermissionPageComponent` | `lib-permission-page` | Dynamic tabs based on permission mode |
-
----
-
-## Interfaces
+### ActionApiService
 
-### Core Types
+Manages available permission actions (resource:action pairs):
 
 ```typescript
-enum ActionType { BACKEND = 'backend', FRONTEND = 'frontend', BOTH = 'both' }
-type PermissionAction = 'add' | 'remove';
-type PermissionMode = 'rbac' | 'direct' | 'full';
-```
+import { ActionApiService } from '@flusys/ng-iam';
 
-### IAction (extends IBaseEntity)
+@Injectable({ ... })
+export class MyService {
+  private actionApi = inject(ActionApiService);
 
-```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;
-  serial: number | null;
-  isActive: boolean;
-  metadata: Record<string, unknown> | null;
+  getActions(): Observable<IListResponse<IAction>> {
+    return this.actionApi.getAll({ pageSize: 100 });
+  }
 }
-interface IActionTreeDto extends IAction { children: IActionTreeDto[]; }
 ```
 
-### IRole (extends IBaseEntity)
+### RoleApiService
+
+Manages roles and their permission assignments:
 
 ```typescript
-interface IRole extends IBaseEntity {
-  readOnly: boolean;
-  name: string;
-  description: string | null;
-  companyId: string | null;
-  isActive: boolean;
-  serial: number | null;
-  metadata: Record<string, unknown> | null;
-}
-```
+import { RoleApiService } from '@flusys/ng-iam';
 
-### Assignment DTOs
+@Injectable({ ... })
+export class MyService {
+  private roleApi = inject(RoleApiService);
 
-```typescript
-interface IPermissionItemDto { id: string; action: PermissionAction; }
+  createRole(name: string, permissions: string[]): Observable<ISingleResponse<IRole>> {
+    return this.roleApi.insert({ name, permissions });
+  }
 
-interface IAssignUserActionsDto {
-  userId: string; companyId?: string; branchId?: string; items: IPermissionItemDto[];
-}
-interface IAssignRoleActionsDto { roleId: string; items: IPermissionItemDto[]; }
-interface IAssignCompanyActionsDto { companyId: string; items: IPermissionItemDto[]; }
-interface IAssignUserRolesDto {
-  userId: string; companyId?: string; branchId?: string; items: IPermissionItemDto[];
+  assignRoleToUser(userId: string, roleId: string): Observable<IMessageResponse> {
+    return this.roleApi.assignToUser({ userId, roleId });
+  }
 }
 ```
 
-### Response DTOs
+### UserPermissionApiService
 
-All response DTOs include: `id`, entity reference IDs, `actionCode`/`roleCode`, `actionName`/`roleName`, `createdAt`.
+Manages direct permission assignments to users:
 
 ```typescript
-interface IMyPermissionsResponseDto {
-  frontendActions: Array<{ id: string; code: string; name: string; description: string }>;
-  cachedEndpoints: number;  // Endpoint count for backend PermissionGuard
-}
-
-interface IPermissionOperationResultDto {
-  success: boolean; added: number; removed: number; message: string;
-  prerequisiteErrors?: IPrerequisiteValidationError[];
-}
-```
+import { UserPermissionApiService } from '@flusys/ng-iam';
 
-### Simple Models
+@Injectable({ ... })
+export class MyService {
+  private userPermApi = inject(UserPermissionApiService);
 
-```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; }
+  assignPermissions(userId: string, permissions: string[]): Observable<IMessageResponse> {
+    return this.userPermApi.assign({ userId, permissions });
+  }
+}
 ```
 
 ---
 
-## Utils & Constants
-
-Utils are **internal** (not exported from public API).
-
-### permission-logic.util.ts
-
-| Function | Description |
-|----------|-------------|
-| `validateActionPrerequisites(action, selectedIds, allActions)` | Validate prerequisites respecting AND/OR |
-| `extractRequiredActionIds(logic, allActions)` | Extract all action IDs from logic tree |
+## Components
 
-### tree-utils.ts
+### PermissionPageComponent
 
-| Function | Description |
-|----------|-------------|
-| `flattenTree<T>(tree)` | Flatten hierarchical tree into flat array |
-| `buildTreeFromFlat<T>(flatList)` | Build tree from flat list using `parentId` |
-| `convertActionToTreeNode(actions)` | Convert to PrimeNG `TreeNode<IAction>[]` |
+Full-page IAM management UI. Renders different panels based on `permissionMode`:
 
-### Constants
+| Mode | Panels Shown |
+|------|-------------|
+| `RBAC` | Roles list, Role editor, User-role assignment |
+| `DIRECT` | User permission editor |
+| `FULL` | All RBAC panels + User permission editor |
 
 ```typescript
-export const MAX_DROPDOWN_ITEMS = 100;  // Max items for dropdown lists
+// In routes:
+{
+  path: 'iam',
+  loadComponent: () =>
+    import('@flusys/ng-iam').then(m => m.PermissionPageComponent),
+}
 ```
 
----
-
-## Responsive Table Patterns
+### LogicBuilderComponent
 
-All IAM tables use consistent Tailwind CSS patterns:
+Visual drag-and-drop AND/OR nested logic builder for complex permission rules.
 
 ```html
-<!-- Container: horizontal scroll on mobile, full-width on desktop -->
-<div class="overflow-x-auto -mx-4 sm:mx-0">
-  <p-treeTable [tableStyle]="{ 'min-width': '50rem' }">...</p-treeTable>
-</div>
-
-<!-- Responsive columns -->
-<th>Name</th>                           <!-- Always visible -->
-<th class="hidden sm:table-cell">Code</th>     <!-- 640px+ -->
-<th class="hidden md:table-cell">Status</th>   <!-- 768px+ -->
-<th class="hidden lg:table-cell">Description</th> <!-- 1024px+ -->
+<flusys-logic-builder
+  [availableActions]="actions"
+  [(logicTree)]="permissionLogic"
+  (logicChange)="onLogicChange($event)"
+/>
 ```
 
-| Breakpoint | Class | Visibility |
-|------------|-------|------------|
-| Always | (none) | Always visible |
-| sm | `hidden sm:table-cell` | 640px+ |
-| md | `hidden md:table-cell` | 768px+ |
-| lg | `hidden lg:table-cell` | 1024px+ |
+**Supports:**
+- AND groups (all conditions must match)
+- OR groups (any condition must match)
+- Nesting (AND inside OR, etc.)
+- Individual permission conditions
+- Visual drag-to-reorder
 
 ---
 
-## Angular 21 Signal Forms Pattern
-
-```typescript
-import { form, required } from '@angular/forms';
-
-readonly formModel = {
-  name: '',
-  description: '',
-  code: '',
-  actionType: ActionType.FRONTEND,
-  parentId: null as string | null,
-  serial: null as number | null,
-  isActive: true,
-  permissionLogic: null as ILogicNode | null,
-};
-
-readonly actionForm = form(this.formModel, (f) => {
-  required(f.name, { message: 'Name is required' });
-});
+## Integration
 
-readonly canSubmit = computed(() => this.actionForm.valid() && !this.isSaving());
-```
-
----
+### With HasPermissionDirective (from ng-shared)
 
-## Backend Integration
+Once `provideIamProviders()` is registered, `HasPermissionDirective` works automatically:
 
-### Required Endpoints
+```html
+<button *hasPermission="'product:delete'">Delete</button>
 
+<div *hasPermission="['admin:manage', 'user:read']">
+  Admin Section
+</div>
 ```
-# Action CRUD
-POST /iam/actions/tree
-POST /iam/actions/tree-for-permission
-POST /iam/actions/get-all
-POST /iam/actions/get/:id
-POST /iam/actions/insert
-POST /iam/actions/update
-POST /iam/actions/delete
-
-# Role CRUD
-POST /iam/roles/get-all
-POST /iam/roles/get/:id
-POST /iam/roles/insert
-POST /iam/roles/update
-POST /iam/roles/delete
-
-# Permission Assignments
-POST /iam/permissions/my-permissions
-POST /iam/permissions/user-actions/assign
-POST /iam/permissions/get-user-actions
-POST /iam/permissions/user-roles/assign
-POST /iam/permissions/get-user-roles
-POST /iam/permissions/role-actions/assign
-POST /iam/permissions/get-role-actions
-POST /iam/permissions/company-actions/assign
-POST /iam/permissions/get-company-actions
-```
-
----
 
-## Best Practices
-
-### Permission Loading
+### With PermissionGuard (from ng-shared)
 
 ```typescript
-// In guard - block navigation until ready
-if (!permissionState.isLoaded()) {
-  await firstValueFrom(permissionState.loadPermissions());
+{
+  path: 'admin',
+  canActivate: [PermissionGuard],
+  data: { permission: 'admin:manage' },
+  loadComponent: () => import('./admin.component'),
 }
 ```
 
-- Cache in memory (PermissionStateService handles this)
-- Clear on logout
-- Never store in localStorage (security risk)
-- Never load in component `ngOnInit` (race conditions)
-
-### Permission Checks
-
-```typescript
-validator.hasAction('user.create');                       // Single
-validator.hasAllActions(['user.create', 'user.update']); // ALL required
-validator.hasAnyAction(['user.view', 'user.list']);      // ANY required
-```
-
-Cache check results in computed signals, not in templates.
+### With appInitGuard (from ng-auth)
 
-### Menu Filtering
+`appInitGuard` automatically loads permissions after session restoration when `iam.enabled: true`:
 
 ```typescript
-this.layoutService.setMenu(menuItems);
-this.layoutService.setPermissionChecker((code) => validator.hasAction(code));
-```
-
-### Action Naming
-
-Format: `module.operation` or `module.entity.operation`
-
-```typescript
-// Good: 'user.create', 'report.export', 'admin.system.config'
-// Bad: 'create' (generic), 'userCreate' (not dot notation)
-```
-
-### LogicNode Pattern
-
-```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' },
-    ]},
-  ],
-};
+// The guard calls PermissionStateService.load() automatically
+// No manual setup needed
 ```
 
 ---
 
-## Configuration
+## API Endpoints
 
-```typescript
-// Frontend: environment.ts
-services: { iam: { baseUrl: 'http://localhost:2002/iam', enabled: true } }
-```
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| POST | `/iam/action/get-all` | List all permission actions |
+| POST | `/iam/action/insert` | Create action |
+| POST | `/iam/action/update` | Update action |
+| POST | `/iam/action/delete` | Delete action |
+| POST | `/iam/role/get-all` | List all roles |
+| POST | `/iam/role/get/:id` | Get role by ID |
+| POST | `/iam/role/insert` | Create role |
+| POST | `/iam/role/update` | Update role |
+| POST | `/iam/role/delete` | Delete role |
+| POST | `/iam/role/assign-user` | Assign role to user |
+| POST | `/iam/role/unassign-user` | Remove role from user |
+| POST | `/iam/user-permission/get/:userId` | Get user's direct permissions |
+| POST | `/iam/user-permission/assign` | Assign direct permissions to user |
+| POST | `/iam/permission/get-my-permissions` | Get current user's effective permissions |
 
-```bash
-# Backend: .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 |
+## Troubleshooting
 
----
+**`HasPermissionDirective` always hides content**
 
-## Provider Functions
+Permissions aren't loaded. Check that:
+1. `provideIamProviders()` is in `app.config.ts`
+2. `services.iam.enabled: true` in environment
+3. `appInitGuard` runs and calls `PermissionStateService.load()`
 
-### provideIamProviders()
+**Permissions don't refresh after role change**
 
-Registers adapters for cross-package communication (e.g., ng-auth profile page).
+Call `PermissionStateService.invalidate()` after modifying roles/permissions:
 
 ```typescript
-import { provideIamProviders } from '@flusys/ng-iam';
-providers: [...provideIamProviders()]
+this.permState.invalidate(); // Clears 1-hour cache, forces reload
 ```
 
-Registers `PROFILE_PERMISSION_PROVIDER` with `ProfilePermissionProviderAdapter`.
+**`FULL` mode shows RBAC UI but not direct permissions UI**
 
----
+Verify `permissionMode: 'FULL'` in your environment and that `PermissionPageComponent` reads the mode from `APP_CONFIG`.
 
-## Common Issues
+**Permission check for wildcards (`product:*`) not working**
 
-| Problem | Solution |
-|---------|----------|
-| `permissionState.isLoaded()` returns false | Check `services.iam.enabled: true`, verify `/iam/permissions/my-permissions` works |
-| Empty menu after login | Verify user has frontend actions, check `requiredAction` matches action codes |
-| Menu items not filtered | Call `layoutService.setPermissionChecker()` after loading permissions |
-| 401 on IAM endpoints | Ensure auth interceptor adds `Authorization` header |
-| Provider not configured error | Add required providers to `app.config.ts` |
-| Empty dropdowns | Ensure adapters return `IListResponse<T>` format |
-| Table not scrollable on mobile | Add `overflow-x-auto -mx-4 sm:mx-0` wrapper |
-| Columns overflow on mobile | Add `hidden sm:table-cell` to non-essential columns |
+Ensure the backend sends flat expanded permissions, not wildcards. The client evaluates exact string matches plus wildcard expansion.
 
 ---
 
-## 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-25
-**Version:** 3.0.1
-**Angular Version:** 21
+MIT © FLUSYS