Files

DonaldFang 方士碩 a6af297623 backup: 完成 HR_position_ 表格前綴重命名與欄位對照表整理

變更內容：
- 所有資料表加上 HR_position_ 前綴
- 整理完整欄位顯示名稱與 ID 對照表
- 模組化 JS 檔案 (admin.js, ai.js, csv.js 等)
- 專案結構優化 (docs/, scripts/, tests/ 等)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

2025-12-09 12:05:20 +08:00

28 KiB

Raw Blame History

軟體設計文件 (SDD) - 代碼分離優化

文件版本: v1.0 建立日期: 2024-12-04 專案名稱: HR Position Management System 優化目標: 將 CSS 和 JavaScript 從 index.html 分離狀態: 📋 待決策階段

📋 目錄

專案現況分析
優化目標與效益
需要決策的事項
建議的架構方案
分離策略
風險評估
執行計畫
驗收標準

專案現況分析

📊 當前檔案結構

d:\00001_Vibe_coding\1204剛為\
├── index.html           (約 4,700 行) ⚠️ 包含 HTML + CSS + JavaScript
├── login.html           (約 470 行)   ⚠️ 包含 HTML + CSS + JavaScript
├── hierarchical_data.js (已分離)     ✅ 組織架構資料
├── dropdown_data.js     (已分離)     ✅ 下拉選單資料
├── app.py               (Flask 後端)
├── .env                 (環境設定)
└── prompt.md            (AI Prompt 文件)

📈 當前 index.html 組成分析

內容類型	預估行數	佔比	說明
HTML 結構	~1,500 行	32%	5 個主要頁籤的表單結構
CSS 樣式	~700 行	15%	內嵌於 `<style>` 標籤中
JavaScript	~2,500 行	53%	內嵌於 `<script>` 標籤中

⚠️ 當前問題

維護困難: 單一檔案過於龐大，難以快速定位問題
協作不便: 多人同時修改容易產生衝突
載入效能: 無法利用瀏覽器快取分離的資源檔案
程式碼重用: CSS 和 JS 無法在其他頁面（如 login.html）重用
偵錯困難: 瀏覽器開發者工具中程式碼不易閱讀
版本控制: Git diff 難以追蹤具體修改內容

優化目標與效益

🎯 優化目標

分離關注點: HTML 結構、CSS 樣式、JavaScript 邏輯各自獨立
提升可維護性: 每個檔案職責單一，易於理解和修改
改善效能: 利用瀏覽器快取機制，減少重複載入
便於協作: 不同團隊成員可同時修改不同檔案
增強可測試性: JavaScript 獨立後更容易進行單元測試

📈 預期效益

效益項目	改善程度	說明
維護效率	⬆️ 40-60%	快速定位和修改程式碼
載入速度	⬆️ 20-30%	瀏覽器快取 CSS/JS 檔案
協作效率	⬆️ 50-70%	減少 Git 衝突，平行開發
程式碼重用	⬆️ 80-100%	CSS/JS 可在多個頁面共用
偵錯效率	⬆️ 30-50%	獨立檔案，Source Map 支援

需要決策的事項

🔔 請針對以下問題做出選擇，我會根據您的決策提供對應的實作方案

❓ 決策 1: CSS 分離策略

問題: 如何分離 CSS 樣式？

選項 A: 單一 CSS 檔案（簡單方案）✨ 推薦新手

styles/
└── main.css  (包含所有樣式)

優點:

✅ 結構簡單，易於實作
✅ 只需引入一個 CSS 檔案
✅ 適合小型專案

缺點:

❌ 單一檔案可能過大
❌ 不同頁面的樣式混在一起

選項 B: 模組化 CSS 檔案（推薦方案）✨ 推薦

styles/
├── base.css       (基礎樣式、CSS Reset、變數)
├── layout.css     (整體布局、Grid、Flexbox)
├── components.css (按鈕、表單、卡片等元件)
├── modules.css    (5 個頁籤的專屬樣式)
└── utilities.css  (工具類別、響應式)

優點:

✅ 職責分明，易於維護
✅ 可按需載入（未來優化）
✅ 符合業界最佳實踐

缺點:

