I. Tổng quan

Mô tả: Tính năng đồng bộ và hiển thị nhãn dán (sticker/label) từ Meta Business Suite Inbox lên hệ thống Đa kênh.

1. Vấn đề

Hiện tại, người dùng quản lý tin nhắn khách hàng trên Meta Business Suite có sử dụng hệ thống nhãn (label) để phân loại trạng thái khách hàng hoặc mức độ ưu tiên.
Khi sử dụng hệ thống Đa kênh của chúng ta, người dùng không nhìn thấy được các nhãn này, dẫn đến thiếu đồng bộ về thông tin, buộc phải mở song song Meta Business Suite để kiểm tra, làm mất nhiều thời gian và giảm hiệu suất công việc.

2. Giải pháp

Tự động lấy các nhãn dán được gán cho thread tin nhắn từ Meta Business Suite (Inbox) và đồng bộ, gán vào thread tin nhắn tương ứng trên nền tảng Đa kênh của hệ thống.
Hiển thị rõ ràng các nhãn dán này trên giao diện, với thiết kế đặc trưng của Facebook (có Logo Facebook, màu tone xanh Facebook), được đặt cạnh vị trí của nhãn dán Zalo hiện tại để người dùng dễ dàng nhận diện.

3. Đối tượng

Nhân viên thao tác trực tiếp trên Đa kênh (Sales, CSKH) để nhận diện khách.
Quản lý/Admin sử dụng để giám sát, theo dõi trạng thái khách hàng.

4. Tầm nhìn/insight (Các vấn đề sẽ làm trong tương lai)

Hỗ trợ bộ lọc (filter) tìm kiếm hội thoại theo nhãn dán Facebook.
Hỗ trợ gán/xoá nhãn dán Facebook trực tiếp từ hệ thống Đa kênh và đồng bộ ngược về Meta Business Suite (Two-way sync) thay vì chỉ đọc (Read-only) như phase này.

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

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

Đồng bộ dữ liệu nhãn dán hội thoại từ Meta Business Suite.
Hiển thị nhãn dán Facebook trên danh sách hội thoại (Chat List).
Hiển thị nhãn dán Facebook trong phần thông tin chi tiết hội thoại (Chat Box/User Info).

2. Đặc tả chi tiết

User story: Là một [Nhân viên CSKH], tôi muốn [thấy được nhãn dán Facebook đồng bộ từ Meta Business Suite] để [nhanh chóng nắm bắt trạng thái khách hàng mà không cần chuyển qua lại giữa các tab].

Tên Use Case	[UC-01] Xem nhãn dán Facebook trên hội thoại
Actor (Người dùng)	Nhân viên CSKH, Quản lý
Pre-condition (Tiền ĐK)	User đã đăng nhập hệ thống, Fanpage đã được kết nối và tài khoản Meta có sử dụng nhãn(label) cho hội thoại.
Main Flow (Luồng chính)	(Xem sơ đồ luồng chi tiết bên dưới)
Alternate/Exception Flow (Luồng rẽ nhánh/Ngoại lệ)	Hội thoại Facebook chưa được gán nhãn nào từ Meta: Không hiển thị giao diện nhãn Facebook.
Post-condition (Hậu ĐK)	Giao diện hiển thị đúng nhãn đã cấu hình trên FB, đúng màu sắc chuẩn và kèm logo FB.

Tên Use Case	[UC-02] Cập nhật thay đổi nhãn dán từ Meta Business Suite
Actor (Người dùng)	Hệ thống, Nhân viên CSKH (thao tác trên Meta)
Pre-condition (Tiền ĐK)	Hội thoại đang được gán nhãn, đổi nhãn hoặc gỡ nhãn trực tiếp trên nền tảng Meta Business Suite Inbox.
Main Flow (Luồng chính)	1. User thao tác Thêm / Sửa / Xóa nhãn dán cho một hội thoại trên Meta Business Suite. 2. Meta Gửi Webhook sự kiện thay đổi nhãn về hệ thống. 3. Hệ thống tiếp nhận, tiến hành cập nhật danh sách nhãn dán tương ứng của hội thoại trên Database. 4. Giao diện Đa kênh tự động cập nhật (render lại) danh sách nhãn dán mới theo thời gian thực (nếu user đang mở màn hình) hoặc tải mới khi truy cập lại trang.
Alternate/Exception Flow (Luồng rẽ nhánh/Ngoại lệ)	Lỗi đồng bộ Webhook/Mạng: Giao diện Đa kênh chậm hiển thị hoặc vẫn hiển thị nhãn ở trạng thái cũ.
Post-condition (Hậu ĐK)	Dữ liệu và trạng thái hiển thị nhãn dán trên Đa kênh đồng nhất hoàn toàn với Meta Business Suite ngay sau khi thay đổi được ghi nhận.

Sơ đồ luồng người dùng (User Flow):

