c9c60c3a61
Phase S 技術債修復 (首席架構師審查 82→完整): - S-01: generate_alert_fingerprint 移至 AlertAnalyzer.generate_fingerprint() staticmethod - S-04: 移除 Pydantic v2 deprecated json_encoders (直接用原生 datetime 序列化) Sentry MCP 整合 (Phase 23): - ADR-048: Sentry→OpenClaw AI Triage 架構決策 - sentry_webhook_service.py: parse/analyze/create_incident/build_message Service 層 - config.py: SENTRY_WEBHOOK_SECRET (Fail-Closed HMAC-SHA256) Playwright MCP 整合 (短期): - smoke.spec.ts: 5 頁面 E2E smoke test (home/dashboard/incidents/approvals/terminal) - cd.yaml: E2E Smoke Test 步驟 + Telegram 🎭 Smoke 狀態通知 長期規劃 ADR: - ADR-049: Figma Code Connect 設計系統同步 - ADR-050: Telegram 互動式 Incident 2.0 (6鍵 Inline Keyboard) - ADR-051: Context7 依賴升級顧問 (Next.js 14→15, FastAPI 0.115→0.128) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
171 lines
6.0 KiB
Markdown
171 lines
6.0 KiB
Markdown
# 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
|