# Plan: 巡樓後端（Phase C · live）

> Status: `approved`  
> Status note: **approved** 2026-07-10 使用者「好先這樣拆吧」  
> Source: `docs/product/haixun-backend/spec.md`（**approved** 2026-07-10 使用者「spec 通過」）  
> Last updated: `2026-07-10`

## 1. 交付策略

1. **先搬骨架再砍電商**：把 `stand-alone-service` 遷入主線（**根目錄固定 `apps/backend`**；gateway + 獨立 worker main 同包），收斂 **一份 etc**，建立 **cmd/init** 與 **cmd/seeder**。  
2. **先身份與權限可登**：數字 uid、admin 代建、完整 Auth API（含註冊／三方 API）、middleware；前端主路徑仍 admin 代建。  
3. **再 OAuth 真連帳**：P0 結束時必須有 usable Threads 帳號，不是假連線。  
4. **再創作＋Worker 真發送**：Play／Compose（含排程）→ Outbox → worker 打 Threads；驗收對齊 spec §9.12。  
5. **並行加深**：用量（platform／BYOK **分計分顯**）、人設、靈感研究、海巡雙路徑、邀請。  
6. **前端 live 接線**穿插在 M2 起：每完成一域就接 `createRepos('live')` 對應 repo，禁止整包最後才接。  

驗收一律對照 **spec §9** 的 ID（A-xx、AU-xx…）；task 完成定義須寫明覆蓋哪些 ID。

## 2. 里程碑

### M0 — 搬遷骨架與工程底座

- **目標：** 可編譯、可啟動的 go-zero gateway + 空 worker；單 etc；init／seeder 殼。  
- **完成定義：**  
  - `stand-alone-service` 已遷入主線並可 `go build`。  
  - 刪除或 build tag 排除 cart／order／product 等電商域。  
  - `etc/gateway.yaml` **僅一份**；env 可覆寫 secret。  
  - `cmd/init`（mongo index 可跑空轉或最小 ping）、`cmd/seeder` 獨立入口。  
  - 成功 envelope 統一 **102000**（若原碼不同則改）。  
- **建議 task 區間：** **T100–T109**  
- **驗證：** A-01～A-03、A-06～A-08 相關；`go test ./...` 通過或明確跳過舊電商測試。  

### M1 — 會員、權限、Admin、設定殼

- **目標：** 數字 uid 會員閉環；admin 代建；Auth API 齊（含註冊／三方介面）；設定讀寫＋平台 key 進 etc。  
- **完成定義：**  
  - Member model：數字 uid、roles、status、email_verified、invite_code 欄位預留。  
  - login／logout／refresh／me／profile／驗證／重設密碼。  
  - register + 三方 OAuth **API 可測**（UI 可不接）。  
  - Admin：listPage／create／suspend／roles／verify／resetPassword。  
  - Permission middleware：member vs admin。  
  - Settings get/save Ai／Placement（key 只 configured）；etc 平台 AI／Exa key 可注入。  
  - init 建立 member 相關 index；seeder 至少一 admin 帳。  
- **建議 task 區間：** **T110–T129**  
- **驗證：** §9.1 AU、§9.2 AR、§9.3 AP、§9.4 AO、§9.5 AD、§9.0 A-04/A-05、§9.8 ST-01～04/14～15。  

### M2 — Threads OAuth + Job/通知 + 前端 live 地基

- **目標：** 真 OAuth 綁帳；Job 狀態機 + worker 骨架；通知；前端可 live 登入／me／帳號列表。  
- **完成定義：**  
  - oauthStart／callback／list／refreshSession／disconnect；token 僅服務端。  
  - Job CRUD／進度／guarded 更新；worker 可跑 demo job。  
  - Notification list／read。  
  - `apps/web` live：Auth + Accounts + Jobs + Notifications 接真。  
- **建議 task 區間：** **T130–T149**  
- **驗證：** §9.6 TH-01～10、§9.7 JB-01～10、§9.17 X-*；前端 live 手測登入→OAuth。  

### M3 — 用量平台/BYOK + AI/Exa 代打

- **目標：** 外部 AI／搜尋可打；platform 扣點與 BYOK 次數 **分計分顯**。  
- **完成定義：**  
  - 金鑰解析 platform vs byok。  
  - UsageEvent + Summary：`platform.*` 與 `byok.*` 分欄；listEvents 可篩 key_mode。  
  - 產文／研究等至少一條真實外部呼叫路徑（失敗可讀）。  
  - 前端 Usage／Settings live 對齊分顯（若 mock 結構不同則擴充 summary 型別）。  
- **建議 task 區間：** **T150–T164**  
- **驗證：** §9.8 ST-05～13、§9.9 USG-01～14。  

### M4 — 創作、Outbox、Worker 真發送

- **目標：** Play／Compose（含 `schedule_start_at`）→ Outbox → **Threads 真發**。  
- **完成定義：**  
  - Personas CRUD + 分析（可 Job）。  
  - Plays save/submit；Compose publishSingle + 排程。  
  - Outbox list/get/retry/remove；worker 到點發送；root fail 規則。  
  - OwnPosts sync／sendReply、Mentions 基本狀態（真送）。  
  - 前端 Studio／Outbox live。  
- **建議 task 區間：** **T165–T189**  
- **驗證：** §9.10 PE、§9.11 PL、§9.12 OB、§9.13 OP。  

