# 夥伴對齊系統 - 專案檢核報告

**檢核日期：** 2025年1月28日  
**專案名稱：** 夥伴對齊系統 (Partner Alignment System)  
**檢核人員：** 資深全端工程師

---

## 📋 專案結構與依賴檢查

### 1. 入口檔案
- ✅ 有 `simple_app.py` 作為主入口檔案（第953行：`app.run(debug=True, host='0.0.0.0', port=5000)`）

### 2. 專案結構
- ✅ 具備明確的專案結構：
  - `templates/` - HTML 模板目錄
  - `static/css/` - 樣式檔案目錄
  - `static/js/` - JavaScript 檔案目錄
  - `instance/` - 資料庫檔案目錄
  - `__pycache__/` - Python 快取目錄
- ⚠️ 缺少標準化的 `app/` 或 `src/` 結構目錄
- ⚠️ 路由、模型、配置等均集中在單一檔案 `simple_app.py`（共954行）

### 3. 依賴管理檔案
- ✅ 有 `requirements.txt` 且包含完整依賴套件（22個套件）
- ✅ 有 `requirements-simple.txt` 提供簡化版依賴清單

### 4. 使用框架
- ✅ 明確使用 Flask 2.3.3 (Web框架)
- ✅ 使用 SQLAlchemy 3.0.5 (ORM)
- ✅ 使用 Flask-CORS 4.0.0 (跨域支援)
- ✅ 前端使用 Bootstrap 5 (CDN)

### 5. README 文件
- ✅ 有 `README.md` 且包含：
  - 主要功能說明
  - 技術架構說明
  - 快速開始指南
  - 測試帳號資訊
  - API 文檔
- ✅ 有 `PROJECT_SUMMARY.md` 提供專案總結
- ✅ 有 `security-fixes.md` 提供安全審計報告
- ✅ 有 `FEATURES_COMPLETED.md` 提供功能清單

### 6. 依賴套件安全性
- ✅ 主要依賴套件皆為官方維護且版本明確
- ✅ 測試套件齊全 (pytest, pytest-cov, pytest-flask)
- ⚠️ Flask-JWT-Extended 在 requirements.txt 中但實際未使用
- ⚠️ Flask-Bcrypt 在 requirements.txt 中但密碼未實際使用哈希
- ⚠️ APScheduler 在 requirements.txt 中但未實際使用

### 7. 監聽端口與主機位址
- ✅ 監聽端口：5000
- ✅ 主機位址：0.0.0.0 (監聽所有網卡)
- ⚠️ **直接硬編碼在 `simple_app.py` 第953行**：`app.run(debug=True, host='0.0.0.0', port=5000)`
- ❌ 未使用環境變數讀取，而是直接寫死在程式碼中
- ⚠️ Debug 模式設定為 True，應僅用於開發環境
- 本地訪問：http://localhost:5000 或 http://127.0.0.1:5000
- 網路訪問：http://0.0.0.0:5000

---

## 🔒 安全性與環境變數檢核

### 1. 環境變數檔案
- ❌ **無 `.env` 檔案存在**
- ❌ **無 `.env.example` 範本檔案**
- ⚠️ 雖有 `config.py` 可支援環境變數（使用 python-dotenv），但 `simple_app.py` 未使用該配置檔
- ⚠️ `simple_app.py` 與 `config.py` 互相獨立，未整合

### 2. .gitignore 檔案
- ❌ **無 `.gitignore` 檔案**
- ⚠️ `__pycache__/` 目錄存在且未被忽略
- ⚠️ `instance/partner_alignment.db` 資料庫檔案應被忽略但未設定
- ⚠️ 可能導致敏感資訊與快取檔案被 commit

### 3. 資料庫連線設定
- ✅ 使用 SQLAlchemy ORM
- ⚠️ **資料庫連線字串直接硬編碼**：`app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///partner_alignment.db'` (第21行)
- ⚠️ 使用 SQLite (開發環境)，非生產級資料庫
- ⚠️ 資料庫檔案路徑未使用環境變數
- ℹ️ `config.py` 有設定 MySQL 連線字串，但未使用

### 4. 敏感資訊硬編碼
- ❌ **SECRET_KEY 硬編碼**：`app.config['SECRET_KEY'] = 'dev-secret-key-for-testing'` (第20行)
- ❌ **密碼明文存儲**：密碼直接存於資料庫，未使用哈希
  - 第117行：`if user.password_hash != password:`
  - 第168行：`password_hash=data['password']`
  - 第863行：`'password_hash': 'admin123'`
- ❌ **測試帳號密碼明文**：admin123, hr123, user123
- ⚠️ 雖有安裝 Flask-Bcrypt，但未實際使用
- ❌ CORS 設定硬編碼：`origins=['http://localhost:5000', 'http://127.0.0.1:5000']` (第26行)

