# HR 基礎資料維護系統 - 軟體設計文件 (SDD)

**文件版本**：2.0  
**建立日期**：2024-12-03  
**最後更新**：2024-12-04  
**文件狀態**：Released  

---

## 1. 文件概述

### 1.1 目的

本文件為 HR 基礎資料維護系統之軟體設計文件 (Software Design Document)，詳細描述系統架構、模組設計、資料結構、介面規格與 AI 整合功能，供開發人員、測試人員及維護人員參考。

### 1.2 範圍

本系統涵蓋以下三大功能模組：

| 模組 | 功能說明 |
|------|----------|
| 崗位基礎資料 | 崗位主檔維護，含基礎資料與招聘要求 |
| 職務基礎資料 | 職務類別與屬性設定維護 |
| 崗位描述 | 職責描述、崗位要求與任職條件維護 |

### 1.3 參考文件

- 用戶需求規格書 (URD)
- 系統功能規格書 (FSD)
- API 設計規範

### 1.4 術語定義

| 術語 | 定義 |
|------|------|
| 崗位 (Position) | 組織架構中的職位單位，具有編號、級別、編制人數等屬性 |
| 職務 (Job Title) | 職務類別分類，如管理職、技術職、業務職等 |
| 崗位描述 (Job Description) | 詳細描述崗位職責、要求與任職條件的文件 |
| AI 自動填充 | 利用大型語言模型自動生成表單欄位內容的功能 |

---

## 2. 系統架構

### 2.1 整體架構圖

```
┌─────────────────────────────────────────────────────────────────┐
│                        使用者介面層 (UI Layer)                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐              │
│  │ 崗位基礎資料 │  │ 職務基礎資料 │  │  崗位描述   │              │
│  │   模組      │  │    模組     │  │    模組     │              │
│  └─────────────┘  └─────────────┘  └─────────────┘              │
│                           │                                      │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              AI 自動填充服務 (Claude API)                  │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      應用服務層 (Application Layer)              │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                   Flask RESTful API                      │    │
│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐            │    │
│  │  │ Position  │  │    Job    │  │ Reference │            │    │
│  │  │    API    │  │    API    │  │    API    │            │    │
│  │  └───────────┘  └───────────┘  └───────────┘            │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                       資料存取層 (Data Layer)                    │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │              In-Memory Database / Future DB              │    │
│  │         (positions_db, jobs_db, job_desc_db)            │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
```

### 2.2 技術堆疊

| 層級 | 技術選型 | 說明 |
|------|----------|------|
| 前端 | HTML5 + CSS3 + JavaScript | 純前端實作，無框架依賴 |
| 樣式 | Custom CSS + Google Fonts | Noto Sans TC 字型、CSS Variables |
| 後端 | Python Flask | RESTful API 服務 |
| AI 服務 | Claude API (Anthropic) | 智能表單填充 |
| 資料庫 | In-Memory (Dict) | 可擴展至 MySQL/PostgreSQL |

### 2.3 部署架構

```
┌─────────────────────────────────────────┐
│            使用者瀏覽器                  │
│  ┌─────────────────────────────────┐    │
│  │      index.html (前端應用)       │    │
│  └─────────────────────────────────┘    │
└─────────────────────────────────────────┘
            │                    │
            ▼                    ▼
┌───────────────────┐  ┌───────────────────┐
│   Flask Server    │  │   Claude API      │
│   localhost:5000  │  │   api.anthropic   │
└───────────────────┘  └───────────────────┘
```

---

## 3. 模組設計

### 3.1 崗位基礎資料模組

#### 3.1.1 模組概述

提供崗位主檔的 CRUD 操作，分為「基礎資料」與「招聘要求資料」兩個頁籤。

#### 3.1.2 基礎資料頁籤欄位規格

| 欄位名稱 | 欄位ID | 資料類型 | 必填 | 說明 |
|----------|--------|----------|------|------|
| 崗位編號 | positionCode | String(20) | ✓ | 唯一識別碼，格式：XXX-NNN |
| 崗位名稱 | positionName | String(100) | ✓ | 崗位中文名稱 |
| 崗位類別 | positionCategory | Enum | | 01/02/03/04 |
| 崗位類別名稱 | positionCategoryName | String(50) | | 自動帶出，唯讀 |
| 崗位性質 | positionNature | Enum | | FT/PT/CT/IN |
| 崗位性質名稱 | positionNatureName | String(50) | | 自動帶出，唯讀 |
| 編制人數 | headcount | Integer | | 0-9999 |
| 崗位級別 | positionLevel | Enum | | L1-L7 |
| 生效日期 | effectiveDate | Date | | 預設 2001-01-01 |
| 崗位描述 | positionDesc | Text | | 多行文字 |
| 崗位備注 | positionRemark | Text | | 多行文字 |

