Skip to content

Software_Engineering_Contributions.md

Latest commit

 

History

History
525 lines (395 loc) · 13.1 KB

Software_Engineering_Contributions.md

File metadata and controls

525 lines (395 loc) · 13.1 KB

軟體工程觀點下的程式碼貢獻分析

專案概述

本專案是一個基於 IEEE PHM 2012 數據挑戰的軸承剩餘使用壽命（RUL）預測與振動信號分析平台，採用現代化的全端技術架構，整合了科學計算、資料庫管理、視覺化呈現等多元技術。

一、技術架構貢獻

1.1 分層架構設計（Layered Architecture）

┌─────────────────────────────────────┐
│   前端層 (Frontend Layer)            │
│   Vue 3 + Element Plus + Vite      │
└─────────────────────────────────────┘
              ↕ REST API
┌─────────────────────────────────────┐
│   API 網關層 (API Gateway)           │
│   FastAPI + CORS Middleware         │
└─────────────────────────────────────┘
              ↕
┌─────────────────────────────────────┐
│   業務邏輯層 (Business Logic)        │
│   演算法模組 + 資料處理器           │
└─────────────────────────────────────┘
              ↕
┌─────────────────────────────────────┐
│   資料存取層 (Data Access)           │
│   SQLite 資料庫 + 查詢介面          │
└─────────────────────────────────────┘

貢獻點：

  • 清晰的職責分離，每層專注於特定功能
  • RESTful API 設計，符合標準化的通訊協定
  • 易於擴展和維護的模組化架構

1.2 微服務就緒架構（Microservice-Ready）

專案採用 Docker 容器化部署，具備以下優勢：

# docker-compose.yml 的貢獻
- 獨立的後端服務（Python 3.11 + FastAPI）
- 獨立的前端服務（Node.js + Vite）
- Volume 掛載實現資料持久化
- 健康檢查機制

貢獻點：

  • 開發與生產環境一致性
  • 水平擴展能力
  • 輕鬆的 CI/CD 整合

二、程式碼組織與設計模式貢獻

2.1 模組化設計（Modular Design）

後端演算法模組分類

模組 職責 類別
timedomain.py 時域特徵提取（Peak, RMS, Kurtosis, CF, EO） 靜態分析
frequencydomain.py 頻域特徵（FFT, FM0, TSA-FFT） 頻譜分析
filterprocess.py 高階統計（NA4, FM4, M6A, M8A, ER） 進階濾波
timefrequency.py 時頻分析（STFT, CWT, Spectrogram） 時頻分析
hilberttransform.py 希爾伯特轉換與包絡分析 包絡分析

貢獻點：

  • 單一職責原則（SRP）：每個模組專注於一種分析方法
  • 開閉原則（OCP）：易於新增演算法而不修改現有代碼
  • 依賴倒置原則（DIP）：演算法不依賴於具體實現細節

資料庫查詢模組分離

# 獨立的查詢介面類
class PHMDatabaseQuery:      # 振動數據查詢
class PHMTemperatureQuery:   # 溫度數據查詢
class PHMDataProcessor:      # 資料處理與特徵提取

貢獻點：

  • 關注點分離（Separation of Concerns）
  • 減少耦合度，提高測試性
  • 便於未來擴展其他數據類型

2.2 設計模式應用

工廠模式（Factory Pattern）

# 演算法實例化統一管理
td = TimeDomain()
fd = FrequencyDomain()
fp = FilterProcess()
tf = TimeFrequency()
ht = HilbertTransform()

貢獻點：

  • 統一的對象創建方式
  • 降低客戶端與具體實現的耦合

單例模式（Singleton Pattern）

# 資料庫連線管理
_db_local = threading.local()

@contextlib.contextmanager
def get_db_connection(db_path: str):
    # 使用線程本地存儲確保每個線程有自己的連接
    conn = getattr(_db_local, 'conn', None)
    if conn is None:
        conn = sqlite3.connect(db_path)
        _db_local.conn = conn

貢獻點：

  • 資料庫連線池管理
  • 提升性能，避免頻繁創建/關閉連接
  • 線程安全的資源管理

策略模式（Strategy Pattern）

# 不同的分析方法可互換
features = FilterProcess.calculate_all_features(signal, sampling_rate, segment_count)

貢獻點：

  • 演算法可互換
  • 易於添加新的分析策略

三、API 設計貢獻

3.1 RESTful API 設計原則

資源導向的 URL 設計

GET /api/phm/database/bearings              # 獲取所有軸承
GET /api/phm/database/bearing/{name}        # 獲取特定軸承
GET /api/phm/database/bearing/{name}/files  # 獲取軸承檔案列表
GET /api/phm/database/bearing/{name}/measurements  # 獲取測量數據

