332 lines
15 KiB
Markdown
332 lines
15 KiB
Markdown
# 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. 交付策略（怎麼重構）— 硬性順序
|
||
|
||
```text
|
||
Phase A 地基（最小可用平台）
|
||
→ Phase B 新前端 + Mock（流程與風格定稿）
|
||
→ Phase C 後端接真（替換 mock，同一套 UI）
|
||
→ Phase D 業務加深（海巡、進階互回、成效…）
|
||
```
|
||
|
||
| Phase | 目標 | 完成定義（產品語言） |
|
||
|-------|------|----------------------|
|
||
| **A 地基** | 平台能站起來 | 登入會話可用；權限可擋路由；Threads 帳號能綁/能呼叫 API（或明確 mock 開關）；Job 能建立/查狀態/通知；**無假成功** |
|
||
| **B 前端 Mock** | 操作順、好看 | 全主要流程用假資料可點完；你認可 IA + 視覺；API 層可切 `mock | live` |
|
||
| **C 接後端** | 假資料變真 | 同一 UI，逐頁/逐域替換 live；契約與 mock 對齊 |
|
||
| **D 業務加深** | 護城河 | 海巡閉環、進階互回/AI 分角、護欄與成效等 |
|
||
|
||
**原則：**
|
||
|
||
1. **B 未通過前，不開大範圍業務後端**（避免又寫一堆用不到的 API）。
|
||
2. A 只做「所有業務都會用到的管子」，不做完整海巡/完整矩陣。
|
||
3. 新碼只在根目錄新結構；**不在 `old/` 上繼續開發**。
|
||
4. 舊 monorepo **已封存**於 `old/`（2026-07-09）。
|
||
|
||
---
|
||
|
||
## 5. 目標分級
|
||
|
||
### 5.1 P0-A — 地基（平台）
|
||
|
||
1. **登入與會話**
|
||
email/password 登入、logout、refresh；未登入不可進主殼。
|
||
（封閉註冊：admin 建號或 seed；公開註冊非 P0。）
|
||
2. **權限**
|
||
至少：已登入會員 vs admin；前端路由與關鍵操作可依角色顯示/阻擋；後端同語意。
|
||
3. **Threads API 串接完成（基礎）**
|
||
- 綁定帳號（OAuth 或文件化的連線方式）
|
||
- 列表已綁帳號、連線健康/錯誤可讀
|
||
- 具備「用指定帳號打 Threads API」的統一出口（發文/回覆可先最小 smoke，完整業務在 C/D）
|
||
4. **Job 系統（最小）**
|
||
建立任務、查列表/詳情、狀態（queued/running/succeeded/failed/cancelled）、進度摘要。
|
||
5. **Notification（任務通知）**
|
||
任務完成/失敗時，Console 內可感知（鈴鐺列表或 toast + 可點進 job）；不要求 email/push 推播為 P0。
|
||
6. **契約底線**
|
||
JSON envelope、錯誤可讀、時間 UTC nano（後端）、**禁止 stub 回成功**。
|
||
|
||
### 5.2 P0-B — 新前端 + Mock（你要先滿意的部分）
|
||
|
||
1. **全新資訊架構與視覺**（見 §8），不沿用「掌機側欄 + 巨型單頁」當預設。
|
||
2. **Mock 驅動的完整主流程**（假資料也要真實感）：
|
||
- 登入殼 → 總覽（今日待辦）
|
||
- 帳號（多 Threads）
|
||
- **發文計畫 / 串場**（主題 → 主帳+cast → 草稿串 → 預覽 → 排程預覽）
|
||
- 出站佇列（Outbox）狀態
|
||
- 任務與通知中心
|
||
- 設定（AI key 可先 UI only）
|
||
3. **多帳號互回（流程先做對）**
|
||
- 主帳號 **lead** 1 個：負責樓主貼（root）
|
||
- **cast** 多選：本串可出場的其他帳號
|
||
- **發言池 = lead ∪ cast**：每一則「回覆步驟」都可指定池內**任一帳號**，**包含 lead**
|
||
（例：lead 發主貼 → cast 帳回 → **lead 再回那則** → 另一 cast 再接）
|
||
- 單線接龍步驟可編輯、可預覽「誰說什麼」
|
||
- Mock 發布過程：逐步狀態動畫/列表即可
|
||
4. **雙模式資料層**
|
||
`dataSource: mock | api`；B 預設 mock；切 api 時契約不變。
|
||
5. **RWD**：手機可走完核心流（不必完美，但不可壞掉）。
|
||
|
||
### 5.3 P0-C — 接後端（在 B 過關後）
|
||
|
||
1. Auth / me / permissions 接真。
|
||
2. Threads 帳號與 OAuth 接真。
|
||
3. Job + 站內通知接真。
|
||
4. 發文計畫 / 互回草稿 / 佇列逐步接真（可按垂直切片：先單帳發文，再互回）。
|
||
|
||
### 5.4 P1 — 業務加深
|
||
|
||
1. 海巡：品牌 → 主題 → 掃描 → 外展草稿。
|
||
2. 互回進階：AI 分角色產整串、間隔/護欄 per-account、失敗單步重試完善。
|
||
3. 提及收件匣、成效儀表。
|
||
4. Job 可靠度硬化（dedupe/heartbeat 等）。
|
||
5. 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 階段就要順）
|
||
|
||
```text
|
||
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. 開放問題（請你拍板）
|
||
|
||
1. **重寫落點：** ~~二選一~~ → **已決策：舊碼進 `old/`；新前端 `apps/web`；新後端另建（如 `services/api`），不從舊樹原地改。**
|
||
2. **登入是否要 email 驗證才能進？** **預設：A 可先關，P1 再開。**
|
||
3. **視覺提案「Harbor Desk」是否當預設？** 若否，請給 3 個形容詞（例如：極簡黑白 / 編輯器感 / 更活潑）。
|
||
4. **Scout（海巡）在 B 階段：** 完全隱藏，還是放「即將推出」空頁？**預設：空頁占位，免導覽以後大改。**
|
||
5. **Mock 持久化：** 僅 memory，還是 localStorage 跨重新整理？**預設：localStorage。**
|
||
|
||
---
|
||
|
||
## 13. 附錄：與舊需求的差異（摘要）
|
||
|
||
| 舊 | 新 |
|
||
|----|-----|
|
||
| 不在舊樹上重寫 monorepo | **允許整包重構/重寫** |
|
||
| 海巡/文案/發布 P0 一次閉環 | **先 A 地基 + B 前端 mock，再 C 接真** |
|
||
| 沿用田園掌機 UI | **新 IA + Harbor Desk 風格提案** |
|
||
| 多帳互回（已納入） | **保留，且 B 階段就要流程順** |
|
||
|
||
---
|
||
|
||
## 14. 批准
|
||
|
||
- [x] 需求已批准：2026-07-09（使用者 OK；採預設：`apps/web`、Harbor Desk、海巡空頁、email 驗證 A 先關、mock localStorage）
|
||
- 下一步：審核 [spec.md](./spec.md) → 回 `spec OK` 後寫 plan
|