# 專案健檢報告 — KNEO Academy

## 基本資訊
- **專案名稱**：KNEO Academy（Innovedus AI Playground）
- **版本**：v2.0
- **程式碼來源**：本地路徑 `C:\Users\sungs\Documents\abin\KNEO-Academy`
- **主要語言**：Python 3.12
- **最後更新時間**：2026-04-04
- **Git branch**：main

---

## 技術堆疊

| 層級 | 技術 | 版本 |
|------|------|------|
| GUI 框架 | PyQt5 | 5.15.11 |
| 電腦視覺 | OpenCV | 4.10.0.84 |
| AI 推論 SDK | KneronPLUS | 3.1.2 |
| AI 推論（通用） | PyTorch, TensorFlow, ONNX Runtime | 最新 |
| 音訊 | librosa, sounddevice | — |
| 打包 | PyInstaller | 6.12.0 |
| 加密 | PyArmor | — |

---

## 專案結構概覽

```
KNEO-Academy/
├── main.py                         # Entry point，AppController（QStackedWidget 管理頁面）
├── src/
│   ├── config.py                   # 全域常數、路徑、顏色、DeviceType enum
│   ├── controllers/
│   │   ├── device_controller.py    # Kneron dongle 掃描、連接、韌體上傳
│   │   ├── inference_controller.py # 推論工具選擇、model 載入、queue 管理
│   │   └── media_controller.py     # 相機、影片捕捉
│   ├── models/
│   │   ├── inference_worker.py     # 標準推論 worker thread（動態載入 script.py）
│   │   ├── custom_inference_worker.py # 自定義模型推論 worker（YOLOv5 後處理）
│   │   └── video_thread.py         # 相機影像擷取 thread
│   ├── views/
│   │   ├── mainWindows.py          # 主應用視窗（推論結果顯示、工具選擇）
│   │   ├── selection_screen.py     # 首頁選擇畫面
│   │   ├── login_screen.py         # 工具程式登入頁
│   │   └── utilities_screen.py     # 裝置管理工具頁
│   ├── services/
│   │   ├── device_service.py       # 掃描 Kneron 裝置（含 timeout 機制）
│   │   ├── file_service.py         # 檔案上傳服務
│   │   └── script_service.py       # 推論腳本執行服務
│   └── utils/
│       ├── config_utils.py         # 設定工具
│       └── image_utils.py          # QImage ↔ NumPy 轉換
├── uxui/                           # 靜態 UI 資源（PNG、SVG、GIF）
├── dist/
│   └── test.iss                    # Inno Setup 安裝包設定
├── flowchart.md                    # 裝置連接流程設計圖（Mermaid）
└── env.txt                         # pip 套件清單
```

**資料目錄（執行期，存在 %LOCALAPPDATA%/Kneron_Academy/）：**
```
uploads/          # 使用者上傳的圖片/影片
utils/
  config.json     # 全域 plugin 設定
  {mode}/{model}/
    script.py     # 推論腳本
    config.json   # 模型設定
    *.nef         # 模型檔
firmware/
  {device}/
    fw_scpu.bin
    fw_ncpu.bin
```

---

## 應用頁面流程

```
SelectionScreen（首頁）
  ├── → LoginScreen → UtilitiesScreen（裝置管理工具，需登入）
  └── → MainWindow（Demo AI App，直接進入）
```

---

## 主要功能清單

| 功能 | 描述 | 狀態 |
|------|------|------|
| 頁面路由 | QStackedWidget 管理多頁面切換 | ✅ 完成 |
| 裝置掃描 | 掃描連接的 Kneron dongle（KL520 / KL720） | ✅ 完成 |
| 裝置連接 | 連接裝置並上傳 firmware | ✅ 完成 |
| 裝置中斷 | 安全中斷連接 | ✅ 完成 |
| Video 推論 | 相機即時推論（QThread + queue） | ✅ 完成 |
| Image 推論 | 上傳圖片單次推論 | ✅ 完成 |
| 動態 Script 載入 | 從 utils/ 目錄動態 import script.py | ✅ 完成 |
| 自定義模型推論 | 上傳 .nef + firmware，使用 YOLOv5 後處理 | ✅ 完成 |
| Plugin 系統 | 透過 config.json 定義 mode/model 結構 | ✅ 完成 |
| APP 打包 | PyInstaller 打包 + Inno Setup 安裝包 | ✅ 有設定 |
| 登入驗證 | Server 驗證（詳細流程見 flowchart.md） | 🔄 設計中（有 flowchart） |
| Dongle 授權管理 | KN 號碼查詢、授權卡驗證 | 🔄 設計中（有 flowchart） |

---

## 文件完整度

| 文件類型 | 狀態 | 位置 | 備註 |
|---------|------|------|------|
| README | ✅ 有 | `README.md` | 完整，含安裝、架構、功能說明 |
| 流程圖 | ⚠️ 部分 | `flowchart.md` | 僅有裝置連接/授權流程，缺主 App 完整流程 |
| PRD / 需求文件 | ❌ 無 | — | 無正式產品需求文件 |
| 架構設計文件 | ❌ 無 | — | 無正式架構文件 |
| API 文件 | ❌ 無 | — | 無（script.py 介面未有規格文件） |
| 設計稿 | ⚠️ 部分 | `uxui/` | 有 UI 資源圖，無 Wireframe 或設計規格 |
| TDD（技術設計文件） | ❌ 無 | — | 無 |
| 測試文件 | ❌ 無 | — | README 提到 tests/ 目錄，但實際不存在 |
| 部署文件 | ⚠️ 部分 | `dist/test.iss` | 有 Inno Setup 設定，無完整部署指南 |

---

## 程式碼健康度

| 項目 | 狀態 | 備註 |
|------|------|------|
| 測試覆蓋率 | ❌ 無測試 | tests/ 目錄不存在 |
| 程式碼組織 | ✅ 良好 | MVC 架構清晰，職責分明 |
| Docstring 完整度 | ✅ 良好 | 主要類別和方法均有完整 docstring |
| 錯誤處理 | ⚠️ 部分 | 多處使用 try/except，但部分只 print 不處理 |
| Thread 安全 | ⚠️ 待確認 | Queue 管理有，但 UI 更新路徑需確認 |
| 技術債 | ⚠️ 少量 | debug print 語句散落在 controller 中 |

---

## 基礎設施

| 項目 | 狀態 | 備註 |
|------|------|------|
| Docker | ❌ 無 | 桌面應用，暫不需要 |
| CI/CD | ❌ 無 | 無自動化建置/測試流程 |
| 打包 | ✅ 有 | PyInstaller + Inno Setup |
| 加密 | ⚠️ 計畫中 | PyArmor 已列在計畫中 |
| 監控 | ❌ 無 | 無 |

---

## 目前正在修改的檔案（git status）

以下檔案有未提交的修改：

- `src/controllers/device_controller.py`
- `src/controllers/inference_controller.py`
- `src/models/custom_inference_worker.py`
- `src/models/video_thread.py`
- `src/services/device_service.py`
- `src/views/utilities_screen.py`

---

## 缺失項目摘要

**高優先：**
- PRD / 需求文件（產品功能邊界不清晰）
- 測試（完全沒有自動化測試）

**中優先：**
- 架構文件 / TDD（plugin script.py 介面規格未文件化）
- 完整流程圖（主 App 推論流程尚未有流程圖）

**低優先：**
- 部署完整指南
- 設計規格文件（Wireframe + Design Tokens）