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:

Validation: Chỉ cho phép định dạng ảnh (jpg, png), PDF và Video ngắn (<20MB).
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.
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:

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'.

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.

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.

Viết Pest Test bao phủ toàn bộ logic phân quyền và chuyển tiếp bộ phận."

5.4 KiB Raw Blame History