feat: AfterSales CRM - SOP compliant real-estate customer care system
- Departments + cross-department transfer workflow - Role-based closing (staff→resolved, manager→closed) with proof_of_resolution - Private file storage with collection system + temporary signed URLs - Dashboard: resolved tickets table, stats, handler performance bar chart - Spatie RBAC (admin/manager/staff) - Notifications: TicketTransferred, TicketClosed (database + mail) - Pest tests: 8 tests, 21 assertions - Docker production-ready (Dockerfile + compose + entrypoint)
This commit is contained in:
121
SOP_des.md
Normal file
121
SOP_des.md
Normal file
@@ -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."
|
||||
Reference in New Issue
Block a user