solution-erp/.claude/skills/permission-matrix/SKILL.md

---
name: permission-matrix
description: Hệ thống phân quyền Role × MenuKey × CRUD (12 root + Ct_*/Wf_*/Pe_*/PeWf_*/Catalogs — số menu-key · policy canonical → docs/STATUS.md, KHÔNG chép số ở đây). FE PermissionGuard + usePermission. BE AuthorizationHandler + policy `{menu}.{action}`. Dùng khi debug access denied, gán role, menu không hiện, inheritance không work.
when-to-use:
  - "permission denied"
  - "access denied"
  - "menu không hiện"
  - "gán role cho user"
  - "seed permission"
  - "permission matrix edit"
  - "menu inheritance không work"
---

# Permission Matrix Skill

> **Status (cập-nhật 2026-07-15 — S122 W4):** base Phase 1 đợt 2 + extended qua mọi phase.
> 🔴 **Số menu-key · số policy = canonical ở [`docs/STATUS.md`](../../../docs/STATUS.md)** (row `Menu keys` / `Policies`) — **KHÔNG chép số vào file này** (B1). Policy = **DERIVED**: `|MenuKeys.All| × |Actions|` (`Api/Program.cs`) ⇒ đổi menu **BUỘC** đổi cả 2 row cùng lúc.
> 🔍 **Đếm THẬT = đọc mã, đừng tin doc:** `MenuKeys.All` ở `src/Backend/SolutionErp.Domain/Identity/MenuKeys.cs:147`.
>
> **Nhóm menu (hình-dạng, KHÔNG phải con-số):**
> - Core: Dashboard / Master+3 leaves / Forms / Reports / System+Users/Roles/Permissions
> - Contracts root + `Ct_*` (7 type × {Group/List/Create/Pending}) + Workflows root + `Wf_*`
> - PurchaseEvaluations root + `Pe_*` (2 type × 3 action) + PeWorkflows root + `PeWf_*`
> - Catalogs group + 4 leaves (Units/Materials/Services/WorkItems)
> - Office/HRM/… — xem `MenuKeys.cs` (mã là nguồn)
> - 🧊 ~~Budgets root + `Bg_*`~~ — **XOÁ S61 (Mig 50)**, module Budget cũ thay bằng `PeWorkItemBudgets` (ngân-sách per-gói-thầu). Bia-mộ: `MenuKeys.cs:70` + `fe-{admin,user}/src/lib/menuKeys.ts:29`. *(Skill này liệt `Bg_*` như menu ĐANG SỐNG suốt từ S61 → S122 — stale **nặng hơn** lệch con-số vì nó mô-tả thứ **không tồn tại**; vá @S122 W4.)*
>
> **Inheritance roots (4 group, gotcha #35):** `Contracts` → `Ct_*`, `Workflows` → `Wf_*`, `PurchaseEvaluations` → `Pe_*`, `PeWorkflows` → `PeWf_*`. Thêm root mới có children → **PHẢI extend 3 chỗ** trong `GetMyMenuTreeQuery` (gotcha #35). *(🧊 câu cũ "Budgets KHÔNG inherit (Bg_* phải grant tay)" — gỡ theo module.)*

## Model

```
User ────< UserRoles ────< Role ────< Permissions ────< MenuItem
                                       (RoleId, MenuKey, CRUD flags)
```

- 1 User có N Role (qua `AspNetUserRoles` rename → `UserRoles`)
- 1 Role có N Permission (1 row per MenuKey × 4 CRUD flag)
- Union (OR) nhiều role → user có quyền nếu **bất kỳ role nào** cho quyền đó
- Admin role → **bypass** check (luôn pass mọi policy)

## Menu tree (seed — ~60 key sau Phase 8)

```
Dashboard
Master
  ├── Suppliers
  ├── Projects
  ├── Departments
  └── Catalogs (group)
       ├── UnitsOfMeasure
       ├── MaterialItems
       ├── ServiceItems
       └── WorkItems
Contracts (root inherit)
  └── Ct_<Code>_<Group|List|Create|Pending>   × 7 type = 28 leaf
Forms
PurchaseEvaluations (root inherit)
  └── Pe_<Code>_<List|Create|Pending>          × 2 type = 6 leaf
Budgets (root, NO inherit — grant tay)
  ├── Bg_List
  ├── Bg_Create
  └── Bg_Pending
Reports
System
  ├── Users
  ├── Roles
  ├── Permissions
  ├── Workflows (root inherit)
  │    └── Wf_<Code>                           × 7 type = 7 leaf
  └── PeWorkflows (root inherit)
       └── PeWf_<Code>                         × 2 type = 2 leaf
```

Tree hierarchy qua `ParentKey` field. Seed trong `DbInitializer.SeedMenuTreeAsync` + Pe/Wf/Bg seeders riêng.

## Code pointers

**Backend:**
- `Domain/Identity/MenuKeys.cs` — const class, single source of truth
- `Domain/Identity/MenuItem.cs` — entity (Key PK, Label, ParentKey, Order, Icon)
- `Domain/Identity/Permission.cs` — entity (RoleId, MenuKey, 4 flag)
- `Application/Permissions/Queries/GetMyMenuTree/GetMyMenuTreeQuery.cs` — resolve per-user, union OR, filter tree
- `Application/Permissions/PermissionFeatures.cs` — list/upsert
- `Api/Authorization/MenuPermissionRequirement.cs` + `MenuPermissionHandler.cs` — policy check
- `Api/Program.cs` — register policy `{menu}.{action}` trong AddAuthorization (**số = `|MenuKeys.All| × |Actions|` DERIVED**; canonical → `docs/STATUS.md` row `Policies` — KHÔNG hardcode ở đây)
- `Infrastructure/Persistence/DbInitializer.cs` — `SeedMenuTreeAsync` + `SeedAdminPermissionsAsync`
- `Api/Controllers/MenusController.cs`, `RolesController.cs`, `PermissionsController.cs`

**Frontend (fe-admin):**
- `src/lib/menuKeys.ts` — const mirror, cần **đồng bộ tay** với BE
- `src/types/menu.ts` — MenuNode type
- `src/hooks/usePermission.ts` — `can(menuKey, action)` helper
- `src/components/PermissionGuard.tsx` — wrap button/content
- `src/components/Layout.tsx` — render sidebar động từ AuthContext.menu
- `src/pages/system/PermissionsPage.tsx` — ma trận edit UI
- `src/contexts/AuthContext.tsx` — `loadMenu()` on login + localStorage cache

## BE policy usage

Register trong Program.cs:

```csharp
services.AddAuthorization(opts =>
{
    foreach (var menu in MenuKeys.All)
        foreach (var action in MenuKeys.Actions)
            opts.AddPolicy($"{menu}.{action}", p =>
                p.Requirements.Add(new MenuPermissionRequirement(menu, action)));
});
services.AddScoped<IAuthorizationHandler, MenuPermissionHandler>();
```

Apply ở controller:

```csharp
[HttpPut("{id:guid}")]
[Authorize(Policy = "Contracts.Update")]
public async Task<IActionResult> Update(...) { }
```

## FE guard usage

```tsx
// Hook
const { can } = usePermission()
if (!can('Contracts', 'Update')) return null

// Component wrap
<PermissionGuard menuKey="Contracts" action="Update">
  <Button>Sửa</Button>
</PermissionGuard>

// Route guard
<Route
  path="/system/permissions"
  element={
    <PermissionGuard menuKey="Permissions" action="Read" fallback={<Forbidden />}>
      <PermissionsPage />
    </PermissionGuard>
  }
/>
```

## Workflow — gán quyền cho role mới

1. Admin login → `/system/permissions`
2. Chọn role (vd "CostControl")
3. Tick checkbox trên matrix grid — mỗi lần tick tự động PUT `/api/permissions` upsert
4. User thuộc role đó logout/login lại → thấy permission mới (menu refresh từ `/api/menus/me`)

## Guard rules đã implement

- **Admin bypass:** role `Admin` luôn pass mọi policy (kể cả chưa seed row Permission)
- **Not user active:** `User.IsActive=false` → AuthorizationHandler return fail
- **Self-demote protection:** admin đang edit không thể giảm quyền role Admin (check trong `UpsertPermissionCommandHandler`)

## Common pitfalls

- **Quên refresh menu sau update permission** → user thấy menu cũ. Giải pháp: logout/login, hoặc Phase 3 thêm SignalR push.
- **MenuKey typo** — TS không check vì menu.key là string. Luôn dùng `MenuKeys.Contracts` const, không hardcode `"Contracts"`.
- **FE cache menu trong localStorage** → sau user được assign role mới, FE thấy menu cũ. Login lại fix.
- **Hai role conflict** (1 cho, 1 cấm): union OR → có ít nhất 1 role cho là được.
- **403 ở API nhưng FE không hide button** → FE guard chỉ UX, BE phải là source of truth. Phải apply `[Authorize(Policy = "X.Y")]` ở controller.

## Phase tiếp theo

- **Phase 3:** SignalR notify khi permission đổi → FE tự refetch `/api/menus/me`
- **Phase 4:** Per-user override (ngoài role) — thêm bảng `UserPermissionOverrides`
- **Phase 4:** Invalidate JWT khi role đổi (rare event, nhưng secure)