# Trợ lý chăm sóc CRM

Tài liệu này mô tả tính năng **Trợ lý chăm sóc** trên trang `crm_lead`, dựa trên logic đang được triển khai trong source tại ngày 23/09/2026.

## 1. Mục tiêu

Trợ lý chăm sóc tự tổng hợp các hồ sơ CRM cần được xử lý tiếp theo, sắp xếp theo mức độ ưu tiên và đưa ra thao tác phù hợp. Mục tiêu là giúp tư vấn viên không bỏ sót lịch hẹn, mốc chăm sóc, học viên sau học thử hoặc hồ sơ đã lâu chưa được liên hệ.

Tính năng chỉ đọc dữ liệu CRM hiện có để tạo danh sách gợi ý. Khi người dùng hoàn thành một việc, hệ thống ghi nhận hoạt động thật vào lịch sử CRM.

## 2. Nguồn dữ liệu

Trợ lý sử dụng các dữ liệu sau:

- Hồ sơ CRM trong `crm_lead_tb`.
- Giai đoạn/mối quan hệ trong `crm_stage_tb`.
- Nhật ký hoạt động trong `crm_activity_tb`.
- Lịch hẹn trong `crm_appointment_tb`.
- Người phụ trách trong `member_tb`.
- Thông tin học viên trong `student_tb`.
- Thông tin Zalo phụ huynh trong `guardian_tb` và `student_guardian_tb`.

Chỉ hồ sơ đang thuộc nhóm giai đoạn `pipeline` mới được đưa vào danh sách gợi ý chăm sóc.

## 3. Các loại việc được tự động đề xuất

Trợ lý xét mỗi hồ sơ theo thứ tự ưu tiên dưới đây. Một hồ sơ chỉ tạo một thẻ công việc có độ ưu tiên cao nhất tại một thời điểm.

| Thứ tự | Loại công việc | Điều kiện hiện tại | Mức hiển thị | Thao tác chính |
|---|---|---|---|---|
| 1 | Lịch hẹn quá hạn | Lịch vẫn ở trạng thái `scheduled` và thời gian hẹn nhỏ hơn thời gian hiện tại | Ưu tiên cao | Cập nhật kết quả lịch hẹn |
| 2 | Mốc chăm sóc quá hạn | `next_follow_up_at` đã qua nhưng chưa được xử lý | Ưu tiên cao | Nhắn Zalo, gọi điện hoặc xem hồ sơ |
| 3 | Lịch hẹn hôm nay | Lịch `scheduled` diễn ra trong hôm nay và chưa tới giờ | Cần theo dõi nếu còn tối đa 2 giờ, nếu không hiển thị mức thường | Xem chi tiết lịch hẹn |
| 4 | Chăm sóc sau học thử | Hồ sơ ở giai đoạn `trial` và không có hoạt động mới từ 1 ngày trở lên | Cần theo dõi; từ 3 ngày là ưu tiên cao | Liên hệ và đánh dấu đã xử lý |
| 5 | Chưa phân công | Hồ sơ chưa có tư vấn viên phụ trách | Cần phân công | Mở form phân công |
| 6 | Lâu chưa chăm sóc | Hoạt động gần nhất đã cách hiện tại từ 3 ngày trở lên | Cần theo dõi | Liên hệ và đánh dấu đã xử lý |

### Cách chọn kênh liên hệ

1. Nếu có Zalo phụ huynh, hiển thị nút **Nhắn Zalo**.
2. Nếu không có Zalo phụ huynh nhưng có số điện thoại học viên, hiển thị nút **Gọi điện**.
3. Nếu không có cả hai, hiển thị nút **Xem hồ sơ** để bổ sung thông tin liên hệ.

## 4. Sắp xếp công việc

Danh sách được sắp theo:

1. Độ ưu tiên của loại công việc theo bảng phía trên.
2. Tên người học theo thứ tự tiếng Việt nếu hai việc cùng độ ưu tiên.

Các thẻ hỗ trợ các bộ lọc:

- **Tất cả:** toàn bộ việc đang cần xử lý.
- **Ưu tiên cao:** lịch hoặc mốc đã quá hạn và các trường hợp học thử quá hạn dài.
- **Của tôi:** chỉ việc có `assigned_member_id` trùng với người dùng hiện tại.
- **Lịch hôm nay:** chỉ các thẻ liên quan đến lịch hẹn hôm nay.

## 5. Thông tin tổng hợp

Khối trợ lý hiển thị ba chỉ số nhanh:

- Số việc quá hạn: lịch hẹn quá hạn và mốc chăm sóc quá hạn.
- Số hồ sơ chưa phân công.
- Số lịch hẹn đang được lên lịch trong hôm nay.

Khi bộ lọc không có kết quả, giao diện hiển thị trạng thái rỗng thay cho vùng thẻ công việc.

## 6. Tiến độ hôm nay

Tiến độ có dạng `đã hoàn thành / tổng số việc`.

```text
Tổng số việc = số việc đã hoàn thành hôm nay + số việc hiện còn chờ xử lý
Tỷ lệ hoàn thành = số việc đã hoàn thành hôm nay / tổng số việc
```

Số việc hoàn thành hôm nay gồm:

