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

name, description, when-to-use

name	description	when-to-use
permission-matrix	Hệ thống phân quyền Role × MenuKey × CRUD. Seed 12 menu + admin full. FE PermissionGuard + usePermission. BE AuthorizationHandler + 48 policy. Dùng khi debug access denied, gán role, menu không hiện.	permission denied access denied menu không hiện gán role cho user seed permission permission matrix edit

Permission Matrix Skill

Status: Phase 1 đợt 2 IMPLEMENTED + extended qua các phase sau (28 Ct_* + 7 Wf_* + Phase 6 thêm 13 Pe_/PeWf_).

Phase 6 cross-ref (2026-04-23): Thêm menu keys module Duyệt NCC:

• PurchaseEvaluations (root group) + PeWorkflows (admin root, WIP)
• Pe_<Code>_<Action> cho 2 type × 3 action = 6 leaf (Pe_DuyetNcc_List/Create/Pending, Pe_DuyetNccPhuongAn_List/Create/Pending)
• PeWf_<Code> cho admin designer UI (FE chưa build)
• Inheritance: PurchaseEvaluations.Read → auto grant Pe_* descendants (pattern Contracts → Ct_*)
• FE resolver Layout.tsx: Pe_<Code>_List → /purchase-evaluations?type=N (1=NccOnly / 2=NccWithPlan)
• TODO session tiếp: grant non-admin role PurchaseEvaluations.Read qua /system/permissions để user thấy menu Pe_*.

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)

12 menu trong MenuKeys.All:

Dashboard
Master
  ├── Suppliers
  ├── Projects
  └── Departments
Contracts
Forms
Reports
System
  ├── Users
  ├── Roles
  └── Permissions

Tree hierarchy qua ParentKey field. Seed trong DbInitializer.SeedMenuTreeAsync.

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 48 policy {menu}.{action} trong AddAuthorization
• 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:

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:

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

FE guard usage

// 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)