16 KiB
16 KiB
Requirements: 巡樓後端（依 apps/web 接 live）
Status:
approved
Status note: 使用者 2026-07-10「需求 OK」
Slug:haixun-backend
Last updated:2026-07-10
輸入真相：apps/web現有畫面與 repository 介面；AGENTS.md；old/業務參考；stand-alone-service/後端基礎設施骨架
1. 一句話
把 Harbor Desk 前端已能用 mock 完成的操作，接到可長期維運的真後端與 worker（含 Threads OAuth、真實發文、海巡、邀請），讓 live 模式可上線使用。
2. 誰用、在什麼情境
| 角色 | 目標 |
|------|------|2jo4
| 一般會員（島民） | 登入後經營 Threads：OAuth 連帳、人設、創作串場、真發送、海巡、用量、邀請關係 |
| 管理員 | 代建島民、管權限／停權／方案、調邀請歸屬、系統設定 |
| 營運／實作者 | 依 stand-alone-service 風格骨架交付可部署的 API＋worker |
3. 背景與動機（As-is → 為什麼改）
- 現況問題： 前端 Phase B mock 完整；
live無真後端。 - 不改的後果： 無法上線；繼續堆 mock 無法驗證 OAuth／真發文／海巡。
- 參考（非需求本體）：
- 行為：
apps/web（repos／pages） - 契約精神：
AGENTS.md - 業務舊碼：
old/backend（海巡／Threads 模式可抄，不整包搬） - 基礎設施：
stand-alone-service/— 直接搬進主線再改造成巡樓 API（重點保留／改造 model 層；有 bug 或更好寫法可邊做邊修） - 邀請：
docs/product/invite-network/
- 行為：
4. 目標（To-be）
4.1 必須達成（P0）— 身份、帳號 OAuth、地基
- 會員身份
- 登入／登出／me／refresh；信箱驗證；重設密碼；改個人資料。
- 頁面：現階段不開公開註冊／三方 UI；營運以管理員代建為主。
- API：會員相關（含自助註冊、三方註冊／登入）功能要完整，供日後開頁或外部使用。
- 管理員島民管理：分頁搜尋、新增（回傳臨時密碼）、停權／復權、角色、驗證狀態、代重設密碼。
- Threads 經營帳號＝真 OAuth 優先
- 發起授權、callback 換 token、列表、連線狀態、刷新 session、解除綁定。
- 禁止「只登記假連線、永遠不 OAuth」當 P0 完成定義。
- Job 與站內通知：建立／查詢、進度與終態、通知列表／未讀／已讀。
- 系統設定：
- etc 系統級 AI／Exa key（平台代打）。
- 會員可填自己的 key → BYOK（見 spec 計費）。
- AI 單一 provider＋model（xAI｜OpenCode Go）；搜尋 Exa；開發模式；擴充 ZIP。
- 統一契約：UTC nano、envelope、分頁、權限錯誤；禁止未實作 API 回成功空資料。
- 前端 live：可打真後端；失敗不亂清 token。
4.2 應該有（P1）— 創作、真發送、海巡、邀請
- 人設：CRUD、active、文字／帳號分析（可 Job）。
- 互回方案 ThreadPlay：存檔、外部連結解析、提交進 Outbox。
- Outbox 真發送
- 列表／詳情、步驟狀態、重試、刪除。
- Worker 真實呼叫 Threads 發文／回覆（非僅模擬按鈕）；失敗可觀測、可重試；root 失敗不得誤標後續成功。
- 已發貼文／提及／單篇發布：同步、產文、真送回覆、略過。
- 靈感／研究／媒體：僅現 UI 版（趨勢 list/refresh、元素 CRUD、session、chat 產文）；Exa 研究、生圖／上傳。不做舊 list／viral／bookmark／spark 流。
- 用量與方案：本月摘要、事件、三檔方案、admin 代設、購買紀錄（付款可假成功）。
- 海巡 Scout（必做，雙路徑）
- 品牌／產品／brief／掃描命中／外展草稿與發送狀態。
- 行為對齊前端 mock＋參考
old/backend海巡／爬蟲／搜尋模式。 - 路徑分流（產品規則）：
- 開發模式關閉（預設）： 掃描／取樣走 Threads／官方 API（或產品既定 API 路徑）。
- 開發模式開啟： 允許／應使用 Chrome 擴充 session 爬蟲路徑（對齊前端擴充＋old 爬蟲能力）。
- 兩條路徑都要做；以會員設定的
dev_mode決定預設走哪條。
- 邀請關係（必做）
- 每人邀請碼；補填綁定（僅無邀請人）；會員看邀請人／直邀／延伸；管理員搜尋＋調歸屬（防環）。
- 用語：邀請人／直邀／延伸（不用上線／下線產品文案）。
4.3 以後再說（P2）
- 真實金流／發票、多租戶帳單。
- Insights 真數據管線、Islander agent。
- Extension 安全同步硬化、公開自助註冊（若未來要開）。
5. 範圍
In scope
- 依
apps/web能力交付真 API＋worker。 - 後端基礎設施：直接搬
stand-alone-service進主線再改造（非從零新骨架）。 - 撰寫方式必須走 go-zero 慣例（見 §6.1），不可自創另一套目錄／設定風格。
- Worker 獨立 binary：Outbox 真發送、Job（分析、同步、海巡掃描等）。
- 會員 JWT vs AI／Exa token 分離。
- 權限（permission）概念：至少區分一般會員／管理員能力；中介層與模組可對齊 stand-alone 的 auth／admin 模式並收斂到巡樓角色。
- 初始化與種子分開：Mongo index 等 init、資料 seeder 各成一包／獨立指令，不塞進 gateway 啟動主路徑胡亂混寫。
Out of scope（明確不做）
- 公開自助註冊（本階段）。
- 重做前端視覺大改。
old/backend整包當交付。- 未實作卻回成功空資料。
- 真實金流（P2）。
- 多份環境 etc 碎檔（見 §6：etc 只要一份）。
- 把會員 uid 改成字串 slug（如
user_demo）當主鍵語意——必須維持可讀的數字 uid。
6. 已鎖定決策（2026-07-10）
| # | 議題 | 決策 |
|---|---|---|
| 1 | 公開註冊 UI | 頁面先不做；主路徑仍 admin 代建。 |
| 1b | 會員 API | 完整提供（含註冊、三方登入等）；不因無頁而砍 API。 |
| 2 | Threads 綁帳 | 要先 OAuth（P0）。 |
| 3 | Outbox／回覆 | 真的送出（P1，非模擬完成）。 |
| 4 | 邀請＋海巡 | 都要做（P1）。海巡參考 old。 |
| 5 | 後端骨架 | 直接搬 stand-alone-service，改造成巡樓；重點在 model；bug／更好寫法邊做邊修或討論。 |
| 6 | Worker | 獨立 binary（與 gateway 分離）。 |
| 7 | 海巡路徑 | API＋爬蟲都要；未開 dev mode → 預設 API；開 dev mode → 可／應走爬蟲。 |
| 8 | 程式風格 | 一律 go-zero 方式撰寫／產生（.api → generate、handler／logic 分層等）。 |
| 9 | etc 設定 | 只要一份設定檔（例：etc/gateway.yaml）；環境差異用變數或單一檔內區塊，不要 gateway-dev／prod／nas 多份碎檔為交付常態。 |
| 10 | 會員 uid | 數字 uid（可讀、可排序、人眼能懂）；不可改成隨機字串主識別。前端 mock 的 user_* 字串在 live 應對齊後端數字 uid 契約。 |
| 11 | 權限 | 要有權限概念（member／admin 與後續可擴充）；API 中介層強制。 |
| 12 | 初始化 | Mongo index 等初始化寫成另外一包／獨立 cmd，不與業務 handler 混在一起。 |
| 13 | Seeder | 插入種子資料的 seeder 分開一包／獨立 cmd，與 index init 分離。 |
| 14 | AI／搜尋 key | etc 系統預設 key；會員有填＝BYOK，該 meter 不扣方案點仍記 event。 |
| 15 | 用量 | platform 扣 credits 並單獨統計；BYOK 另計次數並分開顯示，禁止與平台混成同一進度／總次數（見 spec §4.7）。 |
| 16 | 範圍原則 | 以現在 apps/web UI 主路徑為準（有畫面呼叫 = 後端 MUST；僅 mock／死碼 = 不做）。 |
| 17 | 靈感 | 舊靈感流完全捨棄；只做現 UI：trends／elements／session／chat。 |
| 18 | 死 API | Remove：generateFromFormula、ScoutTopic CRUD、舊 inspiration list/viral/bookmark/spark/searchTrends 等。 |
| 19 | 媒體附圖 | 真上傳（持久可取 URL）；不得以本機-only data URL 當 live 完成。 |
| 20 | Insights | 維持 P2（本階段不做真 Insights 管線）。 |
| 21 | 前端 uid | API 為數字；FE 顯示／狀態可用字串化，不得把 user_* 當後端主鍵契約。 |
6.1 go-zero 與目錄（需求層約束，非完整實作步驟）
- API 以 go-zero
.api定義 為源，經 generate 產出路由／types 骨架；業務寫在 logic／module。 - 分層大致：
generate/api→handler→logic→module（domain／repository）→svc。 - 禁止為圖省事繞過 go-zero、手寫一整套私有 router 風格當主路徑。
- etc：交付只維護一份主設定（開發／正式差異用 env 覆寫或文件說明，不複製多份 yaml 當常態）。
6.2 身份識別（uid）
- 系統內會員主識別為 數字 uid（與 stand-alone-service「可產生、可讀」方向一致，禁止難讀隨機字串當主 uid）。
- 登入帳號仍用 email；對外 API／管理畫面以數字 uid 為準。
- 前端 live 接線時，mock 的
user_demo類字串 不得成為後端契約；spec 階段對齊型別。
6.3 初始化與 Seeder（分開）
| 包／指令（名稱 plan 再定） | 職責 |
|---|---|
| init／migrate 類 | Mongo index、必要 schema 約束、集合準備 |
| seeder 類 | 插入示範／管理員種子、選用 demo 資料 |
| gateway／worker 啟動 | 不負責 bulk seed；至多檢查連線 |
兩者必須可分開執行、可重複跑時行為可預期（idempotent 精神進 spec）。
7. 使用者故事（可驗收）
P0
| ID | 作為… | 我想要… | 以便… | 驗收要點 |
|---|---|---|---|---|
| US-01 | 島民 | email／密碼登入與會話 | 進／app | live 登入；me 持久；錯誤可讀 |
| US-02 | 島民 | 驗證信箱、重設密碼、改資料 | 帳號可用 | 驗證閘對齊前端；改信箱重驗證 |
| US-03 | 管理員 | 代建與管理島民 | 無公開註冊也能加人 | 臨時密碼一次顯示；停權不可登；保留至少一 admin；數字 uid 可見 |
| US-08 | 系統 | 依權限擋 API | 非 admin 不能管島民 | 無 permission 回可讀錯誤 |
| US-04 | 島民 | OAuth 綁定 Threads | 真連帳 | 授權完成後列表出現 usable 帳號；token 安全保存；可刷新／解除 |
| US-05 | 系統 | Job＋通知 | 知背景結果 | 狀態機合法；終態有通知 |
| US-06 | 島民 | AI／Exa／開發模式設定 | 後續能力 | key 不回顯；換 provider 有模型清單 |
| US-07 | 前端 | live 打真 API | 離 mock | 未實作＝明確錯誤 |
P1
| ID | 作為… | 我想要… | 以便… | 驗收要點 |
|---|---|---|---|---|
| US-10 | 島民 | 人設 CRUD／分析 | 產文像我 | 可落庫；active |
| US-11 | 島民 | 互回方案→Outbox | 排程發串 | 發言池規則對齊前端 |
| US-12 | 島民 | Outbox 真發到 Threads | 真實上線 | 步驟 published 對應平台成功；失敗可重試；root fail 不誤標 reply |
| US-13 | 島民 | 同步貼文／提及／真回覆 | 日常 | 同步可列表；送出真上平台 |
| US-14 | 島民 | 靈感／研究／媒體 | 開題 | session 可續；研究有來源 |
| US-15 | 島民／admin | 用量與方案 | 控成本 | 點數；admin 代設 |
| US-20 | 島民 | 海巡 brief＋掃描＋外展 | 找機會 | 命中列表；狀態可更新；關 dev→API；開 dev→爬蟲 皆可驗收 |
| US-21 | 島民 | 邀請碼＋補填＋直邀 | 關係 | 無邀請人可綁一次；已綁不可自改 |
| US-22 | 管理員 | 調邀請歸屬 | 糾錯 | 防環；路徑正確 |
8. 成功標準
- 無公開註冊；admin 可代建並登入。
- P0：live OAuth 完成至少一 Threads 帳號 且 me／Job／通知可用。
- P1：至少一條 方案→Outbox→Threads 平台上可見發文／回覆（真發送）。
- P1：海巡可完成一輪 brief→掃描→命中列表；dev off＝API、dev on＝爬蟲 各至少一條可驗收路徑；邀請可補填與管理歸屬。
- 未實作能力不得假成功。
- 時間 UTC nano；JWT 與 provider key 分離。
- 後端以 搬入並改造的 stand-alone-service 為骨架；獨立 worker binary 存在。
- go-zero 風格；etc 僅一份主設定。
- 會員 數字 uid；權限中介層生效。
- index init 與 seeder 分包裝、可獨立執行。
9. 約束與假設
- 約束：
AGENTS.md契約精神。- 新交付不在
old/。 - 基礎設施：直接搬
stand-alone-service進主線並改造成巡樓；電商域刪除；model 優先；可修 bug／改寫。 - 撰寫＝go-zero 方式（
.apigenerate、handler／logic 分層）。 - etc 只要一份（不維護多份 gateway-*.yaml 為常態）。
- uid＝數字，可讀；不做字串主鍵改造。
- 權限概念必有（member／admin 起）。
- init（含 mongo index） 與 seeder 分開兩包／兩指令。
- Worker 獨立 binary。
- 海巡／Threads 可參考
old/backend，契約以新前端為準。 - 前端 mock｜live 同一 repos 介面；live 時 uid 契約對齊數字。
- 假設：
- 單租戶
default先夠用。 - Threads App 金鑰由環境提供。
- 購買方案可先假付款；真金流 P2。
- stand-alone 的 member／token／permission 模式可重用並裁剪。
- 單租戶
10. 風險
| 風險 | 影響 | 緩解 |
|---|---|---|
| OAuth＋真發文＋海巡同進 P0/P1 | 工期長 | P0 只鎖 OAuth＋地基；真發文／海巡／邀請在 P1 但仍必做 |
| stand-alone-service 電商殘留 | 噪音、誤用 | 刪除 cart／order／product；保留 member／token／permission／mongo 模式 |
| etc 多檔環境漂移 | 難維運 | 只留一份主 yaml＋env |
| 字串 uid 難讀／與前端 mock 混用 | 除錯痛 | 堅持數字 uid；前端 live 對齊 |
| old 海巡與新前端語意差 | 行為漂移 | spec 以 apps/web 為準，old 只供演算法／爬蟲 |
| Threads API 變更／限流 | 發送失敗 | 錯誤進 Outbox／Job；可重試 |
| 密鑰外洩 | 資安 | 分離儲存；禁止 log 明文 |
11. 開放問題（剩餘）
（原 1–3 已鎖定，見 §6。）
- 搬入後目錄命名：已定
apps/backend（由stand-alone-service遷入改造；非services/api）。 - Threads App／爬蟲帳號與金鑰的環境變數清單— spec／plan 列配置項。
12. 前端能力對照
| 域 | 前端 | 波次 |
|---|---|---|
| Auth／Profile（無公開註冊） | Login, Profile… | P0 |
| Admin 島民 | AdminUsersPage | P0 |
| Crew 帳號 OAuth | CrewPage | P0 |
| Jobs／通知 | Jobs, bell | P0 |
| Settings | SettingsPage | P0 |
| 人設 | Crew personas | P1 |
| Studio／Outbox 真發送 | Studio, Outbox | P1 |
| 已發／提及 | OwnPosts, Mentions | P1 |
| 靈感／研究／媒體 | Inspire… | P1 |
| 用量／方案 | Usage, Plans | P1 |
| ji3 | 海巡／品牌 | Scout, Brands |
| 邀請關係 | InvitePage | P1 |
| Insights | InsightsPage | P2 |
13. 批准
- 需求已批准（2026-07-10 / 使用者「需求 OK」）：
決策 1–7 已全部鎖定。
若整體沒問題，請回 「需求 OK」 → 下一回合寫 spec.md（行為契約、狀態機、搬 stand-alone-service 的 Retain-Replace-Remove、海巡 dev 分流）→ 再 plan → 再拆 task。