# ADR-051: Context7 依賴升級顧問整合

| 項目 | 內容 |
|------|------|
| **狀態** | 📋 已批准，待實作 |
| **日期** | 2026-04-01 |
| **決策者** | 首席架構師 + 統帥 |
| **觸發** | MCP 整合長期計畫 |

## 背景

AWOOOI monorepo 依賴多個快速迭代的框架，手動追蹤升級耗時且容易遺漏重要的安全修補或 Breaking Changes：

| 套件 | 當前版本 | 最新版本 | 差距 |
|------|----------|----------|------|
| FastAPI | `>=0.115.0` | `0.128.0` | 13 個小版本 |
| Next.js | `14.1.0` | `15.1.11` | 1 個主版本 |
| Pydantic | `>=2.5.0` | v2 最新 | 需確認 |
| @sentry/nextjs | `^10.45.0` | 需確認 | 需確認 |
| lewooogo-brain | 內部套件 | - | 依發布追蹤 |

**核心問題**：

1. **安全漏洞**：CVE 修補若不及時，可能已有已知漏洞在生產環境
2. **技術債累積**：次版本差距越大，升級時 Breaking Changes 越難處理
3. **文件落後**：框架升級後，Claude Code 若依賴訓練資料，可能給出過時的 API 建議

## 決策

建立**每月依賴審查流程**，在每月 1 日，由 Claude Code 使用 **Context7 MCP** 查詢各主要依賴的最新版本、Breaking Changes 與官方遷移指南，生成升級評估報告，並建立追蹤 Issue 排入技術債計畫。

## 審查流程

### 觸發時機

- **定期**：每月 1 日（由統帥手動觸發或 Schedule Agent）
- **臨時**：收到 CVE 通知、框架發布重大版本（如 Next.js 16）
- **被動**：CI 出現 deprecation warning 時

### 執行步驟

```
Step 1: 使用 Context7 查詢各依賴最新文件
  → resolve-library-id: "fastapi", "nextjs", "pydantic", "sentry"
  → query-docs: "latest version", "changelog", "migration guide"

Step 2: 比對當前版本（讀 apps/api/requirements.txt + apps/web/package.json）

Step 3: 評估 Breaking Changes 風險
  → 主版本升級 → 🔴 高風險，需完整測試
  → 次版本升級 → 🟡 中風險，需讀 changelog
  → Patch 升級  → 🟢 低風險，通常可直接升

Step 4: 生成升級評估報告（輸出至 docs/adr/upgrade-report-YYYY-MM.md）

Step 5: 建立 GitHub Issue（含升級計畫 + 預估工時）
         排入 Phase S+N 技術債看板
```

## 升級優先順序

### 🔴 P1：安全修補（立即執行）

**觸發條件**：任何 CVE CVSS ≥ 7.0，或套件官方發布安全公告

**處理流程**：
1. 當日確認修補版本
2. 本地測試通過後，當日發 PR
3. 直接合入 main，不等月度審查
4. 同步更新 LOGBOOK.md

**已知高風險套件**：
- `cryptography` (Python) — 頻繁 CVE
- `next` (Node) — SSR 相關安全漏洞
- `pydantic` — 資料驗證繞過風險

### 🟡 P2：主要功能改善（月度計畫）

**範例**：

| 升級 | 主要改善 | 預估工時 |
|------|----------|----------|
| Next.js 14 → 15 | App Router 效能優化、Turbopack 穩定 | 2-4 天 |
| FastAPI 0.115 → 0.128 | dependency injection 改善、OpenAPI 更新 | 0.5 天 |

**Next.js 15 升級注意事項**（預查）：
- `async` Server Components 預設行為變更
- `cookies()`、`headers()` 改為 async API
- Turbopack 成為預設（需測試 build 輸出）
- 需執行 `npx @next/codemod@latest upgrade`

### 🟢 P3：小版本 / Patch（批次更新）

每季度批次更新，使用 `npm update` + `pip install -U` 後執行完整測試套件。

## 報告格式

```markdown
# 依賴升級報告 2026-04

生成時間：2026-04-01 00:00 +08
工具：Context7 MCP + Claude Code

## 摘要

| 優先級 | 套件數 | 行動 |
|--------|--------|------|
| 🔴 P1 (安全) | 0 | 無 CVE |
| 🟡 P2 (功能) | 2 | 建立 Issue |
| 🟢 P3 (patch) | 5 | 排入季度批次 |

## P2 升級建議

### Next.js 15.1.11
- 當前版本：14.1.0
- Breaking Changes：[列出]
- 遷移指南：[Context7 查詢結果]
- 預估工時：2-4 天
- 建議 Phase：Phase S+3

...
```

## 技術約束

1. **Context7 MCP 使用限制**：每次查詢消耗 token，月度審查批次執行，不頻繁觸發
2. **升級前必讀**：`feedback_read_comments_first.md` — 涉及 `requirements.txt` 和 `package.json` 的修改
3. **禁止直接 push**：所有版本升級必須經過 PR + CI 測試，遵守 `feedback_build_from_git_only.md`
4. **Next.js 升級特別注意**：`apps/web/` 的升級需確認 `NEXT_PUBLIC_*` build-time 變數仍正常（`feedback_docker_nextjs_api_url.md`）

## 當前待處理升級清單

| 套件 | 當前 | 目標 | 優先級 | 預計執行 |
|------|------|------|--------|----------|
| FastAPI | `>=0.115.0` | `0.128.0` | 🟡 P2 | Phase S+1 |
| Next.js | `14.1.0` | `15.1.11` | 🟡 P2 | Phase S+2 |
| @sentry/nextjs | `^10.45.0` | 需 Context7 確認 | 🟢 P3 | 季度批次 |
| Pydantic | `>=2.5.0` | 需 Context7 確認 | 🟢 P3 | 季度批次 |

## 首次執行指令（由 Claude Code 執行）

```bash
# 1. 確認當前版本
cat /Users/ogt/awoooi/apps/api/requirements.txt | grep -E "fastapi|pydantic|sentry"
cat /Users/ogt/awoooi/apps/web/package.json | grep -E "next|sentry"

# 2. 使用 Context7 查詢（Claude Code 手動執行）
# → resolve-library-id: fastapi
# → query-docs: "0.128 changelog breaking changes"
# → 依此類推

# 3. 生成報告並建立 Issue
```

## 影響

| 面向 | 影響 |
|------|------|
| **安全** | P1 CVE 修補時間從「被動發現」縮短為「月內主動處理」 |
| **技術債** | 避免版本差距累積超過 1 個主版本 |
| **CI 穩定性** | 及時升級避免 deprecation warning 轉成 error |
| **開發體驗** | Claude Code 可查最新 API 文件，減少過時建議 |

## 相關文件

- [feedback_stable_mainstream_practices.md](~/.claude/projects/-Users-ogt-awoooi/memory/feedback_stable_mainstream_practices.md)
- [feedback_build_from_git_only.md](~/.claude/projects/-Users-ogt-awoooi/memory/feedback_build_from_git_only.md)
- [feedback_docker_nextjs_api_url.md](~/.claude/projects/-Users-ogt-awoooi/memory/feedback_docker_nextjs_api_url.md)
- [project_phase_r_refactoring.md](~/.claude/projects/-Users-ogt-awoooi/memory/project_phase_r_refactoring.md)
- Context7 官方文件：https://context7.com/docs