thread-master/docs/product/haixun-console/spec.md

# Spec: 巡樓 Console 重構（Harbor Desk）

> Status: **`approved`**  
> Source: `docs/product/haixun-console/requirements.md`（approved 2026-07-09）  
> Last updated: `2026-07-09`  
> 批准：使用者要求開始拆 plan/tasks（2026-07-09）  
> 變更：reply 步驟發言池含 lead（主帳可回別人的回覆）  
> 範圍：Phase A 地基契約 + Phase B 前端/Mock 行為；Phase C 接真映射；Phase D 僅邊界預留

---

## 1. 摘要

重構後的巡樓 Console 分四階段交付。本規格鎖定：

1. **平台地基**：登入會話、角色權限、Threads 帳號基礎、Job、站內通知。  
2. **新前端 Harbor Desk**：5 入口 IA、Studio 多帳互回 wizard、Outbox、通知；**預設 mock 資料**。  
3. **同一契約**在 `mock | live` 切換；B 未過關不開大型業務後端。

落點（2026-07-09 已封存舊碼）：

| 項目 | 決策 |
|------|------|
| 舊 monorepo | **`old/` 整包封存，只讀** |
| 新前端 | repo 根 `apps/web`（從零） |
| 新後端 | `services/api`（從零；A 可先 mock-only 前端） |
| 視覺 | Harbor Desk 為唯一預設主題 |
| 海巡 Scout | B 階段占位空頁 |
| Email 驗證閘 | A/B 關閉 |
| Mock 持久化 | `localStorage` |

---

## 2. 名詞與實體

| 名詞 | 定義 |
|------|------|
| Member | 登入會員（email/password + JWT） |
| Role | 簡化：`member` \| `admin`（可多值） |
| ThreadsAccount | 已綁定的 Threads 經營帳號（OAuth token 由後端保管） |
| Lead | 本串**主帳號**：固定發 `root` 樓主貼；並屬於發言池，可在後續 `reply` 再出場 |
| Cast | 本串**額外可出場帳號**（通常不含 lead）；與 lead 組成發言池 |
| Speakers（發言池） | `{ lead_account_id } ∪ cast_account_ids`；**每一則 reply 步驟的 `account_id` 必須 ∈ Speakers**，**允許 = lead** |
| ThreadPlay | **發文計畫 / 串場劇本**（一則主貼 + 有序回覆步驟） |
| PlayStep | 劇本一步：`kind=root\|reply`、綁定 `account_id`、文案、可選排程偏移；`reply` 語意為接上一步（單線） |
| OutboxItem | 出站佇列項目：對應某 PlayStep 的一次發送意圖與狀態 |
| Job | 背景任務 run（進度、狀態、結果摘要） |
| Notification | 站內通知（多由 Job 終態產生） |
| DataSource | `mock` \| `live`：前端資料來源模式 |

---

## 3. 狀態機

### 3.1 Job

```text
pending --> queued --> running --> succeeded
                       running --> failed
                       running --> cancel_requested --> cancelled
queued|pending --> cancelled   (若支援提前取消)
* --> expired                  (lock 逾時，後端語意；mock 可簡化省略)
```

### 3.2 ThreadPlay

```text
draft --> ready          (劇本與帳號齊全、通過預覽)
ready --> scheduling     (寫入 Outbox)
scheduling --> active    (至少一步 in flight 或 scheduled)
active --> completed     (全部步驟 succeeded 或 skipped)
active --> partial_failed (有 failed，可重試)
draft|ready --> archived
```

### 3.3 PlayStep / OutboxItem

```text
draft --> scheduled --> publishing --> published
                         publishing --> failed
scheduled --> cancelled
failed --> scheduled     (retry)
```

**規則：**

- `root` 步驟未 `published` 前，後續 `reply` 不得進入 `publishing`。  
- `root` 若 `failed`，後續步驟保持 `scheduled` 或改 `blocked`（顯示「等待主貼」）。  
- `root.account_id` **必須** = `lead_account_id`。  
- 任一 `reply.account_id` **必須** ∈ Speakers（**含 lead**）；校驗失敗不可 submit。  
- P0 單線：第 n 步 reply 視為回覆第 n−1 步已發出的那則（不另選 parent；D 再談樹狀）。

