forked from masonhuang/KNEO-Academy
174 lines
6.4 KiB
Markdown
174 lines
6.4 KiB
Markdown
# 專案健檢報告 — 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）
|