Bỏ qua nội dung
VNexus VNexus Requirement

Origin cố định, token tự đọc & phạm vi kích hoạt Extension

Feature URL
Module
browser-extension
Status
in-development
Priority
P2
Platforms
fe
AC progress
0 / 8
Last reviewed
2026-06-29

Mục tiêu

Mô tả cách extension được “khoá cứng” về môi trường và phạm vi hoạt động để luồng prefill chạy đúng và an toàn cho mục đích cá nhân. Khác với hướng cũ (có trang Options cho user tự nhập backend/token), bản hiện tại bỏ trang cấu hình: origin backend và FE được hardcode, access token tự đọc từ tab V-Nexus đang đăng nhập, và popup chỉ bật trên đúng trang quản lý tin của user.

Phạm vi

Trong phạm vi (In scope):

  • Origin cố định trong code (bản Staging): backend https://api-test.dainv.io.vn/api, FE https://vnexus-test.dainv.io.vn.
  • Phạm vi kích hoạt popup: chỉ bật khi tab ở URL bắt đầu bằng <FE origin>/user/my-listings; trang khác → icon bị disable, popup không mở.
  • Cơ chế tự đọc access token từ localStorage của tab V-Nexus đang đăng nhập (qua quyền scripting), không yêu cầu user dán token.
  • Ràng buộc host_permissions phải khớp: backend + FE origin + host sàn (muaban.net, chotot.com, nhatot.com).
  • Trang Options còn lại chỉ là trang thông tin tĩnh (hiển thị origin đang dùng), không đăng ký làm options_page và không có ô nhập liệu.
  • Ràng buộc/cảnh báo bảo mật: bản này là Staging, dùng cho cá nhân.

Ngoài phạm vi (Out of scope):

  • Trang Options cho user tự nhập backendBaseUrl / backendToken / vnexusOrigin — đã bỏ.
  • Đổi môi trường (test/local/prod) qua UI — phải sửa origin trong code rồi build lại.
  • Quản lý key tập trung và phân phối rộng qua Chrome Web Store.
  • Lưu secret thật vào tài liệu requirement này.
  • Luồng prefill và map field — xem extension-listing-prefill và extension-field-mapping.

User Stories

  • Là user cá nhân, tôi muốn extension trỏ sẵn đúng môi trường Staging mà không phải cấu hình gì.
  • Là user, tôi muốn extension tự lấy token từ phiên đăng nhập V-Nexus của tôi để khỏi dán JWT thủ công.
  • Là user, tôi muốn icon extension chỉ bật ở trang “Tin của tôi” để không bấm nhầm ở ngữ cảnh khác.
  • Là người quản trị bản build, tôi muốn đổi origin/môi trường bằng cách sửa code và build lại, đảm bảo host_permissions khớp theo.

Luồng chức năng

sequenceDiagram
    actor User
    participant Tab as Tab V-Nexus
    participant SW as Background Worker
    participant Cfg as Origin cố định trong code
    participant BE as V-Nexus BE

    User->>Tab: Mở trang /user/my-listings (đã đăng nhập)
    SW->>SW: Theo dõi URL tab, bật action khi khớp ACTIVE_URL_PREFIX, ngược lại disable
    User->>SW: Bấm prefill từ popup
    SW->>Tab: Đọc access token từ localStorage của tab (scripting)
    SW->>Cfg: Lấy backend base URL cố định
    SW->>BE: Gọi backend bằng token vừa đọc
    Note over SW,BE: Không có ô cấu hình — origin hardcode, token tự đọc theo phiên

Acceptance Criteria

  • AC-1: Backend base URL và FE origin được hardcode trong code (Staging), không có UI để user sửa.
  • AC-2: Extension không đăng ký options_page; trang Options nếu mở chỉ hiển thị thông tin origin đang dùng, không có ô nhập liệu.
  • AC-3: Icon/popup chỉ kích hoạt khi tab có URL bắt đầu bằng <FE origin>/user/my-listings; các trang khác icon bị disable và popup không mở.
  • AC-4: Khi cần gọi backend, extension tự đọc access token từ localStorage của tab V-Nexus đang đăng nhập.
  • AC-5: Không có luồng nào yêu cầu user dán token thủ công.
  • AC-6: host_permissions bao gồm backend origin + FE origin + host sàn (muaban.net, chotot.com, nhatot.com).
  • AC-7: Đổi origin/môi trường yêu cầu sửa code và cập nhật host_permissions cho khớp, rồi build lại.
  • AC-8: Không có secret thật nào được lưu trong tài liệu/cấu hình mẫu công khai.

Quy tắc nghiệp vụ

  • Origin backend + FE được cố định trong code; không còn cơ chế cấu hình runtime. Muốn đổi môi trường phải sửa code + host_permissions rồi build lại.
  • Access token không được lưu trong extension; nó được đọc tại thời điểm gọi từ localStorage của tab V-Nexus đang đăng nhập (các key token phổ biến: token, accessToken, jwt…), giảm rủi ro lộ token lưu lâu dài.
  • Popup chỉ hoạt động trên đúng trang quản lý tin (/user/my-listings); background worker chủ động enable/disable action theo URL của tab.
  • host_permissions phải khớp cả backend, FE origin và host sàn; sai host → extension không gọi được API hoặc content script không chạy.
  • Bảo mật: đây là bản Staging dành cho mục đích cá nhân. Vì token được đọc từ phiên của chính user nên quyền truy cập dữ liệu đúng bằng quyền của user đó. Muốn phân phối rộng, phải đưa các call nhạy cảm ra backend trung gian thay vì cho extension trực tiếp dùng token phiên.
  • Tài liệu này chỉ mô tả ràng buộc, không chứa giá trị secret thật.

Dữ liệu & Trạng thái

Entity nghiệp vụ:

  • FixedConfig: origin cố định trong code — backend base URL, FE origin, ACTIVE_URL_PREFIX (<FE origin>/user/my-listings).
  • HostPermissions: danh sách host được cấp quyền (backend + FE origin + host sàn).
  • ResolvedToken: access token đọc được từ tab V-Nexus tại thời điểm gọi (không lưu trữ).

Trạng thái user-facing:

  • active — tab ở đúng trang /user/my-listings, icon bật, sẵn sàng prefill.
  • inactive — tab ở trang khác, icon bị làm mờ, popup không mở.
  • token-resolved — đọc được token từ tab đang đăng nhập.
  • token-missing — không đọc được token (chưa đăng nhập / không truy cập được tab) → call backend có thể bị mask hoặc lỗi.
  • host-mismatch — host_permissions chưa khớp backend/origin/sàn, cần cập nhật trong code.

Liên quan