Initial commit

2025-10-28 15:50:53 +08:00
commit 297ef231c5
31 changed files with 12708 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,390 @@
+# 夥伴對齊系統 (Partner Alignment System)
+
+一個基於 Flask 的現代化夥伴對齊管理系統，提供能力評估、STAR 回饋、排名系統和全面的用戶管理功能。
+
+## 🌟 主要功能
+
+### 🔐 認證與授權
+- **JWT 認證**: 安全的令牌基礎認證系統
+- **角色權限管理**: 靈活的角色和權限控制
+- **用戶註冊/登入**: 完整的用戶生命週期管理
+- **會話管理**: 安全的會話和令牌刷新機制
+
+### 📊 個人儀表板
+- **積分追蹤**: 實時顯示總積分和月度積分
+- **排名顯示**: 部門排名和總排名
+- **通知中心**: 系統通知和成就提醒
+- **活動記錄**: 個人活動和成就歷史
+
+### 📝 能力評估系統
+- **拖拽式評估**: 直觀的能力等級評估界面
+- **多維度評估**: 支持多種能力項目的評估
+- **評估歷史**: 完整的評估記錄和追蹤
+- **數據導出**: Excel/CSV 格式的評估數據導出
+
+### ⭐ STAR 回饋系統
+- **結構化回饋**: 基於 STAR 方法的回饋收集
+- **積分獎勵**: 自動積分計算和分配
+- **回饋追蹤**: 完整的回饋歷史記錄
+- **績效分析**: 基於回饋的績效分析
+
+### 🏆 排名系統
+- **實時排名**: 總排名和月度排名
+- **百分位計算**: 精確的排名百分位顯示
+- **部門篩選**: 按部門查看排名
+- **排名歷史**: 排名變化和趨勢分析
+
+### 👥 管理功能
+- **用戶管理**: 完整的用戶 CRUD 操作
+- **角色管理**: 角色創建、分配和權限管理
+- **審計日誌**: 完整的系統操作記錄
+- **數據管理**: 評估和回饋數據管理
+
+## 🏗️ 技術架構
+
+### 後端技術棧
+- **Flask 2.3.3**: Web 框架
+- **SQLAlchemy**: ORM 數據庫操作
+- **MySQL 5.7+**: 主數據庫
+- **JWT**: 認證令牌
+- **Flask-Login**: 會話管理
+- **Flask-Bcrypt**: 密碼加密
+- **APScheduler**: 定時任務
+
+### 前端技術棧
+- **HTML5**: 語義化標記
+- **Bootstrap 5**: 響應式 UI 框架
+- **JavaScript ES6+**: 現代 JavaScript
+- **Fetch API**: 異步數據請求
+- **CSS3**: 現代樣式和動畫
+
+### 開發工具
+- **pytest**: 測試框架
+- **Docker**: 容器化部署
+- **GitHub Actions**: CI/CD 流水線
+- **Nginx**: 反向代理和負載均衡
+
+## 📁 項目結構
+
+```
+partner-alignment-system/
+├── app.py                 # 主應用程式文件
+├── config.py             # 配置文件
+├── models.py             # 數據模型
+├── auth.py               # 認證邏輯
+├── auth_routes.py        # 認證路由
+├── dashboard_routes.py   # 儀表板路由
+├── admin_routes.py       # 管理路由
+├── init_system.py        # 系統初始化
+├── requirements.txt      # Python 依賴
+├── pytest.ini           # 測試配置
+├── conftest.py          # 測試配置
+├── run_tests.py         # 測試運行器
+├── Dockerfile           # Docker 配置
+├── docker-compose.yml   # Docker Compose 配置
+├── nginx.conf           # Nginx 配置
+├── templates/           # HTML 模板
+│   └── index.html       # 主頁面
+├── static/              # 靜態文件
+│   ├── css/
+│   │   └── style.css    # 樣式文件
+│   └── js/
+│       └── app.js       # 前端邏輯
+├── tests/               # 測試文件
+│   ├── unit/            # 單元測試
+│   ├── integration/     # 集成測試
+│   ├── api/             # API 測試
+│   └── e2e/             # 端到端測試
+├── .github/             # GitHub 配置
+│   └── workflows/
+│       └── ci.yml       # CI/CD 流水線
+├── SETUP.md             # 設置指南
+├── DEPLOYMENT.md        # 部署指南
+└── README.md            # 項目說明
+```
+
+## 🚀 快速開始
+
+### 1. 環境要求
+- Python 3.8+
+- MySQL 5.7+
+- Node.js (可選，用於前端開發)
+
+### 2. 安裝依賴
+```bash
+# 克隆項目
+git clone <repository-url>
+cd partner-alignment-system
+
+# 創建虛擬環境
+python -m venv venv
+source venv/bin/activate  # Linux/Mac
+# 或
+venv\Scripts\activate     # Windows
+
+# 安裝依賴
+pip install -r requirements.txt
+```
+
+### 3. 配置環境
+```bash
+# 複製環境變量模板
+cp .env.example .env
+
+# 編輯環境變量
+nano .env
+```
+
+### 4. 初始化數據庫
+```bash
+# 創建數據庫表
+python init_db.py
+
+# 初始化系統數據
+python init_system.py
+```
+
+### 5. 運行應用程式
+```bash
+# 開發模式
+python app.py
+
+# 或使用 Flask 命令
+flask run
+
+# 生產模式
+gunicorn -c gunicorn.conf.py app:app
+```
+
+### 6. 訪問系統
+打開瀏覽器訪問 `http://localhost:5000`
+
+**默認管理員帳號:**
+- 用戶名: `admin`
+- 密碼: `admin123`
+
+## 🧪 測試
+
+### 運行所有測試
+```bash
+python run_tests.py --type all
+```
+
+### 運行特定測試
+```bash
+# 單元測試
+python run_tests.py --type unit
+
+# API 測試
+python run_tests.py --type api
+
+# 認證測試
+python run_tests.py --type auth
+```
+
+### 生成覆蓋率報告
+```bash
+python run_tests.py --coverage
+```
+
+## 🐳 Docker 部署
+
+### 使用 Docker Compose
+```bash
+# 啟動所有服務
+docker-compose up -d
+
+# 查看日誌
+docker-compose logs -f app
+
+# 停止服務
+docker-compose down
+```
+
+### 單獨使用 Docker
+```bash
+# 構建鏡像
+docker build -t partner-alignment .
+
+# 運行容器
+docker run -d -p 5000:5000 partner-alignment
+```
+
+## 📊 數據庫設計
+
+### 主要表結構
+- **users**: 用戶信息
+- **roles**: 角色定義
+- **permissions**: 權限定義
+- **assessments**: 能力評估
+- **capabilities**: 能力項目
+- **star_feedbacks**: STAR 回饋
+- **employee_points**: 員工積分
+- **monthly_rankings**: 月度排名
+- **audit_logs**: 審計日誌
+- **notifications**: 通知消息
+
+### 關係設計
+- 用戶與角色：多對多關係
+- 角色與權限：多對多關係
+- 用戶與評估：一對多關係
+- 用戶與回饋：一對多關係（評估者和被評估者）
+
+## 🔒 安全特性
+
+### 認證安全
+- JWT 令牌認證
+- 密碼哈希加密
+- 會話超時管理
+- 令牌刷新機制
+
+### 授權控制
+- 基於角色的訪問控制 (RBAC)
+- 細粒度權限管理
+- API 端點保護
+- 前端路由守衛
+
+### 數據安全
+- SQL 注入防護
+- XSS 攻擊防護
+- CSRF 保護
+- 安全標頭配置
+
+### 審計追蹤
+- 完整的操作日誌
+- 用戶行為追蹤
+- 系統事件記錄
+- 安全事件監控
+
+## 📈 性能優化
+
+### 數據庫優化
+- 索引優化
+- 查詢優化
+- 連接池配置
+- 緩存策略
+
+### 應用程式優化
+- 異步處理
+- 緩存機制
+- 靜態文件優化
+- 壓縮配置
+
+### 前端優化
+- 資源壓縮
+- 懶加載
+- 緩存策略
+- CDN 配置
+
+## 🔧 配置選項
+
+### 環境變量
+```bash
+# 應用程式配置
+SECRET_KEY=your-secret-key
+JWT_SECRET_KEY=your-jwt-secret
+FLASK_ENV=production
+
+# 數據庫配置
+DB_HOST=localhost
+DB_PORT=3306
+DB_USER=username
+DB_PASSWORD=password
+DB_NAME=database_name
+
+# 認證配置
+ENABLE_REGISTRATION=True
+DEFAULT_ROLE=user
+SESSION_TIMEOUT=3600
+
+# 郵件配置
+MAIL_SERVER=smtp.gmail.com
+MAIL_PORT=587
+MAIL_USE_TLS=True
+MAIL_USERNAME=your-email
+MAIL_PASSWORD=your-password
+```
+
+## 📚 API 文檔
+
+### 認證端點
+- `POST /api/auth/register` - 用戶註冊
+- `POST /api/auth/login` - 用戶登入
+- `POST /api/auth/refresh` - 刷新令牌
+- `GET /api/auth/protected` - 受保護端點測試
+
+### 評估端點
+- `GET /api/capabilities` - 獲取能力項目
+- `POST /api/assessments` - 創建評估
+- `GET /api/assessments` - 獲取評估列表
+
+### 回饋端點
+- `POST /api/star-feedbacks` - 創建 STAR 回饋
+- `GET /api/star-feedbacks` - 獲取回饋列表
+
+### 排名端點
+- `GET /api/rankings/total` - 獲取總排名
+- `GET /api/rankings/monthly` - 獲取月度排名
+
+### 管理端點
+- `GET /api/admin/users` - 獲取用戶列表
+- `POST /api/admin/users` - 創建用戶
+- `PUT /api/admin/users/{id}` - 更新用戶
+- `DELETE /api/admin/users/{id}` - 刪除用戶
+
+### 儀表板端點
+- `GET /api/dashboard/me` - 獲取個人儀表板數據
+- `POST /api/dashboard/notifications/{id}/read` - 標記通知為已讀
+
+## 🤝 貢獻指南
+
+### 開發流程
+1. Fork 項目
+2. 創建功能分支
+3. 提交更改
+4. 創建 Pull Request
+
+### 代碼規範
+- 遵循 PEP 8 規範
+- 使用類型提示
+- 編寫單元測試
+- 更新文檔
+
+### 提交規範
+```
+feat: 新功能
+fix: 修復問題
+docs: 文檔更新
+style: 代碼格式
+refactor: 重構
+test: 測試
+chore: 構建過程
+```
+
+## 📄 許可證
+
+本項目採用 MIT 許可證 - 查看 [LICENSE](LICENSE) 文件了解詳情。
+
+## 📞 支持與聯繫
+
+### 問題報告
+- GitHub Issues: [創建問題](https://github.com/your-org/partner-alignment/issues)
+- 郵箱支持: support@company.com
+
+### 文檔
+- 在線文檔: [https://docs.company.com](https://docs.company.com)
+- API 文檔: [https://api-docs.company.com](https://api-docs.company.com)
+
+### 社區
+- 討論區: [GitHub Discussions](https://github.com/your-org/partner-alignment/discussions)
+- 技術博客: [https://blog.company.com](https://blog.company.com)
+
+## 🙏 致謝
+
+感謝所有為這個項目做出貢獻的開發者和用戶。
+
+---
+
+**版本**: 2.0.0  
+**最後更新**: 2024年10月  
+**維護者**: 開發團隊