❌ 需要管理多個檔案
❌ 初期設定較複雜

選項 C: 按頁籤分離 CSS（精細方案）

styles/
├── common.css           (共用樣式)
├── position-basic.css   (崗位基礎資料)
├── position-recruit.css (崗位招聘要求)
├── job-basic.css        (職務基礎資料)
├── dept-function.css    (部門職責維護)
├── job-desc.css         (崗位描述)
└── position-list.css    (崗位清單)

優點:

✅ 極度模組化
✅ 按需載入效能最佳
✅ 適合大型專案

缺點:

❌ 檔案數量多，管理複雜
❌ 共用樣式可能重複定義

您的選擇: [ ] A / [ ] B / [ ] C / [ ] 其他建議: _______________

❓ 決策 2: JavaScript 分離策略

問題: 如何組織 JavaScript 程式碼？

選項 A: 功能模組化（推薦方案）✨ 推薦

js/
├── config.js          (設定檔：API URL、常數)
├── utils.js           (工具函式：showToast、fillIfEmpty)
├── api.js             (API 呼叫：callClaudeAPI、fetch 相關)
├── ui.js              (UI 操作：switchModule、updatePreview)
├── form-handlers.js   (表單處理：驗證、提交)
├── ai-generators.js   (AI 生成函式：5 個 generate 函式)
├── dropdown.js        (下拉選單邏輯：階層式選單)
└── main.js            (主程式：初始化、事件監聽)

優點:

✅ 職責清晰，易於維護
✅ 符合 MVC/MVVM 架構思想
✅ 便於單元測試
✅ 符合業界最佳實踐

缺點:

❌ 需要處理模組間依賴關係
❌ 檔案數量較多

選項 B: 按頁籤分離（直觀方案）

js/
├── common.js              (共用功能)
├── position-basic.js      (崗位基礎資料)
├── position-recruit.js    (崗位招聘要求)
├── job-basic.js           (職務基礎資料)
├── dept-function.js       (部門職責維護)
├── job-desc.js            (崗位描述)
└── position-list.js       (崗位清單)

優點:

✅ 對應頁籤結構，直觀易懂
✅ 修改特定頁籤功能時容易定位

缺點:

❌ 共用函式可能在多個檔案重複
❌ 跨頁籤功能需要協調多個檔案

選項 C: 混合方案（平衡方案）✨ 折衷選擇

js/
├── core/
│   ├── config.js       (設定)
│   ├── utils.js        (工具)
│   ├── api.js          (API)
│   └── ui.js           (UI)
├── modules/
│   ├── position-basic.js
│   ├── position-recruit.js
│   ├── job-basic.js
│   ├── dept-function.js
│   ├── job-desc.js
│   └── position-list.js
└── main.js             (主程式)

優點:

✅ 兼具模組化與直觀性
✅ 核心功能集中管理
✅ 頁籤功能獨立開發

缺點:

❌ 目錄結構較複雜
❌ 需要規劃模組間通訊

您的選擇: [ ] A / [ ] B / [ ] C / [ ] 其他建議: _______________

❓ 決策 3: 模組載入方式

問題: 如何在 HTML 中載入分離後的 JS 檔案？

選項 A: 傳統 `<script>` 標籤（相容性最佳）✨ 推薦相容

<script src="js/config.js"></script>
<script src="js/utils.js"></script>
<script src="js/api.js"></script>
<!-- 按順序載入，注意依賴關係 -->

優點:

✅ 相容所有瀏覽器（包含 IE11）
✅ 不需要打包工具
✅ 實作簡單

缺點:

❌ 需要手動管理載入順序
❌ 全域命名空間污染風險
❌ 無法使用 import/export

選項 B: ES6 Modules（現代方案）✨ 推薦現代

<script type="module" src="js/main.js"></script>
<!-- main.js 中使用 import 載入其他模組 -->

// main.js
import { showToast } from './utils.js';
import { callClaudeAPI } from './api.js';

優點:

✅ 現代瀏覽器原生支援
✅ 自動處理依賴關係
✅ 避免全域污染
✅ 支援按需載入（Tree Shaking）

缺點:

