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/docs/TDD.md
+++ b/docs/TDD.md
@@ -0,0 +1,496 @@
+# HR 基礎資料維護系統 - 測試設計文件 (TDD)
+
+**文件版本**：1.1
+**建立日期**：2024-12-06
+**最後更新**：2025-12-08
+**文件狀態**：Draft
+
+---
+
+## 1. 文件概述
+
+### 1.1 目的
+
+本文件為 HR 基礎資料維護系統之測試設計文件 (Test Design Document)，描述測試策略、測試範圍、測試案例設計與驗收標準，供測試人員與開發人員參考。
+
+### 1.2 範圍
+
+本測試涵蓋以下功能模組：
+
+| 模組 | 測試重點 |
+|------|----------|
+| 崗位基礎資料 | CRUD 操作、欄位驗證、資料聯動 |
+| 職務基礎資料 | CRUD 操作、類別關聯、Toggle 控件 |
+| 部門職責 | CRUD 操作、組織層級聯動 |
+| 崗位描述 | CRUD 操作、版本控制 |
+| AI 幫我想 | LLM 呼叫、JSON 解析、Prompt 編輯、結果填入 |
+| 崗位清單 | 列表顯示、搜尋過濾、資料匯出 |
+| 組織階層 | 事業體/處級/部級單位、級聯選擇、API 查詢 |
+| CSV 匯入匯出 | 批次匯入、範本下載、資料驗證 |
+
+### 1.3 參考文件
+
+- 軟體設計文件 (SDD.md)
+- API 設計規範
+- 需求確認文件
+
+---
+
+## 2. 測試策略
+
+### 2.1 測試層次
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    E2E 測試 (End-to-End)                │
+│  ┌─────────────────────────────────────────────────┐   │
+│  │              整合測試 (Integration)               │   │
+│  │  ┌─────────────────────────────────────────┐   │   │
+│  │  │           單元測試 (Unit)                │   │   │
+│  │  │  ┌─────────────────────────────────┐   │   │   │
+│  │  │  │       函數 / API / 元件          │   │   │   │
+│  │  │  └─────────────────────────────────┘   │   │   │
+│  │  └─────────────────────────────────────────┘   │   │
+│  └─────────────────────────────────────────────────┘   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### 2.2 測試類型
+
+| 類型 | 說明 | 工具 |
+|------|------|------|
+| 單元測試 | 測試單一函數或模組 | Jest / pytest |
+| 整合測試 | 測試模組間互動 | pytest |
+| API 測試 | 測試 RESTful API | Postman / pytest |
+| UI 測試 | 測試使用者介面 | 手動測試 / Selenium |
+| 效能測試 | 測試系統效能 | Apache JMeter |
+
+### 2.3 測試環境
+
+| 環境 | 配置 |
+|------|------|
+| 前端 | Chrome/Firefox/Edge 最新版 |
+| 後端 | Python 3.9+, Flask 2.0+ |
+| LLM | Ollama localhost:11434 |
+| 資料庫 | In-Memory (測試環境) |
+
+---
+
+## 3. 功能測試案例
+
+### 3.1 崗位基礎資料模組
+
+#### 3.1.1 新增崗位
+
+| TC-ID | TC-POS-001 |
+|-------|------------|
+| 測試名稱 | 新增崗位 - 正常流程 |
+| 前置條件 | 系統已啟動，用戶在崗位基礎資料頁面 |
+| 測試步驟 | 1. 輸入崗位編號 "ENG-001"<br>2. 輸入崗位名稱 "資深軟體工程師"<br>3. 選擇崗位類別 "技術職"<br>4. 點擊「保存」按鈕 |
+| 預期結果 | 顯示「保存成功」Toast，資料寫入成功 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-POS-002 |
+|-------|------------|
+| 測試名稱 | 新增崗位 - 必填欄位驗證 |
+| 前置條件 | 系統已啟動，用戶在崗位基礎資料頁面 |
+| 測試步驟 | 1. 不輸入崗位編號<br>2. 不輸入崗位名稱<br>3. 點擊「保存」按鈕 |
+| 預期結果 | 顯示錯誤訊息「請填寫必填欄位」 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-POS-003 |
+|-------|------------|
+| 測試名稱 | 新增崗位 - 編號重複檢查 |
+| 前置條件 | 已存在編號 "ENG-001" 的崗位 |
+| 測試步驟 | 1. 輸入崗位編號 "ENG-001"<br>2. 輸入其他欄位<br>3. 點擊「保存」按鈕 |
+| 預期結果 | 顯示錯誤訊息「崗位編號已存在」 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+#### 3.1.2 編輯崗位
+
+| TC-ID | TC-POS-004 |
+|-------|------------|
+| 測試名稱 | 編輯崗位 - 正常流程 |
+| 前置條件 | 已存在崗位 "ENG-001" |
+| 測試步驟 | 1. 瀏覽至崗位 "ENG-001"<br>2. 修改崗位名稱為 "高級軟體工程師"<br>3. 點擊「保存」按鈕 |
+| 預期結果 | 顯示「更新成功」Toast，資料已更新 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+#### 3.1.3 刪除崗位
+
+| TC-ID | TC-POS-005 |
+|-------|------------|
+| 測試名稱 | 刪除崗位 - 正常流程 |
+| 前置條件 | 已存在崗位 "ENG-001" |
+| 測試步驟 | 1. 瀏覽至崗位 "ENG-001"<br>2. 點擊「刪除」按鈕<br>3. 確認刪除 |
+| 預期結果 | 顯示「刪除成功」Toast，資料已移除 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+### 3.2 職務基礎資料模組
+
+| TC-ID | TC-JOB-001 |
+|-------|------------|
+| 測試名稱 | 新增職務 - 正常流程 |
+| 前置條件 | 系統已啟動，用戶在職務基礎資料頁面 |
+| 測試步驟 | 1. 選擇職務類別 "技術職"<br>2. 輸入職務編號 "TECH-001"<br>3. 輸入職務名稱 "軟體工程師"<br>4. 點擊「保存」按鈕 |
+| 預期結果 | 顯示「保存成功」Toast |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-JOB-002 |
+|-------|------------|
+| 測試名稱 | Toggle 開關功能 |
+| 前置條件 | 系統已啟動，用戶在職務基礎資料頁面 |
+| 測試步驟 | 1. 開啟「是否有全勤獎金」Toggle<br>2. 開啟「是否住房補貼」Toggle<br>3. 保存資料 |
+| 預期結果 | Toggle 狀態正確保存，重新載入後狀態一致 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+### 3.3 部門職責模組
+
+| TC-ID | TC-DF-001 |
+|-------|------------|
+| 測試名稱 | 新增部門職責 - 正常流程 |
+| 前置條件 | 系統已啟動，用戶在部門職責頁面 |
+| 測試步驟 | 1. 輸入職責編號 "DF-001"<br>2. 輸入職責名稱 "研發部門職責"<br>3. 選擇事業體、處級單位、部級單位<br>4. 輸入核心職責<br>5. 點擊「保存」按鈕 |
+| 預期結果 | 顯示「保存成功」Toast |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-DF-002 |
+|-------|------------|
+| 測試名稱 | 組織層級聯動 |
+| 前置條件 | 系統已啟動 |
+| 測試步驟 | 1. 選擇事業體 "SBU"<br>2. 觀察處級單位選項變化<br>3. 選擇處級單位<br>4. 觀察部級單位選項變化 |
+| 預期結果 | 各層級選項正確聯動，無無效選項 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+### 3.4 AI 幫我想功能
+
+> **說明**：v1.1 版本將三個錦囊按鈕整合為單一「AI 幫我想」按鈕，並提供可編輯的 Prompt 編輯器。
+
+| TC-ID | TC-AI-001 |
+|-------|------------|
+| 測試名稱 | AI 幫我想 - 正常流程 |
+| 前置條件 | Ollama 服務已啟動，用戶在崗位基礎資料頁面 |
+| 測試步驟 | 1. 查看預設 Prompt 內容<br>2. 點擊「AI 幫我想」按鈕<br>3. 等待 AI 生成完成 |
+| 預期結果 | AI 生成資料並填充至表單空白欄位，顯示「AI 生成完成！已填入表單」Toast |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-AI-002 |
+|-------|------------|
+| 測試名稱 | Prompt 編輯功能 |
+| 前置條件 | 系統已啟動 |
+| 測試步驟 | 1. 在 Prompt 編輯器修改內容<br>2. 點擊「AI 幫我想」按鈕<br>3. 重新整理頁面<br>4. 檢查 Prompt 是否保留 |
+| 預期結果 | 修改的 Prompt 保存至 LocalStorage，重新整理後恢復 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-AI-003 |
+|-------|------------|
+| 測試名稱 | Prompt 重置功能 |
+| 前置條件 | 已修改 Prompt 內容 |
+| 測試步驟 | 1. 修改 Prompt 內容<br>2. 點擊重置按鈕（↺ 圖示） |
+| 預期結果 | Prompt 恢復為預設值，顯示「已重置為預設 Prompt」Toast |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-AI-004 |
+|-------|------------|
+| 測試名稱 | 各模組 AI 功能 |
+| 前置條件 | Ollama 服務已啟動 |
+| 測試步驟 | 分別在以下模組測試 AI 功能：<br>1. 崗位基礎資料 (positionBasic)<br>2. 招聘要求 (positionRecruit)<br>3. 職務基礎資料 (jobBasic)<br>4. 部門職責 (deptFunction)<br>5. 崗位描述 (jobDesc) |
+| 預期結果 | 各模組 AI 均能正常生成對應欄位資料 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-AI-005 |
+|-------|------------|
+| 測試名稱 | JSON 解析錯誤處理 |
+| 前置條件 | LLM 返回非標準 JSON 格式（含思考過程） |
+| 測試步驟 | 使用 deepseek-reasoner 等推理模型，觀察 JSON 解析 |
+| 預期結果 | 系統正確從回應中提取 JSON 物件，忽略思考過程文字 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-AI-006 |
+|-------|------------|
+| 測試名稱 | 按鈕載入狀態 |
+| 前置條件 | 系統已啟動 |
+| 測試步驟 | 1. 點擊「AI 幫我想」按鈕<br>2. 觀察按鈕狀態變化 |
+| 預期結果 | 按鈕顯示 spinner 和「AI 生成中...」文字，完成後恢復原狀 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-AI-007 |
+|-------|------------|
+| 測試名稱 | 空白 Prompt 防護 |
+| 前置條件 | 系統已啟動 |
+| 測試步驟 | 1. 清空 Prompt 編輯器<br>2. 點擊「AI 幫我想」按鈕 |
+| 預期結果 | 顯示錯誤訊息「請輸入 Prompt 指令」 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+### 3.5 CSV 匯入匯出
+
+| TC-ID | TC-CSV-001 |
+|-------|------------|
+| 測試名稱 | 下載 CSV 範本 |
+| 前置條件 | 系統已啟動 |
+| 測試步驟 | 1. 點擊「下載崗位 CSV 範本」按鈕 |
+| 預期結果 | 瀏覽器下載 CSV 檔案，格式正確 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-CSV-002 |
+|-------|------------|
+| 測試名稱 | 匯入崗位 CSV |
+| 前置條件 | 已準備符合格式的 CSV 檔案 |
+| 測試步驟 | 1. 點擊「匯入崗位」按鈕<br>2. 選擇 CSV 檔案<br>3. 確認匯入 |
+| 預期結果 | 顯示匯入結果，資料正確寫入 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-CSV-003 |
+|-------|------------|
+| 測試名稱 | 匯入 CSV - 格式錯誤 |
+| 前置條件 | CSV 檔案格式不正確 |
+| 測試步驟 | 1. 選擇格式錯誤的 CSV 檔案<br>2. 嘗試匯入 |
+| 預期結果 | 顯示錯誤訊息，說明格式問題 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+### 3.6 組織階層模組
+
+| TC-ID | TC-ORG-001 |
+|-------|------------|
+| 測試名稱 | 事業體列表載入 |
+| 前置條件 | 組織階層資料已匯入 |
+| 測試步驟 | 1. 開啟部門職責頁面<br>2. 查看事業體下拉選單 |
+| 預期結果 | 顯示所有事業體選項（SBU, PBU, NBU 等） |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-ORG-002 |
+|-------|------------|
+| 測試名稱 | 處級單位級聯選擇 |
+| 前置條件 | 組織階層資料已匯入 |
+| 測試步驟 | 1. 選擇事業體 "SBU"<br>2. 觀察處級單位選項 |
+| 預期結果 | 處級單位僅顯示屬於 SBU 的選項 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-ORG-003 |
+|-------|------------|
+| 測試名稱 | 部級單位級聯選擇 |
+| 前置條件 | 已選擇事業體和處級單位 |
+| 測試步驟 | 1. 選擇處級單位<br>2. 觀察部級單位選項 |
+| 預期結果 | 部級單位僅顯示屬於該處級單位的選項 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+| TC-ID | TC-ORG-004 |
+|-------|------------|
+| 測試名稱 | 崗位名稱級聯選擇 |
+| 前置條件 | 已選擇部級單位 |
+| 測試步驟 | 1. 選擇部級單位<br>2. 觀察崗位名稱選項 |
+| 預期結果 | 崗位名稱僅顯示屬於該部級單位的選項 |
+| 實際結果 | |
+| 通過/失敗 | |
+
+---
+
+## 4. API 測試案例
+
+### 4.1 崗位 API
+
+| TC-ID | 端點 | 方法 | 測試說明 | 預期狀態碼 |
+|-------|------|------|----------|------------|
+| TC-API-001 | /api/positions | GET | 查詢所有崗位 | 200 |
+| TC-API-002 | /api/positions | POST | 新增崗位（正常） | 201 |
+| TC-API-003 | /api/positions | POST | 新增崗位（缺少必填） | 400 |
+| TC-API-004 | /api/positions/{id} | GET | 查詢單一崗位 | 200 |
+| TC-API-005 | /api/positions/{id} | GET | 查詢不存在崗位 | 404 |
+| TC-API-006 | /api/positions/{id} | PUT | 更新崗位 | 200 |
+| TC-API-007 | /api/positions/{id} | DELETE | 刪除崗位 | 200 |
+
+### 4.2 職務 API
+
+| TC-ID | 端點 | 方法 | 測試說明 | 預期狀態碼 |
+|-------|------|------|----------|------------|
+| TC-API-011 | /api/jobs | GET | 查詢所有職務 | 200 |
+| TC-API-012 | /api/jobs | POST | 新增職務（正常） | 201 |
+| TC-API-013 | /api/jobs/{id} | PUT | 更新職務 | 200 |
+| TC-API-014 | /api/jobs/{id} | DELETE | 刪除職務 | 200 |
+
+### 4.3 LLM API
+
+| TC-ID | 端點 | 方法 | 測試說明 | 預期狀態碼 |
+|-------|------|------|----------|------------|
+| TC-API-021 | /api/llm/generate | POST | LLM 生成（Ollama） | 200 |
+| TC-API-022 | /api/llm/generate | POST | LLM 生成（無效 API） | 400 |
+| TC-API-023 | /api/llm/generate | POST | LLM 服務不可用 | 500 |
+
+### 4.4 組織階層 API
+
+| TC-ID | 端點 | 方法 | 測試說明 | 預期狀態碼 |
+|-------|------|------|----------|------------|
+| TC-API-031 | /api/hierarchy/business-units | GET | 查詢所有事業體 | 200 |
+| TC-API-032 | /api/hierarchy/divisions | GET | 查詢所有處級單位 | 200 |
+| TC-API-033 | /api/hierarchy/divisions?business=SBU | GET | 按事業體篩選處級單位 | 200 |
+| TC-API-034 | /api/hierarchy/departments | GET | 查詢所有部級單位 | 200 |
+| TC-API-035 | /api/hierarchy/departments?division=技術處 | GET | 按處級篩選部級單位 | 200 |
+| TC-API-036 | /api/hierarchy/positions | GET | 查詢所有崗位名稱 | 200 |
+| TC-API-037 | /api/hierarchy/positions?department=研發部 | GET | 按部級篩選崗位 | 200 |
+| TC-API-038 | /api/hierarchy/full | GET | 查詢完整階層資料 | 200 |
+| TC-API-039 | /api/hierarchy/full?page=1&size=50 | GET | 分頁查詢階層資料 | 200 |
+| TC-API-040 | /api/hierarchy/cascade | GET | 查詢級聯選擇資料 | 200 |
+| TC-API-041 | /api/hierarchy/stats | GET | 查詢組織統計 | 200 |
+
+---
+
+## 5. UI 測試案例
+
+### 5.1 表單互動
+
+| TC-ID | TC-UI-001 |
+|-------|------------|
+| 測試名稱 | 頁籤切換 |
+| 測試步驟 | 1. 點擊「招聘要求資料」頁籤<br>2. 點擊「基礎資料」頁籤 |
+| 預期結果 | 頁籤內容正確切換，動畫流暢 |
+
+| TC-ID | TC-UI-002 |
+|-------|------------|
+| 測試名稱 | 類別聯動顯示 |
+| 測試步驟 | 1. 選擇崗位類別 "01"<br>2. 觀察崗位類別名稱欄位 |
+| 預期結果 | 自動顯示「技術職」 |
+
+| TC-ID | TC-UI-003 |
+|-------|------------|
+| 測試名稱 | Toast 通知顯示 |
+| 測試步驟 | 1. 執行保存操作 |
+| 預期結果 | 右上角顯示 Toast 通知，3秒後自動消失 |
+
+### 5.2 響應式設計
+
+| TC-ID | TC-UI-010 |
+|-------|------------|
+| 測試名稱 | 手機版佈局 |
+| 測試步驟 | 將瀏覽器寬度調整為 375px |
+| 預期結果 | 表單變為單欄佈局，按鈕仍可操作 |
+
+| TC-ID | TC-UI-011 |
+|-------|------------|
+| 測試名稱 | 平板版佈局 |
+| 測試步驟 | 將瀏覽器寬度調整為 768px |
+| 預期結果 | 佈局適當調整，無元素重疊 |
+
+---
+
+## 6. 效能測試
+
+### 6.1 載入效能
+
+| 測試項目 | 目標值 | 測試方法 |
+|----------|--------|----------|
+| 首次載入時間 | < 3秒 | Chrome DevTools |
+| API 回應時間 | < 500ms | Postman |
+| LLM 生成時間 | < 30秒 | 實際測試 |
+
+### 6.2 並發測試
+
+| 測試項目 | 目標值 |
+|----------|--------|
+| 同時連線數 | 50+ |
+| API 請求/秒 | 100+ |
+
+---
+
+## 7. 安全測試
+
+### 7.1 輸入驗證
+
+| TC-ID | TC-SEC-001 |
+|-------|------------|
+| 測試名稱 | XSS 防護 |
+| 測試步驟 | 在輸入框輸入 `<script>alert('XSS')</script>` |
+| 預期結果 | 腳本不執行，內容被轉義或過濾 |
+
+| TC-ID | TC-SEC-002 |
+|-------|------------|
+| 測試名稱 | SQL Injection 防護 |
+| 測試步驟 | 在輸入框輸入 `'; DROP TABLE positions; --` |
+| 預期結果 | SQL 不執行，顯示錯誤或過濾 |
+
+### 7.2 API 安全
+
+| TC-ID | TC-SEC-010 |
+|-------|------------|
+| 測試名稱 | CORS 設定 |
+| 測試步驟 | 從不同來源發送 API 請求 |
+| 預期結果 | 僅允許白名單來源 |
+
+---
+
+## 8. 測試報告模板
+
+### 8.1 測試摘要
+
+| 項目 | 數值 |
+|------|------|
+| 總測試案例數 | |
+| 通過數 | |
+| 失敗數 | |
+| 通過率 | |
+| 測試日期 | |
+| 測試人員 | |
+
+### 8.2 缺陷追蹤
+
+| 缺陷ID | 嚴重度 | 標題 | 狀態 | 負責人 |
+|--------|--------|------|------|--------|
+| | | | | |
+
+---
+
+## 9. 驗收標準
+
+### 9.1 功能驗收
+
+- [ ] 所有 CRUD 操作正常運作
+- [ ] 三個錦囊 AI 功能可正常生成內容
+- [ ] CSV 匯入匯出功能完整
+- [ ] 所有必填欄位驗證正確
+- [ ] 組織層級聯動正確
+
+### 9.2 效能驗收
+
+- [ ] 頁面載入時間 < 3秒
+- [ ] API 回應時間 < 500ms
+- [ ] 無明顯 UI 卡頓
+
+### 9.3 相容性驗收
+
+- [ ] Chrome 最新版正常
+- [ ] Firefox 最新版正常
+- [ ] Edge 最新版正常
+
+---
+
+## 10. 版本歷史
+
+| 版本 | 日期 | 作者 | 變更說明 |
+|------|------|------|----------|
+| 1.0 | 2024-12-06 | System | 初始版本 |
+| 1.1 | 2025-12-08 | System | 1. 更新 AI 功能測試案例（三個錦囊 → AI 幫我想）<br>2. 新增組織階層模組測試案例<br>3. 新增組織階層 API 測試案例<br>4. 更新 JSON 解析錯誤處理測試（支援推理模型） |
+
+---
+
+**文件結束**