# CR-040　前端依賴升版以修補 1 個 HIGH ＋ 3 個 MODERATE

| 項目 | 內容 |
|---|---|
| 文件編號 | CR-040 |
| 版本 | **1.0** |
| 狀態 | ✅ 已裁定並執行 |
| 提出日 | 2026-10-05 |
| 提出者 | WorkBuddy AI（開發團隊） |
| 緣起 | `#A-160` 掃描之**最後一批前端命中**；BEAM PMO：「**請接著把前端那 1 個 HIGH…處理掉**」 |
| 前案 | `CR-037`（Tomcat）／`CR-038`（Jackson）／`CR-039`（lz4）——皆為 Gradle；**本案為 npm 生態，機制不同** |
| 關聯 | `CSP-006 §2.8`（前端基線）、`CSP-005 §4.3` |
| 嚴重度 | 🟠 **中高**——`TRP-001 §6.2` 第 7 條「安全掃描無高／嚴重漏洞」之**最後一項阻礙** |

---

## 1. 問題

| 套件 | 實際安裝版本 | 嚴重度 | 公告 |
|---|---|---|---|
| `vite` | **5.4.21** | **HIGH** | `GHSA-fx2h-pf6j-xcff`：`server.fs.deny` bypass on Windows alternate paths |
| `vite` | 同上 | MODERATE ×2 | `GHSA-4w7w-2-5vf9`（Optimized Deps `.map` 路徑穿越）／`GHSA-v6wh-96g9-6wx3`（launch-editor NTLMv2） |
| `react-router`／`react-router-dom` | **6.30.6** | MODERATE ×2 | `GHSA-337j-9hxr-rhxg`（SSR hydration constructor injection）／`GHSA-wrjc-x8rr-h8h6`（open redirect） |

> ⚠️ `package.json` 宣告 `vite: ^5.4.11`、`react-router-dom: ^6.28.0`——**實際安裝為 5.4.21／6.30.6**。

---

## 2. 查證（`version-compat-verification` 紀律；2026-10-05 實查）

| # | 查證項 | 方法 | 結果 |
|---:|---|---|---|
| 1 | ★ **修復版本** | OSV 逐筆取詳情 | **vite**：`6.4.3`／`7.3.5`／`8.0.16`（**5.x 線無修復版**）；**react-router**：`7.18.0` |
| 2 | 各線最新版 | npm registry | vite **6.4.3**／**7.3.6**／**8.3.2**（`dist-tags.latest` ＝ **8.3.2**，`previous` ＝ 7.3.6）；react-router **8.4.0**、react-router-dom **7.18.4** |
| 3 | ★ **`@vitejs/plugin-react` 之 peer 對應** | npm registry | **6.1.1** → `vite ^8.0.0`；**5.2.0／4.7.0** → `^4.2 \|\| ^5 \|\| ^6 \|\| ^7`（**不支援 8**）→ ★ **版本必須成對升級** |
| 4 | plugin-react 6.1.1 之額外 peer 是否必裝 | 讀 `peerDependenciesMeta` | ✅ **`oxc-transform-react`／`@rolldown/plugin-babel`／`babel-plugin-react-compiler` 皆 `optional: true`** → **不需額外安裝** |
| 5 | Node 版本要求 | `engines` | vite 8.3.2 與 plugin-react 6.1.1 皆 `^20.19.0 \|\| >=22.12.0`；**本機 v22.22.2** ✅ |
| 6 | react-router-dom 7.18.4 之 peer | npm registry | `react >=18`／`react-dom >=18` ✅（本專案 React **18.3.1**）；依賴 `react-router 7.18.4` |
| 7 | ★ **本專案之改動範圍** | 掃描 `frontend/src` | **僅 3 檔**：`main.tsx`（`BrowserRouter`）／`App.tsx`（`NavLink`/`Route`/`Routes`/`useLocation`）／`DashboardConsole.tsx`（`Link`）——**皆為 v7 不變之經典 API** |
| 8 | `vite.config.ts` 複雜度 | 讀檔 | **極簡**：`defineConfig({ plugins: [react()], server: { port, proxy } })`——**無外掛式設定**，跨版風險低 |

---

## 3. 裁定

| 套件 | 現行 | 目標 | 理由 |
|---|---|---|---|
| `vite` | 5.4.21 | **8.3.2** | `dist-tags.latest`；★ **5.x 無修復版**，且 **6.x 已落後兩線**（`previous` 為 7.3.6）→ 依「**不用 EOL 的東西**」原則取**現行支援線** |
| `@vitejs/plugin-react` | 4.3.4 | **6.1.1** | ★ **必須成對**：6.1.1 之 peer 為 `vite ^8.0.0` |
| `react-router-dom` | 6.30.6 | **7.18.4** | 修復版為 7.18.0；取 **7 線最新**（**保留 `react-router-dom` 套件名**——v8 已無該套件，升 v8 須改 import 路徑，**非必要不動**） |

