1. Context & Goal (Bối cảnh & Mục tiêu)

1.1. Bối cảnh

• Khách hàng hiện đang tương tác qua nhiều kênh khác nhau:

  • Odoo Live Chat / Discuss trên website hoặc backend.

  • Zalo (trao đổi trực tiếp giữa khách và nhân viên).

  • vRoute Abivin Website

• Vấn đề hiện tại:

  • Dữ liệu hội thoại bị phân tán, đặc biệt trên Zalo dễ mất nếu để lâu.

  • Agent khi hỗ trợ không có bức tranh đầy đủ:

    • Không biết khách là ai, từ công ty nào, ở quốc gia nào.

    • Không nắm được khách đã từng trao đổi, gặp lỗi gì, làm việc với ai trước.

Điều này tạo ra UX Friction, giảm hiệu quả hỗ trợ và tỉ lệ chốt.

1.2. Nguyên tắc kiến trúc

• Odoo là trung tâm dữ liệu (Customer 360 & Data Hub):

  • Tất cả lịch sử hội thoại, meta-data, mapping khách → đều được lưu TẬP TRUNG trong Odoo.

  • Odoo là system of record cho tương tác khách hàng.

• vRoute là một kênh/ứng dụng vận hành (Operational App & Channel):

  • Nếu khách chat trên vRoute, vRoute chỉ là UI gửi/nhận, còn dữ liệu chat phải được đẩy vào Odoo (tạo mail.channel, mail.message, v.v.).

  • Khi vRoute cần xem lịch sử hoặc thông tin khách → vRoute gọi API/Odoo để đọc dữ liệu, không tự giữ bản gốc.

• Các kênh khác (Zalo, Facebook, Website…):

  • Cũng được coi là channel đẩy dữ liệu hội thoại về Odoo.

1.3. Phạm vi áp dụng

• Ưu tiên cho khách đã có tài khoản / đã có contact trong hệ thống:

  • Khách hàng hiện hữu, partner, user vRoute, user portal…

  • Tức là đã có res.partner và (thường) đã biết Quốc gia, Công ty, Tên.

• Trường hợp khách ẩn danh (anonymous) là ngoại lệ, vẫn xử lý nhưng không phải luồng chính.

1.4. Mục tiêu Business

• Tập trung dữ liệu tương tác về Odoo:

  • Lưu toàn bộ lịch sử hội thoại từ:

    • Odoo Live Chat / Discuss

    • Zalo (qua connector/sync)

• • • Các kênh khác nếu thêm sau này

• Unified Support View cho Agent trong Odoo:

  • Khi Agent mở 1 cuộc chat hoặc ticket:

    • Thấy ngay Thông tin khách (tên, công ty, quốc gia, lĩnh vực, contact…).

    • Thấy được lịch sử hội thoại & tương tác trước đó trên mọi kênh (đã sync về Odoo).

• Giảm thời gian “nhận diện & hiểu khách”, tăng tỉ lệ chốt,

• Tránh mất dữ liệu do chỉ nằm trên Zalo hoặc app ngoài.

2. Functional Requirements (Yêu cầu chức năng)

2.1. Multi-channel Chat – Odoo là trung tâm

Channels (nguồn chat):

• Abivin Website Live Chat / Odoo Discuss

• Abivin vRoute Web App, Abivin vRoute Mobile App (sau này khách chat trên vRoute)

• Zalo (qua connector)

• Các kênh khác (Facebook, WhatsApp…) nếu có trong tương lai.

Nguyên tắc chung:

• Bất kể khách chat ở kênh nào, mọi tin nhắn đều phải được tạo & lưu trong Odoo:

  • Tạo mail.channel / helpdesk.ticket tương ứng (nếu cần).

  • Lưu mail.message cho từng tin nhắn.

  • Link với res.partner (nếu nhận diện được) để phục vụ Customer 360.

• vRoute và các kênh khác không được coi là nơi lưu dữ liệu gốc, chỉ là UI hoặc consumer của dữ liệu Odoo.

2.2. Smart Identification (Nhận diện khách hàng thông minh)

