1015_IT_behavior_alignment_V2/Check.md

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

檢核日期： 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日
下次檢核建議： 完成安全修正後