From d2df9edd69f5fd254a9735a94683845a38c09232 Mon Sep 17 00:00:00 2001 From: phuongtc Date: Wed, 29 Apr 2026 08:18:08 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20Add=20Permission=20System=20Design=20(H?= =?UTF-8?q?=C6=B0=E1=BB=9Bng=20B)=20to=20WORKFLOW.md=20and=20AGENTS.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 21 +++++++++-- WORKFLOW.md | 105 +++++++++++++++++++++++++++++++++++++++++++++++++++- 2 files changed, 121 insertions(+), 5 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 25bac0a..cdc4565 100644 --- a/AGENTS.md +++ b/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 -6. **Appendix Resource:** Quản lý phụ lục 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 +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 ✅ +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 ✅ ### 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 diff --git a/WORKFLOW.md b/WORKFLOW.md index d8a4b25..ac04607 100644 --- a/WORKFLOW.md +++ b/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ụ.*