# 前後端改進建議

依「影響使用者 / 維護成本 / 風險」排序。細節背景見先前健康檢查；**架構導覽**見 `docs/architecture.md`。

---

## 後端：立刻值得修的問題

### 1. Job dedupe：改寫草稿全域互擋

`generate-rewrite-draft` 的 `DedupeKeys` 為空，但 `buildDedupeKey` 仍用 `type|scope` 產 key → 所有 `scope=persona` 的改寫 job 共用一把 lease。

- 檔案：`internal/model/job/usecase/usecase.go`、`helpers.go`
- 建議：`DedupeKeys: []string{"scope_id"}`，或空 keys 時回傳 `""` 不啟用 lease
- 補 test

### 2. CreateRun 失敗路徑用裸 `Update`

lease 失敗時 `runs.Update` 直接改 status，違反 guarded 規則。

- 改 `UpdateIfStatus(pending → cancelled)`

### 3. ClaimNext lock 失敗立刻 re-enqueue

可能 tight loop 打 Redis。應 delay / 檢查狀態後再入列，FindByID 失敗不要 silent drop。

### 4. Worker 忽略 Heartbeat 錯誤

`_ = step.Heartbeat(ctx)` 在 lock 過期後仍繼續跑。失敗應中止 step。

### 5. Refresh token 並發

先發新 token 再 blacklist 舊的 → 並發 refresh 可能雙活。應用原子輪替（Lua / 先 blacklist 再 issue，或 refresh family）。

---

## 後端：結構與可維護性

| 議題 | 建議 |
|------|------|
| ServiceContext 過胖 | 依域拆 bootstrap（auth/job/content/publish），減少單檔 400+ 行 DI |
| 每個 worker process 註冊全部 handler | 只 register 該 `workerType` 需要的 step；啟動時 assert template↔handler |
| ghost worker 在 compose | 已清理一輪；新增 template 時同步 `dev-all` / `docker-compose` |
| 列表 API 用 `limit` | 新 API 一律 `page/pageSize`；舊的雙讀後 deprecate |
| `time.Now().UnixNano()` 散落 | 統一 `clock.NowUnixNano()` 利於測試 |
| Secrets key 可空 | prod config validate：`HAIXUN_SECRETS_KEY` 必填 |
| copy_mission 半殘 | 見 `post-project-plan`：過渡期只留 inspire；完整 pipeline 勿再接，走 Post Project |
| 測試 | Job 較完整；auth refresh、ClaimNext race、logic 層幾乎無測 — 優先補 P0 |

### 錯誤處理慣例

- 好：`errs.For(code.X).…` + `response.Write`
- 差：`_, _ = FailRun` / `UpdateProgress` 吞錯誤 → 可觀測性差，長任務尤其危險

### 不建議做的事

- 為了 template-monorepo 相容引入 OAuth/OTP/Zitadel 重依賴
- 在 provider adapter 裡讀 Mongo / setting
- 裸 `Update` 蓋 job / publish_queue 狀態

---

## 前端：可明顯變好的地方

### 1. 登入態對 5xx 過於暴力

`AuthContext.reloadMember` 任何錯誤都 `clearTokens()`。gateway 短暫 502 會踢登出。

建議：僅 401 / refresh 失敗清 token；5xx 顯示「後端暫時無法連線」。

### 2. 巨型頁面

| 檔案 | 約略行數 | 建議 |
|------|----------|------|
| `PatrolPage.tsx` | ~1900 | 拆 list / graph / scan / outreach 子元件 + hooks |
| `MissionsPage.tsx` | ~1200 | 若走 Post Project 直接換 wizard，勿再膨脹 |
| `OwnPostsHub.tsx` | ~750 | 拆 formula / reply / list |

好處：可測、可讀、島民/自動化也較好掛 `data-islander-*`。

### 3. Hash 路由的限制

- 無巢狀 path、難做 deep link（例如 `#patrol/topic/xyz`）
- 中長期可考慮 React Router，或至少支援 `page + query` 狀態

### 4. 過時 UI / 死 client

| 項目 | 建議 |
|------|------|
| `GapsPage` | 對齊 `threads-automation-gap-plan` 真實進度，或改「已完成 checklist」 |
| `haixun.ts` 未呼叫方法 | 定期刪（inventory API client 等） |
| `extensionSync` 固定 reject | 文件與 UI 標「已停用」；重啟時勿再 postMessage JWT |
| jobLabels 幽靈 type | 隨 ghost template 刪 |

### 5. 設計系統（已做得不錯）

- 繼續只用 `--hx-*` / semantic Tailwind；勿引入 MUI/Ant
- 共用 `ui.tsx`（Button 必須有 children）
- 大頁面新功能優先組 Card / Field / Badge，不要另寫色票

### 6. API 層

`client.ts` 的 refresh single-flight、502 retry 是好的。可再：

- 對 `ApiError` 做 `isUnauthorized` / `isUnavailable` helper，頁面統一處理
- 長輪詢（jobs 3s）考慮 visibility API：分頁隱藏時降頻

### 7. 測試

目前幾乎無前端 test。最低投資：

- `client.ts` refresh + 502 retry
- `AuthContext` 5xx 不登出
- 純函式：`jobStatus`、`format` nano 轉換

### 8. AGENTS 寫了但未存在的功能

- **Islander agent runtime**（`web/src/lib/islander`）文件超前，程式沒有  
  → 實作或從 AGENTS 刪除描述，避免後續 agent 按空文件改碼

---

## 產品債（架構外但影響體感）

1. **Flow A 過渡態**：Missions 用 inspire + content_ops + drafts，舊 copy_mission CRUD 已移除/不可用；應盡快 Post Project 或明確標「精簡模式」。  
2. **Extension 同步關閉**：海巡 dev crawl 若依賴 browser session，需新安全協議（short-lived code，勿 JWT postMessage）。  
3. **Publish inventory refill job** 無 handler：policy API 可留，refill job 勿再 enqueue（應已清）。

---

## 建議迭代順序（若只做改進、不做大功能）

```text
Sprint A  正確性
  rewrite dedupe、CreateRun guarded cancel、ClaimNext、Heartbeat、AuthContext 5xx

Sprint B  可理解性
  拆 PatrolPage / Missions 邊界、GapsPage 對齊、AGENTS 修路徑與 auth matrix

Sprint C  可觀測
  worker 錯誤上報、job stranded reaper、prod secrets validate

Sprint D  產品
  Post Project（取代 Flow A）或凍結 Missions 只修 bug
```

---

## 自我檢查清單（PR 前）

後端：

- [ ] 列表是否 `page/pageSize` + pagination  
- [ ] Job 狀態是否 guarded  
- [ ] 長任務是否處理 Heartbeat 錯誤  
- [ ] 錯誤是否 `errs.For(code.X)`  
- [ ] 時間是否 unix nano UTC  

前端：

- [ ] 是否只用 semantic token  
- [ ] Button 是否有中文動詞 children  
- [ ] 是否經 `api/client` envelope  
- [ ] 錯誤是否區分 401 vs 5xx  
- [ ] `make web-build` 通過