❌ 不支援 IE11（需要 polyfill）
❌ 本地開發需要 HTTP Server（不能用 file:// 協議）
❌ 需要調整現有程式碼結構

選項 C: 打包工具（Webpack/Vite）（進階方案）

<script src="dist/bundle.js"></script>
<!-- 所有 JS 打包成單一檔案 -->

優點:

✅ 最佳效能（壓縮、優化）
✅ 支援所有瀏覽器
✅ 可使用 npm 套件
✅ 支援 TypeScript、Babel 等工具

缺點:

❌ 需要安裝 Node.js 和打包工具
❌ 開發流程變複雜（需要 build）
❌ 學習曲線較陡

您的選擇: [ ] A / [ ] B / [ ] C / [ ] 其他建議: _______________

❓ 決策 4: 共用樣式處理

問題: index.html 和 login.html 有部分共用樣式，如何處理？

選項 A: 建立共用樣式檔（推薦）✨ 推薦

styles/
├── common.css     (兩個頁面共用的樣式)
├── index.css      (index.html 專屬)
└── login.css      (login.html 專屬)

優點:

✅ 避免重複程式碼
✅ 樣式一致性高
✅ 修改一處，全站生效

缺點:

❌ 需要識別哪些是共用樣式

選項 B: 各自獨立（簡單方案）

styles/
├── index.css      (包含所有 index.html 需要的樣式)
└── login.css      (包含所有 login.html 需要的樣式)

優點:

✅ 實作最簡單
✅ 兩頁面完全獨立

缺點:

❌ 樣式重複（如按鈕、表單元件）
❌ 修改需要同步更新多處

您的選擇: [ ] A / [ ] B / [ ] 其他建議: _______________

❓ 決策 5: CSS 變數與主題管理

問題: 系統使用紫色漸層主題，是否要統一管理？

選項 A: 使用 CSS 變數（推薦）✨ 推薦