### 3.4 ThreadsAccount.connection

```text
unknown --> connected
unknown --> error
connected --> error
error --> connected      (重新授權/診斷成功)
```

---

## 4. 使用者流程

### 4.1 登入（A/B）

1. 使用者開 `/login`，輸入 email、password（可選 tenant 若多租戶 UI 需要；mock 固定 `default`）。  
2. 成功 → 存 access/refresh（live）或 session flag（mock）→ 進 `/app/today`。  
3. 失敗 → 表單錯誤，不進主殼。  
4. 重新整理：有有效會話則進主殼，否則回登入。  
5. 登出 → 清會話 → 登入頁。

### 4.2 帳號 Crew（B mock / C live）

1. 列表顯示已綁帳號：顯示名、頭像色、connection、是否預設 lead 候選。  
2. 「連接 Threads」：live 走 OAuth；mock 新增一個假帳號。  
3. 標記不健康帳號不可被選為 Lead/Cast（disabled + 原因）。

### 4.3 創作 Studio — 互回 wizard（B 核心）

| 步驟 | 畫面行為 |
|------|----------|
| 1 主題 | 標題/一句主題；可「示範填入」 |
| 2 船隊 | 必選 1 Lead；多選 Cast（≥0，UI 列表可預設排除 lead，避免重複勾）；不可選 error 帳號 |
| 3 劇本 | 第 0 步固定 `root` + `account_id=lead`（不可改帳）；其後每步 `reply`：**下拉發言池 = lead + 全部 cast**（**含 lead**，以便主帳回別人的回覆）+ textarea；可增刪排序（root 固定頂） |
| 4 預覽 | 對話泡泡：帳號名 + 文案；root 標記；可見 lead 出現在非第 0 步 |
| 5 船期 | 主貼時間（datetime）；回覆間隔（分鐘，預設 5）；可預覽各步預計時間 |
| 6 提交 | 建/更新 ThreadPlay=`scheduling`，生成 OutboxItem；導向 Outbox 或 Today |

任一步「上一步」保留表單狀態。草稿自動存（mock：`localStorage` key 見 §8）。

### 4.4 Outbox

1. 列表：Play 標題、狀態、步驟進度（2/5）。  
2. 點進詳情：逐步狀態時間線。  
3. Mock「模擬發送」：依序 root→replies 推進狀態（可加速）。  
4. 失敗步驟顯示錯誤文案 +「重試」（mock 直接 succeeded）。

### 4.5 Today

1. 卡片：待處理失敗、今日排程、進行中 Job、快捷「開新串場」。  
2. 點通知/失敗 → 對應 Outbox 或 Job 詳情。

### 4.6 通知

1. 頂欄鈴鐺：未讀數。  
2. 下拉最近 N 筆；點擊標記已讀並 navigate。  
3. Job `succeeded|failed` 產生通知（mock 在模擬結束時寫入）。

### 4.7 Scout（B）

占位頁：標題「探查」、短說明「海巡獲客將在下一階段開放」、無假成功操作。

### 4.8 設定

- 顯示目前 `DataSource` 切換（dev 可見；prod 預設 live 且可藏）。  
- AI key：B 僅 UI 存 local（不送出）；C 再定義。

---

## 5. 介面契約

### 5.0 共用規則

| 規則 | 規格 |
|------|------|
| Envelope | `{ code, message, data?, error? }`；成功 `code=102000` |
| 列表 | query `page`/`pageSize`；`data: { pagination, list }` |
| 時間 | API/DB：**unix nanoseconds int64 UTC**；UI 顯示本地時區 |
| Auth | `Authorization: Bearer <access>`；401 → refresh 一次 → 仍失敗登出 |
| 禁止 | 未實作端點回 200+空成功；應 501 或明確業務錯誤 |

前端 repository 介面（概念）：

