DonaldFang 方士碩
a6af297623
變更內容： - 所有資料表加上 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>
1121 lines
28 KiB
Markdown
1121 lines
28 KiB
Markdown
# 軟體設計文件 (SDD) - 代碼分離優化
|
||
|
||
> **文件版本**: v1.0
|
||
> **建立日期**: 2024-12-04
|
||
> **專案名稱**: HR Position Management System
|
||
> **優化目標**: 將 CSS 和 JavaScript 從 index.html 分離
|
||
> **狀態**: 📋 待決策階段
|
||
|
||
---
|
||
|
||
## 📋 目錄
|
||
|
||
1. [專案現況分析](#專案現況分析)
|
||
2. [優化目標與效益](#優化目標與效益)
|
||
3. [需要決策的事項](#需要決策的事項)
|
||
4. [建議的架構方案](#建議的架構方案)
|
||
5. [分離策略](#分離策略)
|
||
6. [風險評估](#風險評估)
|
||
7. [執行計畫](#執行計畫)
|
||
8. [驗收標準](#驗收標準)
|
||
|
||
---
|
||
|
||
## 專案現況分析
|
||
|
||
### 📊 當前檔案結構
|
||
|
||
```
|
||
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>` 標籤中 |
|
||
|
||
### ⚠️ 當前問題
|
||
|
||
1. **維護困難**: 單一檔案過於龐大，難以快速定位問題
|
||
2. **協作不便**: 多人同時修改容易產生衝突
|
||
3. **載入效能**: 無法利用瀏覽器快取分離的資源檔案
|
||
4. **程式碼重用**: CSS 和 JS 無法在其他頁面（如 login.html）重用
|
||
5. **偵錯困難**: 瀏覽器開發者工具中程式碼不易閱讀
|
||
6. **版本控制**: Git diff 難以追蹤具體修改內容
|
||
|
||
---
|
||
|
||
## 優化目標與效益
|
||
|
||
### 🎯 優化目標
|
||
|
||
1. **分離關注點**: HTML 結構、CSS 樣式、JavaScript 邏輯各自獨立
|
||
2. **提升可維護性**: 每個檔案職責單一，易於理解和修改
|
||
3. **改善效能**: 利用瀏覽器快取機制，減少重複載入
|
||
4. **便於協作**: 不同團隊成員可同時修改不同檔案
|
||
5. **增強可測試性**: 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>` 標籤（相容性最佳）✨ 推薦相容
|
||
```html
|
||
<script src="js/config.js"></script>
|
||
<script src="js/utils.js"></script>
|
||
<script src="js/api.js"></script>
|
||
<!-- 按順序載入，注意依賴關係 -->
|
||
```
|
||
**優點**:
|
||
- ✅ 相容所有瀏覽器（包含 IE11）
|
||
- ✅ 不需要打包工具
|
||
- ✅ 實作簡單
|
||
|
||
**缺點**:
|
||
- ❌ 需要手動管理載入順序
|
||
- ❌ 全域命名空間污染風險
|
||
- ❌ 無法使用 `import/export`
|
||
|
||
---
|
||
|
||
#### 選項 B: ES6 Modules（現代方案）✨ 推薦現代
|
||
```html
|
||
<script type="module" src="js/main.js"></script>
|
||
<!-- main.js 中使用 import 載入其他模組 -->
|
||
```
|
||
```javascript
|
||
// main.js
|
||
import { showToast } from './utils.js';
|
||
import { callClaudeAPI } from './api.js';
|
||
```
|
||
**優點**:
|
||
- ✅ 現代瀏覽器原生支援
|
||
- ✅ 自動處理依賴關係
|
||
- ✅ 避免全域污染
|
||
- ✅ 支援按需載入（Tree Shaking）
|
||
|
||
**缺點**:
|
||
- ❌ 不支援 IE11（需要 polyfill）
|
||
- ❌ 本地開發需要 HTTP Server（不能用 file:// 協議）
|
||
- ❌ 需要調整現有程式碼結構
|
||
|
||
---
|
||
|
||
#### 選項 C: 打包工具（Webpack/Vite）（進階方案）
|
||
```html
|
||
<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 變數（推薦）✨ 推薦
|
||
```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: 直接寫死顏色值（簡單方案）
|
||
```css
|
||
.button {
|
||
background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
|
||
}
|
||
```
|
||
**優點**:
|
||
- ✅ 相容所有瀏覽器
|
||
- ✅ 不需要額外設定
|
||
|
||
**缺點**:
|
||
- ❌ 修改主題色需要全局搜尋替換
|
||
- ❌ 無法動態切換主題
|
||
|
||
---
|
||
|
||
**您的選擇**: [ ] A / [ ] B / [ ] 其他建議: _______________
|
||
|
||
---
|
||
|
||
### ❓ 決策 6: 執行順序與回滾計畫
|
||
|
||
**問題**: 如何進行代碼分離，以降低風險？
|
||
|
||
#### 選項 A: 一次性全部分離（快速方案）
|
||
**執行步驟**:
|
||
1. 一次性建立所有 CSS/JS 檔案
|
||
2. 從 index.html 移除所有 `<style>` 和 `<script>`
|
||
3. 完整測試所有功能
|
||
|
||
**優點**:
|
||
- ✅ 快速完成重構
|
||
- ✅ 避免中間狀態
|
||
|
||
**缺點**:
|
||
- ❌ 風險較高，問題多時難以回滾
|
||
- ❌ 測試工作量大
|
||
|
||
---
|
||
|
||
#### 選項 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: 建立平行版本（保守方案）
|
||
**執行步驟**:
|
||
1. 複製 index.html 為 index-refactor.html
|
||
2. 在新檔案中進行重構
|
||
3. 完成後替換原檔案
|
||
|
||
**優點**:
|
||
- ✅ 最安全，隨時可回滾
|
||
- ✅ 可對比新舊版本
|
||
|
||
**缺點**:
|
||
- ❌ 需要維護兩個版本
|
||
- ❌ 浪費開發資源
|
||
|
||
---
|
||
|
||
**您的選擇**: [ ] 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
|
||
/**
|
||
* CSS Variables - 主題色、間距、字體
|
||
* CSS Reset - Normalize.css
|
||
* 全域樣式 - body, html, *
|
||
*/
|
||
```
|
||
**包含內容**:
|
||
- CSS 變數定義（顏色、間距、字體、陰影等）
|
||
- CSS Reset（統一瀏覽器預設樣式）
|
||
- 全域樣式（body、html、通用選擇器）
|
||
|
||
---
|
||
|
||
#### 2. layout.css - 布局樣式（約 100 行）
|
||
```css
|
||
/**
|
||
* Container - 容器
|
||
* Grid System - 網格系統
|
||
* Flexbox Layout - 彈性布局
|
||
* Header/Footer - 頁首頁尾
|
||
*/
|
||
```
|
||
**包含內容**:
|
||
- `.container`、`.main-content`
|
||
- Grid 和 Flexbox 布局類別
|
||
- 頁面整體結構（header、footer、sidebar）
|
||
|
||
---
|
||
|
||
#### 3. components.css - 元件樣式（約 250 行）
|
||
```css
|
||
/**
|
||
* 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 行）
|
||
```css
|
||
/**
|
||
* Position Basic - 崗位基礎資料模組
|
||
* Position Recruit - 崗位招聘要求模組
|
||
* Job Basic - 職務基礎資料模組
|
||
* Dept Function - 部門職責維護模組
|
||
* Job Desc - 崗位描述模組
|
||
* Position List - 崗位清單模組
|
||
*/
|
||
```
|
||
**包含內容**:
|
||
- 各頁籤的專屬樣式
|
||
- 特殊布局需求
|
||
- 模組內的特殊元件
|
||
|
||
---
|
||
|
||
#### 5. utilities.css - 工具類別（約 50 行）
|
||
```css
|
||
/**
|
||
* 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 行）
|
||
```javascript
|
||
/**
|
||
* 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 行）
|
||
```javascript
|
||
/**
|
||
* showToast() - 顯示提示訊息
|
||
* fillIfEmpty() - 填充空白欄位
|
||
* getFieldValue() - 取得欄位值
|
||
* setButtonLoading() - 設定按鈕載入狀態
|
||
* formatDate() - 日期格式化
|
||
* debounce() - 防抖函式
|
||
*/
|
||
export function showToast(message, type = 'info') { ... }
|
||
export function fillIfEmpty(fieldId, value) { ... }
|
||
```
|
||
|
||
---
|
||
|
||
#### 3. api.js - API 呼叫（約 150 行）
|
||
```javascript
|
||
/**
|
||
* callClaudeAPI() - 呼叫 LLM API
|
||
* fetchPositions() - 取得崗位清單
|
||
* createPosition() - 建立崗位
|
||
* updatePosition() - 更新崗位
|
||
* deletePosition() - 刪除崗位
|
||
*/
|
||
export async function callClaudeAPI(prompt) { ... }
|
||
export async function fetchPositions() { ... }
|
||
```
|
||
|
||
---
|
||
|
||
#### 4. ui.js - UI 操作（約 300 行）
|
||
```javascript
|
||
/**
|
||
* switchModule() - 切換模組
|
||
* updatePreview() - 更新預覽
|
||
* showModal() - 顯示彈窗
|
||
* hideModal() - 隱藏彈窗
|
||
* renderPositionList() - 渲染崗位清單
|
||
*/
|
||
export function switchModule(moduleName) { ... }
|
||
export function updatePreview() { ... }
|
||
```
|
||
|
||
---
|
||
|
||
#### 5. form-handlers.js - 表單處理（約 400 行）
|
||
```javascript
|
||
/**
|
||
* validatePositionForm() - 驗證崗位表單
|
||
* submitPositionForm() - 提交崗位表單
|
||
* clearForm() - 清除表單
|
||
* saveToPositionList() - 儲存至崗位清單
|
||
*/
|
||
export function validatePositionForm() { ... }
|
||
export async function submitPositionForm() { ... }
|
||
```
|
||
|
||
---
|
||
|
||
#### 6. ai-generators.js - AI 生成（約 500 行）
|
||
```javascript
|
||
/**
|
||
* generatePositionBasic() - 生成崗位基礎資料
|
||
* generatePositionRecruit() - 生成崗位招聘要求
|
||
* generateJobBasic() - 生成職務基礎資料
|
||
* generateDeptFunction() - 生成部門職責
|
||
* generateJobDesc() - 生成崗位描述
|
||
*/
|
||
export async function generatePositionBasic() { ... }
|
||
export async function generatePositionRecruit() { ... }
|
||
```
|
||
|
||
---
|
||
|
||
#### 7. dropdown.js - 下拉選單（約 300 行）
|
||
```javascript
|
||
/**
|
||
* initializeDropdowns() - 初始化下拉選單
|
||
* onBusinessUnitChange() - 事業體改變處理
|
||
* onDivisionChange() - 處級單位改變處理
|
||
* onDepartmentChange() - 部級單位改變處理
|
||
* updatePositionDropdown() - 更新崗位下拉選單
|
||
*/
|
||
export function initializeDropdowns() { ... }
|
||
export function onBusinessUnitChange(event) { ... }
|
||
```
|
||
|
||
---
|
||
|
||
#### 8. validators.js - 表單驗證（約 200 行）
|
||
```javascript
|
||
/**
|
||
* validateRequired() - 驗證必填欄位
|
||
* validateEmail() - 驗證電子郵件
|
||
* validateDate() - 驗證日期格式
|
||
* validateNumber() - 驗證數字範圍
|
||
*/
|
||
export function validateRequired(value) { ... }
|
||
export function validateEmail(email) { ... }
|
||
```
|
||
|
||
---
|
||
|
||
#### 9. main.js - 主程式（約 150 行）
|
||
```javascript
|
||
/**
|
||
* 初始化應用程式
|
||
* 設定事件監聽器
|
||
* 載入使用者資訊
|
||
* 啟動應用
|
||
*/
|
||
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](https://developer.mozilla.org/zh-TW/docs/Web/JavaScript/Guide/Modules)
|
||
- [CSS Variables - MDN](https://developer.mozilla.org/zh-TW/docs/Web/CSS/Using_CSS_custom_properties)
|
||
- [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript)
|
||
|
||
#### 最佳實踐
|
||
- [Google HTML/CSS Style Guide](https://google.github.io/styleguide/htmlcssguide.html)
|
||
- [Clean Code JavaScript](https://github.com/ryanmcdermott/clean-code-javascript)
|
||
|
||
---
|
||
|
||
### 🔧 開發工具建議
|
||
|
||
#### HTTP Server（本地開發）
|
||
如果選擇 ES6 Modules，需要使用 HTTP Server：
|
||
|
||
**選項 1: Python HTTP Server**
|
||
```bash
|
||
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**
|
||
```bash
|
||
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: 建構工具或輔助工具變動
|
||
```
|
||
|
||
**範例**:
|
||
```bash
|
||
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寫的，不要問我
|