hr-position-system/SDD.md

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

文件版本：2.1 建立日期：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/position-descriptions	獲取所有崗位描述
GET	/api/position-descriptions/{position_code}	獲取單一崗位描述
POST	/api/position-descriptions	新增或更新崗位描述
PUT	/api/position-descriptions/{position_code}	更新崗位描述
DELETE	/api/position-descriptions/{position_code}	刪除崗位描述

4.1.4 崗位清單 API

方法	端點	說明
GET	/api/position-list	獲取崗位清單（支援分頁、搜尋）
GET	/api/position-list/export	匯出完整崗位清單為 CSV

4.1.5 CSV 匯入匯出 API

方法	端點	說明
GET	/api/positions/csv-template	下載崗位資料 CSV 範本
POST	/api/positions/import-csv	批次匯入崗位資料
GET	/api/jobs/csv-template	下載職務資料 CSV 範本
POST	/api/jobs/import-csv	批次匯入職務資料

4.1.6 參照資料 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

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)

{
  "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

GET /api/positions?page=1&size=20&search=工程師

Response (200 OK)

{
  "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	伺服器內部錯誤

錯誤回應格式

{
  "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

/**
 * 只在欄位為空時填入值
 * @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

/**
 * 獲取空白欄位列表
 * @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

{
  "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 輸入框

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 開關

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

6.4 響應式斷點

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

---

7. 資料結構

7.1 崗位資料 (Position)

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)

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 崗位描述資料 (PositionDescription)

interface PositionDescription {
  id: string;                    // 崗位編號 (PK)
  positionCode: string;          // 崗位編號
  positionName: string;          // 崗位名稱
  effectiveDate: string;         // 生效日期
  jobDuties: string;             // 工作職責
  requiredSkills: string;        // 所需技能
  workEnvironment: string;       // 工作環境
  careerPath: string;            // 職涯發展路徑
  createdAt: string;             // 建立時間
  updatedAt: string;             // 更新時間
}

7.4 崗位清單資料 (PositionListItem)

interface PositionListItem {
  positionCode: string;          // 崗位編號
  positionName: string;          // 崗位名稱
  positionCategory: string;      // 崗位類別
  positionNature: string;        // 崗位性質
  headcount: string;             // 編制人數
  positionLevel: string;         // 崗位等級
  effectiveDate: string;         // 生效日期
  minEducation: string;          // 最低學歷
  salaryRange: string;           // 薪資範圍
  hasDescription: boolean;       // 是否有描述
  jobDuties: string;             // 工作職責
  requiredSkills: string;        // 所需技能
  workEnvironment: 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 儲存替換為正式資料庫：

# 建議使用 SQLAlchemy ORM
from flask_sqlalchemy import SQLAlchemy

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

10.2 權限控制整合

# 建議整合 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 審計日誌

# 記錄所有資料變更
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 多語言支援

// 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 版本控制
2.1	2024-12-04	System	新增崗位描述保存功能、崗位清單模組、管理者頁面匯出功能、CSV 批次匯入

---

12. 附錄

附錄 A：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 截圖參考

（請參考系統實際畫面）

---

文件結束