daniel.w
/
thread-master
1
0
Fork 0
Code Issues Pull Requests 1 Packages Projects Releases Wiki Activity
thread-master/docs/product/haixun-backend/plan.md

8.8 KiB
Raw Permalink Blame History

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. 依賴

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. 全域驗證指令

# 後端（根目錄：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. 批准

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