Mục tiêu: Khi có một phiên chat mới (từ bất kỳ channel nào), hệ thống tự động nhận diện khách và link với đúng res.partner.

2.2.1. Luồng chính – Khách đã có tài khoản (partner_id có sẵn)

• Khi khách đã login:

  • Odoo sẽ có:

    • author_id (res.users) → partner_id

    • hoặc partner_ids trên mail.channel.

• Nếu tồn tại partner_id:

  • Hệ thống coi đây là khách đã định danh (main flow).

  • Lấy thông tin từ res.partner:

    • Họ tên, Công ty, Quốc gia, Email, SĐT, Ngành/lĩnh vực, VAT, Tags…

  • Link phiên chat (mail.channel / helpdesk.ticket) với partner_id.

  • Lưu toàn bộ mail.message gắn vào channel đó.

2.2.2. Fallback – Khách chưa login nhưng có thông tin nhận diện

Chỉ dùng khi không có partner_id:

• Hệ thống đọc các trường từ phiên chat/visitor:

  • Email, SĐT, Họ tên, VAT (Tax ID) nếu có.

• Thực hiện tra cứu:

  • res.partner trong Odoo.

  • Kho data crawl thuế (VAT → tên công ty, ngành) để enrich.

Expected behavior (fallback):

• Match duy nhất (1 partner):

  • Tự động link session với partner đó.

  • Hiển thị đầy đủ profile trong Sidebar (xem Section 2.3).

  • Lưu chat gắn với partner như bình thường.

• Không tìm thấy partner:

  • Phiên chat được lưu trong Odoo với trạng thái “khách chưa lưu / khách lạ”.

  • Hiển thị label tương ứng trên UI.

  • Có nút “Create/Link Contact” để Agent tạo mới hoặc gán với 1 res.partner.

  • Sau khi Agent tạo/link, các message tương lai sẽ gắn với partner đó.

• Nhiều partner trùng (Ambiguous):

  • Hệ thống phát hiện có ≥ 2 res.partner trùng email/phone/VAT.

  • Rule auto:

    • Ưu tiên partner mới nhất (write_date mới nhất)

    • Hoặc partner active=True (tuỳ business rule).

  • UI:

    • Hiển thị cảnh báo “Có nhiều khách trùng thông tin”.

    • (Tuỳ lựa chọn) Cho phép Agent chọn lại partner đúng.

  • Hệ thống log warning để Admin xử lý data trùng.

2.3. Context Sidebar trong Odoo Discuss (Unified Support View)

Tại màn hình Odoo Discuss/Chat (hoặc Helpdesk), bổ sung Context Sidebar bên phải (toggle ẩn/hiện):

2.3.1. Customer Profile

Hiển thị:

• Avatar

• Họ tên

• Công ty

• Chức vụ (nếu có)

• Quốc gia

• Lĩnh vực/Industry (nếu có field)

• Tags (VIP, Partner, Trial, v.v.)

• Email, SĐT

• VAT (Tax ID)

Nút thao tác:

• “Mở Contact” → mở Form res.partner trong Odoo (tab mới hoặc popup).

• “Xem trên vRoute” → mở Customer tương ứng trong vRoute (deep link, nếu đã có mapping).

2.3.2. Interaction History (Lịch sử tương tác)

Hiển thị:

• Danh sách hội thoại/tương tác trước đó của khách (theo thời gian), gồm:

  • Các phiên Odoo Live Chat/Discuss.

  • Ticket Helpdesk liên quan.

  • Các log/tương tác khác đã được sync về Odoo (ví dụ từ Zalo).

• Mỗi dòng history có:

  • Thời gian, loại kênh, tên Agent xử lý.

• Các Log Note/Internal Note quan trọng gắn với contact.

Nút/View:

• Quick Look xem nhanh nội dung (xem 2.4).

• Link “Xem thêm trên vRoute” (nếu vRoute có view tổng hợp riêng dựa trên data Odoo).

2.4. Quick Look (Xem nhanh hội thoại cũ)

