hr-position-system/SDD_代碼分離優化.md

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

📁 推薦的最終檔案結構

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 個	待測試

---

附錄

📚 參考資源

技術文件

• ES6 Modules - MDN
• CSS Variables - MDN
• Airbnb JavaScript Style Guide

最佳實踐

• Google HTML/CSS Style Guide
• Clean Code JavaScript

---

🔧 開發工具建議

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寫的，不要問我