190 lines
8.8 KiB
Markdown
190 lines
8.8 KiB
Markdown
# 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 整合測** |
|
||
| T130–T149 | M2 OAuth／Job／FE live + **T136** |
|
||
| 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同意」） |