awoooi/docs/adr/ADR-051-context7-dependency-advisor.md

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 後執行完整測試套件。

報告格式

# 依賴升級報告 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 執行）

# 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
• feedback_build_from_git_only.md
• feedback_docker_nextjs_api_url.md
• project_phase_r_refactoring.md
• Context7 官方文件：https://context7.com/docs