Đặc tả tính năng: Bộ lọc Lịch sử hoạt động Đối tượng CRM (Activity History Filter)

I. Tổng quan

Tài liệu đặc tả nghiệp vụ, giao diện và luồng dữ liệu cho tính năng Bộ lọc Lịch sử hoạt động (Activity History Filter) áp dụng trên toàn bộ các đối tượng CRM (tham chiếu tài liệu Objects (Đối tượng CRM) bao gồm: Contact, Enterprise, Deal, Ticket, Order, Task, Meeting…).

1. Vấn đề

  • Dòng thời gian lịch sử hoạt động (Activity Timeline) của các đối tượng CRM ghi nhận khối lượng thông tin tương tác rất lớn: từ thao tác thủ công của nhân viên (sửa thông tin, ghi chú, gọi điện), các sự kiện tự động của hệ thống (phân bổ lead, sinh ticket, đổi trạng thái qua webhook) cho tới các hành động của AI Agent (Callbot gọi tự động, Chatbot tư vấn, trích xuất dữ liệu).
  • Khi lượng bản ghi lịch sử ngày càng nhiều, nhân viên kinh doanh (Sales), chăm sóc khách hàng (CSKH) và quản lý gặp khó khăn:
    • Bị “ngập” trong các thông báo hệ thống tự động, khó tìm thấy những tương tác quan trọng do con người hoặc AI Agent tạo ra.
    • Thiếu công cụ lọc theo tác nhân thực hiện (ai làm gì, bot nào làm, hệ thống tự động sinh khi nào).
    • Thiếu công cụ lọc theo khoảng thời gian linh hoạt (chỉ muốn xem các hoạt động trong tháng này hoặc tuần qua).
    • Mỗi lần truy cập vào từng khách hàng/đối tượng đều phải tìm kiếm lại thủ công, chưa có cơ chế lưu bộ lọc mặc định theo thói quen cá nhân của từng nhân sự.

2. Giải pháp

  • Bổ sung Bộ lọc nâng cao cho Lịch sử hoạt động ngay tại thanh công cụ hoạt động của màn hình chi tiết mọi đối tượng CRM:
    • Cho phép người dùng lọc hoạt động theo Tác nhân tạo (Tạo bởi / Created By): hỗ trợ phân loại linh hoạt giữa Người dùng (User), Hệ thống (System) và AI Agent.
    • Cho phép người dùng lọc theo Thời gian tạo (Created Time) với các mốc thời gian động (Hôm nay, 7 ngày qua, 30 ngày qua, Tháng này…) hoặc khoảng ngày tùy chọn.
  • Cung cấp tính năng Cấu hình bộ lọc hoạt động mặc định tại Cài đặt cá nhân:
    • Từng nhân sự có thể cấu hình sẵn tiêu chí lọc ưu tiên (ví dụ: chỉ xem hoạt động của User và AI Agent trong 30 ngày qua).
    • Khi mở bất kỳ đối tượng CRM nào, hệ thống tự động áp dụng bộ lọc cá nhân này giúp tối ưu trải nghiệm và tiết kiệm thời gian làm việc.

3. Đối tượng sử dụng

  • Nhân viên Sales / CSKH: Nhanh chóng nắm bắt lịch sử tương tác của đồng nghiệp hoặc AI Agent với khách hàng trong giai đoạn gần nhất; loại bỏ các log hệ thống không cần thiết.
  • Quản lý / Team Leader: Kiểm tra và đánh giá các can thiệp thủ công của nhân viên trên deal/ticket hoặc rà soát xem AI Agent đã thực hiện những hành động tự động nào.
  • Admin / Kỹ thuật viên: Dễ dàng lọc riêng các hoạt động do “Hệ thống” sinh ra để đối soát lỗi hoặc kiểm tra luồng tích hợp webhook/automation.

4. Tầm nhìn / Định hướng tương lai (Future Roadmap)

  • Mở rộng thêm tiêu chí lọc theo Loại hành động chi tiết (Tạo mới, Cập nhật trạng thái, Gửi tin nhắn, Ghi âm cuộc gọi).
  • Cho phép lưu nhiều Bộ lọc mẫu (Preset Filters) ngay tại popover lọc để chuyển đổi nhanh (ví dụ: Preset “Chỉ tương tác AI”, Preset “Nhân viên cập nhật”).
  • Hỗ trợ xuất file Excel lịch sử hoạt động đã lọc phục vụ kiểm toán nội bộ.