• Khi Agent click vào 1 dòng lịch sử:

  • Hệ thống hiển thị pop-over hoặc expand ngay trong Sidebar với:

    • Ít nhất: nội dung chính (summary) hoặc full message của phiên đó.

  • Không reload trang, không đổi URL, không mất nội dung chat hiện tại.

2.5. Tích hợp vRoute ↔ Odoo (theo mô hình Odoo trung tâm)

2.5.1. Nếu khách chat trên vRoute

• vRoute đóng vai trò UI chat client.

• Với mỗi message khách/agent gửi ở vRoute:

  • vRoute gọi API/Controller của Odoo để:

    • Tạo hoặc reuse mail.channel tương ứng.

    • Ghi mail.message mới vào Odoo.

  • Odoo thực hiện toàn bộ logic:

    • Nhận diện khách (Smart Identification).

    • Lưu lịch sử, mapping với res.partner.

    • Xuất hiện trong Context Sidebar như các kênh khác.

2.5.2. Nếu khách chat qua Odoo Live Chat / Zalo

• Với Odoo Live Chat:

  • Odoo lưu message trực tiếp (native).

• Với Zalo:

  • Connector Zalo nhận message → gọi API vào Odoo để tạo mail.message/mail.channel.

  • Sau khi vào Odoo, được đối xử như message từ các kênh khác (đều là data chat trong Odoo).

3. UX/UI Guidelines

• Style: gọn, rõ, không phá vỡ UI Odoo; bám theo theme Odoo hiện có.

• Layout Desktop:

  • Cột trái: danh sách hội thoại.

  • Cột giữa: nội dung chat hiện tại.

  • Cột phải: Context Sidebar (Profile + History).

• Responsive:

  • Trên mobile: Sidebar ẩn mặc định, có nút icon (ví dụ “i” / “info”) để mở/đóng.

4. Acceptance Criteria (DoD)

1. Multi-channel → Odoo:

   • Dù khách chat trên:

     • Odoo Website,

     • vRoute,

     • Zalo,

       → tất cả message đều được lưu thành mail.channel + mail.message trong Odoo, có link với res.partner nếu nhận diện được.

2. Auto-Match (khách đã login):

   • Với user đã login, hệ thống lấy partner_id và:

     • Link phiên chat với đúng res.partner.

     • Sidebar hiển thị đầy đủ profile.

3. Auto-Match (fallback):

   • Với khách chưa login nhưng có email/phone/VAT:

     • Nếu tìm được duy nhất 1 partner → tự động link.

     • Nếu không → hiển thị “Khách lạ/Chưa lưu”, cho phép Create/Link nhanh.

4. Context Visibility:

   • Khi Agent mở hội thoại bất kỳ:

     • Sidebar hiển thị đúng Customer Profile.

     • Lịch sử tương tác được liệt kê đầy đủ trong Interaction History.

5. Zero Navigation for History:

   • Agent xem được nội dung phiên chat cũ qua Quick Look mà:

     • Không bị đổi màn hình.

     • Không mất nội dung chat hiện tại.

6. Odoo Persistence (rất quan trọng):

   • Dù kết nối với vRoute hay Zalo có lỗi:

     • Dữ liệu chat đã vào Odoo không bị rollback/mất.

     • Odoo luôn giữ vai trò nguồn dữ liệu chuẩn.

7. vRoute Integration (khi khách chat trên vRoute):

   • Message gửi từ UI vRoute xuất hiện trong Odoo Discuss/Helpdesk như các message bình thường.

   • Sidebar trong Odoo vẫn hoạt động đầy đủ với các message nguồn từ vRoute.

8. Performance:

   • Sidebar load dữ liệu < 1 giây trong điều kiện bình thường.

   • Việc load Sidebar không làm chậm trải nghiệm chat realtime.

9. Unit Test Performance (cho Dev):

   • Các unit test cho:

     • Logic nhận diện,

     • Mapping partner,

     • Gọi API Odoo/vRoute,

       không chạy quá 1 giây/case (với I/O được mock).

5. Exceptions (Ngoại lệ & xử lý)

6. Test Scenarios / Test Cases