**機制**：npm **直接升版 `package.json`**（本案為**直接相依**，**非**傳遞相依 → **不需 `overrides`**）。
★ 與 Gradle 之機制 A／B（`CSP-006 §2.14`）不同——**npm 之 `overrides` 僅在需覆寫「傳遞相依」時使用**。

**降級方案**（若 8.3.2 實測失敗）：`vite 7.3.6` ＋ `@vitejs/plugin-react 5.2.0`（peer 含 `^7`）。

---

## 4. 驗證要求（`CSP-006 §5.2`）

| # | 驗證項 | 通過標準 |
|---:|---|---|
| 1 | **實際安裝版本** | `vite 8.3.2`／`plugin-react 6.1.1`／`react-router-dom 7.18.4`（以 `node_modules` 實查，非看宣告） |
| 2 | **型別檢查** | `npm run typecheck`（`tsc --noEmit`）通過 |
| 3 | **正式建置** | `npm run build`（`tsc -b && vite build`）成功產出 `dist/` |
| 4 | **執行期** | dev server 可起、頁面可載入（headless Chrome 實測） |
| 5 | **漏洞歸零** | `npm audit` 之 **HIGH 1 → 0、MODERATE 3 → 0** |
| 6 | **未破壞其他相依** | `npm ls` 無 **unmet peer** 警告 |

---

## 5. 驗證結果（2026-10-05）

> ★ 依 `CR-038 §4.2` 之教訓：**本表於實跑後填入，不預填預期值。**

| # | 驗證項 | 結果 |
|---:|---|---|
| 1 | 實際安裝版本 | ✅ `vite **8.3.2**`／`@vitejs/plugin-react **6.1.1**`／`react-router-dom **7.18.4**`（`react-router 7.18.4`、React 18.3.1 不變）——**以 `node_modules` 實查，非看宣告** |
| 2 | 型別檢查 | ✅ `npm run typecheck`（`tsc --noEmit`）**無錯誤** |
| 3 | 正式建置 | ✅ `npm run build` → **`vite v8.3.2` 120 modules、built in 781ms**；產出 `dist/assets/index-*.js` 465.82 kB（gzip 117.93 kB） |
| 4 | **執行期（真實瀏覽器）** | ✅★ **headless Chrome 渲染成功**——`#root` 內容 **3,741 bytes**（非空殼）；出現「歸戶／授權／額度」；**8 個導覽連結正確渲染**（`/dashboard`、`/authorizations`、`/limit-adjustments`、`/parties`、`/accounts`、`/postings`、`/statements`、`/payments`） |
| 5 | 漏洞歸零 | ✅★ **`npm audit`：`found 0 vulnerabilities`**（**HIGH 1 → 0；MODERATE 3 → 0**） |
| 6 | 未破壞其他相依 | ✅ `npm ls` **無 unmet／invalid／missing**；`npm install` 回報 `added 1 package, audited 34 packages` |

> ★ **第 4 項之方法揭露**：首次以**預設（SSO 開啟）**建置做 Chrome 實測時，頁面**被導向 Keycloak**
> 並回 `Invalid parameter: redirect_uri`——★ **此與本次升版無關**，係 **`vite preview` 之埠（4173）
> 未註冊於 Keycloak `cardcore-web` 之 redirect URI**（屬既有設定，vite 5 亦然）。
> 為**隔離**該設定、專注驗證「React ＋ router 能否渲染」，遂以 `VITE_AUTH_ENABLED=false` **另建一次**
> 做渲染實測（**`dist/` 已 gitignore，且事後已還原為正常建置**）。
> ⚠️ **此非「SSO 已驗證」**——SSO 端到端屬另一範疇（`SCS-022 §8` 五情境）。

---

## 6. 已知限制（誠實揭露）

1. **vite 為跨 3 個大版（5 → 8）之升級**——雖 `vite.config.ts` 極簡、router 用法為經典 API，
   仍屬**較大變動**；已備**降級方案**（vite 7.3.6 ＋ plugin-react 5.2.0）。
2. **未做瀏覽器相容性矩陣**（NFR「Front-end System」15 項）——本 CR 僅驗「能建置、能載入」。
3. **前端仍無測試框架**（`TRP-002 §7.2 #2`）→ 本次驗證**無自動化回歸**，僅型別 ＋ 建置 ＋ 手動載入。
4. **`esbuild` 之 MODERATE 不在本 CR 直接處理**——由 vite 升版連帶更新（其版本由 vite 決定）。

---

## 7. 修訂記錄

| 版本 | 日期 | 修訂內容 |
|---|---|---|
| 1.0 | 2026-10-05 | 初版：診斷 1 HIGH ＋ 3 MODERATE；**查證 8 項**（★ 發現 **5.x 無修復版**、**plugin-react 必須成對升級**、**改動僅 3 檔**）；裁定 vite **8.3.2**／plugin-react **6.1.1**／react-router-dom **7.18.4**；載明**降級方案**；訂定 6 項驗證要求（**結果待實跑填入**） |