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

AGENTS.md

@@ -331,10 +331,10 @@
 4. **Command generate schedule hàng loạt:** `php artisan contracts:generate-schedules` cho 139 hợp đồng đã import
 
 ### Giai đoạn 2: Module Bổ sung (Ưu tiên TRUNG BÌNH)
-5. **PaymentFine Resource:** Quản lý tiền phạt chậm thanh toán
+5. **PaymentFine Resource:** Quản lý tiền phạt chậm thanh toán ✅
-6. **Appendix Resource:** Quản lý phụ lục hợp đồng
+6. **Appendix Resource:** Quản lý phụ lục hợp đồng ✅
-7. **Settlement Resource:** Quản lý thanh lý hợp đồng
+7. **Settlement Resource:** Quản lý thanh lý hợp đồng ✅
-8. **Discount Engine:** Tính toán tự động chiết khấu từ `discount_details` vào giá trị hợp đồng
+8. **Discount Engine:** Tính toán tự động chiết khấu từ `discount_details` vào giá trị hợp đồng ✅
 
 ### Giai đoạn 3: Báo cáo & Tối ưu (Ưu tiên THẤP)
 9. **Dashboard Tài chính:** Tổng doanh thu, dòng tiền dự kiến, công nợ phải thu ✅
@@ -342,6 +342,19 @@
 11. **Export Excel:** Xuất báo cáo công nợ khách hàng ✅
 12. **Notification:** Cảnh báo đợt thanh toán sắp đến hạn ✅
 
+### Giai đoạn 4: An toàn & Audit (Đang làm)
+13. **Soft Delete:** Contract, Payment, Customer + Restore/ForceDelete UI ✅
+14. **Payment.collected_by:** Ghi nhận ngườ thu tiền ✅
+
+### Giai đoạn 5: Phân quyền (Thiết kế xong, chờ triển khai)
+15. **Permission System (Hướng B - Tự viết, không Spatie):**
+    - `role_templates`: Mẫu nhóm với permissions JSONB
+    - `users`: role_template_id + extra_permissions + excluded_permissions
+    - Session cache effective permissions (tính 1 lần/login)
+    - `php artisan permissions:sync` thủ công khi thêm module
+    - Action mới mặc định TẮT, admin bật thủ công
+    - Xem chi tiết: `WORKFLOW.md` Phần VIII
+
 ---
 
 ## 7. CÂU LỆNH THƯỜNG DÙNG

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ụ.*