Gợi ý: dùng các cột: TC ID, Title, Precondition, Steps, Test Data, Expected Result.

6.1. Multi-channel → Odoo

TC_MC_001 – Chat từ Odoo Website

• Precondition: Live Chat bật trên website; Odoo Discuss OK.

• Steps:

  1. Mở website Abivin, click Live Chat.

  2. Gửi message “Xin chào, tôi cần hỗ trợ”.

• Expected:

  • Tạo mail.channel mới.

  • Message (khách + agent) lưu thành mail.message.

  • Nếu login portal → channel link đúng res.partner.

TC_MC_002 – Chat từ vRoute Web

• Precondition: vRoute Web tích hợp API; user vRoute vroute_user_01 map với P002.

• Steps:

  1. Login vRoute Web bằng vroute_user_01.

  2. Mở màn hình chat support.

  3. Gửi message “Xe giao hàng gặp lỗi GPS”.

• Expected:

  • vRoute gọi API sang Odoo → tạo/reuse mail.channel.

  • Message lưu thành mail.message.

  • Channel link với P002.

  • Trong Odoo Discuss/Helpdesk thấy hội thoại đầy đủ.

TC_MC_003 – Chat từ Zalo

• Precondition: Connector Zalo hoạt động, mapping OA ↔ Odoo endpoint.

• Steps:

  1. Từ Zalo, khách gửi message “Hỗ trợ đơn hàng 123”.

• Expected:

  • Connector đẩy message vào Odoo, tạo/reuse mail.channel (theo Zalo thread).

  • Message lưu thành mail.message.

  • Nếu map được customer → link res.partner, nếu không → đánh dấu chưa định danh (Ex07).

6.2. Smart Identification

TC_ID_001 – Khách đã login (main flow)

• Precondition: res.users U001 có partner_id = P001; user đã login portal/vRoute.

• Steps:

  1. User login.

  2. Mở chat, gửi message bất kỳ.

• Expected:

  • Hệ thống dùng author_id/partner_ids để lấy P001.

  • Channel link với P001.

  • Sidebar hiển thị profile P001.

TC_ID_002 – Fallback: match duy nhất bằng email

• Test Data: dùng D_FB_01 (Nguyen A, customer@abivin.com).

• Precondition: chỉ có P002 dùng email customer@abivin.com.

• Steps:

  1. Khách (chưa login) mở chat.

  2. Nhập Name = Nguyen A, Email = customer@abivin.com.

  3. Gửi message.

• Expected:

  • Query res.partner theo email → P002.

  • Channel tự link với P002.

  • Sidebar hiển thị đúng thông tin P002.

TC_ID_003 – Ex01: khách vãng lai (Not Found)

• Test Data: dùng D_VISIT1 (Visitor X, unknown@abc.com).

• Precondition: không có partner nào dùng email/phone này.

• Steps:

  1. Khách mở chat, nhập D_VISIT1.

  2. Gửi message “Tư vấn giúp tôi giải pháp tối ưu vận tải”.

• Expected:

  • Query partner trả về rỗng.

  • Vẫn tạo mail.channel + mail.message.

  • Channel không có partner_id.

  • UI: label “Khách lạ / Chưa lưu” + nút “Create/Link Contact”.

TC_ID_004 – Ex02: Ambiguous (nhiều partner trùng)

• Test Data: dùng D_AMB_01 (email dup@abivin.com).

• Precondition: có P003 & P004 cùng email, P004 có write_date mới hơn.

• Steps:

  1. Khách (chưa login) nhập email dup@abivin.com.

  2. Gửi message.

• Expected:

  • Query trả về [P003, P004].

  • Code chọn P004 (rule: write_date mới nhất).

  • Log warning data trùng.

  • UI: hiển thị profile P004 + cảnh báo “Nhiều khách trùng thông tin”.

TC_ID_005 – Ex03: VAT không tra được nhưng email hợp lệ

• Test Data: dùng D_VAT_01 (vatuser@abivin.com, VAT ABC123INVALID).

• Precondition: P005 có email vatuser@abivin.com; kho VAT không có ABC123INVALID.

