# 專案健檢報告

## 基本資訊

- **專案名稱**：Cluster4NPU UI — Visual Pipeline Designer
- **版本**：v0.0.3
- **程式碼來源**：本地路徑 `C:\Users\sungs\Documents\abin\temp\cluster4npu`
- **Git 分支**：developer（主分支為 main）
- **最後 commit**：feat: Reorganize test scripts and improve YOLOv5 postprocessing
- **健檢日期**：2026-04-05

---

## 技術堆疊

| 層級 | 技術 | 版本 |
|------|------|------|
| 語言 | Python | >=3.9, <3.12 |
| GUI 框架 | PyQt5 | >=5.15.11 |
| 視覺節點編輯器 | NodeGraphQt | >=0.6.40 |
| 影像處理 | OpenCV | (runtime dependency) |
| 數值運算 | NumPy | (runtime dependency) |
| 硬體 SDK | Kneron KP SDK | (runtime, NPU dongle 驅動) |
| 套件管理 | uv | — |
| 打包 | PyInstaller (main.spec) | — |

**支援硬體：** Kneron NPU dongles — KL520、KL720、KL1080

---

## 專案結構概覽

```
cluster4npu/
├── main.py                        # 應用程式入口點
├── config/                        # 設定與主題 (settings.py, theme.py)
├── core/
│   ├── pipeline.py                # Pipeline 分析、stage 偵測、驗證
│   ├── functions/
│   │   ├── InferencePipeline.py   # 多 stage pipeline 執行引擎（多執行緒）
│   │   ├── Multidongle.py         # NPU dongle 管理與自動偵測
│   │   ├── camera_source.py       # 相機輸入來源
│   │   ├── video_source.py        # 影片輸入來源
│   │   ├── result_handler.py      # 推論結果處理
│   │   ├── workflow_orchestrator.py
│   │   ├── mflow_converter.py     # .mflow 格式轉換
│   │   └── yolo_v5_postprocess_reference.py
│   └── nodes/                     # 節點定義（5 種類型）
│       ├── base_node.py
│       ├── input_node.py
│       ├── model_node.py
│       ├── preprocess_node.py
│       ├── postprocess_node.py
│       ├── output_node.py
│       ├── simple_input_node.py
│       └── exact_nodes.py
├── ui/
│   ├── windows/                   # 主視窗（login.py, dashboard.py, pipeline_editor.py）
│   ├── components/                # 可重用元件（node_palette, properties_widget, common_widgets）
│   └── dialogs/                   # 對話框（deployment, performance, stage_config 等）
├── utils/                         # 工具函式（file_utils, folder_dialog, ui_utils）
├── example_utils/                 # 範例後處理工具（ByteTrack 等）
├── tests/                         # 測試腳本（42 個，多為腳本式，非正式 test suite）
├── resources/                     # 資源檔案
└── output/                        # 推論輸出結果
```

---

## 文件完整度

| 文件類型 | 狀態 | 位置 | 備註 |
|---------|------|------|------|
| README | ✅ 有 | `README.md` | 詳細，含安裝、架構說明 |
| 產品需求 / PRD | ⚠️ 部分 | `PROJECT_SUMMARY.md` | 有願景與待開發功能，但非正式 PRD 格式 |
| 開發路線圖 | ✅ 有 | `DEVELOPMENT_ROADMAP.md` | 四個 Phase，有具體目標 |
| 架構設計文件 | ❌ 無 | — | README 內有簡介，但無正式 Design Doc |
| API 文件 | ❌ 無 | — | 無正式 API 文件 |
| 設計稿 | ❌ 無 | 只有 `Flowchart.jpg` | 無 Wireframe 或 UI 規格 |
| 技術設計文件 (TDD) | ❌ 無 | — | 無 |
| 測試計畫 | ❌ 無 | — | 有測試腳本但無正式測試計畫 |
| 部署文件 | ⚠️ 部分 | README 內 | 有基本步驟，無完整部署文件 |
| Release Notes | ✅ 有 | `release_note.md` | 目前到 v0.0.2 |

---

## 程式碼健康度

- **測試覆蓋率**：⚠️ 部分測試 — `tests/` 下有 42 個腳本，但多為情境測試腳本（非 pytest 單元測試），缺乏系統性覆蓋
- **程式碼品質**：中等 — 有明確的模組分離；部分根目錄腳本（debug_*.py, force_cleanup.py 等）為開發過程遺留，結構略混亂
- **安全性**：低風險（本地桌面應用，無網路 API）
- **技術債**：
  - 根目錄有多個 debug/cleanup 腳本未整理
  - tests/ 下腳本命名與分類混亂（部分非 test_ 開頭）
  - 缺乏正式的 pytest 測試架構

---

## 現有功能清單

| 功能 | 描述 | 狀態 |
|------|------|------|
| 視覺化 Pipeline 編輯器 | 拖拽節點建立 Pipeline（NodeGraphQt） | ✅ 完成 |
| 5 種節點類型 | Input / Preprocess / Model / Postprocess / Output | ✅ 完成 |
| Pipeline 驗證 | 即時 stage 偵測與錯誤標示 | ✅ 完成 |
| .mflow 檔案格式 | Pipeline 儲存與載入（JSON） | ✅ 完成 |
| 多 NPU Dongle 支援 | KL520 / KL720 / KL1080 自動偵測 | ✅ 完成 |
| 多 stage 推論引擎 | 多執行緒 Pipeline 執行 | ✅ 完成 |
| 效能監控 | FPS、延遲即時顯示 | ✅ 完成（有 known bugs） |
| 相機 / 影片 / 圖片輸入 | 多種輸入來源 | ✅ 完成 |
| 專案管理 | 登入畫面、最近專案、新增/載入 Pipeline | ✅ 完成 |
| YOLOv5 後處理 | 偵測結果格式化 | ✅ 完成（最近改善） |
| ByteTrack 追蹤 | 物件追蹤後處理 | ✅ 完成（example_utils） |

---

## 缺失項目摘要（待開發）

根據 `PROJECT_SUMMARY.md` 與 `DEVELOPMENT_ROADMAP.md`：

1. **效能視覺化**：並行 vs 循序執行比較、Speedup 指標顯示（Phase 1）
2. **Benchmarking 系統**：自動化效能測試、圖表比較（Phase 1）
3. **裝置管理介面**：視覺化裝置分配、負載平衡（Phase 2）
4. **即時監控 Dashboard**：FPS/延遲圖表、資源使用率（Phase 2）
5. **優化引擎**：自動化建議、效能預測（Phase 3）

已知 Bug：
- 節點屬性顯示問題
- 輸出視覺化（含後處理）

---

## CI/CD 與基礎設施

| 項目 | 狀態 |
|------|------|
| Docker | ❌ 無 |
| CI/CD | ❌ 無 |
| 部署設定 | ❌ 無（本地桌面應用，有 PyInstaller spec） |
| 環境變數管理 | ❌ 無 |
| 版本控制 | ✅ Git（GitHub 遠端） |