II. Yêu cầu chức năng

1. Danh sách tính năng

  1. Nút mở Bộ lọc hoạt động: Icon phễu lọc đặt cạnh ô tìm kiếm hoạt động tại chi tiết đối tượng CRM.
  2. Lọc theo Người tạo (Tạo bởi - Created By):
    • Hỗ trợ các nhóm tác nhân: Người dùng (User), Hệ thống (System), AI Agent.
    • Hỗ trợ các phép so sánh: Bằng, Không bằng, Thuộc danh sách, Không thuộc danh sách, Thuộc loại tác nhân, Có giá trị, Không có giá trị.
  3. Lọc theo Thời gian tạo (Created Time):
    • Hỗ trợ các mốc thời gian định sẵn: Hôm nay, Hôm qua, 7 ngày qua, 30 ngày qua, Tuần này, Tháng này, Tháng trước.
    • Hỗ trợ các phép so sánh thời gian: Trong khoảng (Từ ngày - Đến ngày), Vào ngày, Trước ngày, Sau ngày.
  4. Hành động tại Popover lọc: Nút [Áp dụng] và [Xoá bộ lọc].
  5. Chỉ báo trạng thái bộ lọc: Đổi màu icon phễu và hiển thị badge khi có bộ lọc đang áp dụng.
  6. Cấu hình bộ lọc mặc định trong Cài đặt cá nhân:
    • Trang Cài đặt cá nhân cho phép thiết lập điều kiện mặc định cho Tạo bởi và Thời gian tạo.
    • Nút [Lưu cấu hình] để lưu vào User Profile.
  7. Tự động áp dụng bộ lọc mặc định: Tự động áp dụng cấu hình cá nhân khi mở chi tiết đối tượng CRM bất kỳ.

2. Đặc tả chi tiết (Use Cases)

UC-ACT-01: Lọc hoạt động tại chi tiết đối tượng CRM

Thuộc tính Chi tiết
Tên Use Case Lọc lịch sử hoạt động theo Tác nhân và Thời gian
Actor Mọi User có quyền xem chi tiết đối tượng CRM
Tiền điều kiện User đang mở tab “Hoạt động” tại màn hình chi tiết của một đối tượng CRM (Contact, Enterprise, Deal, Ticket, Order…).
Luồng chính (Main Flow) 1. User click vào Icon Phễu lọc (bên phải ô nhập “Tìm kiếm hoạt động”).
2. Hệ thống hiển thị Popover “Lọc hoạt động” gồm 2 hàng điều kiện:
    - Hàng 1 (Icon User): Tạo bởi - [Phép so sánh] - [Điền giá trị].
    - Hàng 2 (Icon Clock): Thời gian tạo - [Phép so sánh] - [Điền giá trị].
3. User chọn tiêu chí lọc mong muốn:
    - Chọn Tạo bởi: Chọn phép so sánh (ví dụ: Bằng) và giá trị (ví dụ: Hệ thống, AI Agent hoặc chọn tên nhân viên cụ thể như Quan Nguyen).
    - Chọn Thời gian tạo: Chọn phép so sánh (ví dụ: Trong khoảng) và nhập khoảng ngày (ví dụ: 01/03/2024 - 22/03/2024).
4. User click nút [Áp dụng].
5. Hệ thống đóng popover, hiển thị Icon phễu ở trạng thái active (màu xanh dương kèm chấm báo hiệu), đồng thời gửi request tải lại danh sách hoạt động.
6. Timeline hoạt động chỉ hiển thị các bản ghi thỏa mãn đồng thời các điều kiện lọc.
Luồng Xóa bộ lọc 1a. User mở lại Popover “Lọc hoạt động”.
2a. User click nút [Xoá bộ lọc].
3a. Hệ thống reset các trường lọc về rỗng, icon phễu trở lại màu xám mặc định, danh sách timeline tải lại toàn bộ hoạt động mà không bị giới hạn điều kiện tác nhân/thời gian.
Ngoại lệ (Không có dữ liệu) Nếu không có hoạt động nào thỏa mãn điều kiện lọc, hệ thống hiển thị Empty State: “Không tìm thấy hoạt động nào phù hợp với bộ lọc.” kèm nút “Xóa bộ lọc”.

UC-ACT-02: Cấu hình bộ lọc hoạt động mặc định tại Cài đặt cá nhân