- Hoạt động có `activity_type = care_task` được ghi nhận trong ngày.
- Các nhãn hoàn thành cũ còn được hỗ trợ để tương thích dữ liệu trước đây.
- Lịch hẹn chuyển sang trạng thái `completed` trong ngày.

Các hoạt động thông thường như tạo hồ sơ, đổi giai đoạn, ghi chú hoặc hủy lịch không được tính là hoàn thành việc của Trợ lý.

Nếu không có việc hoàn thành và không có việc chờ xử lý, tiến độ là `0/0` và thanh tiến độ ở mức 0%.

## 7. Thao tác trên thẻ công việc

### Cập nhật kết quả lịch hẹn

- Mở popup chi tiết lịch hẹn.
- Cho phép cập nhật mối quan hệ, ngày giờ, người phụ trách và ghi chú.
- Khi gửi kết quả, lịch chuyển sang `completed` và không còn trong danh sách lịch đang chờ.
- Hoạt động hoàn thành lịch được ghi vào lịch sử CRM.

### Đánh dấu đã xử lý

- Gọi API `complete_care_task`.
- Tạo một hoạt động `care_task` trong `crm_activity_tb`.
- Với việc `follow_up`, hệ thống đồng thời xóa `next_follow_up_at` đã hoàn tất.
- Dữ liệu trang được tải lại để cập nhật thẻ và tiến độ.

### Liên hệ

- **Nhắn Zalo:** mở đường dẫn Zalo theo số đã lưu.
- **Gọi điện:** mở liên kết `tel:` sau khi làm sạch số điện thoại.
- **Xem hồ sơ:** mở popup chi tiết người học.
- **Phân công:** mở form chỉnh sửa hồ sơ để chọn tư vấn viên.

## 8. Phân quyền và phạm vi dữ liệu

- Quản lý xem các hồ sơ CRM trong phạm vi quyền quản lý hiện tại.
- Vai trò tư vấn chỉ nhận dữ liệu của các hồ sơ có `assigned_member_id` bằng ID của chính mình.
- Backend kiểm tra lại quyền khi người dùng đánh dấu hoàn thành hoặc sửa dữ liệu; không chỉ dựa vào giao diện.
- Với vai trò tư vấn, bộ lọc theo tư vấn viên được ẩn vì dữ liệu đã được cố định theo tài khoản đăng nhập.

## 9. Giới hạn hiện tại cần lưu ý

### Khái niệm "hoạt động gần nhất"

Cảnh báo **Lâu chưa chăm sóc** hiện lấy hoạt động CRM gần nhất, bao gồm cả hoạt động hệ thống, đổi giai đoạn hoặc tạo lịch. Vì vậy một thao tác quản trị có thể làm mới mốc thời gian dù tư vấn viên chưa thật sự gọi điện hoặc nhắn tin.

Nếu cần đo chính xác nghiệp vụ chăm sóc, nên chỉ tính các loại hoạt động liên hệ như `call`, `zalo`, `email`, `direct`, `trial`, `note` có chủ đích và `care_task`; đồng thời tách riêng thời điểm `last_contact_at` trong database.

### Ngưỡng thời gian đang cố định trong frontend

- Học thử chưa chăm sóc: 1 ngày.
- Học thử chuyển ưu tiên cao: 3 ngày.
- Hồ sơ lâu chưa chăm sóc: 3 ngày.
- Lịch hôm nay chuyển mức cần theo dõi: còn tối đa 2 giờ.

Các ngưỡng này chưa có màn hình cấu hình và chưa được lưu trong database.

### Thời gian và múi giờ

Ngày hiện tại được tính theo thời gian của backend và trình duyệt. Hệ thống cần duy trì cùng múi giờ `Asia/Ho_Chi_Minh` để tránh lệch thống kê ở thời điểm gần 00:00.

## 10. Vị trí code

- Giao diện: `public_html/Frontend/view/frontend/member/pages/crm_lead.phtml`
- Logic hiển thị và sinh gợi ý: `public_html/template/frontend/src/js/page_crm_lead.js`
- CSS: `public_html/template/frontend/src/css/page_crm_lead.css`
- CSS build: `public_html/template/frontend/dist/css/page_crm_lead.css`
- Dịch vụ và truy vấn dữ liệu: `public_html/Frontend/src/Frontend/Service/CrmLeadService.php`
- API action: `public_html/Frontend/src/Frontend/Controller/MemberController.php`

## 11. Quy ước khi nâng cấp

- Mỗi thẻ chỉ đại diện cho một việc ưu tiên nhất của một hồ sơ.
- Mọi thao tác hoàn thành phải ghi lịch sử ở backend để có thể kiểm tra lại.
- Không tính hoạt động chung là việc hoàn thành của Trợ lý.
- Công thức tiến độ phải dùng dữ liệu trong cùng phạm vi quyền với danh sách hồ sơ.
- Khi thêm loại việc mới, cần cập nhật đồng thời điều kiện sinh thẻ, thứ tự ưu tiên, API hoàn thành, bộ đếm tiến độ và tài liệu này.
- Mọi cỡ chữ mới trong giao diện CRM phải từ 12px trở lên.