### 5. SQL Injection / XSS 防護
- ✅ 使用 SQLAlchemy ORM 進行資料庫操作，**自動防護 SQL Injection**
- ✅ 使用參數化查詢（例如：`Capability.query.filter_by(name=row['name'])`）
- ⚠️ 前端使用 Bootstrap，但未見明確的 XSS 防護機制
- ⚠️ 使用者輸入未做 sanitization（例如 JSON 輸入直接使用 `data.get('username')`）
- ⚠️ 評估資料存儲為 JSON 文字，需確認前端驗證是否完善

### 6. 其他安全疑慮
- ⚠️ **JWT 令牌簡化實作**（第124行）：使用時間戳記而非真正的 JWT
- ⚠️ **無速率限制機制**（Rate Limiting）
- ⚠️ **無 CSRF 保護**（Flask 預設未啟用）
- ⚠️ **Debug 模式啟用**，會洩漏錯誤堆疊資訊
- ⚠️ **無 HTTPS 支援**，使用 HTTP 傳輸
- ⚠️ **CORS 設定過於寬鬆**，僅允許特定來源但未動態配置
- ⚠️ 雖有認證機制但為簡化版，不適合生產環境

---

## 💻 程式品質與可維護性

### 1. 錯誤處理
- ⚠️ **錯誤處理不完善**：
  - 僅 5 個函數使用 try-except（login, register, set_department_capabilities, import_capabilities_csv）
  - 多數 API 端點（如 `/api/assessments`, `/api/star-feedbacks`）未包裝錯誤處理
  - 使用過於廣泛的 `except Exception`，未針對特定異常類型處理
  - 無統一的錯誤處理機制（middleware）
  - 錯誤訊息直接洩漏至前端（例如：第138行、第186行）
- ⚠️ **缺乏輸入驗證**：
  - 僅檢查欄位是否存在（`if not username or not password`）
  - 未驗證資料格式（例如 email 格式、密碼強度）
  - 未限制字串長度，可能導致 DoS 攻擊
- ⚠️ **異常回滾機制**：
  - 僅註冊和匯入功能有 `db.session.rollback()`
  - 其他資料庫操作無回滾機制

### 2. 程式碼結構
- ❌ **單一檔案過大**：`simple_app.py` 達954行
- ❌ **缺乏模組化**：
  - 路由、模型、業務邏輯混在一起
  - 無獨立的 `models.py`、`routes.py`、`config.py` 整合
  - 雖有 `config.py` 但未被使用
- ⚠️ **重複程式碼**：
  - JSON 回應格式重複
  - 資料轉換邏輯重複
- ✅ **註解清楚**：多數函數有 docstring

### 3. 可維護性
- ⚠️ **配置管理**：
  - 配置散落各處（第19-26行）
  - `config.py` 與 `simple_app.py` 配置不一致
  - 無統一的配置管理機制
- ⚠️ **測試覆蓋**：
  - 雖有 pytest 依賴但未見測試檔案
  - 無實際的單元測試或整合測試
- ⚠️ **日誌系統**：
  - 僅使用 `print()` 輸出訊息
  - 無結構化日誌系統（如 logging 模組）
  - 無日誌級別管理（INFO、ERROR、DEBUG）

---

## 📊 檢核結果總覽

### 專案結構與依賴檢查
- ✅ 1. 有 simple_app.py 作為入口
- ⚠️ 2. 專案結構不完善（缺少 app/src 目錄）
- ✅ 3. 有 requirements.txt
- ✅ 4. 使用 Flask 框架明確
- ✅ 5. 有完整的 README.md 與安裝說明
- ⚠️ 6. 部分依賴未實際使用（JWT、Bcrypt、APScheduler）
- ❌ 7. 端口與主機位址硬編碼，未使用環境變數

### 安全性與環境變數檢核
- ❌ 1. 無 .env 檔案
- ❌ 2. 無 .gitignore 檔案
- ⚠️ 3. 有資料庫連線設定但硬編碼
- ❌ 4. 大量敏感資訊硬編碼（SECRET_KEY、密碼、CORS）
- ⚠️ 5. SQL Injection 有防護（ORM），但 XSS 防護不足
- ❌ 6. 多項安全問題：無速率限制、無 CSRF、無 HTTPS、Debug 模式開啟、密碼未哈希

### 程式品質與可維護性
- ⚠️ 1. 錯誤處理不完善（僅部分函數有，且過於廣泛）
- ❌ 2. 程式碼未模組化（單檔954行）
- ⚠️ 3. 無測試覆蓋、無結構化日誌、配置管理混亂