Thuộc tính Chi tiết
Tên Use Case Thiết lập bộ lọc hoạt động mặc định cho cá nhân
Actor Mọi User trong hệ thống
Tiền điều kiện User đã đăng nhập vào hệ thống.
Luồng chính (Main Flow) 1. User truy cập menu Cài đặt -> chọn Cài đặt cá nhân.
2. Tại khu vực “Cấu hình bộ lọc hoạt động của các đối tượng CRM” (phụ đề: “Chỉ hiển thị các hoạt động thoả mãn tất cả điều kiện sau:”):
    - Dòng 1: Cấu hình điều kiện cho Tạo bởi.
    - Dòng 2: Cấu hình điều kiện cho Thời gian tạo.
3. User chọn phép so sánh và điền giá trị mong muốn (ví dụ: Tạo bởi Thuộc loại tác nhân = Người dùng, Thời gian tạo Trong = 30 ngày qua).
4. User click nút [Lưu cấu hình] ở góc trên bên phải màn hình.
5. Hệ thống lưu cấu hình vào bảng thiết lập cá nhân của User (user_settings), hiển thị Toast thông báo “Cập nhật cấu hình thành công”.
Hậu điều kiện Từ thời điểm này, mỗi khi User mở bất kỳ màn hình chi tiết Object CRM nào, hệ thống tự động nạp sẵn và kích hoạt bộ lọc theo đúng các giá trị mặc định này.

3. Danh sách nghiệp vụ (Business Rules)

  • BR-ACT-01: Phân loại Tác nhân tạo (Created By Types)
    • Hệ thống chuẩn hóa 3 nhóm tác nhân tạo hoạt động:
      1. USER (Người dùng nội bộ): Là các thành viên có tài khoản trong workspace (nhân viên, quản lý, admin). Dữ liệu lưu created_by_type = 'USER', created_by_id = {user_uuid}.
      2. SYSTEM (Hệ thống): Là các tiến trình nền tự động, trigger nội bộ, webhook từ dịch vụ bên thứ ba hoặc cronjob định kỳ. Dữ liệu lưu created_by_type = 'SYSTEM', created_by_id = NULL (hoặc định danh hệ thống).
      3. AI_AGENT (Trợ lý ảo AI / Callbot / Chatbot): Là các bot AI tự động tương tác với khách hàng hoặc tự động xử lý nghiệp vụ (ví dụ: Bot Callbot gọi ra, Chatbot AI đa kênh trả lời và gắn thẻ). Dữ liệu lưu created_by_type = 'AI_AGENT', created_by_id = {bot_agent_uuid}.
  • BR-ACT-02: Phép so sánh & Giá trị của trường “Tạo bởi”
    • Danh sách phép so sánh hỗ trợ:
      • equals (Bằng): Chọn 1 giá trị cụ thể (Hệ thống, AI Agent - [Tên Bot], hoặc Người dùng - [Tên User]).
      • not_equals (Không bằng): Loại trừ 1 giá trị cụ thể.
      • in (Thuộc danh sách): Chọn đa giá trị (multiselect).
      • not_in (Không thuộc danh sách): Loại trừ đa giá trị.
      • actor_type_is (Thuộc loại tác nhân): Chọn 1 trong 3 nhóm: Tất cả người dùng, Hệ thống, Tất cả AI Agent.
      • is_not_empty (Có giá trị) / is_empty (Không có giá trị): Kiểm tra tính tồn tại của thông tin người tạo.
  • BR-ACT-03: Phép so sánh & Giá trị của trường “Thời gian tạo”
    • Danh sách phép so sánh hỗ trợ:
      • Thời gian động (Relative Dates): Hôm nay (today), Hôm qua (yesterday), 7 ngày qua (last_7_days), 30 ngày qua (last_30_days), Tuần này (this_week), Tháng này (this_month), Tháng trước (last_month), Quý này (this_quarter), Năm nay (this_year).
      • Khoảng thời gian tuyệt đối (Absolute Date Range):
        • between (Trong khoảng): Yêu cầu chọn from_date và to_date.
        • on (Vào ngày): Yêu cầu chọn 1 ngày cụ thể (tính từ 00:00:00 đến 23:59:59 của ngày đó).
        • after (Sau ngày / >=): Tính từ 00:00:00 của ngày được chọn đến hiện tại.
        • before (Trước ngày / <=): Tính từ thời điểm bắt đầu hệ thống đến 23:59:59 của ngày được chọn.
  • BR-ACT-04: Logic kết hợp điều kiện lọc (Combined Filters)
    • Tất cả các điều kiện trong bộ lọc hoạt động kết hợp với nhau theo phép toán AND (Thỏa mãn đồng thời): \(\text{Kết quả hiển thị} = (\text{Keyword Search}) \cap (\text{Tab Loại hoạt động}) \cap (\text{Điều kiện Tạo bởi}) \cap (\text{Điều kiện Thời gian tạo})\)
    • Ví dụ: Đang đứng ở tab Cuộc gọi, gõ tìm kiếm “tư vấn”, lọc Tạo bởi = AI Agent và Thời gian tạo = 7 ngày qua -> Chỉ các cuộc gọi có chứa từ khóa “tư vấn” do AI Agent thực hiện trong 7 ngày qua mới được hiển thị.
  • BR-ACT-05: Ưu tiên áp dụng và Vòng đời bộ lọc (Filter Precedence & Lifecycle)
    • Mức 1 (Mặc định cá nhân): Khi mở trang chi tiết Object CRM lần đầu, hệ thống tự động load cấu hình từ user_settings của user đăng nhập.
    • Mức 2 (Phiên làm việc - Runtime override): Nếu user click vào popover “Lọc hoạt động” và đổi giá trị rồi bấm [Áp dụng]:
      • Bộ lọc mới có hiệu lực ngay lập tức trên màn hình hiện tại.
      • Bộ lọc này không tự động ghi đè vào Cài đặt cá nhân.
    • Khi bấm [Xoá bộ lọc]: Tạm thời đưa cả 2 trường Tạo bởi và Thời gian tạo về rỗng (hiển thị không điều kiện).
    • Khi user refresh trình duyệt (F5) hoặc mở một Object khác: Hệ thống lại ưu tiên nạp từ Cài đặt cá nhân.
  • BR-ACT-06: Phân quyền & Bảo mật (Security & Scope)
    • Cấu hình bộ lọc cá nhân là riêng biệt cho từng tài khoản user (user_id), không chia sẻ và không ảnh hưởng đến người dùng khác trong workspace.
    • Danh sách nhân viên trong dropdown Điền giá trị của trường Tạo bởi chỉ hiển thị những user thuộc cùng workspace và người dùng hiện tại có quyền xem.
    • Tương tự, danh sách bot trong tùy chọn AI Agent chỉ bao gồm các AI Agent được phân quyền cho workspace đó.