#### 3.1.3 招聘要求資料頁籤欄位規格

| 欄位名稱 | 欄位ID | 資料類型 | 說明 |
|----------|--------|----------|------|
| 最低學歷 | minEducation | Enum | HS/JC/BA/MA/PHD |
| 要求性別 | requiredGender | Enum | 空值=不限, M=男, F=女 |
| 薪酬范圍 | salaryRange | Enum | A/B/C/D/E/N |
| 工作經驗 | workExperience | Enum | 0/1/3/5/10 (年) |
| 最小年齡 | minAge | Integer | 18-65 |
| 最大年齡 | maxAge | Integer | 18-65 |
| 工作性質 | jobType | Enum | FT/PT/CT/DP |
| 招聘職位 | recruitPosition | Enum | ENG/MGR/AST/OP/SAL |
| 職位名稱 | jobTitle | String(100) | |
| 職位描述 | jobDesc | Text | |
| 崗位要求 | positionReq | Text | |
| 職稱要求 | titleReq | Enum | NONE/CERT/LIC |
| 專業要求 | majorReq | String(200) | 多選，逗號分隔 |
| 技能要求 | skillReq | String(200) | |
| 語言要求 | langReq | String(100) | |
| 其他要求 | otherReq | String(200) | |
| 上級崗位編號 | superiorPosition | String(20) | |
| 備注說明 | recruitRemark | Text | |

#### 3.1.4 類別代碼對照表

**崗位類別 (positionCategory)**

| 代碼 | 名稱 |
|------|------|
| 01 | 技術職 |
| 02 | 管理職 |
| 03 | 業務職 |
| 04 | 行政職 |

**崗位性質 (positionNature)**

| 代碼 | 名稱 |
|------|------|
| FT | 全職 |
| PT | 兼職 |
| CT | 約聘 |
| IN | 實習 |

**崗位級別 (positionLevel)**

| 代碼 | 名稱 |
|------|------|
| L1 | 基層員工 |
| L2 | 資深員工 |
| L3 | 主管 |
| L4 | 經理 |
| L5 | 總監 |
| L6 | 副總 |
| L7 | 總經理 |

---

### 3.2 職務基礎資料模組

#### 3.2.1 模組概述

提供職務類別主檔的維護功能，包含職務屬性設定。

#### 3.2.2 欄位規格

| 欄位名稱 | 欄位ID | 資料類型 | 必填 | 說明 |
|----------|--------|----------|------|------|
| 職務類別編號 | jobCategoryCode | Enum | ✓ | MGR/TECH/SALE/ADMIN/RD/PROD |
| 職務類別名稱 | jobCategoryName | String(50) | | 自動帶出，唯讀 |
| 職務編號 | jobCode | String(20) | ✓ | 唯一識別碼 |
| 職務名稱 | jobName | String(100) | ✓ | 職務中文名稱 |
| 職務英文 | jobNameEn | String(100) | | 職務英文名稱 |
| 生效日期 | jobEffectiveDate | Date | | |
| 編制人數 | jobHeadcount | Integer | | 0-9999 |
| 排列順序 | jobSortOrder | Integer | | 顯示排序 |
| 備注說明 | jobRemark | Text | | |
| 職務層級 | jobLevel | String(50) | | 可設為 *保密* |
| 是否有全勤 | hasAttendanceBonus | Boolean | | Toggle 開關 |
| 是否住房補貼 | hasHousingAllowance | Boolean | | Toggle 開關 |

#### 3.2.3 職務類別代碼對照表

| 代碼 | 名稱 |
|------|------|
| MGR | 管理職 |
| TECH | 技術職 |
| SALE | 業務職 |
| ADMIN | 行政職 |
| RD | 研發職 |
| PROD | 生產職 |

---

### 3.3 崗位描述模組

#### 3.3.1 模組概述

提供完整的崗位描述書 (Job Description) 維護功能，包含崗位基本信息、職責描述與崗位要求三大區塊。

#### 3.3.2 頂部區域欄位

| 欄位名稱 | 欄位ID | 資料類型 | 說明 |
|----------|--------|----------|------|
| 工號 | jd_empNo | String(20) | 員工編號 |
| 姓名 | jd_empName | String(50) | 自動帶出，唯讀 |
| 崗位代碼 | jd_positionCode | String(20) | |
| 版本更新日期 | jd_versionDate | Date | |

