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
parent a068ef9704
commit a6af297623
82 changed files with 8685 additions and 4933 deletions
--- a/SDD_代碼分離優化.md
+++ b/SDD_代碼分離優化.md
@@ -1,567 +1,5 @@
 # 軟體設計文件 (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 - 現代瀏覽器
-```

 ### 📁 推薦的最終檔案結構