docs: Add Permission System Design (Hướng B) to WORKFLOW.md and AGENTS.md

WORKFLOW.md

@@ -452,7 +452,7 @@ User 1───* Notification (MorphMany)
 | # | Vấn đề | Mức độ | Ghi chú |
 |---|--------|--------|---------|
 | 1 | **~~Soft Delete~~ ✅** | 🟢 Đã xong | Contract, Payment, Customer có SoftDeletes + Restore/ForceDelete UI |
-| 2 | **Phân quyền** | 🟡 Trung bình | Chỉ 1 loại user. Ai cũng xóa/sửa được mọi thứ |
+| 2 | **Phân quyền** | 🟡 Đang thiết kế | Kiến trúc Hướng B (Tự viết, không Spatie). Xem chi tiết Phần VIII |
 | 3 | **~~Payment.collected_by~~ ✅** | 🟢 Đã xong | Đã thêm collected_by (FK → users) + hiển thị Form/Table |
 | 4 | **Sổ quỹ** | 🟡 Trung bình | Thu tiền nhưng không ghi vào quỹ TM/NH. Không đối soát được |
 | 5 | **CRM Pipeline** | 🟢 Thấp | Chưa quản lý Lead/Khách hàng tiềm năng |
@@ -460,4 +460,107 @@ User 1───* Notification (MorphMany)
 
 ---
 
+---
+
+## VIII. PERMISSION SYSTEM DESIGN (Hướng B - Tự viết, không Spatie)
+
+> **Quyết định kiến trúc:** Không dùng Spatie Permission. Tự viết module phân quyền đơn giản, đủ dùng, kiểm soát 100%.
+> **Lý do:** Tránh config phức tạp, tránh xung đột UUID/BIGINT, phù hợp 5-10 role, không cần advanced features.
+
+### Kiến trúc 3 lớp
+
+```
+LAYER 1: ROLE TEMPLATE (Mẫu nhóm)
+  role_templates.id(UUID) | name | description | permissions(JSONB) | is_active
+  
+  permissions lưu dạng:
+  {
+    "contracts": ["view","create","update","delete","restore","forceDelete","export"],
+    "payments": ["view","create","update","delete"],
+    "customers": ["view","create","update","delete"]
+  }
+
+LAYER 2: USER (Kế thừa + Override)
+  users.role_template_id(UUID) → nullable
+  users.extra_permissions(JSONB) → thêm quyền vượt cấp
+  users.excluded_permissions(JSONB) → bớt quyền so với mẫu
+
+LAYER 3: EFFECTIVE PERMISSIONS (Tính toán động, cache trong Session)
+  effective = template_permissions + extra_permissions - excluded_permissions
+  
+  Tính 1 lần khi user login → lưu vào session()->get('user.{id}.permissions')
+  Tự động xóa khi logout
+  Có thể xóa thủ công: auth()->user()->clearPermissionCache()
+```
+
+### Quy tắc khai báo Permission trong Resource
+
+Mỗi Resource khai báo:
+```php
+class ContractResource extends Resource
+{
+    protected static array $permissionActions = [
+        'view', 'create', 'update', 'delete', 
+        'restore', 'forceDelete', 'export'
+    ];
+    protected static string $permissionLabel = 'Hợp đồng';
+}
+```
+
+Naming: `{snake_case_resource_name}.{action}` (ví dụ: `contracts.create`, `payments.delete`)
+
+### Command đồng bộ (THỦ CÔNG - KHÔNG TỰ ĐỘNG)
+
+```bash
+php artisan permissions:sync
+```
+
+**Khi nào chạy:**
+- Khi thêm Resource mới
+- Khi thêm/bớt `$permissionActions` trong Resource
+- KHÔNG chạy tự động trong composer post-autoload-dump
+
+**Command làm gì:**
+1. Quét tất cả Filament Resources, lấy `$permissionActions` + `$permissionLabel`
+2. Lưu vào bảng `permission_modules` (module, label, actions)
+3. Action mới mặc định **TẮT** cho tất cả role hiện tại (an toàn)
+4. Admin phải vào bật thủ công sau
+
+### Luồng thêm module/action mới
+
+**Step 1: Dev code**
+- Tạo Resource mới / thêm action vào Resource
+- Thêm `$permissionActions` vào Resource class
+
+**Step 2: Dev chạy command**
+- `php artisan permissions:sync`
+
+**Step 3: Admin cấu hình**
+- Vào Role Template UI → thấy module/action mới (badge "Mới")
+- Tick bật quyền cho các nhóm cần dùng
+
+### Các hàm kiểm tra quyền
+
+```php
+// User Model
+public function getEffectivePermissions(): array;
+public function hasEffectivePermission(string $permission): bool;
+public function clearPermissionCache(): void;
+
+// Trong Resource
+public static function canCreate(): bool 
+{
+    return auth()->user()->can('contracts.create');
+}
+```
+
+### UI quản lý (Filament Resources)
+
+| Resource | Chức năng |
+|----------|-----------|
+| **RoleTemplateResource** | CRUD mẫu nhóm. Form chọn module → tick actions. CheckboxList per module |
+| **UserPermissionPage** | Chọn user → hiện role template đang dùng → thêm/bớt quyền chi tiết → preview effective permissions |
+
+---
+
 *File này cần được cập nhật mỗi khi có thay đổi lớn trong kiến trúc hoặc nghiệp vụ.*