#### 3.3.3 崗位基本信息區塊

| 欄位名稱 | 欄位ID | 資料類型 | 說明 |
|----------|--------|----------|------|
| 崗位名稱 | jd_positionName | String(100) | |
| 所屬部門 | jd_department | String(100) | |
| 崗位生效日期 | jd_positionEffectiveDate | Date | |
| 直接領導職務 | jd_directSupervisor | String(100) | |
| 崗位職等&職務 | jd_positionGradeJob | String(100) | 選擇按鈕 |
| 匯報對象職務 | jd_reportTo | String(100) | 選擇按鈕 |
| 直接下級 | jd_directReports | String(200) | 格式：職位 x 人數 |
| 任職地點 | jd_workLocation | Enum | HQ/TPE/TYC/KHH/SH/SZ |
| 員工屬性 | jd_empAttribute | Enum | FT/CT/PT/IN/DP |

#### 3.3.4 職責描述區塊

| 欄位名稱 | 欄位ID | 資料類型 | 說明 |
|----------|--------|----------|------|
| 崗位設置目的 | jd_positionPurpose | String(500) | 單行文字 |
| 主要崗位職責 | jd_mainResponsibilities | Text | 編號格式 1、2、3、... |

#### 3.3.5 崗位要求區塊

| 欄位名稱 | 欄位ID | 資料類型 | 說明 |
|----------|--------|----------|------|
| 教育程度 | jd_education | String(200) | |
| 基本技能 | jd_basicSkills | Text | |
| 專業知識 | jd_professionalKnowledge | Text | |
| 工作經驗 | jd_workExperienceReq | Text | |
| 其他 | jd_otherRequirements | Text | |

#### 3.3.6 任職地點代碼對照表

| 代碼 | 名稱 |
|------|------|
| HQ | 總部 |
| TPE | 台北辦公室 |
| TYC | 桃園廠區 |
| KHH | 高雄廠區 |
| SH | 上海辦公室 |
| SZ | 深圳辦公室 |

#### 3.3.7 員工屬性代碼對照表

| 代碼 | 名稱 |
|------|------|
| FT | 正式員工 |
| CT | 約聘人員 |
| PT | 兼職人員 |
| IN | 實習生 |
| DP | 派遣人員 |

---

## 4. API 設計

### 4.1 API 端點總覽

#### 4.1.1 崗位資料 API

| 方法 | 端點 | 說明 |
|------|------|------|
| GET | `/api/positions` | 獲取所有崗位（支援分頁、搜尋） |
| GET | `/api/positions/{id}` | 獲取單一崗位 |
| POST | `/api/positions` | 新增崗位 |
| PUT | `/api/positions/{id}` | 更新崗位 |
| DELETE | `/api/positions/{id}` | 刪除崗位 |
| POST | `/api/positions/{id}/change-code` | 更改崗位編號 |

#### 4.1.2 職務資料 API

| 方法 | 端點 | 說明 |
|------|------|------|
| GET | `/api/jobs` | 獲取所有職務（支援分頁、搜尋、類別篩選） |
| GET | `/api/jobs/{id}` | 獲取單一職務 |
| POST | `/api/jobs` | 新增職務 |
| PUT | `/api/jobs/{id}` | 更新職務 |
| DELETE | `/api/jobs/{id}` | 刪除職務 |
| POST | `/api/jobs/{id}/change-code` | 更改職務編號 |

#### 4.1.3 參照資料 API

| 方法 | 端點 | 說明 |
|------|------|------|
| GET | `/api/reference/categories` | 崗位類別選項 |
| GET | `/api/reference/job-categories` | 職務類別選項 |
| GET | `/api/reference/natures` | 崗位性質選項 |
| GET | `/api/reference/education` | 學歷選項 |
| GET | `/api/reference/majors` | 專業選項 |

### 4.2 API 請求/回應範例

#### 4.2.1 新增崗位

**Request**
```http
POST /api/positions
Content-Type: application/json

{
  "basicInfo": {
    "positionCode": "ENG-001",
    "positionName": "資深軟體工程師",
    "positionCategory": "01",
    "positionNature": "FT",
    "headcount": "5",
    "positionLevel": "L3",
    "effectiveDate": "2024-01-01",
    "positionDesc": "負責系統架構設計與核心模組開發"
  },
  "recruitInfo": {
    "minEducation": "BA",
    "salaryRange": "D",
    "workExperience": "5",
    "skillReq": "Python, JavaScript, SQL"
  }
}
```