• Steps:

  1. Khách nhập email + VAT như trên.

  2. Gửi message.

• Expected:

  • Tra VAT lỗi → log “Không tra cứu được VAT”.

  • Không crash, fallback match bằng email → P005.

  • Channel link với P005.

  • Sidebar hiển thị profile P005; field VAT trống hoặc thông báo phù hợp.

6.3. Context Sidebar & Interaction History

TC_UI_001 – Hiển thị Customer Profile đầy đủ

• Precondition: P010 (any) có đầy đủ Name, Company, Country, Email, Phone, Industry, VAT, Tags; đã có ít nhất 1 phiên tương tác.

• Steps:

  1. Agent mở hội thoại với P010.

  2. Mở Context Sidebar.

• Expected:

  • Sidebar hiển thị đầy đủ các field.

  • Có nút “Mở Contact”, “Xem trên vRoute”.

TC_UI_002 – Interaction History + Quick Look

• Precondition: P010 có ≥ 1 phiên Live Chat, Ticket, log Zalo.

• Steps:

  1. Mở hội thoại với P010.

  2. Mở Sidebar → xem Interaction History.

  3. Click 1 item trong history.

• Expected:

  • Lịch sử liệt kê đầy đủ theo thời gian.

  • Click item → popup/expand show nội dung phiên cũ.

  • Không đổi URL, không reload, không mất nội dung chat hiện tại.

6.4. Exceptions hiển thị & tích hợp

TC_EX_004 – Ex04: Missing Fields (partner thiếu dữ liệu)

• Precondition: P006 chỉ có Name, các field khác trống.

• Steps:

  1. Mở hội thoại gắn với P006.

  2. Mở Sidebar.

• Expected:

  • Name hiển thị bình thường.

  • Field thiếu hiển thị trống/“…”

  • Không lỗi UI/exception.

TC_EX_005 – Ex05: Không load được lịch sử chat

• Precondition: mock API load history bị timeout/error.

• Steps:

  1. Agent mở hội thoại bất kỳ.

  2. Mở Sidebar.

• Expected:

  • UI: “Không tải được lịch sử, vui lòng thử lại”.

  • Chat realtime vẫn hoạt động bình thường.

TC_EX_006 – Ex06: vRoute không phản hồi khi push

• Precondition: mock API vRoute trả HTTP 5xx/timeout.

• Steps:

  1. Thực hiện action trong Odoo khiến push data sang vRoute.

• Expected:

  • Data trong Odoo không bị rollback/mất.

  • (Nếu có UI) hiển thị banner nhỏ “Không kết nối được vRoute”.

  • Event push được queue/retry; lỗi được log.

TC_EX_007 – Ex07: Dữ liệu Zalo thiếu/không chuẩn

• Precondition: connector Zalo chỉ gửi zalo_user_id, không có email/phone.

• Steps:

  1. Khách gửi message từ Zalo.

  2. Connector đẩy vào Odoo.

• Expected:

  • Odoo tạo mail.channel + mail.message.

  • Không match được partner → không gán partner_id.

  • History hiển thị label “Tương tác chưa định danh (Zalo)”.

6.5. Performance

TC_PERF_001 – Thời gian load Sidebar

• Precondition: khách có ≤ 50 phiên tương tác.

• Steps:

  1. Mở hội thoại.

  2. Click mở Sidebar, đo thời gian.

• Expected:

  • Sidebar load hoàn tất < 1 giây.

  • Chat realtime không bị lag rõ rệt.

7. Test Data (Dữ liệu mẫu)

7.1. res.partner

(Có thể thêm P007… nếu cần mapping đặc biệt.)

7.2. res.users

7.3. Input form chat (visitor/vRoute)

7.4. Zalo / vRoute

• Zalo sample:

  • zalo_user_id: ZALO_123456789

  • display_name: Zalo Customer X

  • Không có email/phone → dùng cho Ex07.

• vRoute sample:

  • vroute_user_id: vroute_user_01 (map U002 → P002)

  • Message: Xe giao hàng gặp lỗi GPS.

​