# 夥伴對齊系統 (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月  
**維護者**: 開發團隊