貢獻點：

  • 符合 REST 風格的資源命名
  • 層次化的 URL 結構
  • 清晰的資源關係

統一的錯誤處理

try:
    # 業務邏輯
except FileNotFoundError as e:
    raise HTTPException(status_code=404, detail="友善錯誤訊息")
except Exception as e:
    raise HTTPException(status_code=500, detail=str(e))

貢獻點：

  • 一致的錯誤回應格式
  • 友善的錯誤訊息
  • 適當的 HTTP 狀態碼

3.2 API 端點數量與複雜度

專案提供 30+ 個 API 端點，涵蓋：

  • 數據查詢：7 個端點（軸承、檔案、測量數據、統計、異常）
  • 時域分析：2 個端點（單檔分析、趨勢分析）
  • 頻域分析：4 個端點（FFT、FM0、TSA、趨勢）
  • 包絡分析：2 個端點（包絡頻譜、希爾伯特轉換）
  • 時頻分析：3 個端點（STFT、CWT、Spectrogram）
  • 高階統計：2 個端點（濾波特徵、趨勢）
  • 溫度數據：6 個端點（查詢、趨勢、統計、搜尋）

貢獻點：

  • 完整的功能覆蓋
  • 合理的端點粒度
  • 支持單檔與多檔批量分析

四、資料庫設計貢獻

4.1 正規化資料庫結構

振動數據庫（phm_data.db）

bearings (一對多)
  ↓
measurement_files (一對多)
  ↓
measurements

貢獻點：

  • 第三正規化（3NF）：消除冗餘，避免異常
  • 外鍵約束確保數據完整性
  • 索引優化（bearing_id, file_id）

4.2 獨立的資料庫設計

  • 振動數據庫：phm_data.db
  • 溫度數據庫：phm_temperature_data.db

貢獻點：

  • 關注點分離
  • 獨立擴展能力
  • 更好的性能優化空間

五、配置管理貢獻

5.1 集中式配置（config.py）

# 資料庫路徑
PHM_DATABASE_PATH = os.path.join(BACKEND_DIR, "phm_data.db")
PHM_TEMPERATURE_DATABASE_PATH = os.path.join(BACKEND_DIR, "phm_temperature_data.db")

# 採樣率配置
DEFAULT_SAMPLING_RATE = 25600  # Hz

# 包絡分析濾波器配置
ENVELOPE_FILTER_LOWCUT = 10  # Hz
ENVELOPE_FILTER_HIGHCUT = 500  # Hz

# 資料點顯示限制
SIGNAL_DISPLAY_LIMIT = 1000
SPECTRUM_DISPLAY_LIMIT = 1000

貢獻點：

  • 單一真相來源（Single Source of Truth）
  • 易於環境切換（開發/生產）
  • 可維護性提升

5.2 動態路徑處理

_current_dir = os.path.dirname(os.path.abspath(__file__))
if _current_dir not in sys.path:
    sys.path.insert(0, _current_dir)

貢獻點：

  • 容器環境兼容性
  • 跨平台路徑處理
  • 避免硬編碼路徑

六、前端架構貢獻

6.1 Vue 3 Composition API

<script setup>
// 組合式 API，更好的邏輯復用
import { ref, computed, onMounted } from 'vue'
</script>

貢獻點：

  • 更好的 TypeScript 支援
  • 更靈活的邏輯組織
  • 減少 this 上下文混亂

6.2 路由設計

// 清晰的頁面分類
- /time-domain          # 時域分析
- /frequency-domain     # 頻域分析
- /envelope-analysis    # 包絡分析
- /time-frequency       # 時頻分析
- /higher-order-statistics  # 高階統計

貢獻點：

  • 直觀的 URL 結構
  • 易於導航的用戶體驗
  • 支援深層連結

6.3 主題系統統一

/* 深色主題變數 */
:root {
  --bg-primary: #0a0a0f;
  --bg-secondary: #141419;
  --bg-card: #1a1a23;
  --text-primary: #e4e4e7;
  --text-secondary: #a1a1aa;
  --accent-primary: #6366f1;
}

貢獻點：

  • 一致的視覺體驗
  • 易於主題切換
  • 維護性提升

七、科學計算整合貢獻

7.1 NumPy / SciPy 集成

專案深度整合科學計算庫：

import numpy as np
from scipy import signal
from scipy.fft import fft, fftfreq
from scipy.signal import hilbert, butter, filtfilt

貢獻點：

  • 高效的數值計算
  • 專業的信號處理能力
  • 與學術界標準對接

7.2 Pandas 資料處理

import pandas as pd
df = pd.read_sql_query(query, conn)

