haixunMaster/extension/haixun-threads-sync/README.md

# 巡樓 Threads Session 同步（Chrome 擴充）

從你已登入的 Chrome Threads 帳號，一鍵把 session 傳到巡樓 Go 後端（`:8890`）。

## 安裝

**方式 A（推薦）**：巡樓「設定」頁 → **下載擴充套件（ZIP）** → 解壓後載入。

**方式 B**：直接選擇 repo 資料夾 `extension/haixun-threads-sync`。

1. Chrome 打開 `chrome://extensions`
2. 開啟「開發人員模式」
3. 點「載入未封裝項目」
4. 選擇解壓後的 `haixun-threads-sync` 資料夾

## 必要條件

- 後端 API 在跑：`make run`（預設 `http://127.0.0.1:8890`）
- 前端在跑：`make web-dev`（預設 `http://localhost:5173`）
- 已在 Chrome 登入 `threads.com` 或 `threads.net`
- 已在巡樓網頁登入（JWT 存在 localStorage）

## 使用方式 A：連線設定頁（推薦）

1. 開啟 `http://localhost:5173` 並登入
2. 頂部切換目標經營帳號
3. 到「帳號 → 連線設定」
4. 切換到 **開發模式（爬蟲）**
5. 確認顯示「擴充已偵測」
6. 按 **「從 Chrome 同步到目前帳號」**

> 關閉開發模式 = 全部走 Threads API，不需要同步 Chrome session。

## 使用方式 B：擴充圖示

1. 先開著巡樓分頁並登入
2. 點擴充圖示 →「同步到巡樓」
3. 擴充會自動讀取巡樓分頁的 JWT 與目前帳號

## 設定 server 網址

擴充選項填入**前端網址**（不是 8890），例如：

- 本機：`http://localhost:5173` 或 `http://127.0.0.1:5173`
- 遠端：`https://haixun.example.com`

儲存後會自動注入網頁橋接腳本。API 在本機 dev 時會自動改打 `:8890`。

## 常見問題

| 現象 | 原因與處理 |
|------|------------|
| 尚未偵測擴充 | 擴充安裝/更新後頁面不會自動注入腳本 → `chrome://extensions` 重新載入擴充，再 **F5 刷新巡樓頁** |
| 等待擴充逾時 | 巡樓網址與擴充選項不一致（`localhost` vs `127.0.0.1`）→ 統一用同一個，或在擴充選項重新儲存 |
| 找不到登入狀態 / JWT | 開錯網站：要用 **新版** `http://localhost:5173`（Go 後台），不是舊版 Next `:3000` |
| 無法連線後端 :8890 | 只開了 `make web-dev` 沒開 API → 另開終端執行 `cd haixun-backend && make run` |
| invalid access token | JWT 過期（15 分鐘）→ 在巡樓頁重新整理或重新登入後再同步 |
| 找不到 cookies | 先在 Chrome 開 threads.com / threads.net 完成登入，再同步 |
| 缺少帳號 ID | 在巡樓頂部切換經營帳號，或打開 `/threads/:id/connections` |
| 開發模式未開啟 | 連線頁底部「開發工具」要先 **開啟開發模式**，同步按鈕才會出現 |

## 技術說明

- 網頁透過 `postMessage` 與 `content-haixun.js` 溝通
- 擴充 background 收集 Threads/Instagram cookies，組成 Playwright `storageState`
- 呼叫 `POST /api/v1/threads-accounts/:id/session/import`（Bearer JWT）