update DOC

luutru/SOP_des.md

@@ -0,0 +1,121 @@
+# BẢN ĐẶC TẢ HỆ THỐNG AFTER-SALE CRM (PHIÊN BẢN NÂNG CAO)
+
+## 1. Cấu trúc dữ liệu mở rộng (Extended Database Schema)
+
+AI Agent cần bổ sung các bảng và trường dữ liệu sau để phục vụ việc luân chuyển và lưu trữ bằng chứng:
+
+### A. Quản lý Tài liệu & Bằng chứng (Attachment Management)
+
+- **`media_attachments`**:
+  
+  - `id`, `uuid`, `disk`, `file_path`, `file_name`, `mime_type`, `file_size`.
+  
+  - `model_type` (Ticket hoặc Interaction), `model_id`.
+  
+  - `collection`: (Ví dụ: 'proof_of_resolution' - bằng chứng xử lý, 'customer_evidence' - khách hàng cung cấp).
+  
+  - `uploader_id` (User ID của người tải lên).
+
+### B. Luồng điều phối đa bộ phận (Cross-department Routing)
+
+- **`departments`**: `id`, `name` (Kỹ thuật, Kế toán, Chăm sóc khách hàng, Pháp lý), `manager_id`.
+
+- **`tickets` (Bổ sung)**:
+  
+  - `current_department_id`: Phòng ban đang thụ lý.
+  
+  - `handler_id`: Nhân viên cụ thể đang xử lý.
+  
+  - `is_escalated`: Boolean (Đánh dấu nếu bị khiếu nại vượt cấp).
+
+- **`ticket_transfer_logs`**: (Theo dõi lịch sử chuyển giao)
+  
+  - `id`, `ticket_id`, `from_department_id`, `to_department_id`, `sender_id`, `reason`, `created_at`.
+
+---
+
+## 2. Logic luồng xử lý (Workflow Engine Logic)
+
+AI Agent phải triển khai logic xử lý theo các ràng buộc sau:
+
+### A. Quy tắc Chuyển tiếp (Transfer Logic)
+
+- Khi nhân viên A (Phòng CSKH) chuyển Ticket cho Phòng Kỹ thuật:
+  
+  - Hệ thống yêu cầu nhập `reason` và đính kèm tài liệu liên quan (nếu có).
+  
+  - `current_department_id` cập nhật sang ID Phòng Kỹ thuật.
+  
+  - `handler_id` sẽ được reset về `null` (chờ Trưởng phòng Kỹ thuật chỉ định nhân viên mới) hoặc tự động gán cho Trưởng phòng đó.
+
+### B. Quy tắc Đóng Ticket (Closing Permissions)
+
+- **Status: `closed`** là trạng thái cuối cùng.
+
+- **Ràng buộc (Constraint):** * Nếu `user_role` là 'Staff', hệ thống chỉ được phép chuyển trạng thái sang `resolved` (Đã xử lý xong - chờ kiểm duyệt).
+  
+  - Trạng thái `closed` chỉ khả dụng (Visible/Actionable) khi `user_role` là 'Manager' hoặc 'Department_Head'.
+  
+  - Trước khi chuyển sang `closed`, hệ thống kiểm tra bắt buộc phải có ít nhất 01 tệp tin thuộc collection `proof_of_resolution`.
+
+---
+
+## 3. Quản lý tệp tin (Document & File Handling)
+
+AI Agent cần thiết lập một Service Layer riêng cho việc xử lý File:
+
+1. **Validation:** Chỉ cho phép định dạng ảnh (jpg, png), PDF và Video ngắn (<20MB).
+
+2. **Versioning:** Nếu tải tài liệu mới lên cùng một Ticket, không được xóa tài liệu cũ, phải lưu trữ theo dạng danh sách để làm căn cứ đối chiếu.
+
+3. **Security:** File tải lên phải được lưu trữ trong `private disk` và chỉ những người có quyền truy cập Ticket đó mới có thể Generate Temporary URL để xem.
+
+---
+
+## 4. Kịch bản kiểm thử cho AI Agent (Test Scripts)
+
+### Kịch bản 1: Kiểm tra quyền Đóng Ticket (Permission Check)
+
+- **Input:** User có role `staff` gửi request `PATCH /api/tickets/{id}` với `status: 'closed'`.
+
+- **Expectation:** Trả về lỗi `403 Forbidden`. Thông báo: "Chỉ lãnh đạo cấp phòng mới có quyền đóng phiếu."
+
+### Kịch bản 2: Kiểm tra bắt buộc bằng chứng (Mandatory Evidence)
+
+- **Input:** Manager thực hiện đóng Ticket nhưng chưa tải lên bất kỳ tài liệu nào trong collection `proof_of_resolution`.
+
+- **Expectation:** Trả về lỗi `422 Unprocessable Entity`. Thông báo: "Yêu cầu cung cấp tài liệu bằng chứng để hoàn tất quy trình."
+
+### Kịch bản 3: Kiểm tra luồng chuyển tiếp (Transfer Flow)
+
+- **Input:** Thực hiện `transfer` Ticket từ Phòng CSKH sang Phòng Pháp lý.
+
+- **Expectation:** * Bản ghi mới trong `ticket_transfer_logs` được tạo.
+  
+  - `current_department_id` của Ticket thay đổi thành ID Phòng Pháp lý.
+  
+  - Gửi Notification (Database & Mail) cho Manager của Phòng Pháp lý.
+
+---
+
+## 5. Chỉ dẫn triển khai (Implementation Prompt cho AI Agent)
+
+> "Sử dụng **Laravel 13.x** và **Filament v5.5**, hãy thực hiện:
+> 
+> 1. Thiết lập **Spatie Media Library** (hoặc Custom File Service) để quản lý tài liệu gắn với Ticket và Interaction. Phân loại rõ collection 'evidence' và 'resolution_proof'.
+> 
+> 2. Tại `TicketResource` của Filament:
+>    
+>    - Tạo một Action `Transfer Department`: Hiển thị Modal cho phép chọn Phòng ban và nhập lý do chuyển. Lưu lịch sử vào bảng `ticket_transfer_logs`.
+>    
+>    - Tạo logic ẩn/hiện nút `Close Ticket`: Chỉ hiển thị nếu User có role 'Manager'.
+>    
+>    - Sử dụng **Validation Rule** tùy chỉnh: Khi status chuyển sang `closed`, kiểm tra sự tồn tại của file trong media collection.
+> 
+> 3. Xây dựng trang Dashboard cho Lãnh đạo phòng:
+>    
+>    - Hiển thị danh sách Ticket đang ở trạng thái `resolved` (chờ đóng).
+>    
+>    - Biểu đồ thời gian xử lý trung bình của từng nhân viên trong phòng.
+> 
+> 4. Viết **Pest Test** bao phủ toàn bộ logic phân quyền và chuyển tiếp bộ phận."