```text
AuthRepo, MemberRepo, PermissionRepo,
ThreadsAccountRepo, ThreadPlayRepo, OutboxRepo,
JobRepo, NotificationRepo
```

`createRepos(dataSource)` → mock 或 live 實作同一 TypeScript interface。

### 5.1 HTTP / API（Phase A 最小 + C 對齊）

> 路徑為**目標契約**；可與舊 `/api/v1` 對齊以利搬碼。Mock 不經 HTTP 亦可，但 shape 相同。

#### Auth / Member / Permission

| Method | Path | 用途 | 要點 |
|--------|------|------|------|
| POST | `/api/v1/auth/login` | 登入 | body: email, password, tenant_id? → tokens |
| POST | `/api/v1/auth/refresh` | 換票 | refresh_token → tokens |
| POST | `/api/v1/auth/logout` | 登出 | auth |
| GET | `/api/v1/members/me` | 我 | tenant_id, uid, email, roles[] |
| GET | `/api/v1/permissions/me` | 我的權限 | keys[] 或 * |

Admin 建號可延後；mock 內建一組使用者即可。

#### Threads accounts

| Method | Path | 用途 |
|--------|------|------|
| GET | `/api/v1/threads-accounts` | 列表（pagination） |
| POST | `/api/v1/threads-accounts/oauth/start` | 取得授權 URL（live） |
| GET | `/api/v1/threads-accounts/:id` | 詳情 / 健康 |
| POST | `/api/v1/threads-accounts/:id/diagnostics` | 連線診斷（可選 A） |

#### Jobs

| Method | Path | 用途 |
|--------|------|------|
| GET | `/api/v1/jobs` | 列表 |
| GET | `/api/v1/jobs/:id` | 詳情 |
| POST | `/api/v1/jobs/:id/cancel` | 取消 |
| POST | `/api/v1/jobs` | 建立（A 可僅 demo 或內部） |

Job 資源欄位（最低）：`id, template_type, status, progress_summary, progress_percent, error?, created_at, updated_at, completed_at?`

#### Notifications

| Method | Path | 用途 |
|--------|------|------|
| GET | `/api/v1/notifications` | 列表 |
| POST | `/api/v1/notifications/:id/read` | 已讀 |
| POST | `/api/v1/notifications/read-all` | 全已讀 |

欄位：`id, title, body, kind, ref_type, ref_id, read_at?, created_at`

#### ThreadPlay / Outbox（B mock 完整；C 再 live）

| Method | Path | 用途 |
|--------|------|------|
| GET/POST | `/api/v1/thread-plays` | 列表 / 建立 |
| GET/PATCH | `/api/v1/thread-plays/:id` | 讀 / 更新劇本 |
| POST | `/api/v1/thread-plays/:id/submit` | 提交進 Outbox |
| GET | `/api/v1/outbox` | 佇列列表 |
| GET | `/api/v1/outbox/:id` | 詳情（含 steps） |
| POST | `/api/v1/outbox/:id/steps/:stepId/retry` | 重試一步 |

**ThreadPlay 主體（邏輯 JSON）：**

```json
{
  "id": "…",
  "title": "週末咖啡話題",
  "topic": "…",
  "status": "draft",
  "lead_account_id": "…",
  "cast_account_ids": ["…"],
  "steps": [
    {
      "id": "s0",
      "sort_order": 0,
      "kind": "root",
      "account_id": "…",
      "text": "主貼文案",
      "delay_from_previous_sec": 0
    },
    {
      "id": "s1",
      "sort_order": 1,
      "kind": "reply",
      "account_id": "…",
      "text": "回覆文案",
      "delay_from_previous_sec": 300
    }
  ],
  "schedule_start_at": 0,
  "created_at": 0,
  "updated_at": 0
}
```

### 5.2 前端路由（`apps/web`）

使用 **path router**（非 hash），basename 可 `/`。