/* base.css */
:root {
    /* 主題色 */
    --primary-color: #667eea;
    --primary-dark: #764ba2;
    --gradient-primary: linear-gradient(135deg, #667eea 0%, #764ba2 100%);

    /* 語義化顏色 */
    --color-success: #10b981;
    --color-warning: #f59e0b;
    --color-danger: #ef4444;

    /* 間距 */
    --spacing-sm: 8px;
    --spacing-md: 16px;
    --spacing-lg: 24px;

    /* 字體 */
    --font-family: 'Microsoft JhengHei', 'Segoe UI', sans-serif;
    --font-size-base: 14px;
}

優點:

✅ 統一管理主題色
✅ 輕鬆實現換色/Dark Mode
✅ 語義化命名，易於理解

缺點:

❌ 不支援 IE11（需要 polyfill）

選項 B: 直接寫死顏色值（簡單方案）

.button {
    background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
}

優點:

✅ 相容所有瀏覽器
✅ 不需要額外設定

缺點:

❌ 修改主題色需要全局搜尋替換
❌ 無法動態切換主題

您的選擇: [ ] A / [ ] B / [ ] 其他建議: _______________

❓ 決策 6: 執行順序與回滾計畫

問題: 如何進行代碼分離，以降低風險？

選項 A: 一次性全部分離（快速方案）

執行步驟:

一次性建立所有 CSS/JS 檔案
從 index.html 移除所有 <style> 和 <script>
完整測試所有功能

優點:

✅ 快速完成重構
✅ 避免中間狀態

缺點:

❌ 風險較高，問題多時難以回滾
❌ 測試工作量大

選項 B: 分階段漸進式分離（穩健方案）✨ 推薦

階段 1: CSS 分離（1-2 天）

建立 CSS 檔案
測試樣式正確性
Git commit

階段 2: JavaScript 工具函式分離（1-2 天）

分離 utils.js、api.js
測試基礎功能
Git commit

階段 3: JavaScript 模組分離（2-3 天）

按選定策略分離各模組
逐一測試各頁籤功能
Git commit

階段 4: 優化與收尾（1 天）

程式碼審查
效能測試
文件更新

優點:

✅ 風險可控，問題易定位
✅ 每階段可獨立回滾
✅ 便於測試和驗證

缺點:

❌ 時間較長
❌ 可能存在中間狀態

選項 C: 建立平行版本（保守方案）

執行步驟:

複製 index.html 為 index-refactor.html
在新檔案中進行重構
完成後替換原檔案

優點:

✅ 最安全，隨時可回滾
✅ 可對比新舊版本

缺點:

❌ 需要維護兩個版本
❌ 浪費開發資源

您的選擇: [ ] A / [ ] B / [ ] C / [ ] 其他建議: _______________

❓ 決策 7: 命名規範

問題: 檔案和函式的命名風格？

選項 A: Kebab-case（檔案）+ camelCase（函式）✨ 推薦

檔案名稱: form-handlers.js, ai-generators.js
函式名稱: generatePositionBasic(), showToast()

優點:

✅ 符合業界慣例
✅ URL 友善（不需要編碼）

選項 B: camelCase（檔案）+ camelCase（函式）

檔案名稱: formHandlers.js, aiGenerators.js
函式名稱: generatePositionBasic(), showToast()

優點:

✅ 與 JavaScript 慣例一致

缺點:

❌ Windows/Mac 檔案系統可能有大小寫問題

選項 C: snake_case（檔案）+ camelCase（函式）

檔案名稱: form_handlers.js, ai_generators.js
函式名稱: generatePositionBasic(), showToast()

優點:

✅ Python 開發者熟悉

缺點:

❌ JavaScript 社群較少使用

您的選擇: [ ] A / [ ] B / [ ] C / [ ] 其他建議: _______________

❓ 決策 8: 瀏覽器相容性

問題: 系統需要支援哪些瀏覽器？

選項 A: 現代瀏覽器（Chrome/Firefox/Safari/Edge 最新版）✨ 推薦

技術選擇:

✅ 可使用 ES6 Modules
✅ 可使用 CSS Grid、Flexbox
✅ 可使用 CSS Variables
✅ 開發效率高

支援範圍:

Chrome 60+
Firefox 60+
Safari 11+
Edge 79+ (Chromium)

選項 B: 包含 IE11（企業環境）

技術選擇:

❌ 需要使用 Babel 轉譯
❌ 需要 CSS Variables polyfill
❌ 需要 Flexbox fallback
❌ 開發成本增加 30-50%

您的選擇: [ ] A / [ ] B / [ ] 其他說明: _______________

建議的架構方案

🏆 我的推薦配置（根據專案特性）

基於您的專案現況，我推薦以下配置：

✅ 決策 1: 選項 B - 模組化 CSS 檔案
✅ 決策 2: 選項 A - 功能模組化 JavaScript
✅ 決策 3: 選項 B - ES6 Modules（需要 HTTP Server）
✅ 決策 4: 選項 A - 建立共用樣式檔
✅ 決策 5: 選項 A - 使用 CSS 變數
✅ 決策 6: 選項 B - 分階段漸進式分離
✅ 決策 7: 選項 A - Kebab-case + camelCase
✅ 決策 8: 選項 A - 現代瀏覽器

📁 推薦的最終檔案結構

d:\00001_Vibe_coding\1204剛為\
├── index.html                  (僅 HTML 結構，約 1,500 行)
├── login.html                  (僅 HTML 結構，約 200 行)
│
├── styles/                     (CSS 樣式)
│   ├── base.css               (基礎樣式、變數、Reset)
│   ├── layout.css             (整體布局)
│   ├── components.css         (按鈕、表單、卡片元件)
│   ├── modules.css            (5 個頁籤的專屬樣式)
│   ├── utilities.css          (工具類別)
│   └── login.css              (登入頁專屬樣式)
│
├── js/                        (JavaScript 程式碼)
│   ├── config.js              (設定：API URL、常數)
│   ├── utils.js               (工具函式)
│   ├── api.js                 (API 呼叫)
│   ├── ui.js                  (UI 操作)
│   ├── form-handlers.js       (表單處理)
│   ├── ai-generators.js       (AI 生成函式)
│   ├── dropdown.js            (下拉選單邏輯)
│   ├── validators.js          (表單驗證)
│   └── main.js                (主程式、初始化)
│
├── data/                      (資料檔案 - 已存在)
│   ├── hierarchical_data.js   ✅ 已存在
│   └── dropdown_data.js       ✅ 已存在
│
├── docs/                      (文件)
│   ├── prompt.md              ✅ 已存在
│   ├── 權限矩陣.md             ✅ 已存在
│   └── SDD_代碼分離優化.md     (本文件)
│
├── app.py                     ✅ 後端程式
├── .env                       ✅ 環境設定
├── .gitignore
└── README.md

分離策略

📝 CSS 分離策略詳解

1. base.css - 基礎樣式（約 150 行）

/**
 * CSS Variables - 主題色、間距、字體
 * CSS Reset - Normalize.css
 * 全域樣式 - body, html, *
 */

包含內容:

CSS 變數定義（顏色、間距、字體、陰影等）
CSS Reset（統一瀏覽器預設樣式）
全域樣式（body、html、通用選擇器）

2. layout.css - 布局樣式（約 100 行）

/**
 * Container - 容器
 * Grid System - 網格系統
 * Flexbox Layout - 彈性布局
 * Header/Footer - 頁首頁尾
 */

包含內容:

.container、.main-content
Grid 和 Flexbox 布局類別
頁面整體結構（header、footer、sidebar）

3. components.css - 元件樣式（約 250 行）

/**
 * Buttons - 按鈕（.btn-primary, .ai-generate-btn）
 * Forms - 表單（.form-group, input, select, textarea）
 * Cards - 卡片（.info-card, .module-card）
 * Tabs - 頁籤（.tab-nav, .tab-panel）
 * Modals - 彈窗
 * Toast - 提示訊息
 */

包含內容:

可重用的 UI 元件
按鈕樣式（各種變體）
表單元件（input、select、textarea、checkbox）
卡片、頁籤、彈窗等元件

4. modules.css - 模組樣式（約 150 行）

/**
 * Position Basic - 崗位基礎資料模組
 * Position Recruit - 崗位招聘要求模組
 * Job Basic - 職務基礎資料模組
 * Dept Function - 部門職責維護模組
 * Job Desc - 崗位描述模組
 * Position List - 崗位清單模組
 */

包含內容:

各頁籤的專屬樣式
特殊布局需求
模組內的特殊元件

5. utilities.css - 工具類別（約 50 行）

/**
 * Spacing - 間距（m-1, p-2）
 * Text - 文字（text-center, text-bold）
 * Display - 顯示（d-none, d-block）
 * Colors - 顏色（text-primary, bg-success）
 * Responsive - 響應式（@media）
 */

包含內容:

快速工具類別
響應式斷點
常用的單一用途類別

💻 JavaScript 分離策略詳解

1. config.js - 設定檔（約 50 行）

/**
 * API 端點設定
 * 常數定義
 * 環境設定
 */
export const API_BASE_URL = 'http://127.0.0.1:5000/api';
export const TOAST_DURATION = 3000;
export const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB

2. utils.js - 工具函式（約 200 行）

/**
 * showToast() - 顯示提示訊息
 * fillIfEmpty() - 填充空白欄位
 * getFieldValue() - 取得欄位值
 * setButtonLoading() - 設定按鈕載入狀態
 * formatDate() - 日期格式化
 * debounce() - 防抖函式
 */
export function showToast(message, type = 'info') { ... }
export function fillIfEmpty(fieldId, value) { ... }

3. api.js - API 呼叫（約 150 行）

/**
 * callClaudeAPI() - 呼叫 LLM API
 * fetchPositions() - 取得崗位清單
 * createPosition() - 建立崗位
 * updatePosition() - 更新崗位
 * deletePosition() - 刪除崗位
 */
export async function callClaudeAPI(prompt) { ... }
export async function fetchPositions() { ... }

4. ui.js - UI 操作（約 300 行）

/**
 * switchModule() - 切換模組
 * updatePreview() - 更新預覽
 * showModal() - 顯示彈窗
 * hideModal() - 隱藏彈窗
 * renderPositionList() - 渲染崗位清單
 */
export function switchModule(moduleName) { ... }
export function updatePreview() { ... }

5. form-handlers.js - 表單處理（約 400 行）

/**
 * validatePositionForm() - 驗證崗位表單
 * submitPositionForm() - 提交崗位表單
 * clearForm() - 清除表單
 * saveToPositionList() - 儲存至崗位清單
 */
export function validatePositionForm() { ... }
export async function submitPositionForm() { ... }

6. ai-generators.js - AI 生成（約 500 行）

/**
 * generatePositionBasic() - 生成崗位基礎資料
 * generatePositionRecruit() - 生成崗位招聘要求
 * generateJobBasic() - 生成職務基礎資料
 * generateDeptFunction() - 生成部門職責
 * generateJobDesc() - 生成崗位描述
 */
export async function generatePositionBasic() { ... }
export async function generatePositionRecruit() { ... }

7. dropdown.js - 下拉選單（約 300 行）

/**
 * initializeDropdowns() - 初始化下拉選單
 * onBusinessUnitChange() - 事業體改變處理
 * onDivisionChange() - 處級單位改變處理
 * onDepartmentChange() - 部級單位改變處理
 * updatePositionDropdown() - 更新崗位下拉選單
 */
export function initializeDropdowns() { ... }
export function onBusinessUnitChange(event) { ... }

8. validators.js - 表單驗證（約 200 行）

/**
 * validateRequired() - 驗證必填欄位
 * validateEmail() - 驗證電子郵件
 * validateDate() - 驗證日期格式
 * validateNumber() - 驗證數字範圍
 */
export function validateRequired(value) { ... }
export function validateEmail(email) { ... }

9. main.js - 主程式（約 150 行）

/**
 * 初始化應用程式
 * 設定事件監聽器
 * 載入使用者資訊
 * 啟動應用
 */
import { initializeDropdowns } from './dropdown.js';
import { loadUserInfo } from './ui.js';
import { API_BASE_URL } from './config.js';

document.addEventListener('DOMContentLoaded', () => {
    loadUserInfo();
    initializeDropdowns();
    // ... 其他初始化邏輯
});

風險評估

⚠️ 潛在風險與對策

風險項目	風險等級	影響範圍	對策
載入順序錯誤	🔴 高	功能失效	使用 ES6 Modules 自動處理依賴
全域變數衝突	🟡 中	部分功能異常	使用模組化，避免全域污染
快取問題	🟡 中	更新未生效	使用版本號 `?v=1.0.0`
路徑錯誤	🟢 低	載入失敗	使用相對路徑，充分測試
效能下降	🟢 低	載入變慢	HTTP/2 多路復用，瀏覽器快取
回滾困難	🟡 中	無法還原	分階段執行，每階段 Git commit

執行計畫

📅 分階段執行時程（選項 B）

階段 1️⃣: CSS 分離（預估 1-2 天）

Day 1 上午: CSS 檔案建立

建立 styles/ 目錄
建立 base.css（CSS 變數、Reset）
建立 layout.css（布局）
建立 components.css（元件）
建立 modules.css（模組）
建立 utilities.css（工具）

Day 1 下午: CSS 程式碼搬移

從 index.html 複製 CSS 到對應檔案
轉換硬編碼顏色為 CSS 變數
在 index.html 引入 CSS 檔案

Day 2 上午: CSS 測試

測試各頁籤樣式正確性
測試響應式布局
測試按鈕、表單、卡片元件
修正樣式問題

Day 2 下午: CSS 優化與提交

檢查是否有重複樣式
優化選擇器效能
Git commit: "refactor: separate CSS from index.html"

階段 2️⃣: JavaScript 工具函式分離（預估 1-2 天）

Day 3 上午: 建立核心模組

建立 js/ 目錄
建立 config.js（設定）
建立 utils.js（工具函式）
建立 api.js（API 呼叫）

Day 3 下午: 搬移工具函式

搬移 showToast()
搬移 fillIfEmpty()
搬移 getFieldValue()
搬移 setButtonLoading()
搬移 callClaudeAPI()

Day 4 上午: 測試核心功能

測試 Toast 提示
測試 API 呼叫
測試欄位填充
測試按鈕載入狀態

Day 4 下午: 提交

Git commit: "refactor: separate utils and api modules"

階段 3️⃣: JavaScript 模組分離（預估 2-3 天）

Day 5: UI 與表單處理

建立 ui.js
建立 form-handlers.js
建立 validators.js
搬移相關函式
測試表單功能
Git commit

Day 6: AI 生成與下拉選單

建立 ai-generators.js
建立 dropdown.js
搬移 5 個 AI 生成函式
搬移下拉選單邏輯
測試 AI 生成功能
測試階層式下拉選單
Git commit

Day 7: 主程式整合

建立 main.js
設定模組匯入
整合所有模組
完整功能測試
Git commit

階段 4️⃣: 優化與收尾（預估 1 天）

Day 8 上午: 程式碼審查

檢查模組依賴關係
檢查是否有遺漏的函式
檢查命名一致性
檢查註解文件

Day 8 下午: 效能測試與文件

測試頁面載入速度
測試瀏覽器快取
更新 README.md
更新開發文件
Git commit: "docs: update documentation for refactored code"

🔄 每日檢查清單

每天開發前:

拉取最新程式碼 git pull
建立功能分支（如有需要）
備份當前版本

每天開發後:

執行完整測試
Commit 當日進度
更新進度表
記錄遇到的問題

驗收標準

✅ 功能驗收清單

1. CSS 分離驗收

所有頁籤樣式正確顯示
按鈕顏色與漸層正確
表單元件樣式一致
響應式布局正常
沒有樣式閃爍（FOUC）
瀏覽器開發者工具無 CSS 錯誤

2. JavaScript 分離驗收

所有頁籤功能正常
AI 生成功能正常
表單驗證正常
下拉選單連動正常
Toast 提示顯示正常
API 呼叫正常
瀏覽器 Console 無錯誤

3. 效能驗收

首次載入時間 ≤ 3 秒
後續載入時間 ≤ 1 秒（快取生效）
無記憶體洩漏
CPU 使用率正常

4. 相容性驗收

Chrome 最新版正常
Firefox 最新版正常
Safari 最新版正常（如需支援）
Edge 最新版正常

5. 程式碼品質驗收

檔案結構清晰
命名規範一致
註解完整
無重複程式碼
模組依賴清晰

📊 效能指標

指標項目	當前值	目標值	驗收標準
首次載入時間	~2.5s	≤ 3s	✅ 通過
快取載入時間	N/A	≤ 1s	待測試
CSS 檔案大小	內嵌	≤ 100KB	待測試
JS 檔案大小	內嵌	≤ 300KB	待測試
HTTP 請求數	3-5 個	≤ 15 個	待測試

附錄

📚 參考資源

技術文件

最佳實踐

🔧 開發工具建議

HTTP Server（本地開發）

如果選擇 ES6 Modules，需要使用 HTTP Server：

選項 1: Python HTTP Server

cd d:\00001_Vibe_coding\1204剛為
python -m http.server 8000
# 瀏覽器開啟: http://localhost:8000

選項 2: Live Server（VS Code 套件）

安裝 VS Code 套件「Live Server」
右鍵點擊 index.html → "Open with Live Server"

選項 3: Node.js http-server

npm install -g http-server
cd d:\00001_Vibe_coding\1204剛為
http-server -p 8000

📝 Git Commit 規範建議

feat: 新功能
fix: 修復 Bug
refactor: 重構（不影響功能）
style: 樣式調整（不影響程式邏輯）
docs: 文件更新
test: 測試相關
chore: 建構工具或輔助工具變動

範例:

git commit -m "refactor: separate CSS into modular files"
git commit -m "refactor: extract utils and api modules"
git commit -m "docs: update SDD with final architecture"

決策回覆表單

請將您的決策填寫在下方，我會根據您的選擇提供對應的實作方案：

=== 決策回覆表單 ===

決策 1 (CSS 分離策略): [ ]
決策 2 (JavaScript 分離策略): [ ]
決策 3 (模組載入方式): [ ]
決策 4 (共用樣式處理): [ ]
決策 5 (CSS 變數與主題): [ ]
決策 6 (執行順序): [ ]
決策 7 (命名規範): [ ]
決策 8 (瀏覽器相容性): [ ]

其他需求或建議:
_____________________________________
_____________________________________
_____________________________________

=== 表單結束 ===

文件狀態: 📋 等待決策 下一步: 請您填寫決策後，我將提供詳細的實作步驟與程式碼範例

提醒: 此 SDD 文件會隨著專案進展持續更新。如有任何疑問或需要調整，歡迎隨時討論。

¯\(ツ)/¯ 那都AI寫的，不要問我

28 KiB Raw Blame History Unescape Escape

軟體設計文件 (SDD) - 代碼分離優化

📋 目錄

專案現況分析

📊 當前檔案結構

📈 當前 index.html 組成分析

⚠️ 當前問題

優化目標與效益

🎯 優化目標

📈 預期效益

需要決策的事項

❓ 決策 1: CSS 分離策略

選項 A: 單一 CSS 檔案（簡單方案）✨ 推薦新手

選項 B: 模組化 CSS 檔案（推薦方案）✨ 推薦

選項 C: 按頁籤分離 CSS（精細方案）

❓ 決策 2: JavaScript 分離策略

選項 A: 功能模組化（推薦方案）✨ 推薦

選項 B: 按頁籤分離（直觀方案）

選項 C: 混合方案（平衡方案）✨ 折衷選擇

❓ 決策 3: 模組載入方式

選項 A: 傳統 <script> 標籤（相容性最佳）✨ 推薦相容

選項 B: ES6 Modules（現代方案）✨ 推薦現代

選項 C: 打包工具（Webpack/Vite）（進階方案）

❓ 決策 4: 共用樣式處理

選項 A: 建立共用樣式檔（推薦）✨ 推薦

選項 B: 各自獨立（簡單方案）

❓ 決策 5: CSS 變數與主題管理

選項 A: 使用 CSS 變數（推薦）✨ 推薦

選項 B: 直接寫死顏色值（簡單方案）

❓ 決策 6: 執行順序與回滾計畫

選項 A: 一次性全部分離（快速方案）

選項 B: 分階段漸進式分離（穩健方案）✨ 推薦

選項 C: 建立平行版本（保守方案）

❓ 決策 7: 命名規範

選項 A: Kebab-case（檔案）+ camelCase（函式）✨ 推薦

選項 B: camelCase（檔案）+ camelCase（函式）

選項 C: snake_case（檔案）+ camelCase（函式）

❓ 決策 8: 瀏覽器相容性

選項 A: 現代瀏覽器（Chrome/Firefox/Safari/Edge 最新版）✨ 推薦

選項 B: 包含 IE11（企業環境）

建議的架構方案

🏆 我的推薦配置（根據專案特性）

📁 推薦的最終檔案結構

分離策略

📝 CSS 分離策略詳解

1. base.css - 基礎樣式（約 150 行）

2. layout.css - 布局樣式（約 100 行）

3. components.css - 元件樣式（約 250 行）

4. modules.css - 模組樣式（約 150 行）

5. utilities.css - 工具類別（約 50 行）

💻 JavaScript 分離策略詳解

1. config.js - 設定檔（約 50 行）

2. utils.js - 工具函式（約 200 行）

3. api.js - API 呼叫（約 150 行）

4. ui.js - UI 操作（約 300 行）

5. form-handlers.js - 表單處理（約 400 行）

6. ai-generators.js - AI 生成（約 500 行）

7. dropdown.js - 下拉選單（約 300 行）

8. validators.js - 表單驗證（約 200 行）

9. main.js - 主程式（約 150 行）

風險評估

⚠️ 潛在風險與對策

執行計畫

📅 分階段執行時程（選項 B）

階段 1️⃣: CSS 分離（預估 1-2 天）

階段 2️⃣: JavaScript 工具函式分離（預估 1-2 天）

階段 3️⃣: JavaScript 模組分離（預估 2-3 天）

階段 4️⃣: 優化與收尾（預估 1 天）

🔄 每日檢查清單

驗收標準

✅ 功能驗收清單

1. CSS 分離驗收

2. JavaScript 分離驗收

3. 效能驗收

4. 相容性驗收

5. 程式碼品質驗收

📊 效能指標

附錄

📚 參考資源

技術文件

28 KiB

Raw Blame History

選項 A: 傳統 `<script>` 標籤（相容性最佳）✨ 推薦相容