前端開發指引
前端開發指引 企業標準技術白皮書|版本 v2.0|2026-10-09 適用範圍:以 Vue 3/TypeScript/Vite/Tailwind CSS 開發的企業 Web 前端,特別是網路銀行、保險、證券等需要處理交易、個資與稽核要求的系統。本指引規範專案結構、命名、TypeScript、靜態檢查、元件、Composables、樣式、路由、狀態管理、API 串接、表單、多語系、前端安全、無障礙實作、效能、錯誤處理與可觀測性、測試、建置部署、版本控制與 CI、相依套件供應鏈、除錯,以及 AI 輔助開發的審查方法。 v2.0 全面改寫 v1.0.0:依 Vue 3.5/Vue Router 5/Pinia 4/Vite 8/TypeScript 6/Tailwind CSS 4/Vitest 5/Playwright 1.64 重新撰寫所有範例,並對照 OWASP ASVS 5.0、OWASP Top 10:2025、WCAG 2.2(ISO/IEC 40500:2025)、Core Web Vitals、RFC 9457、RFC 9700、OAuth 2.0 for Browser-Based Applications、CSP Level 3/Trusted Types、SLSA 1.2 與 CycloneDX 1.7(ECMA-424)。所有規則都有編號(FE-*)、驗證方式與範例;範例都以 vue-tsc、ESLint、Vitest、Vite 與 Playwright 實際執行過(見 附錄 F.3)。 目錄 0. 文件資訊 0.1 文件目的與讀者 0.2 技術與標準基準版本 0.3 規範等級與規則格式 0.4 與其他指引的關係 0.5 如何閱讀與使用本指引 0.6 例外與豁免流程 1. 前端治理與國際標準 1.1 前端品質與 ISO/IEC 25010 1.2 安全與法規基準 1.3 瀏覽器支援政策 1.4 版本支援與升級治理 2. 專案結構與模組邊界 2.1 標準目錄結構 2.2 路徑別名與匯入 2.3 Monorepo 與共用套件 3. 命名規範 3.1 檔案與資料夾 3.2 變數、函式與型別 3.3 TypeScript 的列舉與常數集合 3.4 Vue 元件、Props 與事件 4. TypeScript 撰寫規範 4.1 編譯器設定 4.2 型別系統的逃生門 4.3 外部資料的執行期驗證 4.4 非同步與例外 4.5 金額、數字與日期 4.6 以型別表達狀態 5. 程式風格與靜態檢查 5.1 工具分工 5.2 ESLint 5.3 Prettier 5.4 編輯器設定 5.5 提交前檢查 5.6 註解 6. Vue 元件開發規範 6.1 單檔元件結構 6.2 Props 6.3 v-model 與 defineModel 6.4 事件 6.5 插槽與泛型元件 6.6 範本 6.7 DOM 存取與識別碼 6.8 響應式 6.9 元件介面與實驗性功能 7. Composables 與邏輯重用 7.1 介面設計 7.2 副作用與清理 7.3 測試 Composables 7.4 使用 VueUse 8. 樣式與 Tailwind CSS 4 8.1 Tailwind CSS 4 設定 8.2 Class 的寫法 8.3 元件樣式與 @apply 8.4 響應式與使用者偏好 9. 路由與導覽 9.1 路由表與延遲載入 9.2 導覽守衛 9.3 路由參數 9.4 部署後的 chunk 載入失敗 9.5 檔案式路由(選用) 10. 狀態管理 10.1 狀態的分類 10.2 伺服器狀態:Pinia Colada 10.3 修改資料:useMutation 10.4 Pinia store 10.5 持久化與登出 11. API 串接與資料存取 11.1 共用的 HTTP 用戶端 11.2 API 契約與型別 11.3 錯誤格式:RFC 9457 Problem Details 11.4 逾時、重試與取消 11.5 重複送出與冪等性 12. 表單與輸入驗證 12.1 驗證的分工 12.2 欄位的寫法 12.3 後端錯誤與保留輸入 12.4 確認步驟與送出控制 13. 多語系(i18n) 13.1 設定 13.2 翻譯鍵與訊息 13.3 格式化與語系屬性 14. 前端安全 14.1 跨站腳本(XSS) 14.2 身分驗證與工作階段:BFF 模式 14.3 CSP 與安全標頭 14.4 敏感資料與瀏覽器 API 14.5 授權與檔案 14.6 閒置逾時與登出 15. 無障礙實作 15.1 語意與鍵盤 15.2 應用程式外殼:跳過連結與換頁 15.3 對話框 15.4 自動化檢測 16. 效能 16.1 量測 16.2 載入效能 16.3 執行期效能 17. 錯誤處理、日誌與可觀測性 17.1 全域錯誤處理 17.2 使用者看到的錯誤 17.3 追蹤與關聯 18. 測試 18.1 測試基礎設施 18.2 撰寫測試 18.3 涵蓋率 18.4 端對端測試 19. 建置、環境設定與部署 19.1 建置產物與環境設定 19.2 Vite 設定 19.3 容器化 19.4 nginx 設定與快取 20. 版本控制與持續整合 20.1 分支與提交 20.2 CI 工作流程 20.3 程式碼擁有者 21. 相依套件與供應鏈安全 21.1 引入與鎖定 21.2 安裝時的防護 21.3 漏洞管理與更新 21.4 軟體物料清單(SBOM)與來源證明 22. 除錯與疑難排解 22.1 除錯的流程 22.2 常見錯誤對照表 22.3 記憶體洩漏與效能問題 23. AI 輔助前端開發與審查 23.1 責任與資料保護 23.2 提供脈絡 23.3 審查 AI 產出的程式碼 附錄 A 規則總表 附錄 B 檢查清單與範本 B.1 前端 PR 範本 B.2 發布前檢查清單 B.3 手動無障礙與跨瀏覽器測試紀錄 附錄 C 工具設定與腳本 C.1 TypeScript 設定 C.2 ESLint 設定 C.3 package.json C.4 指令速查 附錄 D 術語表 附錄 E 參考資料 E.1 標準與規範 E.2 框架與工具文件 E.3 本公司相關指引 附錄 F 修訂紀錄與查證紀錄 F.1 v1 與 v2 章節對照 F.2 v1.0 的更正清單 F.3 查證紀錄 F.4 待確認與後續更新 F.5 修訂紀錄 0. 文件資訊 0.1 文件目的與讀者 前端是使用者唯一直接接觸的系統元件。轉帳按鈕按兩下是否會重複扣款、登入權杖會不會被惡意腳本讀走、網路中斷時畫面會不會卡在「載入中」、螢幕閱讀器使用者能不能完成申請,這些都由前端程式碼決定。前端的缺陷因此常以客訴、交易爭議、資安事件與法規風險的形式出現,而不只是「畫面不好看」。 ...