---

## 📈 評分結果

### 專案結構與依賴 (30分)
- 入口檔案：5/5
- 專案結構：3/5（缺乏標準化結構）
- 依賴管理：5/5
- 框架識別：5/5
- README 完整度：5/5
- 依賴安全性：3/5（部分未使用）
- 端口配置：0/5（硬編碼）

**小計：26/30 分**

### 安全性與環境變數 (40分)
- 環境變數：0/10（無 .env 且硬編碼）
- .gitignore：0/5（缺失）
- 資料庫連線：3/10（有設定但硬編碼）
- 敏感資訊：0/10（大量硬編碼）
- SQL Injection 防護：5/5（ORM 自動防護）
- XSS 防護：3/5（部分防護，輸入驗證不足）
- 其他安全措施：0/10（多項缺失）

**小計：11/40 分**

### 程式品質與可維護性 (30分)
- 錯誤處理：3/10（不完善且不統一）
- 程式碼結構：2/10（單檔過大、未模組化）
- 測試覆蓋：0/5（無測試）
- 日誌系統：0/5（僅使用 print）

**小計：5/30 分**

---

## 🎯 總分：42/100 分

### 評分說明
- **26/30** - 專案結構與依賴：結構基本完整但配置管理需改善
- **11/40** - 安全性：重大安全問題，不符合生產環境標準
- **5/30** - 程式品質：程式碼組織混亂，缺乏錯誤處理與測試

---

## ⚠️ 嚴重問題清單（需立即修正）

### 🔴 高風險（必須修正）
1. ❌ **密碼明文存儲** - 必須使用 Flask-Bcrypt 哈希
2. ❌ **SECRET_KEY 硬編碼** - 必須使用環境變數
3. ❌ **無 .gitignore** - 可能洩漏敏感資訊
4. ❌ **調試模式開啟** - 生產環境需關閉
5. ❌ **無速率限制** - 易受暴力破解攻擊

### 🟠 中風險（建議修正）
6. ⚠️ **單檔程式碼過大** - 需模組化拆分
7. ⚠️ **錯誤處理不統一** - 需建立統一機制
8. ⚠️ **無測試覆蓋** - 需補充單元測試
9. ⚠️ **輸入驗證不足** - 需加強資料驗證
10. ⚠️ **無結構化日誌** - 需使用 logging 模組

### 🟡 低風險（可改善）
11. ⚠️ **未使用 .env** - 可改善配置管理
12. ⚠️ **未使用 config.py** - 可整合配置
13. ⚠️ **CORS 硬編碼** - 可使用環境變數
14. ⚠️ **無 HTTPS** - 建議生產環境啟用

---

## ✅ 優點

1. ✅ 使用 ORM 自動防護 SQL Injection
2. ✅ 具備完整的 API 端點（認證、評估、回饋、排名）
3. ✅ 文件齊全（README、專案總結、安全審計）
4. ✅ 依賴管理明確（requirements.txt）
5. ✅ 功能豐富（儀表板、評估、回饋、排名、管理）
6. ✅ 前端響應式設計（Bootstrap 5）
7. ✅ 具備基本錯誤處理（部分功能）

---

## 📝 建議改進方向

### 立即改進（生產環境前）
1. 建立 `.env` 與 `.env.example` 檔案
2. 建立 `.gitignore` 檔案
3. 實作密碼哈希（Flask-Bcrypt）
4. 將所有硬編碼配置移至環境變數
5. 關閉 Debug 模式
6. 實作 CSRF 保護
7. 實作速率限制

### 短期改進（1-2 週）
8. 模組化程式碼（拆分 models.py, routes.py, utils.py）
9. 統一錯誤處理機制（建立 middleware）
10. 加強輸入驗證（使用 Flask-WTF 或自訂驗證器）
11. 實作結構化日誌（logging 模組）
12. 補充單元測試與整合測試

### 長期改進（1-2 個月）
13. 配置 HTTPS/TLS
14. 升級至 MySQL 或 PostgreSQL
15. 實作 JWT 認證
16. 建立監控與告警機制
17. 實作 CI/CD 流程
18. 進行安全滲透測試

---

## 📌 結論

此專案**作為開發/測試環境的簡化版本基本可用**，功能完整且文件齊全。但**不符合生產環境安全標準**，存在多項嚴重安全漏洞（密碼明文、無速率限制、Debug 模式等）。

**建議：**
- ✅ 適合：內部測試、功能演示、快速原型開發
- ❌ 不適合：生產環境、公開部署、處理真實用戶資料

**若要部署至生產環境，必須先完成所有高風險問題的修正。**

---

**檢核完成時間：** 2025年1月28日  
**下次檢核建議：** 完成安全修正後