| Path | 名稱 | 需登入 | Phase |
|------|------|--------|-------|
| `/login` | 登入 | 否 | B |
| `/app` | 佈局殼 | 是 | B |
| `/app/today` | 今日 | 是 | B |
| `/app/crew` | 帳號 | 是 | B |
| `/app/studio` | 創作列表 | 是 | B |
| `/app/studio/new` | 新 wizard | 是 | B |
| `/app/studio/:playId` | 編輯 wizard | 是 | B |
| `/app/outbox` | 發送佇列 | 是 | B |
| `/app/outbox/:id` | 佇列詳情 | 是 | B |
| `/app/jobs` | 任務（可二級） | 是 | B |
| `/app/jobs/:id` | 任務詳情 | 是 | B |
| `/app/scout` | 探查占位 | 是 | B |
| `/app/settings` | 設定 | 是 | B |

**導覽（一級，≤5）：** Today · Crew · Studio · Scout · Outbox  
Jobs 從 Today/通知進入；Settings 在使用者選單。

### 5.3 Job types（A 最小）

| template_type | 用途 | Phase |
|---------------|------|-------|
| `demo_long_task` | 驗證 job+通知 | A/B mock 可模擬 |
| （業務 job） | 發佈串場、8D… | C/D |

B mock 可不跑真 worker：Timer 推進 job 狀態並寫 notification。

---

## 6. 與現況對照

| 能力 | 決策 | 備註 |
|------|------|------|
| 整個舊 monorepo | **Archive** | 實體路徑 `old/`；主線不引用為 package |
| 舊 Auth/JWT/envelope | **參考後重寫** | 契約精神可相容 |
| 舊 Job 核心 | **參考後重寫** | 可抄模式，不搬半成品 |
| copy_mission 管線 | **Discard** | 不復活 |
| 舊 web Console | **Archive** | 新 `apps/web` |
| 海巡 Patrol 全套 | **Defer D** | Scout 占位 |
| 田園掌機 UI | **Discard 預設** | Harbor Desk |
| 時間/envelope/job 規則 | **Keep as policy** | 見根目錄 `AGENTS.md` |

---

## 7. 非功能

### 安全 / 權限

- 未登入不可進 `/app/**`。  
- `admin` 專屬操作（若有）前後端雙檢。  
- Live：token 不進 URL；refresh 單飛。  
- Mock：不模擬權限繞過成功寫入 live。

### 錯誤

- UI 可讀中文 message。  
- 區分 401（登出）vs 5xx（保留會話，顯示重試）。  

### 可觀測

- Job 進度摘要必顯示。  
- Outbox 步驟級狀態必顯示。  

### 效能（B）

- 首屏可互動 < 3s（本機 dev 網路）。  
- 列表 mock ≤ 50 筆即可。  

### 無障礙（基線）

- 表單 label 關聯；主按鈕對比足夠；焦點可見。

---

## 8. 資料保存（邏輯）

### 8.1 Mock localStorage keys

| Key | 內容 |
|-----|------|
| `harbor.datasource` | `mock` \| `live` |
| `harbor.session` | mock 登入態 |
| `harbor.accounts` | ThreadsAccount[] |
| `harbor.plays` | ThreadPlay[] |
| `harbor.outbox` | Outbox 聚合 |
| `harbor.jobs` | Job[] |
| `harbor.notifications` | Notification[] |
| `harbor.play_draft` | wizard 未提交草稿 |

### 8.2 實體欄位（最低）

| 實體 | 關鍵欄位 |
|------|----------|
| Member | uid, tenant_id, email, roles |
| ThreadsAccount | id, username, display_name, connection, is_usable |
| ThreadPlay | 見 §5.1 JSON |
| OutboxBundle | id, play_id, status, steps[] |
| OutboxStep | step_id, account_id, status, error?, published_at?, scheduled_at? |
| Job | 見 §5.1 |
| Notification | 見 §5.1 |

---

## 9. UI 規格（Harbor Desk）

### 9.1 Layout

```text
┌─────────────────────────────────────────────┐
│ Logo   [今日]…          🔔  主題  使用者 ▾   │  topbar
├──────────┬──────────────────────────────────┤
│ Today    │  Page title                      │
│ Crew     │  Content                         │
│ Studio   │                                  │
│ Scout    │                                  │
│ Outbox   │                                  │
└──────────┴──────────────────────────────────┘
```