貢獻點：

  • 強大的資料操作能力
  • 統一的資料格式處理
  • 易於數據分析和視覺化

八、可維護性與可擴展性貢獻

8.1 程式碼註釋與文檔

"""
PHM Database Query Module
Provides query functionality for PHM IEEE 2012 data stored in SQLite.
"""

貢獻點：

  • 清晰的模組說明
  • 函數級別的文檔字串
  • 易於新開發者理解

8.2 向後兼容性

@app.get("/api/algorithms/higher-order/{bearing_name}/{file_number}")
async def calculate_higher_order_stats(...):
    """
    此端點已整合至 /api/algorithms/filter-features
    為了向後兼容性保留
    """

貢獻點：

  • 保護現有 API 使用者
  • 平滑的版本過渡
  • 降低遷移成本

九、開發體驗貢獻

9.1 快速啟動腳本

scripts/start_backend.sh
scripts/start_frontend.sh

貢獻點：

  • 降低入門門檻
  • 標準化啟動流程
  • 減少環境配置錯誤

9.2 uv 套件管理器支援

uv run python main.py

貢獻點：

  • 極快的依賴安裝速度
  • 更好的虛擬環境管理
  • 減少開發時間

十、總體貢獻總結

10.1 技術優勢

維度 評分 說明
架構設計 ⭐⭐⭐⭐⭐ 清晰的分層架構，模組化設計
程式碼質量 ⭐⭐⭐⭐ 良好的命名規範，適當的抽象
可維護性 ⭐⭐⭐⭐⭐ 配置集中化，文檔完備
可擴展性 ⭐⭐⭐⭐⭐ 開閉原則，易於新增功能
性能優化 ⭐⭐⭐⭐ 資料庫連線池，分頁查詢
用戶體驗 ⭐⭐⭐⭐⭐ 友善的錯誤處理，一致的 API
容器化 ⭐⭐⭐⭐⭐ Docker 支援，易於部署

10.2 軟體工程最佳實踐應用

✅ SOLID 原則

  • 單一職責原則（SRP）
  • 開閉原則（OCP）
  • 里氏替換原則（LSP）
  • 介面隔離原則（ISP）
  • 依賴倒置原則（DIP）

✅ DRY 原則

  • 不重複自己（Don't Repeat Yourself）
  • 抽取共同邏輯

✅ KISS 原則

  • 保持簡單愚蠢（Keep It Simple, Stupid）
  • 避免過度工程化

✅ YAGNI 原則

  • 你不會需要它（You Aren't Gonna Need It）
  • 不預先實現不需要的功能

10.3 對軟體工程領域的貢獻

  1. 學術研究與工程實踐的橋樑

    • 將 IEEE PHM 2012 競賽數據轉化為可用的工程系統
    • 提供了從研究到應用的完整範例

  2. 振動分析領域的參考實現

    • 整合了多種經典振動分析演算法
    • 提供了標準化的 API 設計

  3. 全端開發的最佳實踐範例

    • Vue 3 + FastAPI 的現代技術棧
    • Docker 容器化部署
    • 科學計算與 Web 應用的整合

  4. 教育價值

    • 清晰的程式碼結構便於學習
    • 完整的文檔降低入門門檻
    • 實際的工程案例教學

十一、改進建議

11.1 短期改進

  1. 單元測試覆蓋

    # 建議添加測試
tests/test_timedomain.py
tests/test_frequencydomain.py
tests/test_phm_query.py

  2. API 版本控制

    /api/v1/algorithms/time-domain/...
/api/v2/algorithms/time-domain/...

  3. 日誌系統

    import logging
logging.basicConfig(level=logging.INFO)

11.2 長期改進

  1. 異步處理

    • 使用 asyncio 優化長時間運行的計算
    • 任務隊列（Celery）處理批量分析

  2. 快取機制

    • Redis 快取計算結果
    • 減少重複計算開銷

  3. 微服務化

    • 將不同分析模組拆分為獨立服務
    • 提升系統的擴展性和可靠性

  4. 機器學習整合

    • 預測模型部署
    • 實時異常檢測

結論

這個專案從軟體工程的角度來看，是一個設計優良、架構清晰、可維護性高的全端應用系統。它不僅成功整合了複雜的科學計算演算法，還採用了現代化的技術棧和最佳實踐，對振動分析領域和軟體工程實踐都有重要貢獻。

核心價值：

  • 🔬 科學計算與 Web 技術的完美結合
  • 🏗️ 清晰架構與模組化設計
  • 🚀 容器化部署與現代 DevOps 實踐
  • 📚 文檔完備與教育價值
  • 🔧 易於擴展與長期維護

這是一個可以作為學術研究轉化為工程應用的優秀範例，值得相關領域的開發者學習和參考。