### M5 — 靈感／研究／媒體 + 海巡雙路徑

- **目標：** 靈感 session、Exa 研究、媒體；海巡 API＋爬蟲。  
- **完成定義：**  
  - Inspiration／Research／Media API。  
  - Scout brands/products/brief/scan/posts/outreach/homework。  
  - `dev_mode=false` → API 掃描；`true` → 爬蟲（擴充 session）。  
  - 前端 Scout／Inspire live。  
- **建議 task 區間：** **T190–T214**  
- **驗證：** §9.14 IN、§9.15 SC。  

### M6 — 邀請關係 + 收斂

- **目標：** 邀請碼、補填、admin 調歸屬；全站 live 煙測；文件與 seeder 補齊。  
- **完成定義：**  
  - Invite getMyNetwork／apply／admin tree/move。  
  - 前端 Invite live；uid 數字顯示。  
  - P0+P1 驗收表勾選；已知缺口列表。  
- **建議 task 區間：** **T215–T229**  
- **驗證：** §9.16 IV；回歸 AU/TH/OB/SC 抽樣。  

## 3. 依賴

```text
M0 骨架
 └─► M1 會員／Admin／設定殼
      └─► M2 OAuth + Job/通知 + FE live 地基
           ├─► M3 用量 + AI/Exa 代打（BYOK 分計）
           │    ├─► M4 創作 + 真發送
           │    │    └─► M5 靈感 + 海巡
           │    └─► M5（可與 M4 末重疊：海巡依賴帳號+設定+用量）
           └─► M6 邀請 + 收斂（依賴 M1 會員；可與 M5 平行後合併）
```

- **硬依賴：** M4 發送需要 M2 OAuth；M5 爬蟲需要 M1 dev_mode + 擴充 session 機制；M3 宜在大量 AI 呼叫前完成。  
- **可重疊：** M6 邀請可與 M5 後期平行（不同 module）。  

## 4. 風險與緩解

| 風險 | 緩解 |
|------|------|
| 搬 stand-alone 電商殘留拖慢 | M0 明確刪域清單；CI 不編譯舊 module |
| Threads OAuth／發文審核與限流 | M2/M4 用沙箱 App；OB 失敗可觀測；不擋其他 module 開發 |
| BYOK／平台計費混用 | M3 先定 summary schema 與 USG 測試；前端分顯 |
| 爬蟲 session 安全 | 僅 dev_mode；spec 開放題在 M5 定協議 |
| 範圍過大 | 嚴格 milestone 閘；M0–M2 未過不開 M4 真發送 |
| 前端 mock uid 字串 | live 層轉換或改前端型別（T 在 M2） |

## 5. 刻意不做（本 plan 週期內）

- 真實金流／發票（P2）  
- Insights 真管線、Islander agent  
- 前端公開註冊／三方 **頁面**（API 要做）  
- 多份 etc 環境檔  
- 字串 uid 主鍵  
- 以 simulate 當 live 發送完成  

## 6. 測試與驗收策略（v2 · 必做）

對齊 **spec §9（184 IDs）** 與 **§9.18**。詳見 `docs/product/haixun-backend/TESTING.md`。

1. **功能 task**：同 PR 至少最小 unit／handler case（名稱含 ID）。  
2. **里程碑 integration task**（fake 外部）：  
   - M0：T107 testkit、T108 CI  
   - M1：T119（AU/AR/AP/AO/AD）  
   - M2：T136（TH/JB）  
   - M3：T156（ST/USG）  
   - M4：T172（PE/PL/OB/OP，含 worker + fake Threads）  
   - M5：T196（IN/SC 雙路徑）  
   - M6：T219（IV）、T221（X）、T220（**FE↔BE live**）、T222（**184 矩陣閘**）、T218（smoke 補充）  
3. **禁止**：手測／只改 DB 冒充 TH-02／OB-02；mock 前端測不算 live。  
4. **M 完成定義** = 功能 task done **且** 該 M 的 test task 綠。

## 7. 全域驗證指令

```bash
# 後端（根目錄：apps/backend）
cd apps/backend
make test
make build
go run ./cmd/init -f etc/gateway.yaml
go run ./cmd/seeder -f etc/gateway.yaml

# 前端 build + FE↔BE 整合（T220）
cd apps/web && npm run build
LIVE_API_BASE=http://127.0.0.1:8888 npm run test:integration

# 煙測補充（T218）
bash scripts/smoke-p0.sh
bash scripts/smoke-p1.sh
```

## 8. Task 編號

| 區間 | 里程碑 |
|------|--------|
| T100–T109 | M0 骨架 + **testkit/CI** |
| T110–T129 | M1 會員／Admin／設定 + **T119 整合測** |

| T150–T164 | M3 用量／BYOK／AI·Exa + **T156** + ST-16 |
| T165–T189 | M4 創作／Outbox + **T172** |
| T190–T214 | M5 靈感／海巡 + **T196** |
| T215–T229 | M6 邀請 + **FE-BE／矩陣／煙測** |

正式清單：`tasks/INDEX.md`（**v3 · 59 tasks**：feat + test；**UI MUST + 真上傳 + Remove + `apps/backend`**）。

## 9. 批准

- [x] Plan 已批准（2026-07-10 / 使用者「好先這樣拆吧」）  
- [x] Tasks **v3** approved（2026-07-10 使用者「ok同意」）