4. Giao diện người dùng (UI / UX Specifications)

4.1. Màn hình Chi tiết Đối tượng CRM (Activity Tab Toolbar)

  • Vị trí nút Bộ lọc:
    • Nằm ở khối giữa (Center Content) của màn hình chi tiết Object CRM (ví dụ: Khách hàng > Cá nhân > Chi tiết “chị Huyền”).
    • Đặt ngay sau thanh tìm kiếm hoạt động: [ Tìm kiếm hoạt động... Q ] [ Icon Phễu ].
  • Trạng thái Icon Phễu:
    • Chưa áp dụng bộ lọc: Icon phễu màu xám viền (#595959 hoặc #8C8C8C), nền trong suốt hoặc xám nhạt khi hover.
    • Đang áp dụng bộ lọc (Active): Icon phễu màu xanh thương hiệu (#1677FF), có thể kèm chấm xanh nhỏ (Dot badge) ở góc icon để báo hiệu có điều kiện đang hoạt động.

4.2. Popover / Modal “Lọc hoạt động”

  • Kích thước & Kiểu dáng: Popover thả xuống hoặc Modal nhỏ (khoảng 420px - 480px), bo góc chuẩn Ant Design 8px, đổ bóng box-shadow.
  • Thành phần:
    • Header:
      • Tiêu đề: Lọc hoạt động (Font weight: Bold 16px).
      • Nút đóng: Icon [X] ở góc trên bên phải.
    • Hàng 1 - Lọc theo Người tạo:
      • Icon đầu dòng: Icon Người dùng (UserOutlined, màu xám đậm).
      • Dropdown 1: Tạo bởi (chiều rộng cố định ~120px).
      • Dropdown 2: Phép so sánh (placeholder “Phép so sánh”, chiều rộng ~130px).
      • Dropdown / Multi-select 3: Điền giá trị (placeholder “Điền giá trị”, flex còn lại):
        • Nhóm 1: Nhóm Tác nhân chung (Hệ thống, Tất cả AI Agent, Tất cả Người dùng).
        • Nhóm 2: Danh sách AI Agent cụ thể trong workspace.
        • Nhóm 3: Danh sách Nhân viên cụ thể trong workspace (kèm avatar/tên).
    • Hàng 2 - Lọc theo Thời gian tạo:
      • Icon đầu dòng: Icon Đồng hồ (ClockCircleOutlined, màu xám đậm).
      • Dropdown 1: Thời gian tạo (chiều rộng cố định ~120px).
      • Dropdown 2: Phép so sánh (placeholder “Phép so sánh”, chiều rộng ~130px).
      • Component 3: Điền giá trị (Tùy thuộc phép so sánh đã chọn):
        • Nếu chọn phép so sánh tương đối: Dropdown chọn mốc (Hôm nay, 7 ngày qua, Tháng này…).
        • Nếu chọn phép so sánh “Trong khoảng”: Render component RangePicker (Chọn Từ ngày - Đến ngày).
        • Nếu chọn phép so sánh “Vào ngày / Trước ngày / Sau ngày”: Render component DatePicker.
    • Footer:
      • Căn lề phải:
        • Nút [Xoá bộ lọc]: Button viền xám hoặc default text, khi click sẽ clear trắng 2 điều kiện.
        • Nút [Áp dụng]: Primary Button màu xanh dương (#1677FF), click để thực thi lọc và đóng popover.

4.3. Màn hình Cài đặt cá nhân (Settings > Personal Settings)

  • Đường dẫn: Cài đặt -> Cài đặt Callcenter / Cài đặt cá nhân (URL: /settings/personal).
  • Vị trí khối cấu hình:
    • Nằm phía dưới trường “Tự động lưu khi chỉnh sửa ở màn danh sách” và phía trên khối “Tích hợp lịch”.
  • Tiêu đề khối:
    • Tiêu đề: Cấu hình bộ lọc hoạt động của các đối tượng CRM (Font weight: Bold 14px/16px).
    • Subtext hướng dẫn: “Chỉ hiển thị các hoạt động thoả mãn tất cả điều kiện sau:” (Màu xám #8C8C8C, nghiêng).
  • Form điều kiện:
    • Hàng 1 (Icon User): [Tạo bởi v] [Phép so sánh v] [Điền giá trị v].
    • Hàng 2 (Icon Clock): [Thời gian tạo v] [Phép so sánh v] [Điền giá trị v].
  • Hành động lưu:
    • Nút [Lưu cấu hình] ở góc trên bên phải trang Cài đặt cá nhân (Primary Button, màu xanh dương).

III. Yêu cầu phi chức năng

  1. Hiệu năng truy vấn (Performance):
    • API lấy danh sách hoạt động khi áp dụng bộ lọc tác nhân và thời gian phải phản hồi trong thời gian dưới 300ms với tập dữ liệu hoạt động lên tới 100,000 bản ghi.
    • Bắt buộc đánh Composite Index trên database cho các trường: (target_object_type, target_object_id, created_by_type, created_at).
  2. Trải nghiệm người dùng (UX Responsiveness):
    • Chuyển đổi linh hoạt giữa DatePicker và Select box tùy theo phép so sánh được chọn mà không bị giật lag giao diện.
    • Trạng thái lọc được đồng bộ mượt mà, không yêu cầu reload lại toàn bộ trang web (SPA AJAX / React Query refetch).
  3. Lưu trữ cấu hình:
    • Cấu hình bộ lọc cá nhân được lưu ở cả LocalStorage (để render tức thì lúc khởi động) và đồng bộ với database máy chủ (để dùng đồng nhất khi đăng nhập trên thiết bị khác).

IV. Dependency (Liên quan & Phụ thuộc)

  1. Activity / Audit Log Engine: Hệ thống ghi nhận event log của toàn bộ CRM objects phải chuẩn hóa các cột: created_by_type (USER SYSTEM AI_AGENT), created_by_id, created_at.
  2. User & Workspace Service: Cung cấp danh sách thành viên active trong workspace phục vụ dropdown chọn người tạo.
  3. AI Agent Engine (Callbot / Chatbot): Cung cấp danh sách bot định danh đang hoạt động trong workspace.
  4. Personal Settings Service (user_settings): Lưu trữ và truy xuất các thiết lập tùy biến cá nhân của người dùng.