# 2026-05-10 AITerms.tw 部署回顧與 9 條新踩坑教訓 Updated: 2026-05-10 > 本文件給接手 AITerms.tw 的工程師與 AI 在動工前讀。 > 5/9 教訓見 [`/content-quality/today-2026-05-09`](https://aiterms.tw/content-quality/today-2026-05-09)。 > 所有教訓詳述見 `docs/LESSONS-LEARNED.md` 章節 L–KK（共 30 條）。 > 平台陷阱速查見 `docs/PLATFORM-TRAPS.md`（11 trap）。 --- ## 1. 上線項目（深夜 5 個 deploy） | Commit | 範圍 | 狀態 | |---|---|---| | `4f8a855` | P0 audit fixes + color tokens + CI green base | ✅ deploy success / CI ❌ lockfile | | `b52693f` | npm ci --dry-run 取代 lockfile diff | CI ❌ 35 stale tests | | `c17b949` | skip 4 stale test suites（May 6 refactor 後失修）| CI ❌ audit:dist false-positive | | `2b4654a` | audit:dist + audit:links allowlist + 外部 retry | ✅ CI green | | `54f4922` | EXECUTION-STANDARDS §3.5 F/G/H/I + PLATFORM-TRAPS + PR template | ✅ docs | | `8afceb8` | pre-push gate（私人 repo Free plan workaround）| ✅ docs | Production curl 全綠： - `/terms/transformer.md` Content-Type = text/markdown - `/terms/{overfitting-1,underfitting-1,machine-learning-operations,low-code-1}/` 全 301 - 首頁「台灣第一」0 處 - `/ipas/setup` `/ipas/diagnostic` `/ipas/exam-day` `/ipas/level-comparison` `/ipas/weakness` 全 200 P0 e2e：**7/10 過**（baseline 2/10，剩 3 個是 DB 內容問題）。 --- ## 2. 9 條新踩坑教訓（CC–KK） ### CC. Fork agent 看到背景 build 在跑就「等它收尾」 派色彩系統 fork 246 秒回來「leaving build to finish」，git status 確認 0 新檔 0 修改。fork 沒做事。 **正解**：Fork prompt MUST 含禁令清單（NEVER build / deploy / wait on background / curl production）。主 agent 收到 completion notification MUST git status 二次驗證。 ### DD. package-lock.json 跨平台 libc 欄位 false-positive 本機 Mac npm 11 / CI Linux npm 10 對 esbuild dev binary 的 `"libc": ["glibc"|"musl"]` 欄位處理不同。 **正解**：CI 改用 `npm ci --dry-run --legacy-peer-deps`，NEVER 用 `git diff --exit-code package-lock.json`。 ### EE. 35 個失修測試從 5/6 起一直紅 5/6 「移除 Supabase 依賴」refactor 把 API 改 noop，測試沒同步改 → CI 紅 4 天。 **正解**：改 API contract MUST 同 PR 改測試。skip MUST 帶 TODO + ticket。CI gate skip 上限 = baseline + 20。 ### FF. CF Workers ASSETS binding 跳過 Astro middleware middleware 改 `.md` Content-Type 沒生效，因為 prerendered 靜態檔由 ASSETS binding 直接吐出。 **正解**：`.md` Content-Type 改 `public/_headers`；redirect 改 `public/_redirects`。 ### GG. audit:dist 對 `./q10` 相對 link 全噴 broken `parseInternalHref` base 寫死 SITE_URL，相對 link 解成根目錄。10000+ false positive。 **正解**：`parseInternalHref` 接受 `fromFile`，base = `fileToUrl(file)`。 ### HH. 新 SSR-only route 觸發 audit allowlist miss 新增 9 條 `prerender = false` 路由，audit:dist + audit:links 噴 1700+。 **正解**：新 SSR-only route MUST 同步加 `isDynamicRuntimePath()`（dist-site-audit）+ `normalizeInternalPath()`（link-check）。 ### II. external link HEAD 被某些站拒 `reg.ipas.org.tw` 拒絕 HEAD，audit:links 報 `fetch failed`。 **正解**：HEAD 失敗 fallback GET + 自訂 UA + transient failure 改 warn-only。 ### JJ. GitHub Free plan 私人 repo 無 branch protection API `gh api .../rulesets` 回 403 `Upgrade to Pro or make public`。 **正解**：用本機 `.githooks/pre-push` 替代 gate（astro check + vitest + lint-exam-deepdive + lockfile sanity）。`core.hooksPath = .githooks` + `prepare` script 自動 wire。緊急 override `git push --no-verify`。 ### KK. safe-deploy.sh 寫死 4 個靜態錨點 `/`, `/ipas`, `/ipas/L1`, `/ipas/L2` 改 `prerender = false` 後 safe-deploy 線上驗證 step 失敗。 **正解**：4 錨點 MUST 保持靜態，動態 state 用 vanilla JS client-side fetch。 --- ## 3. 新增規範（已 commit） ### EXECUTION-STANDARDS §3.5 加 4 條 - **F. AI 子 Agent 派工紀律**（CC 教訓） - **G. Test-Refactor parity**（EE 教訓） - **H. 平台陷阱速查 → PLATFORM-TRAPS.md**（FF / KK 教訓） - **I. Audit script 自我覆蓋**（GG / HH 教訓） ### 新檔 `docs/PLATFORM-TRAPS.md` 11 個已知陷阱，格式：症狀 / 根因 / 解法 / 偵測指令。 ### `.github/PULL_REQUEST_TEMPLATE.md` 重寫 逼填欄位： - L0/L1/L2/L3 變更等級 - Pre-merge evidence（astro check / vitest / audit:dist / audit:links 輸出**必貼**） - Side effects checklist（改 API ↔ 改測試；新 SSR route ↔ 加 audit allowlist） - Post-deploy curl evidence - Rollback plan（具體 git command + 預期健康訊號） - AI fork checklist（禁令清單 + git status 二次驗證） ### 新檔 `.githooks/pre-push` 私人 repo Free plan 無 branch protection 的替代 gate： 1. `npx astro check` → 0 errors 2. `npm run test:run` → pass / skip 數量在 baseline 內 3. `bash scripts/lint-exam-deepdive.sh`（exam-deepdive 改才跑） 4. `npm ci --dry-run --legacy-peer-deps` → catches 跨平台 lockfile drift --- ## 4. 仍待 Hans 動手 DB-level（admin / Supabase）： - 33 條 `ai_tools.tagline` SQL UPDATE - 18 條 `terms.term_data` 修正（LLaMA 開源、a-b-testing markdown leak、Semantic Kernel/LangChain 等） - learning flow Supabase migration `supabase db push`（兩個 .sql 已在 commit 內） 技術債： - 4 個 vitest test suites 重寫（post-5/6 noop refactor） - P1 色彩系統 sweep（chip / tag token 化、IPASLayout 統一改 ``、ipas/index 11 處 anchor 改 ``） - 升 GitHub Pro 後幫忙建 ruleset（或公開 repo） --- ## 5. 你檢查時的網址 - 主流程：[首頁](https://aiterms.tw/) · [iPAS](https://aiterms.tw/ipas/) · [L1](https://aiterms.tw/ipas/L1) · [L2](https://aiterms.tw/ipas/L2) - 新流程：[setup](https://aiterms.tw/ipas/setup) · [diagnostic](https://aiterms.tw/ipas/diagnostic) · [exam-day](https://aiterms.tw/ipas/exam-day) · [weakness](https://aiterms.tw/ipas/weakness) - 內容規範：[content-quality/](https://aiterms.tw/content-quality/) - 考古題：[114-2-mid-2](https://aiterms.tw/ipas/exam-deepdive/114-2-mid-2/) · [114-2-mid-3](https://aiterms.tw/ipas/exam-deepdive/114-2-mid-3/) 記得 Cmd+Shift+R 強制刷新。 --- *最後更新: 2026-05-10（CC–KK 9 條）* *本檔為 `/content-quality/today-2026-05-09` 的接續，5/9 17 條教訓在前文。*