# 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