夥伴對齊系統 - 軟體設計文件 (SDD) 1. 文件資訊 版本: 1.0 最後更新: 2025年10月 文件狀態: 初版 專案類型: 內部管理系統 2. 執行摘要 2.1 專案目標 建立一套完整的夥伴能力評估與對齊管理平台，透過視覺化拖拉介面簡化能力評估流程，並整合STAR回饋機制與積分排名系統，提升組織內部人才發展與管理效率。 2.2 核心價值主張 * 效率提升: 拖拉式操作減少50%以上評估時間 * 結構化回饋: STAR框架確保回饋品質與可追蹤性 * 激勵機制: 積分排名系統促進員工持續成長 * 資料驅動: 完整的評估資料分析與匯出功能 2.3 關鍵成功指標 * 評估完成率提升30% * 回饋品質標準化達90% * 系統使用率達80%以上 3. 系統架構設計 3.1 技術架構概覽 ┌─────────────────────────────────────────┐ │ 前端層 (Presentation) │ │ HTML5 + Bootstrap 5 + JavaScript │ └─────────────┬───────────────────────────┘ │ HTTP/REST API ┌─────────────▼───────────────────────────┐ │ 應用層 (Application) │ │ Python Flask + SQLAlchemy │ └─────────────┬───────────────────────────┘ │ ORM ┌─────────────▼───────────────────────────┐ │ 資料層 (Data) │ │ MySQL 5.7+ │ └─────────────────────────────────────────┘ 3.2 系統分層說明 3.2.1 前端層 * 職責: 使用者介面、互動邏輯、資料展示 * 技術選型: o Bootstrap 5: 響應式UI框架 o 原生JavaScript: 拖拉功能、表單驗證 o HTML5 Drag & Drop API: 能力評估拖拉介面 * 關鍵模組: o app.js: 全域工具函數與API通訊 o assessment.js: 能力評估拖拉邏輯 o admin.js: 後台管理介面邏輯 3.2.2 應用層 * 職責: 業務邏輯、資料處理、API路由 * 技術選型: o Flask 2.x: 輕量化Web框架 o SQLAlchemy: ORM資料庫抽象層 o Flask-CORS: 跨域請求處理 o pandas + openpyxl: 資料匯出 * 安全機制: o 環境變數管理敏感資訊 o CORS跨域限制 o 輸入驗證與SQL注入防護 o 錯誤處理機制 3.2.3 資料層 * 職責: 資料持久化、查詢優化 * 技術選型: MySQL 5.7+ * 關鍵特性: o 事務處理保證資料一致性 o 索引優化查詢效能 o JSON欄位儲存彈性資料 4. 資料庫設計 4.1 ER關係圖 ┌─────────────────┐ ┌──────────────────┐ │ assessments │ │ capabilities │ │ (能力評估紀錄) │ │ (能力項目定義) │ └─────────────────┘ └──────────────────┘ │ │ ▼ ┌─────────────────┐ ┌──────────────────┐ │ star_feedbacks │─────?│ employee_points │ │ (STAR回饋) │ │ (員工積分) │ └─────────────────┘ └──────────────────┘ │ │ │ ▼ │ ┌──────────────────┐ └──────────────?│ monthly_rankings │ │ (月度排名) │ └──────────────────┘ 4.2 資料表結構 4.2.1 assessments (能力評估紀錄) 欄位名稱 資料型別 說明 約束 id INT 主鍵 PK, AUTO_INCREMENT department VARCHAR(100) 部門 NOT NULL position VARCHAR(100) 職位 NOT NULL employee_name VARCHAR(100) 員工姓名 NULL assessment_data JSON 評估資料 NOT NULL created_at DATETIME 建立時間 DEFAULT CURRENT_TIMESTAMP updated_at DATETIME 更新時間 ON UPDATE CURRENT_TIMESTAMP 索引策略: * idx_department: (department) * idx_position: (position) * idx_created_at: (created_at) 4.2.2 capabilities (能力項目定義) 欄位名稱 資料型別 說明 約束 id INT 主鍵 PK, AUTO_INCREMENT name VARCHAR(200) 能力名稱 NOT NULL, UNIQUE l1_description TEXT L1等級說明 NULL l2_description TEXT L2等級說明 NULL l3_description TEXT L3等級說明 NULL l4_description TEXT L4等級說明 NULL l5_description TEXT L5等級說明 NULL is_active BOOLEAN 是否啟用 DEFAULT TRUE 4.2.3 star_feedbacks (STAR回饋) 欄位名稱 資料型別 說明 約束 id INT 主鍵 PK, AUTO_INCREMENT evaluator_name VARCHAR(100) 評分者姓名 NOT NULL evaluatee_name VARCHAR(100) 受評者姓名 NOT NULL evaluatee_department VARCHAR(100) 受評者部門 NOT NULL evaluatee_position VARCHAR(100) 受評者職位 NOT NULL situation TEXT 情境描述 NOT NULL task TEXT 任務說明 NOT NULL action TEXT 行動描述 NOT NULL result TEXT 結果說明 NOT NULL score INT 評分(1-5) CHECK (score BETWEEN 1 AND 5) points_earned INT 獲得積分 NOT NULL feedback_date DATE 回饋日期 NOT NULL created_at DATETIME 建立時間 DEFAULT CURRENT_TIMESTAMP 索引策略: * idx_evaluatee: (evaluatee_name, evaluatee_department) * idx_feedback_date: (feedback_date) 積分計算規則: points_earned = score × 10 4.2.4 employee_points (員工積分) 欄位名稱 資料型別 說明 約束 id INT 主鍵 PK, AUTO_INCREMENT employee_name VARCHAR(100) 員工姓名 NOT NULL, UNIQUE department VARCHAR(100) 部門 NOT NULL position VARCHAR(100) 職位 NOT NULL total_points INT 總積分 DEFAULT 0 monthly_points INT 當月積分 DEFAULT 0 last_updated DATETIME 最後更新時間 ON UPDATE CURRENT_TIMESTAMP 索引策略: * idx_total_points: (total_points DESC) * idx_monthly_points: (monthly_points DESC) 4.2.5 monthly_rankings (月度排名) 欄位名稱 資料型別 說明 約束 id INT 主鍵 PK, AUTO_INCREMENT ranking_month DATE 排名月份 NOT NULL employee_name VARCHAR(100) 員工姓名 NOT NULL department VARCHAR(100) 部門 NOT NULL position VARCHAR(100) 職位 NOT NULL total_points INT 該月總積分 NOT NULL ranking INT 排名 NOT NULL created_at DATETIME 建立時間 DEFAULT CURRENT_TIMESTAMP 索引策略: * idx_ranking_month: (ranking_month, ranking) * unique_month_employee: (ranking_month, employee_name) UNIQUE 5. 功能模組設計 5.1 模組架構圖 ┌─────────────────────────────────────────────────┐ │ 系統主頁 │ │ (index.html) │ └──────┬─────────┬─────────┬─────────┬───────────┘ │ │ │ │ ┌───▼───┐ ┌──▼───┐ ┌───▼───┐ ┌──▼────┐ │能力評估│ │STAR │ │排行榜 │ │管理 │ │模組 │ │回饋 │ │模組 │ │後台 │ │ │ │模組 │ │ │ │模組 │ └───────┘ └──────┘ └───────┘ └───────┘ 5.2 核心功能模組 5.2.1 能力評估模組 功能目標: 提供直觀的能力評估介面，支援拖拉式操作進行能力等級分配 輸入: * 部門選擇 (必填) * 職位選擇 (必填) * 員工姓名 (選填) * 能力項目拖拉操作 處理邏輯: 1. 載入能力項目清單 2. 初始化5個等級容器 (L1-L5) 3. 監聽拖拉事件 4. 驗證必填欄位 5. 組裝評估資料JSON 6. 提交至後端API 輸出: * 評估結果儲存至資料庫 * 顯示成功/失敗訊息 關鍵技術: // 拖拉事件處理 element.addEventListener('dragstart', handleDragStart); element.addEventListener('dragover', handleDragOver); element.addEventListener('drop', handleDrop); // 資料結構 { "department": "技術部", "position": "資深工程師", "employee_name": "張三", "capabilities": { "L1": ["能力1", "能力2"], "L2": ["能力3"], ... } } 5.2.2 STAR回饋模組 功能目標: 結構化回饋收集，促進有效的績效溝通與記錄 STAR框架說明: * S - Situation (情境): 描述事件發生的背景脈絡 * T - Task (任務): 說明需要達成的目標或責任 * A - Action (行動): 詳述採取的具體步驟與策略 * R - Result (結果): 量化/質化的成果與影響 輸入驗證規則: 欄位 驗證規則 評分者姓名 必填, 2-50字元 受評者姓名 必填, 2-50字元 部門 必填 職位 必填 評分 必填, 1-5整數 S/T/A/R 各必填, 最少10字元 回饋日期 必填, 不可未來日期 積分計算: points_earned = score * 10 # 範例: 評分4分 → 獲得40積分 業務流程: 1. 填寫基本資訊 (評分者、受評者) 2. 選擇評分 (1-5分) 3. 按STAR結構填寫回饋 4. 預覽回饋內容 5. 提交回饋 6. 自動更新受評者積分 7. 觸發排名重算 (月度) 5.2.3 積分排名模組 功能目標: 展示員工積分排名，提供激勵機制與績效可視化 排名類型: 1. 總積分排行榜: 累計所有歷史積分 2. 月度排行榜: 特定月份的積分排名 3. 部門排行榜: 按部門篩選的排名 排名計算邏輯: # 每月1號自動執行 def calculate_monthly_ranking(): # 1. 統計上月所有員工積分 # 2. 按積分降序排序 # 3. 處理並列排名 # 4. 寫入 monthly_rankings 表 # 5. 重置 employee_points.monthly_points 排名規則: * 積分相同時並列同名次 * 下一名次跳號 (例: 2名並列第3, 下一名為第5) * 零積分不列入排名 查詢功能: * 年份選擇器 * 月份選擇器 * 部門篩選器 * 歷史排名比較 5.2.4 資料管理模組 功能目標: 提供完整的資料檢視、查詢、匯出功能 查詢條件: * 部門篩選 * 職位篩選 * 員工姓名搜尋 * 日期區間篩選 * 評估類型篩選 分頁設計: * 每頁顯示20筆 * 顯示總筆數 * 頁碼導航 匯出功能: 1. Excel格式 (.xlsx): o 使用 openpyxl 生成 o 包含格式化表頭 o 支援多工作表 2. CSV格式: o UTF-8 BOM編碼 (Excel相容) o 逗號分隔 o 引號包覆特殊字元 匯出欄位: 評估資料匯出: - ID, 部門, 職位, 員工姓名, 評估資料, 建立時間 STAR回饋匯出: - ID, 評分者, 受評者, 部門, 職位, S/T/A/R內容, 評分, 積分, 回饋日期, 建立時間 6. API端點設計 6.1 RESTful API規範 基礎URL: http://{host}:{port} Content-Type: application/json 字元編碼: UTF-8 6.2 API端點清單 6.2.1 能力評估相關 GET /api/capabilities * 功能: 取得所有啟用的能力項目 * 請求參數: 無 * 回應範例: { "capabilities": [ { "id": 1, "name": "程式設計與開發", "l1_description": "...", "l2_description": "...", "l3_description": "...", "l4_description": "...", "l5_description": "..." } ] } POST /api/assessments * 功能: 提交能力評估 * 請求Body: { "department": "技術部", "position": "資深工程師", "employee_name": "張三", "assessment_data": { "L1": ["能力1"], "L2": ["能力2", "能力3"], ... } } * 驗證規則: o department: 必填 o position: 必填 o assessment_data: 必填, 至少一個能力項目 * 成功回應 (201): { "success": true, "message": "評估提交成功", "assessment_id": 123 } 6.2.2 STAR回饋相關 POST /api/star-feedbacks * 功能: 提交STAR回饋 * 請求Body: { "evaluator_name": "李四", "evaluatee_name": "張三", "evaluatee_department": "技術部", "evaluatee_position": "資深工程師", "situation": "專案緊急需求...", "task": "需在48小時內...", "action": "組織跨部門會議...", "result": "成功交付功能...", "score": 4, "feedback_date": "2025-10-15" } * 業務邏輯: 1. 計算積分: points_earned = score * 10 2. 更新 employee_points 表 3. 新增回饋記錄 * 成功回應 (201): { "success": true, "message": "回饋提交成功", "points_earned": 40 } 6.2.3 排名相關 GET /api/rankings/total * 功能: 取得總積分排行榜 * 請求參數: o department (選填): 部門篩選 o limit (選填): 顯示筆數, 預設50 * 回應範例: { "rankings": [ { "rank": 1, "employee_name": "張三", "department": "技術部", "position": "資深工程師", "total_points": 450 } ] } GET /api/rankings/monthly * 功能: 取得月度排行榜 * 請求參數: o year (必填): 年份 o month (必填): 月份 (1-12) o department (選填): 部門篩選 * 回應範例: { "year": 2025, "month": 10, "rankings": [...] } POST /api/rankings/calculate * 功能: 手動觸發月度排名計算 * 權限: 管理員 * 請求Body: { "year": 2025, "month": 10 } 6.2.4 資料管理相關 GET /api/assessments * 功能: 查詢評估資料 * 請求參數: o page (選填): 頁碼, 預設1 o per_page (選填): 每頁筆數, 預設20 o department (選填): 部門篩選 o position (選填): 職位篩選 o employee_name (選填): 員工姓名搜尋 * 回應範例: { "assessments": [...], "total": 150, "page": 1, "per_page": 20, "pages": 8 } GET /api/export/assessments * 功能: 匯出評估資料 * 請求參數: o format: excel | csv o 其他篩選條件同上 * 回應: 檔案下載 GET /api/export/star-feedbacks * 功能: 匯出STAR回饋資料 * 請求參數: o format: excel | csv o 篩選條件 7. 非功能需求 7.1 效能需求 指標 目標值 說明 頁面載入時間 < 2秒 首頁與主要功能頁 API回應時間 < 500ms 95百分位數 並發使用者 100+ 同時在線使用者數 資料庫查詢 < 100ms 單次查詢時間 檔案匯出 < 5秒 1000筆資料以內 效能優化策略: * 資料庫索引優化 * 前端資源壓縮與快取 * 分頁查詢降低負載 * 非同步處理大量資料匯出 7.2 安全需求 7.2.1 當前實作 ? 已實作: * 環境變數管理敏感資訊 (.env) * CORS跨域請求限制 * SQL注入防護 (SQLAlchemy參數化查詢) * XSS防護 (輸入驗證與清理) * 錯誤訊息脫敏 * HTTPS支援 (需配置) ? 未實作 (生產環境必須): * 使用者身份驗證 * Session管理 * 角色權限控制 * 操作日誌記錄 * API速率限制 7.2.2 安全配置檢查清單 部署前必須完成: □ 生成安全的 SECRET_KEY (32字元以上) □ 設定強密碼的資料庫帳號 □ 關閉生產環境 DEBUG 模式 □ 配置正確的 CORS_ORIGINS □ 啟用 HTTPS (Let's Encrypt) □ 定期備份資料庫 □ 實作使用者認證系統 7.2.3 建議的權限分級 角色 權限 一般員工 填寫評估、檢視自己的資料 主管 評估下屬、檢視部門資料 HR 檢視所有資料、匯出報表 系統管理員 所有權限、系統設定 7.3 可用性需求 目標: 系統可用性 ? 99% 容錯機制: * 資料庫連線重試機制 * 優雅的錯誤處理 * 友善的錯誤提示訊息 * 表單資料暫存 (防止誤關閉) 備份策略: * 每日自動資料庫備份 * 保留30天備份歷史 * 異地備份 (建議) 7.4 可維護性需求 程式碼品質: * 模組化設計 * 清晰的註解 * 遵循PEP 8規範 * 版本控制 (Git) 文件完整性: * API文件 * 資料庫Schema文件 * 部署手冊 * 使用者手冊 7.5 相容性需求 瀏覽器支援: * Chrome 90+ * Firefox 88+ * Safari 14+ * Edge 90+ * 不支援 IE 裝置支援: * 桌面電腦 (主要) * 平板電腦 (響應式) * 手機 (有限支援) 螢幕解析度: * 最低: 1280x720 * 建議: 1920x1080 8. 部署架構 8.1 開發環境 開發機器 ├── Python 3.8+ 虛擬環境 ├── MySQL 5.7+ 本地實例 └── Flask 開發伺服器 (port 5000) 環境變數 (.env): FLASK_ENV=development FLASK_DEBUG=True FLASK_HOST=127.0.0.1 FLASK_PORT=5000 DB_HOST=localhost DB_PORT=3306 DB_NAME=partner_alignment_dev DB_USER=dev_user DB_PASSWORD=dev_password SECRET_KEY=dev_secret_key_for_testing_only CORS_ORIGINS=http://localhost:5000,http://127.0.0.1:5000 8.2 生產環境 (建議架構) Internet ↓ [Cloudflare / CDN] ↓ [Nginx 反向代理] (Port 80/443) ↓ ┌───────────┴───────────┐ ↓ ↓ [Gunicorn Worker 1] [Gunicorn Worker N] (Flask App) (Flask App) ↓ ↓ └───────────┬───────────┘ ↓ [MySQL Master/Slave] ↓ [定期備份至S3] 硬體需求: 元件 最低配置 建議配置 CPU 2核心 4核心 RAM 4GB 8GB 儲存 20GB SSD 50GB SSD 頻寬 10Mbps 100Mbps 軟體堆疊: * OS: Ubuntu 22.04 LTS * Python: 3.10+ * MySQL: 8.0+ * Nginx: 1.22+ * Gunicorn: 20.1+ 8.3 部署步驟 步驟1: 系統準備 # 更新系統 sudo apt update && sudo apt upgrade -y # 安裝必要套件 sudo apt install python3-pip python3-venv mysql-server nginx -y 步驟2: 應用程式部署 # 建立專案目錄 sudo mkdir -p /var/www/partner-alignment cd /var/www/partner-alignment # 複製程式碼 git clone . # 建立虛擬環境 python3 -m venv venv source venv/bin/activate # 安裝依賴 pip install -r requirements.txt pip install gunicorn 步驟3: 環境設定 # 建立生產環境設定 cp .env.example .env nano .env # 設定資料庫 mysql -u root -p < schema.sql 生產環境 .env: FLASK_ENV=production FLASK_DEBUG=False FLASK_HOST=127.0.0.1 FLASK_PORT=5000 DB_HOST=localhost DB_PORT=3306 DB_NAME=partner_alignment_prod DB_USER=prod_user DB_PASSWORD=<強密碼> SECRET_KEY=<64字元隨機金鑰> CORS_ORIGINS=https://your-domain.com 步驟4: Gunicorn設定 # 建立 systemd 服務檔 sudo nano /etc/systemd/system/partner-alignment.service [Unit] Description=Partner Alignment System After=network.target [Service] User=www-data Group=www-data WorkingDirectory=/var/www/partner-alignment Environment="PATH=/var/www/partner-alignment/venv/bin" ExecStart=/var/www/partner-alignment/venv/bin/gunicorn \ --workers 4 \ --bind 127.0.0.1:5000 \ --timeout 120 \ --access-logfile /var/log/partner-alignment/access.log \ --error-logfile /var/log/partner-alignment/error.log \ app:app [Install] WantedBy=multi-user.target # 啟動服務 sudo systemctl daemon-reload sudo systemctl start partner-alignment sudo systemctl enable partner-alignment 步驟5: Nginx設定 sudo nano /etc/nginx/sites-available/partner-alignment server { listen 80; server_name your-domain.com; # 強制HTTPS return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; # SSL憑證 ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; # 安全標頭 add_header X-Frame-Options "SAMEORIGIN" always; add_header X-Content-Type-Options "nosniff" always; add_header X-XSS-Protection "1; mode=block" always; # 靜態檔案 location /static { alias /var/www/partner-alignment/static; expires 30d; add_header Cache-Control "public, immutable"; } # 應用程式 location / { proxy_pass http://127.0.0.1:5000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } } # 啟用網站 sudo ln -s /etc/nginx/sites-available/partner-alignment /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl restart nginx 步驟6: SSL憑證 # 安裝 Certbot sudo apt install certbot python3-certbot-nginx -y # 取得憑證 sudo certbot --nginx -d your-domain.com 8.4 監控與維護 日誌檔案位置: * Gunicorn: /var/log/partner-alignment/ * Nginx: /var/log/nginx/ * MySQL: /var/log/mysql/ 定期維護任務: # 每日備份 (crontab -e) 0 2 * * * /usr/bin/mysqldump -u backup_user -p'password' partner_alignment_prod > /backup/db_$(date +\%Y\%m\%d).sql # 每月排名計算 0 0 1 * * /var/www/partner-alignment/venv/bin/python /var/www/partner-alignment/monthly_ranking.py 9. 專案管理 9.1 開發里程碑 階段 交付項 預計時程 狀態 Phase 1 基礎架構 & 資料庫設計 Week 1-2 ? 完成 Phase 2 能力評估模組 Week 3-4 ? 完成 Phase 3 STAR回饋模組 Week 5-6 ? 完成 Phase 4 積分排名系統 Week 7-8 ? 完成 Phase 5 管理後台 & 匯出 Week 9-10 ? 完成 Phase 6 測試 & 優化 Week 11-12 ?? 進行中 Phase 7 身份驗證系統 Week 13-14 ? 待開始 Phase 8 生產部署 Week 15 ? 待開始 9.2 技術債務追蹤 高優先級: 1. ? 實作使用者身份驗證系統 2. ? 新增操作日誌記錄 3. ? 實作API速率限制 中優先級: 4. 優化大量資料匯出效能 5. 新增單元測試覆蓋率至80%+ 6. 實作前端表單驗證增強 低優先級: 7. 新增更多圖表視覺化 8. 支援多國語言 9. 行動裝置專用介面優化 9.3 測試策略 9.3.1 單元測試 * 覆蓋率目標: 70%+ * 測試框架: pytest * 重點測試: o 資料驗證邏輯 o 積分計算公式 o 排名演算法 9.3.2 整合測試 * API端點測試 * 資料庫CRUD操作 * 匯出功能測試 9.3.3 使用者接受測試 (UAT) * 評估流程端到端測試 * 回饋提交完整流程 * 各種瀏覽器相容性測試 9.3.4 效能測試 * 負載測試: 100並發使用者 * 壓力測試: 找出系統瓶頸 * 長時間穩定性測試 10. 風險管理 10.1 風險識別與對策 風險項目 影響等級 發生機率 對策 無身份驗證導致資料外洩 ?? 極高 高 Phase 7實作認證系統 資料庫無備份機制 ?? 極高 中 設定自動每日備份 單點故障 ?? 中 中 規劃主從式資料庫架構 效能瓶頸 ?? 中 低 持續監控與優化 瀏覽器相容性問題 ?? 低 低 多瀏覽器測試 10.2 應變計畫 資料遺失: 1. 立即停止系統運作 2. 從最近備份還原 3. 分析遺失原因 4. 檢討備份頻率 系統當機: 1. 檢查錯誤日誌 2. 重啟相關服務 3. 確認資料完整性 4. 通知相關人員 安全事件: 1. 隔離受影響系統 2. 收集證據與日誌 3. 評估損害範圍 4. 修補漏洞 5. 強制密碼重置 11. 附錄 11.1 詞彙表 術語 定義 能力對齊 將員工能力與組織目標或職位要求進行匹配的過程 STAR框架 Situation-Task-Action-Result，結構化回饋方法 L1-L5 能力等級，從L1(執行者)到L5(策略制定者) 拖拉式介面 使用滑鼠拖拉操作的直覺式使用者介面 ORM Object-Relational Mapping，物件關聯映射 11.2 參考文件 * Flask官方文件 * SQLAlchemy文件 * Bootstrap 5文件 * MySQL文件 * Gunicorn部署指南 11.3 變更歷史 版本 日期 修改者 變更內容 1.0 2025-10-15 - 初版SDD文件建立 11.4 核准簽署 角色 姓名 簽名 日期 專案經理 技術負責人 產品負責人 品質保證 文件結束