**Response (201 Created)**
```json
{
  "success": true,
  "message": "崗位資料新增成功",
  "data": {
    "id": "ENG-001",
    "basicInfo": { ... },
    "recruitInfo": { ... },
    "createdAt": "2024-12-03T10:30:00",
    "updatedAt": "2024-12-03T10:30:00"
  }
}
```

#### 4.2.2 查詢崗位列表

**Request**
```http
GET /api/positions?page=1&size=20&search=工程師
```

**Response (200 OK)**
```json
{
  "success": true,
  "data": [
    {
      "id": "ENG-001",
      "basicInfo": { ... },
      "recruitInfo": { ... }
    }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 1,
    "totalPages": 1
  }
}
```

### 4.3 錯誤處理

| HTTP 狀態碼 | 錯誤類型 | 說明 |
|-------------|----------|------|
| 400 | Bad Request | 請求參數錯誤或缺少必填欄位 |
| 404 | Not Found | 找不到指定資源 |
| 409 | Conflict | 資源衝突（如編號已存在） |
| 500 | Internal Server Error | 伺服器內部錯誤 |

**錯誤回應格式**
```json
{
  "success": false,
  "error": "錯誤訊息描述"
}
```

---

## 5. AI 自動填充功能設計

### 5.1 功能概述

系統整合 Claude API，提供智能表單填充功能。用戶點擊「✨ I'm feeling lucky」按鈕後，AI 會根據已填寫的內容，自動補充尚未填寫的欄位。

### 5.2 填充邏輯

```
┌─────────────────────────────────────────────────────────┐
│                    AI 填充流程                           │
├─────────────────────────────────────────────────────────┤
│  1. 用戶點擊「I'm feeling lucky」按鈕                    │
│                      │                                   │
│                      ▼                                   │
│  2. 檢查表單欄位狀態                                     │
│     ├── 收集已填寫欄位 (作為上下文)                      │
│     └── 識別空白欄位 (待填充目標)                        │
│                      │                                   │
│                      ▼                                   │
│  3. 若無空白欄位 → 顯示「所有欄位都已填寫完成！」        │
│     若有空白欄位 → 繼續                                  │
│                      │                                   │
│                      ▼                                   │
│  4. 組裝 Prompt                                          │
│     ├── 包含已填寫資料作為參考                           │
│     ├── 指定只生成空白欄位                               │
│     └── 要求返回 JSON 格式                               │
│                      │                                   │
│                      ▼                                   │
│  5. 呼叫 Claude API (claude-sonnet-4-20250514)          │
│                      │                                   │
│                      ▼                                   │
│  6. 解析回應並填充空白欄位                               │
│     └── 已有內容的欄位保持不變                           │
│                      │                                   │
│                      ▼                                   │
│  7. 顯示「✨ AI 已補充 N 個欄位！」                      │
└─────────────────────────────────────────────────────────┘
```

### 5.3 核心函數

#### 5.3.1 fillIfEmpty

```javascript
/**
 * 只在欄位為空時填入值
 * @param {string} elementId - DOM 元素 ID
 * @param {string} value - 要填入的值
 * @returns {boolean} - 是否有填入值
 */
function fillIfEmpty(elementId, value) {
    const el = document.getElementById(elementId);
    if (el && !el.value.trim() && value) {
        el.value = value;
        return true;
    }
    return false;
}
```

#### 5.3.2 getEmptyFields

```javascript
/**
 * 獲取空白欄位列表
 * @param {string[]} fieldIds - 欄位 ID 陣列
 * @returns {string[]} - 空白欄位 ID 陣列
 */
function getEmptyFields(fieldIds) {
    return fieldIds.filter(id => !getFieldValue(id));
}
```

### 5.4 API 呼叫規格

**Endpoint**
```
POST https://api.anthropic.com/v1/messages
```

**Request Body**
```json
{
  "model": "claude-sonnet-4-20250514",
  "max_tokens": 2000,
  "messages": [
    {
      "role": "user",
      "content": "Prompt 內容..."
    }
  ]
}
```

### 5.5 Prompt 設計範例