- 桌面：左導覽 ~220px。  
- 手機：底欄 5 格（Today/Crew/Studio/Scout/Outbox）；設定進使用者選單。  
- 內容最大寬 ~1080px，表單閱讀寬 ~640–720px（wizard）。

### 9.2 視覺 token（建議名，實作可微調色值）

| Token | 用途 | 建議 |
|-------|------|------|
| `--hb-bg` | 頁背景 | 冷灰白 |
| `--hb-surface` | 卡片 | 白 |
| `--hb-ink` | 主文 | 近黑 slate |
| `--hb-muted` | 次文 | 可讀灰（勿過淡） |
| `--hb-line` | 邊框 | 淺灰 |
| `--hb-brand` | 主色/CTA | 霧海青 |
| `--hb-danger` | 錯誤 | 紅 |
| `--hb-success` | 成功 | 綠 |
| `--radius` | 卡片 | 12–16px |
| `--font-sans` | 混排 | Inter, Taipei Sans TC, system |

禁止：滿版動態雲、木質頂欄、emoji 主 icon、彩虹漸層按鈕。

### 9.3 元件基線

Button（primary/ghost/danger）、Input、Textarea、Select、Card、Badge（狀態）、EmptyState、Stepper（wizard）、Toast、BellMenu。

---

## 10. 驗收場景（Given / When / Then）

1. **Given** 未登入 **When** 開 `/app/today` **Then** 導向 `/login`。  
2. **Given** mock 帳密正確 **When** 登入 **Then** 進 Today 且看到至少一張待辦/空狀態。  
3. **Given** 兩個 usable 帳號 A、B **When** Studio：lead=A cast=B，劇本為 root(A) → reply(B) → reply(A) **Then** 可預覽三句；submit 後 Outbox 三步順序正確且第二則回覆發言者為 lead。  
3b. **Given** 劇本某 reply 選了不在 Speakers 的帳號 **When** 提交 **Then** 阻擋並提示。  
4. **Given** 已提交串 **When** 模擬發送 **Then** root→reply 依序 published；通知出現成功。  
5. **Given** root 模擬失敗 **When** 查看 **Then** reply 不標 published；可重試 root。  
6. **Given** Job 模擬完成 **When** 開鈴鐺 **Then** 未讀 +1，點進 job 詳情。  
7. **Given** Scout **When** 進入 **Then** 僅占位，無「成功建立海巡」類假操作。  
8. **Given** live 模式且後端 5xx **When** 拉 me **Then** 不強制清 token（與需求 US-09 對齊，C 必須）。  

---

## 11. Phase 邊界（實作不得越級）

| Phase | 做 | 不做 |
|-------|----|------|
| A | 契約+可選最小 live auth/job；或純 mock 平台殼 | 海巡、完整互回後端 |
| B | `apps/web` 全 mock 體驗 | 大寫業務 API |
| C | 逐 repo 接 live | 改 IA 大翻（除非修 bug） |
| D | 海巡等 | — |

---

## 12. 開放規格問題

1. **Tenant UI：** login 是否顯示 tenant 欄？**預設：隱藏，mock/live 固定 default tenant。**  
2. **Lead 能否出現在 reply？** → **已決策：必須支援**（主帳回別人的回覆）。Cast 多選 UI 仍可不重複勾 lead；發言下拉一定含 lead。  
3. **A 是否必須先有可跑的 Go gateway，還是 B 可完全純前端？** **預設：B 可純前端 mock；A 的 live 可與 B 平行，但不阻塞 B 過關。**  
4. **Outbox 與舊 publish_queue 是否同 collection？** **預設：C 再定映射；規格層當新模型。**  

---

## 13. 批准

- [x] Spec 已批准：2026-07-09（使用者：好請幫我開始拆）  
- 下一步：依 [plan.md](./plan.md) 與 [tasks/](./tasks/) 實作