flowchart TD
    A([Bắt đầu]) --> B{Hội thoại có nhãn <br>từ Meta Business Suite?}
    B -- Có --> C[Hệ thống đồng bộ nhãn dán qua Webhook]
    B -- Không --> D[Hiển thị hội thoại bình thường <br> Không có nhãn Facebook]
    
    C --> E[User truy cập màn hình <b>Đa kênh</b>]
    E --> F[Hiển thị nhãn Facebook tại <b>Danh sách hội thoại</b> <br> *Nằm cạnh vị trí nhãn Zalo*]
    F --> G[User click mở Xem chi tiết hội thoại]
    G --> H[Hiển thị nhãn Facebook tại khu vực <b>Thông tin chung</b> của Chat box]
    
    H --> I([Kết thúc])
    D --> I

    %% Styling
    classDef highlight fill:#e1f5fe,stroke:#0288d1,stroke-width:2px;
    class F,H highlight;

3. Danh sách nghiệp vụ

Tên nhãn dán hiển thị phải trùng khớp hoàn toàn với tên nhãn dán đang có trên nền tảng Meta Business Suite.
Trường hợp một hội thoại có nhiều nhãn dán: Hiển thị danh sách các nhãn. Nếu số lượng nhãn hoặc độ dài tên nhãn quá dài gây tràn UI, áp dụng logic thu gọn +N (tương tự logic áp dụng cho nhãn Zalo hiện tại).

4. Giao diện

Vị trí hiển thị: Nằm sát cạnh vị trí của các nhãn dán Zalo hiện tại.
Trực quan hóa (UI component):
- Layout & Kích thước: Clone giống với hình dáng, font size, padding của nhãn dán Zalo hiện tại ở hệ thống đa kênh để đảm bảo tính đồng bộ trên toàn cục UI.
- Icon: Sử dụng logo Facebook (thay cho logo Zalo).
- Màu sắc: Sử dụng tone màu xanh lam đặc trưng của Facebook (VD: #1877F2 hoặc màu quy chuẩn của dự án cho kênh FB) áp dụng cho viền (border), chữ (text) hoặc nền (background) theo đúng style guide.

Ảnh tham khảo Design (Figma):

Giao diện nhãn Facebook cạnh Zalo

(Hình ảnh minh hoạ hiển thị UI của phần danh sách hội thoại)

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

Độ trễ đồng bộ (Latency): Nhãn dán cần được cập nhật nhanh nhất có thể sau khi có thao tác gán hoặc xóa nhãn từ nền tảng Meta Business Suite nhằm đảm bảo tính real-time (Phụ thuộc vào Webhook của Meta Graph API).
Trải nghiệm UI/UX: Khi load danh sách nhiều chat có đi kèm nhiều nhãn dán, hệ thống không được giật lag. Có cơ chế skeleton loading hoặc lazy load các biểu tượng nhãn. Giao diện đảm bảo responsive, không vỡ layout khi co kéo màn hình.

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

Webhook/Graph API của nền tảng Meta (Messenger API) cung cấp event mỗi khi có sự thay đổi (thêm, xóa, sửa) về Label gắn trên thread message.
Cấu trúc Database của hệ thống Đa kênh hiện tại: Tác động mở rộng column/table để lưu trữ các Label riêng của tính năng FB.
Cấu trúc Component hiển thị danh sách hội thoại ở Frontend.

V. API Contract (Dev viết)

(Đây là phần dự thảo, Dev/Backend sẽ quyết định cấu trúc JSON chuẩn)

API GET: API lấy danh sách chat sẽ trả thêm Payload về facebook_labels.

Response Format (Ví dụ):

{
  "thread_id": "1234567890",
  "facebook_labels": [
    {
      "label_id": "fb_lbl_01",
      "name": "Khách VIP",
      "color": "#1877F2"
    },
    {
      "label_id": "fb_lbl_02",
      "name": "Đã tư vấn",
      "color": "#1877F2"
    }
  ]
}

VI. Test case (BA hoặc Tester viết)

TC1 (Luồng chuẩn - Đồng bộ 1 nhãn): Từ Meta Business Suite, gán 1 nhãn cho hội thoại -> Truy cập hệ thống Đa kênh -> Kiểm tra thấy hội thoại hiển thị đúng tên nhãn đó, có logo Facebook và sử dụng màu xanh đặc trưng.
TC2 (Hiển thị nhiều nhãn & UI hiển thị): Gán 3 nhãn cho một hội thoại FB -> Kiểm tra Đa kênh xem có hiển thị toàn bộ 3 nhãn hay thu gọn thành +2 khi không đủ khoảng trống không.
TC3 (Đồng bộ xóa nhãn): Hủy gán nhãn của 1 hội thoại trên Meta -> Chờ webhook -> Kiểm tra hệ thống Đa kênh thấy nhãn dán đã bị gỡ bỏ ở cả danh sách chat và chi tiết chat.
TC4 (Hiển thị song song Zalo và Facebook): Mở giao diện xem các hội thoại liền kề nhau có cả hội thoại Zalo (Gắn nhãn Zalo) và hội thoại FB (Gắn nhãn FB) -> Đánh giá thiết kế hiển thị chuẩn, không lệch dòng hay lỗi màu sắc giữa 2 kênh.