```
請為HR崗位管理系統生成崗位基礎資料。請用繁體中文回覆。

已填寫的資料（請參考這些內容來生成相關的資料）：
{
  "positionName": "資深前端工程師",
  "positionLevel": "L4"
}

請「只生成」以下這些尚未填寫的欄位：positionCode, positionCategory, positionNature, headcount, positionDesc

欄位說明：
- positionCode: 崗位編號（格式如 ENG-001）
- positionCategory: 崗位類別代碼（01=技術職, 02=管理職...）
...

請直接返回JSON格式，只包含需要生成的欄位：
{
  "positionCode": "...",
  "positionCategory": "...",
  ...
}
```

---

## 6. 使用者介面設計

### 6.1 色彩規範

| 變數名稱 | 色碼 | 用途 |
|----------|------|------|
| --primary | #1a5276 | 主色（崗位模組） |
| --primary-light | #2980b9 | 主色亮色 |
| --primary-dark | #0e3a53 | 主色暗色 |
| --accent | #e67e22 | 強調色（職務模組） |
| --green | #27ae60 | 綠色（崗位描述模組） |
| --success | #27ae60 | 成功狀態 |
| --warning | #f39c12 | 警告狀態 |
| --danger | #e74c3c | 錯誤/必填標示 |

### 6.2 模組主題色

| 模組 | Header 背景 | 按鈕樣式 |
|------|-------------|----------|
| 崗位基礎資料 | 藍色漸層 | primary |
| 職務基礎資料 | 橘色漸層 | accent |
| 崗位描述 | 綠色漸層 | green |

### 6.3 元件規格

#### 6.3.1 輸入框

```css
input, select, textarea {
    padding: 10px 14px;
    border: 1.5px solid var(--border);
    border-radius: 6px;
    font-size: 0.9rem;
}
```

#### 6.3.2 按鈕

| 類型 | Class | 用途 |
|------|-------|------|
| 主要按鈕 | .btn-primary | 保存操作 |
| 次要按鈕 | .btn-secondary | 保存並新增 |
| 取消按鈕 | .btn-cancel | 取消操作 |
| AI 按鈕 | .ai-generate-btn | AI 自動填充 |

#### 6.3.3 Toggle 開關

```css
.toggle-switch {
    width: 52px;
    height: 28px;
}
```

### 6.4 響應式斷點

| 斷點 | 寬度 | 佈局調整 |
|------|------|----------|
| Desktop | > 768px | 雙欄表單佈局 |
| Mobile | ≤ 768px | 單欄表單佈局 |

---

## 7. 資料結構

### 7.1 崗位資料 (Position)

```typescript
interface Position {
  id: string;                    // 崗位編號 (PK)
  basicInfo: {
    positionCode: string;        // 崗位編號
    positionName: string;        // 崗位名稱
    positionCategory: string;    // 崗位類別
    positionCategoryName: string;// 崗位類別名稱
    positionNature: string;      // 崗位性質
    positionNatureName: string;  // 崗位性質名稱
    headcount: string;           // 編制人數
    positionLevel: string;       // 崗位級別
    effectiveDate: string;       // 生效日期
    positionDesc: string;        // 崗位描述
    positionRemark: string;      // 崗位備注
  };
  recruitInfo: {
    minEducation: string;        // 最低學歷
    requiredGender: string;      // 要求性別
    salaryRange: string;         // 薪酬范圍
    workExperience: string;      // 工作經驗
    minAge: string;              // 最小年齡
    maxAge: string;              // 最大年齡
    jobType: string;             // 工作性質
    recruitPosition: string;     // 招聘職位
    jobTitle: string;            // 職位名稱
    jobDesc: string;             // 職位描述
    positionReq: string;         // 崗位要求
    titleReq: string;            // 職稱要求
    majorReq: string;            // 專業要求
    skillReq: string;            // 技能要求
    langReq: string;             // 語言要求
    otherReq: string;            // 其他要求
    superiorPosition: string;    // 上級崗位編號
    recruitRemark: string;       // 備注說明
  };
  createdAt: string;             // 建立時間
  updatedAt: string;             // 更新時間
}
```

### 7.2 職務資料 (Job)

```typescript
interface Job {
  id: string;                    // 職務編號 (PK)
  jobCategoryCode: string;       // 職務類別編號
  jobCategoryName: string;       // 職務類別名稱
  jobCode: string;               // 職務編號
  jobName: string;               // 職務名稱
  jobNameEn: string;             // 職務英文名稱
  jobEffectiveDate: string;      // 生效日期
  jobHeadcount: number;          // 編制人數
  jobSortOrder: number;          // 排列順序
  jobRemark: string;             // 備注說明
  jobLevel: string;              // 職務層級
  hasAttendanceBonus: boolean;   // 是否有全勤
  hasHousingAllowance: boolean;  // 是否住房補貼
  createdAt: string;             // 建立時間
  updatedAt: string;             // 更新時間
}
```

