15 KiB

Raw Blame History

Requirements: 巡樓 Console（整包重構）

Status: approved
Slug: haixun-console
Last updated: 2026-07-09
批准：使用者確認 OK（2026-07-09）
策略：舊碼整包封存 old/；主線從零重寫；先地基 → 前端 mock → 再接後端；文案含多帳號互回
變更：reply 步驟可選 lead（主帳可接續回覆）

1. 一句話

用 Grok 4.5 重構巡樓工作台：先把登入、Threads 串接、Job、通知、權限等地基做對；前端用全新流程與視覺 + 假資料把操作順到你滿意，再補真實後端與業務，避免在舊混亂上疊功能。

2. 誰用、在什麼情境

角色	目標
經營者	綁多個 Threads、產文案（主帳+配角互回）、海巡外展、排程發文；看任務與通知
管理員	建會員、管權限（封閉 beta）
（系統）Worker	長任務執行並回報進度

3. 背景與動機

為什麼要重構（不是小修）

現況前後端半成品交織：假成功 API、幽靈 worker、巨型頁、文件漂移 → 在舊樹上修會繼續亂。
你希望流程與風格都重想；業務好不好用要先用手走完，不是先堆後端。
交付方式：舊 monorepo 已封存至 old/，根目錄從零建立 apps/web、services/* 等；old/ 只讀參考。

參考（非最終規格）

封存：old/backend/、old/docs/、old/AGENTS.md
產品：docs/product/haixun-console/

4. 交付策略（怎麼重構）— 硬性順序

Phase A  地基（最小可用平台）
    → Phase B  新前端 + Mock（流程與風格定稿）
        → Phase C  後端接真（替換 mock，同一套 UI）
            → Phase D  業務加深（海巡、進階互回、成效…）

Phase	目標	完成定義（產品語言）
A 地基	平台能站起來	登入會話可用；權限可擋路由；Threads 帳號能綁/能呼叫 API（或明確 mock 開關）；Job 能建立/查狀態/通知；無假成功
B 前端 Mock	操作順、好看	全主要流程用假資料可點完；你認可 IA + 視覺；API 層可切 `mock
C 接後端	假資料變真	同一 UI，逐頁/逐域替換 live；契約與 mock 對齊
D 業務加深	護城河	海巡閉環、進階互回/AI 分角、護欄與成效等

原則：

B 未通過前，不開大範圍業務後端（避免又寫一堆用不到的 API）。
A 只做「所有業務都會用到的管子」，不做完整海巡/完整矩陣。
新碼只在根目錄新結構；不在 old/ 上繼續開發。
舊 monorepo 已封存於 old/（2026-07-09）。

5. 目標分級

5.1 P0-A — 地基（平台）

登入與會話
email/password 登入、logout、refresh；未登入不可進主殼。
（封閉註冊：admin 建號或 seed；公開註冊非 P0。）
權限
至少：已登入會員 vs admin；前端路由與關鍵操作可依角色顯示/阻擋；後端同語意。
Threads API 串接完成（基礎）
- 綁定帳號（OAuth 或文件化的連線方式）
- 列表已綁帳號、連線健康/錯誤可讀
- 具備「用指定帳號打 Threads API」的統一出口（發文/回覆可先最小 smoke，完整業務在 C/D）
Job 系統（最小）
建立任務、查列表/詳情、狀態（queued/running/succeeded/failed/cancelled）、進度摘要。
Notification（任務通知）
任務完成/失敗時，Console 內可感知（鈴鐺列表或 toast + 可點進 job）；不要求 email/push 推播為 P0。
契約底線
JSON envelope、錯誤可讀、時間 UTC nano（後端）、禁止 stub 回成功。

5.2 P0-B — 新前端 + Mock（你要先滿意的部分）

全新資訊架構與視覺（見 §8），不沿用「掌機側欄 + 巨型單頁」當預設。
Mock 驅動的完整主流程（假資料也要真實感）：
- 登入殼 → 總覽（今日待辦）
- 帳號（多 Threads）
- 發文計畫 / 串場（主題 → 主帳+cast → 草稿串 → 預覽 → 排程預覽）
- 出站佇列（Outbox）狀態
- 任務與通知中心
- 設定（AI key 可先 UI only）
多帳號互回（流程先做對）
- 主帳號 lead 1 個：負責樓主貼（root）
- cast 多選：本串可出場的其他帳號
- 發言池 = lead ∪ cast：每一則「回覆步驟」都可指定池內任一帳號，包含 lead
  （例：lead 發主貼 → cast 帳回 → lead 再回那則 → 另一 cast 再接）
- 單線接龍步驟可編輯、可預覽「誰說什麼」
- Mock 發布過程：逐步狀態動畫/列表即可
雙模式資料層
dataSource: mock | api；B 預設 mock；切 api 時契約不變。
RWD：手機可走完核心流（不必完美，但不可壞掉）。

5.3 P0-C — 接後端（在 B 過關後）

Auth / me / permissions 接真。
Threads 帳號與 OAuth 接真。
Job + 站內通知接真。
發文計畫 / 互回草稿 / 佇列逐步接真（可按垂直切片：先單帳發文，再互回）。

5.4 P1 — 業務加深

海巡：品牌 → 主題 → 掃描 → 外展草稿。
互回進階：AI 分角色產整串、間隔/護欄 per-account、失敗單步重試完善。
提及收件匣、成效儀表。
Job 可靠度硬化（dedupe/heartbeat 等）。
Email 驗證閘道（若仍需要）。

5.5 P2

公開註冊、Islander agent、extension 安全同步、大型多租戶計費等。

6. 範圍

In scope

從零重寫（舊碼在 old/ 封存，主線新樹）。
地基：Auth、Permission、Threads 基礎串接、Job、站內 Notification。
全新前端體驗 + mock 業務流（含多帳互回）。
之後同一套 UI 接後端。
產品文件：docs/product/haixun-console/ 為決策真相。

多帳號互回 — 行為邊界

項目	P0 要	P0 不要
lead	必選 1 個；root 固定 lead；也可在 reply 再出場	主帳只能發主貼、不能回後續
cast	多選其他帳；與 lead 組成發言池	跨會員借號
reply 發言者	lead 或任一 cast（主帳可回別人的回覆）	僅 cast 能回
串結構	單線接龍：每步接上一步	樹狀多分支（以後再說）

Out of scope（本重構週期明確不做）

在 old/ 或舊 UI 上繼續疊功能當最終產品。
把 old/ 整包「搬回」當新主線而不重寫。
復原舊 copy_mission 五段 worker 管線。
自動 refill 庫存 bot、公開自助註冊、MFA、Zitadel。
重型 UI 框架（MUI/Ant/Chakra）。
任天堂 / Nook 元素、emoji 當主圖示。
把海巡與互回做成同一套語意。
未綁定帳號、跨會員借號。
B 階段沒過就大寫海巡/矩陣後端。

7. 使用者故事

地基

ID	作為…	我想要…	以便…	驗收
US-A1	經營者	登入並維持會話	進工作台	登入進主殼；logout 後不可進
US-A2	經營者	依權限看到該看的選單	不誤操作	無 permission 時入口隱藏或 403
US-A3	經營者	綁定並看到 Threads 帳號狀態	後續發文有對象	列表可見；錯誤可讀
US-A4	經營者	看背景任務狀態與完成通知	知道跑完沒	job 列表；完成/失敗有通知可點

前端 Mock / 文案流

ID	作為…	我想要…	以便…	驗收
US-B1	經營者	在新 UI 上走完「今日 → 開一個發文計畫」	覺得流程順	mock 下無卡死、步驟清楚
US-B2	經營者	指定主帳 + 選其他帳互回，且 lead 也可再回後續留言	多號串場、主帳能接話	每句顯示帳號；reply 步驟可選 lead 或 cast；預覽順序正確
US-B3	經營者	在 Outbox 看到這串的排程狀態	掌握發送	mock 狀態流轉合理
US-B4	經營者	從通知跳到對應任務或計畫	減少找頁	一鍵到達

接真後（C）

ID	作為…	我想要…	以便…	驗收
US-C1	經營者	同一套畫面改打真 API 仍可用	上線	mock/api 契約一致；關鍵流 live 通過

8. 新前端：流程與風格方向（提案，待你選/改）

現況問題（簡述）：導覽像「很多 App 格」但主線不清；單頁過重；視覺偏玩具掌機，專業經營感不足；海巡/文案/發布心智模型混。

8.1 產品隱喻（建議）

「泊岸工作台 Harbor Desk」 — 不是掌上遊戲機，而是靠港調度台：

今天要出港的內容（發文/互回）
船隊帳號（多 Threads）
遠航探查（海巡，P1）
船期與回報（Outbox + Jobs + 通知）

語氣：年輕、清楚、短句；可留「島」「巡」詞，但 UI 不要雲朵滿版搶戲。

8.2 資訊架構（建議導覽）

最多 5 個主入口（桌面側欄 + 手機底欄）：

入口	做什麼
今日 Today	待發、失敗需處理、進行中 job、快捷「開新串」
帳號 Crew	綁定/健康/選預設主帳
創作 Studio	發文計畫 wizard + 草稿庫（多帳互回在這裡）
探查 Scout	海巡（P1 再滿血；B 可放空狀態說明）
發送 Outbox	佇列、歷史、護欄狀態

全域： 頂欄右側 = 通知鈴 + 主題 + 使用者選單（設定/登出）。
不做： 十幾個 App tile、Jobs/Gaps 當一級又難找又佔位（Jobs 併入通知與 Today）。

8.3 創作主流程（Studio wizard，B 階段就要順）

1. 主題      一句話 + 可選「幫我想」
2. 船隊      選 lead（主帳）+ cast（其他可出場帳，可多選）
3. 劇本      單線步驟：第 0 步 root=lead；之後每步 = **發言池內帳號（含 lead）** + 文案
4. 預覽      像 Threads 對話泡泡；可見 lead 穿插回覆
5. 船期      主貼時間 + 回覆間隔
6. 提交      進 Outbox（mock 狀態：排程中 → 發送中 → 完成/失敗）

任一兩可回上一步；每步自動存 draft（mock localStorage 即可）。

8.4 視覺方向（建議，可整包替換舊 hx-scene）

面向	建議
調性	安靜專業 + 一點溫度：偏「設計工具 / 編輯台」，不是遊戲 HUD
色彩	深 slate 字 + 暖白紙面 + 單一 brand（建議霧青/海色 `#2A9D8F` 系）；深淺主題都走 token
字體	維持 Inter + Taipei Sans TC（閱讀與中文標題夠用）
版面	左窄導覽（icon+字）+ 右內容；不要固定超寬掌機外框
卡片	1px 細邊、中等圓角（12–16px）、輕陰影；少裝飾 blob
動效	僅頁面切換與列表 150–200ms；不搶操作
圖示	原創線條 SVG 一套即可；禁止 emoji 當主 icon
密度	表單與表格可讀優先；中文 line-height ≥ 1.6

明確告別： 舊「奶油票券 + 滿天雲 + PATROL PAD 掌機」作為預設殼（若你仍想保留可作「懷舊主題」P2，不當預設）。

8.5 Mock 資料原則

預置 2–3 個假 Threads 帳號（不同顯示名/頭像色）。
預置 1 條進行中 job、1 條失敗通知。
預置 1 份範例互回劇本：root(lead) → reply(cast) → reply(lead)（示範主帳接話）。
所有列表可空狀態插畫/短文案，不空白死頁。

9. 成功標準

Phase A

US-A1～A4 在「真後端或契約完整 mock server」下可演示。
無對外 stub 成功 API。

Phase B（你主觀過關為準）

你親自走完 Studio 互回 wizard + Outbox + 通知，認為流程順、風格可接受。
能做出 root(lead) → reply(cast) → reply(lead) 並預覽/進 Outbox。
主 IA ≤ 5 個一級入口；無巨型單頁不可維護感（單檔建議有分頁/步驟元件）。
mock | api 可切換架構已就位（api 可暫時 501，但不能亂成功）。

Phase C

登入、帳號、job/通知、至少「單串發文或 mock 同等」一條 live 路徑。
同一 UI 不需重畫。

全域

產品決策以本文 + 後續 spec/plan/tasks 為準。

10. 約束與假設

重構工具： 以 Grok 4.5 / 本 repo agent 為主；/spec-driven 管文件閘門。
可重寫 monorepo；舊碼是零件庫與行為參考。
後端契約精神可保留（envelope、JWT 分離、job 狀態機），實作可新建。
前端： 輕量 React + Vite（或同等）；不引入重型 UI kit；新 design token 允許全新一輪命名。
假設： B 階段你會參與 1～2 輪流程/視覺拍板，否則 mock 白做。
假設： Threads App 憑證在接 C 時可取得。
互回： 僅自有已綁帳號；P0-B 單線接龍；reply 發言池含 lead（主帳可回別人的回覆）。

11. 風險

風險	緩解
重寫範圍爆炸	死守 A→B→C→D；B 過關才加深後端
Mock 與真 API 契約漂移	先定 thin types / MSW 或 mock 模組與未來 API 同 shape
視覺改了又改	B 只定一套預設主題；大改須改 requirements/spec
舊資料/舊 job 遷移	C 再定；B 不承諾遷移
多帳互回後端複雜	B 只鎖 UX；C 垂直切片接真

12. 開放問題（請你拍板）

重寫落點： ~~二選一~~ → 已決策：舊碼進 old/；新前端 apps/web；新後端另建（如 services/api），不從舊樹原地改。
登入是否要 email 驗證才能進？ 預設：A 可先關，P1 再開。
視覺提案「Harbor Desk」是否當預設？ 若否，請給 3 個形容詞（例如：極簡黑白 / 編輯器感 / 更活潑）。
Scout（海巡）在 B 階段： 完全隱藏，還是放「即將推出」空頁？預設：空頁占位，免導覽以後大改。
Mock 持久化： 僅 memory，還是 localStorage 跨重新整理？預設：localStorage。

13. 附錄：與舊需求的差異（摘要）

舊	新
不在舊樹上重寫 monorepo	允許整包重構/重寫
海巡/文案/發布 P0 一次閉環	先 A 地基 + B 前端 mock，再 C 接真
沿用田園掌機 UI	新 IA + Harbor Desk 風格提案
多帳互回（已納入）	保留，且 B 階段就要流程順

14. 批准

需求已批准：2026-07-09（使用者 OK；採預設：apps/web、Harbor Desk、海巡空頁、email 驗證 A 先關、mock localStorage）
下一步：審核 spec.md → 回 spec OK 後寫 plan

15 KiB Raw Blame History Unescape Escape