### 7.3 崗位描述資料 (JobDescription)

```typescript
interface JobDescription {
  id: string;                    // ID (PK)
  basicInfo: {
    empNo: string;               // 工號
    empName: string;             // 姓名
    positionCode: string;        // 崗位代碼
    versionDate: string;         // 版本更新日期
  };
  positionInfo: {
    positionName: string;        // 崗位名稱
    department: string;          // 所屬部門
    positionEffectiveDate: string; // 崗位生效日期
    directSupervisor: string;    // 直接領導職務
    positionGradeJob: string;    // 崗位職等&職務
    reportTo: string;            // 匯報對象職務
    directReports: string;       // 直接下級
    workLocation: string;        // 任職地點
    empAttribute: string;        // 員工屬性
  };
  responsibilities: {
    positionPurpose: string;     // 崗位設置目的
    mainResponsibilities: string;// 主要崗位職責
  };
  requirements: {
    education: string;           // 教育程度
    basicSkills: string;         // 基本技能
    professionalKnowledge: string; // 專業知識
    workExperienceReq: string;   // 工作經驗
    otherRequirements: string;   // 其他要求
  };
  createdAt: string;             // 建立時間
  updatedAt: string;             // 更新時間
}
```

---

## 8. 快捷鍵設計

| 快捷鍵 | 功能 | 適用範圍 |
|--------|------|----------|
| `Ctrl + S` | 保存并退出 | 所有模組 |
| `Ctrl + N` | 保存并新增 | 所有模組 |

---

## 9. 檔案結構

```
hr_position_form/
├── index.html          # 前端應用主檔
├── app.py              # Flask 後端 API
├── requirements.txt    # Python 依賴套件
├── README.md           # 使用說明文件
└── SDD.md              # 軟體設計文件（本文件）
```

---

## 10. 未來擴展建議

### 10.1 資料庫整合

將 In-Memory 儲存替換為正式資料庫：

```python
# 建議使用 SQLAlchemy ORM
from flask_sqlalchemy import SQLAlchemy

app.config['SQLALCHEMY_DATABASE_URI'] = 'mysql://user:pass@host/db'
db = SQLAlchemy(app)
```

### 10.2 權限控制整合

```python
# 建議整合 Azure AD
from flask_azure_oauth import AzureOAuth

azure_oauth = AzureOAuth(app)

@app.route('/api/positions', methods=['POST'])
@azure_oauth.require_auth
def create_position():
    ...
```

### 10.3 審計日誌

```python
# 記錄所有資料變更
def log_audit(action, entity_type, entity_id, old_data, new_data, user_id):
    audit_log = {
        'action': action,        # CREATE/UPDATE/DELETE
        'entity_type': entity_type,
        'entity_id': entity_id,
        'old_data': old_data,
        'new_data': new_data,
        'user_id': user_id,
        'timestamp': datetime.now().isoformat()
    }
    # 儲存至審計日誌表
```

### 10.4 多語言支援

```javascript
// i18n 國際化
const i18n = {
  'zh-TW': {
    'position.code': '崗位編號',
    'position.name': '崗位名稱',
    ...
  },
  'en-US': {
    'position.code': 'Position Code',
    'position.name': 'Position Name',
    ...
  }
};
```

---

## 11. 版本歷史

| 版本 | 日期 | 作者 | 變更說明 |
|------|------|------|----------|
| 1.0 | 2024-12-03 | System | 初始版本，包含三大模組設計與 AI 功能 |
| 2.0 | 2024-12-04 | System | 新增 MySQL 資料庫整合、多 LLM API 支援、全局錯誤處理、Gitea 版本控制 |

---

## 12. 附錄

### 附錄 A：JSON 資料預覽格式

系統提供即時 JSON 預覽功能，格式如下：

```json
{
  "module": "崗位基礎資料",
  "basicInfo": {
    "positionCode": "ENG-001",
    "positionName": "資深軟體工程師",
    "positionCategory": "01",
    "positionCategoryName": "技術職",
    "positionNature": "FT",
    "positionNatureName": "全職",
    "headcount": "5",
    "positionLevel": "L3"
  },
  "recruitInfo": {
    "minEducation": "BA",
    "salaryRange": "D",
    "workExperience": "5"
  }
}
```

### 附錄 B：UI 截圖參考

（請參考系統實際畫面）

---

**文件結束**