# KNEO Academy（Innovedus AI Playground）v2.0 — 產品需求文件（PRD）

> **文件性質說明**：本 PRD 為從既有程式碼與文件反向整理而成，已對照 README.md、flowchart.md、主要 controller、view 和 service 原始碼推導。標注「⚠️ 待確認」的項目為推斷內容，請產品負責人核實。

---

## 1. 產品概述

### 1.1 產品定位

**KNEO Academy**（對外名稱：**Innovedus AI Playground**）是一款 Windows 桌面應用程式，讓擁有 Kneron NPU USB Dongle 硬體的客戶能夠在本機端執行 AI 推論，無需雲端服務、無需自行撰寫程式碼。

**核心價值主張**：
- 即插即用的 Edge AI 體驗——插上 Kneron dongle 即可執行 AI 模型
- 支援多種推論模式（即時攝影機、圖片上傳、自定義模型）
- 透過 Plugin 系統讓第三方或 Kneron 官方模型能被彈性載入
- 提供硬體管理工具（韌體更新、驅動安裝、裝置授權）

### 1.2 目標使用者

**主要使用者（Persona A）：企業/研發客戶**
- 角色：使用 Kneron NPU 硬體進行 AI PoC 或產品評估的工程師、研究人員
- 目標：快速驗證 Kneron NPU 在特定任務上的推論效果
- 技術素養：中等（懂 AI 概念，不一定熟悉 SDK 整合）
- 痛點：Kneron SDK 入門門檻高，想要一個能快速展示能力的工具

**次要使用者（Persona B）：內部 Demo / 業務展示**
- 角色：Kneron / Innovedus 業務或技術支援人員
- 目標：向潛在客戶展示 Kneron NPU 的 AI 推論能力
- 技術素養：低至中等
- 痛點：需要一個無需開發、開箱即用的展示工具

**⚠️ 待確認**：上述 Persona 定義是從產品功能推斷。實際目標客群請與產品負責人確認。

### 1.3 應用名稱對照

| 名稱 | 用途 |
|------|------|
| KNEO Academy | 專案內部/開發用名稱 |
| Innovedus AI Playground | 對外正式名稱（`APP_NAME` 常數定義） |

---

## 2. 支援的硬體裝置

應用程式目前支援以下 Kneron NPU Dongle 型號（來自 `config.py` 的 `DeviceType` Enum）：

| 裝置型號 | Product ID（Hex） | 支援狀態 |
|---------|-----------------|---------|
| KL520 | 0x100 | ✅ 已支援（有 icon、model map） |
| KL720 | 0x720 | ✅ 已支援（有 icon、model map） |
| KL720_L | 0x200 | ⚠️ Enum 有定義，但無 DongleModelMap 對應，**可能不完整** |
| KL530 | — | ⚠️ Enum 有定義，但無 DongleModelMap 對應 |
| KL832 | — | ⚠️ Enum 有定義，但無 DongleModelMap 對應 |
| KL730 | — | ⚠️ Enum 有定義，但無 DongleModelMap 對應 |
| KL630 | — | ⚠️ Enum 有定義，但無 DongleModelMap 對應 |
| KL540 | — | ⚠️ Enum 有定義，但無 DongleModelMap 對應 |

**⚠️ 待確認**：KL520 和 KL720 以外的裝置是否已在計畫中支援？`DongleModelMap` 僅有這兩型。

---

## 3. 應用程式頁面架構

### 3.1 頁面流程圖

```
應用程式啟動
    │
    ▼
SelectionScreen（首頁 / 入口選擇畫面）
    ├── [Demo App 按鈕] ──────────────────→ MainWindow（AI Demo 推論主視窗）
    └── [Utilities 按鈕] → LoginScreen（登入畫面）
                                │
                                ├── [登入成功] → UtilitiesScreen（裝置管理工具）
                                └── [返回]     → SelectionScreen
```

### 3.2 各頁面功能摘要

| 頁面 | Class 名稱 | 主要用途 | 需要登入 |
|------|-----------|---------|---------|
| 首頁 | `SelectionScreen` | 選擇進入 Demo App 或 Utilities 工具 | 否 |
| 登入畫面 | `LoginScreen` | Server 驗證，作為進入 Utilities 的門禁 | — |
| 裝置管理工具 | `UtilitiesScreen` | 裝置掃描、韌體更新、驅動安裝、已購項目 | 是 |
| AI Demo 主視窗 | `MainWindow` | AI 推論執行、攝影機顯示、工具選擇 | 否 |

---

## 4. 功能需求

### 4.1 SelectionScreen（首頁選擇畫面）

**功能描述**：應用程式的入口，提供兩個主要路徑。

**功能清單**：
- 顯示應用程式 Logo 與名稱
- 「Demo App」按鈕：直接進入 AI 推論主視窗（不需登入）
- 「Utilities」按鈕：跳轉到登入畫面，登入後才能進入裝置管理工具

**⚠️ 待確認**：首頁是否有其他 UI 元素（介紹文字、版本號等）？

---

### 4.2 LoginScreen（登入畫面）

**功能描述**：透過 Server 驗證機制保護 Utilities 功能的存取。

**功能清單**：
- 帳號密碼輸入欄位
- 登入按鈕 → 觸發 Server 驗證
- 返回按鈕 → 回到 SelectionScreen

**登入結果處理**：
| 情境 | 行為 |
|------|------|
| 驗證成功 | 發出 `login_success` signal → 進入 UtilitiesScreen |
| 帳密錯誤 | 顯示「無效用戶名或密碼」提示 |
| 多次錯誤 | Server 停止服務，顯示提示訊息 |
| 返回 | 發出 `back_to_selection` signal → 回到 SelectionScreen |

**⚠️ 待確認**：
- 登入 Server 的端點 URL 在哪裡設定？（程式碼中未見明確設定）
- 是否有記住密碼/Token 快取機制？

---

### 4.3 UtilitiesScreen（裝置管理工具頁面）

**功能描述**：登入後才能存取的裝置管理介面，包含兩個子頁面。

#### 4.3.1 Utilities 子頁面（裝置管理）

**功能清單**：

**裝置掃描與列表**
- 掃描當前連接的 Kneron dongle 裝置（呼叫 `check_available_device()`，含 5 秒 timeout）
- 以表格（`QTableWidget`）顯示裝置清單，欄位包含：裝置型號、KN Number、狀態
- 「Refresh」按鈕：重新掃描裝置
- 未偵測到裝置時顯示提示

**裝置連接操作**
- 選擇裝置後可執行連接（透過 `DeviceController.connect_device()`）
- 連接過程：
  1. 驗證 firmware 檔案是否存在（`%LOCALAPPDATA%/Kneron_Academy/firmware/{device}/`）
  2. 呼叫 `kp.core.connect_devices()`
  3. 上傳 firmware（`fw_scpu.bin` + `fw_ncpu.bin`）
- 中斷連接按鈕（`DeviceController.disconnect_device()`）

**Firmware 管理**
- 顯示目前 Firmware 版本
- 偵測到版本需要更新時，提示使用者是否更新
- 支援從本機載入 firmware 檔案進行更新

**Driver 管理**（⚠️ 設計中，尚未完整實作）
- 偵測 Kneron USB driver 是否已安裝
- 尚未安裝時：提示安裝，詢問使用者是否執行安裝程序
- 安裝失敗處理：顯示錯誤訊息

**Dongle 授權管理**（⚠️ 設計中，尚未完整實作）
- 查詢 KN Number（Dongle 唯一識別號）
- 授權卡（Authorization Card）驗證流程
- 已授權裝置：顯示已授權提示
- 未授權裝置：詢問是否啟動授權，執行授權流程
- **詳細流程見 `flowchart.md`**

**狀態顯示**
- `QProgressBar`：顯示操作進度（連接、韌體上傳等）
- `QLabel`（status_label）：顯示目前狀態訊息

#### 4.3.2 Purchased Items 子頁面（已購項目）

**功能描述**：顯示用戶已購買的 AI 模型，可以下載到本機。

**功能清單**：
- 表格顯示已購買項目，欄位：Select（勾選）、Product（產品名）、Model（模型名）、Current Version（版本）、Compatible Dongles（相容裝置）
- 多選（Checkbox）功能
- 「Refresh Items」按鈕：重新從 Server 取得已購列表
- 「Download Selected」按鈕：下載所選項目到本機

**⚠️ 待確認**：
- 目前程式碼中有 `populate_mock_purchased_items()` 方法，顯示此功能使用 Mock 資料，**尚未對接真實 API**
- 下載後的模型存放路徑？（推斷為 `%LOCALAPPDATA%/Kneron_Academy/utils/`）
- 購買平台/Store 是否已確定？

---

### 4.4 MainWindow（AI Demo 推論主視窗）

**功能描述**：核心的 AI 推論展示視窗，整合攝影機顯示、工具選擇與推論結果呈現。

#### 4.4.1 畫面布局組件

| 組件 | Class 名稱 | 功能 |
|------|-----------|------|
| 攝影機顯示區 | `CanvasArea` | 顯示攝影機畫面和推論結果（Bounding Box 等） |
| 裝置清單 | `DeviceList` | 顯示可連接的 dongle，讓使用者選擇 |
| 裝置連接彈窗 | `DevicePopup` | 彈出式裝置連接確認介面 |
| 媒體控制面板 | `MediaPanel` | 攝影機開啟/暫停、圖片上傳按鈕 |
| AI 工具箱 | `Toolbox` | 顯示可選擇的 AI 模型（來自 config.json） |
| 自定義模型上傳 | `CustomModelBlock` | 上傳自定義 .nef 模型的 UI |

#### 4.4.2 AI 推論模式

##### 模式一：Video 模式（即時攝影機推論）

**流程**：
1. 使用者選擇 Video 類型的 AI 工具
2. 呼叫 `MediaController.start_camera()` 啟動相機
3. `VideoThread` 持續擷取影像幀（640×480, 30fps），轉為 QImage 發出 signal
4. 影像幀轉為 NumPy 陣列後，透過 `InferenceController.add_frame_to_queue()` 放入推論 queue（最大容量：5 幀）
5. `InferenceWorkerThread` 從 queue 取出影像幀，呼叫對應的 `script.py` 執行推論
6. 推論結果透過 `inference_result_signal` 傳回主視窗
7. 主視窗在 `CanvasArea` 上繪製 Bounding Box 等視覺化結果

**效能優化機制**：
- MSE（Mean Squared Error）幀差異偵測：若連續幀的 MSE 低於 `mse_threshold=500`，沿用上一次推論結果（避免重複計算靜止畫面）
- 最短推論間隔：`min_interval=2` 秒（標準模式）
- 模型超時設定：`MODEL_TIMEOUT = 5000` ms（`config.py`）

##### 模式二：Image 模式（上傳圖片單次推論）

**流程**：
1. 使用者選擇 Image 類型的 AI 工具
2. 使用者透過 `MediaPanel` 上傳圖片（存入 `%LOCALAPPDATA%/Kneron_Academy/uploads/`）
3. 使用 `cv2.imread()` 讀取圖片，放入推論 queue（`once_mode=True`，只推論一次）
4. `InferenceWorkerThread` 執行推論並回傳結果
5. 切換到 Image 模式時，相機信號會暫時斷開（非停止），以避免 Video 模式的幀繼續進入 queue

**注意**：切回 Video 工具時，相機信號會重新連接，無需重新開啟相機。

##### 模式三：Custom Model（使用者自定義模型）

**流程**：
1. 使用者透過 `CustomModelBlock` 上傳以下三個檔案：
   - `.nef` 模型檔
   - `fw_scpu.bin`（SCPU firmware）
   - `fw_ncpu.bin`（NCPU firmware）
   - （可選）自定義標籤清單（class labels）
2. `InferenceController.select_custom_tool()` 被呼叫
3. 啟動 `CustomInferenceWorkerThread`（與標準 worker 不同的實作）
4. Custom worker 會在首次推論時自行完成：
   - 連接裝置（`kp.core.connect_devices()`）
   - 上傳 firmware
   - 上傳模型（`kp.core.load_model_from_file()`）
5. 預處理：影像縮放至 640×640，轉為 BGR565 格式
6. 後處理：使用 YOLOv5 演算法（NMS threshold=0.5）解析輸出
7. 若有提供自定義標籤，使用自定義標籤；否則使用預設 COCO 80 類別

**Custom Model 預設行為**：
- 輸入類型：Video（即時攝影機）
- 後處理演算法：固定使用 YOLOv5（**⚠️ 待確認**：是否計畫支援其他後處理演算法？）
- 預設偵測閾值：`thresh=0.2`
- 推論間隔：`min_interval=0.5` 秒（比標準模式更頻繁）

#### 4.4.3 裝置相容性檢查

當使用者選擇 AI 工具時：
- 讀取 `config.json` 中的 `compatible_devices` 欄位
- 比對目前選中的 dongle 型號
- 若不相容，彈出警告對話框並阻止推論啟動

---

### 4.5 Plugin 系統（Script & Model 配置）

**功能描述**：透過設定檔驅動的 Plugin 架構，讓 AI 模型能被動態載入，無需修改應用程式原始碼。

#### 4.5.1 檔案結構

```
%LOCALAPPDATA%/Kneron_Academy/
├── uploads/                    # 使用者上傳的圖片/影片
├── utils/
│   ├── config.json             # 全域 plugin 設定（必要）
│   └── {mode}/                 # 推論模式資料夾（e.g., face_recognition）
│       └── {model}/            # 模型資料夾（e.g., face_detection）
│           ├── config.json     # 模型設定（必要）
│           ├── script.py       # 推論腳本（必要）
│           └── *.nef           # 模型檔（必要）
└── firmware/
    └── {device}/               # 裝置型號資料夾（e.g., KL520）
        ├── fw_scpu.bin
        └── fw_ncpu.bin
```

#### 4.5.2 全域 config.json 格式

```json
{
  "plugins": [
    {
      "mode": "face_recognition",
      "display_name": "人臉辨識",
      "models": [
        {
          "name": "face_detection",
          "display_name": "人臉偵測 (ResNet-18)",
          "description": "基於ResNet-18的高精度人臉偵測",
          "compatible_devices": ["KL520", "KL720"]
        }
      ]
    }
  ]
}
```

#### 4.5.3 模型 config.json 格式

```json
{
  "display_name": "人臉偵測 (ResNet-18)",
  "description": "使用ResNet-18架構的高精度人臉偵測模型",
  "model_file": "face_detection.nef",
  "input_info": {
    "type": "video",
    "supported_formats": ["mp4", "avi", "webm"]
  },
  "input_parameters": {
    "threshold": 0.75,
    "max_faces": 10,
    "tracking": true
  },
  "compatible_devices": ["KL520", "KL720"]
}
```

**`input_info.type` 的有效值**：
- `"video"` — 啟動攝影機進行即時推論
- `"image"` — 使用者上傳圖片進行單次推論
- `"voice"` — 音訊輸入模式（⚠️ **程式碼中有對應處理路徑但未見完整實作**）

#### 4.5.4 script.py 介面規範

`InferenceWorkerThread` 會動態 import 各模型的 `script.py`。

**⚠️ 待確認（重要）**：`script.py` 的標準介面（函數名稱、參數格式、回傳格式）目前無正式文件。

從 `InferenceWorkerThread` 的呼叫方式推斷：
- `script.py` 應提供一個可被 worker 呼叫的推論函數
- 接收 `input_params` 字典（包含 `usb_port_id`、`device_group`、`model`、`scpu_path`、`ncpu_path`、`file_path` 等）
- 回傳 Bounding Box 結果，格式為：
  ```json
  {
    "num_boxes": 2,
    "bounding boxes": [[x1, y1, x2, y2], [x3, y3, x4, y4]],
    "results": ["label1", "label2"]
  }
  ```

---

## 5. 非功能需求

### 5.1 效能需求

| 項目 | 規格 | 來源 |
|------|------|------|
| 推論 Queue 大小 | 最大 5 幀 | `InferenceController.__init__` |
| 標準模式最短推論間隔 | 2 秒 | `InferenceController.select_tool()` |
| Custom Model 最短推論間隔 | 0.5 秒 | `InferenceController.select_custom_tool()` |
| 模型推論超時 | 5,000 ms | `config.py MODEL_TIMEOUT` |
| 裝置掃描超時 | 5 秒 | `device_service.check_available_device()` |
| 攝影機開啟超時 | 5 秒 / 最多 3 次嘗試 | `VideoThread._camera_timeout` |
| 攝影機解析度 | 640×480 | `VideoThread.run()` |
| 攝影機目標幀率 | 30 fps | `VideoThread.run()` |
| Custom Model 輸入大小 | 640×640 | `custom_inference_worker.preprocess_frame()` |
| 模型推論設備超時（Custom） | 5,000 ms | `CustomInferenceWorkerThread.initialize_device()` |

### 5.2 平台相容性

| 項目 | 規格 |
|------|------|
| 作業系統 | Windows（使用 `%LOCALAPPDATA%`，PowerInstaller 打包） |
| Python 版本 | Python 3.12 |
| 視窗尺寸 | 1200×900 像素（固定，`WINDOW_SIZE` 常數） |

**⚠️ 待確認**：是否計畫支援 macOS 或 Linux？目前路徑處理和打包設定為 Windows 專屬。

### 5.3 應用程式打包

| 項目 | 工具 | 狀態 |
|------|------|------|
| 打包工具 | PyInstaller 6.12.0 | ✅ 已設定 |
| 安裝包製作 | Inno Setup（`dist/test.iss`） | ✅ 有設定檔 |
| 程式碼加密 | PyArmor | ⚠️ 計畫中 |

**打包注意事項**：
- 需要包含 KneronPLUS SDK 的 `kp/lib` 資料夾
- 需包含 `uxui/` 資源目錄和 `src/` 目錄

### 5.4 資料儲存

所有執行期資料存放於 `%LOCALAPPDATA%/Kneron_Academy/`：
- **uploads/**：使用者上傳的圖片/影片
- **utils/**：Plugin 設定與模型檔案
- **firmware/**：裝置韌體檔案

**⚠️ 待確認**：安裝包是否會預先建立這些目錄，或由應用程式首次執行時自動建立？

---

## 6. 裝置連接與授權流程（詳細）

根據 `flowchart.md` 的設計（⚠️ 此流程尚未完整實作於程式碼中，為設計規格）：

```
登入畫面
    │
    ▼
Server 驗證（帳密驗證）
    ├── 成功 → 進入 Dongle 模組畫面
    └── 失敗 → 顯示錯誤（帳密錯誤 / 服務被暫停）
    
Dongle 模組畫面
    │
    ▼
連接 Dongle
    ├── 未偵測到 → 顯示「未偵測到裝置」提示
    └── 偵測到 → 檢查 Driver 是否安裝
    
Driver 檢查
    ├── 已安裝 → 檢查 FW 版本
    └── 未安裝 → 詢問是否安裝 Driver
                    ├── 使用者同意 → 執行安裝（可能失敗）
                    └── 失敗 → 顯示錯誤
    
FW 版本檢查
    ├── 版本符合 → 取得 Dongle KN Number
    └── 需要更新 → 詢問是否更新 FW
                    ├── 使用者同意 → 下載並安裝 FW
                    └── 失敗 → 顯示錯誤
    
取得 KN Number
    └── 成功 → 檢查授權狀態
    
授權狀態檢查
    ├── 已授權 → 顯示已授權提示 → 回到 App 主頁
    └── 未授權 → 詢問是否啟動授權
                    ├── 使用者同意 → 執行授權流程
                    │               ├── 成功 → 顯示成功提示 → 回到主頁
                    │               └── 失敗 → 顯示失敗提示
                    └── 使用者不重試 → 顯示提示 → 回到主頁
```

---

## 7. 已知限制與未完成功能

以下為從程式碼分析發現的限制與尚未完成的功能：

### 7.1 尚未完整實作

| 功能 | 狀態 | 說明 |
|------|------|------|
| 登入 Server 驗證 | 🔄 部分實作 | `LoginScreen` 存在，但 Server 端點設定不明確 |
| Driver 自動安裝 | 🔄 設計中 | `flowchart.md` 有設計，程式碼中未見完整實作 |
| Dongle 授權管理 | 🔄 設計中 | `flowchart.md` 有設計，程式碼中未見完整實作 |
| 音訊（voice）推論模式 | 🔄 設計中 | `config.py` 有引入 `librosa`、`sounddevice`，但推論路徑不完整 |
| Purchased Items API 對接 | 🔄 Mock 資料 | `utilities_screen.py` 有 `populate_mock_purchased_items()` 方法，使用假資料 |
| 程式碼加密（PyArmor） | ⏳ 計畫中 | 僅列在 `env.txt`，尚未見到具體加密流程 |
| KL520/KL720 以外裝置支援 | ⏳ 計畫中 | `DeviceType` enum 有定義，但 `DongleModelMap` 僅有這兩型 |

### 7.2 已知技術問題

| 問題 | 嚴重度 | 說明 |
|------|--------|------|
| Debug print 語句殘留 | 低 | 多個 controller 中有大量 `print()` debug 訊息 |
| 錯誤處理不完整 | 中 | 部分 try/except 只 print 不處理（如 `device_controller.py`） |
| 測試覆蓋率為零 | 高 | 完全沒有自動化測試 |
| UI 更新 Thread 安全性 | 中 | 待確認推論結果回傳到主線程的路徑是否完全使用 Qt Signal |
| `custom_inference_worker.py` 中引用未導入的 `kp` | 中 | `_boxes_scale()` 和 `post_process_yolo_v5()` 在模組頂層使用 `kp.HwPreProcInfo` 等型別，但 `import kp` 在函數內才執行 |

### 7.3 設計假設（未驗證）

- Custom Model 後處理固定使用 YOLOv5，未提供自定義後處理的擴充機制
- 應用程式假設攝影機 index 為 0（第一個相機），無法選擇其他相機
- 應用程式固定使用 Windows 路徑格式，不支援跨平台

---

## 8. 功能優先級（RICE 分析）

> ⚠️ 以下 RICE 分數為從現有程式碼功能狀態推斷，Effort 值基於程式碼完成度估算。**請與產品負責人及開發團隊確認 Reach、Impact 和 Confidence 的實際數值。**

| 功能 | Reach | Impact | Confidence | Effort（人天） | RICE 分數 | 階段 |
|------|-------|--------|------------|--------------|----------|------|
| Video 模式推論 | 100% | 3 | 90% | — | 高 | ✅ 已完成 |
| Image 模式推論 | 90% | 2 | 90% | — | 高 | ✅ 已完成 |
| Plugin 系統（config.json） | 100% | 3 | 85% | — | 高 | ✅ 已完成 |
| Custom Model 推論 | 60% | 3 | 80% | — | 中高 | ✅ 已完成 |
| 裝置掃描 / 連接 | 100% | 3 | 90% | — | 高 | ✅ 已完成 |
| 登入驗證（完整實作） | 100% | 3 | 70% | 5 | 高 | 🔄 進行中 |
| Dongle 授權管理 | 100% | 3 | 65% | 10 | 高 | 🔄 設計中 |
| Purchased Items API 對接 | 80% | 2 | 70% | 7 | 中 | 🔄 設計中 |
| Driver 自動安裝 | 70% | 2 | 60% | 5 | 中 | 🔄 設計中 |
| 音訊推論模式 | 40% | 2 | 50% | 10 | 低中 | ⏳ 待實作 |
| 多攝影機選擇 | 30% | 1 | 70% | 3 | 低 | ⏳ 未排期 |
| 跨平台支援（macOS/Linux） | 50% | 2 | 50% | 20 | 中 | ⏳ 未排期 |

---

## 9. 輸入資料格式規範

### 9.1 攝影機影像

- 擷取方式：OpenCV `cv2.VideoCapture`，DirectShow backend（Windows 優先）
- 解析度：640×480
- 格式：`QImage.Format_RGB888`（透過 `VideoThread` 發出），後轉為 NumPy 陣列 `(height, width, 3)`，通道順序 RGB888

### 9.2 上傳圖片

- 讀取方式：`cv2.imread()`
- 格式：NumPy 陣列，BGR 格式（OpenCV 預設）
- 儲存位置：`%LOCALAPPDATA%/Kneron_Academy/uploads/`

### 9.3 Custom Model 輸入（預處理後）

- 目標大小：640×640
- 格式：BGR565（`cv2.COLOR_BGR2BGR565`）

### 9.4 input_params 字典格式

`InferenceWorkerThread` 接收的 `input_params` 標準結構：

```python
{
    "usb_port_id": 32,                          # Dongle USB port ID
    "device_group": <kp.DeviceGroup>,           # 已連接的裝置群組物件
    "scpu_path": "...\\firmware\\KL520\\fw_scpu.bin",
    "ncpu_path": "...\\firmware\\KL520\\fw_ncpu.bin",
    "fw_folder": "...\\firmware",               # 全域 firmware 目錄
    "file_path": "...\\uploads\\image.jpg",    # 圖片模式使用
    "model": "...\\utils\\{mode}\\{model}\\{model_file}.nef",
    "model_descriptor": <kp.ModelDescriptor>,  # 已上傳的模型描述符
    # 以下為 config.json 中的 input_parameters 欄位（由模型設定決定）
    "threshold": 0.75,
    "max_faces": 10,
    ...
}
```

---

## 10. 推論結果輸出格式

`script.py` 回傳或 `CustomInferenceWorkerThread` 發出的標準推論結果：

```json
{
  "num_boxes": 2,
  "bounding boxes": [[x1, y1, x2, y2], [x3, y3, x4, y4]],
  "results": ["label1", "label2"]
}
```

其中座標為絕對像素值，對應原始影像尺寸（非縮放後的模型輸入尺寸）。

---

## 11. 安裝需求

### 11.1 開發環境安裝

```shell
# 1. 安裝 KneronPLUS SDK
cd ./external/kneron_plus_{version}/package/{platform}/
pip install KneronPLUS-{version}-py3-none-any.whl

# 2. 安裝其他依賴
pip install PyQt5 opencv-python pyinstaller pyarmor

# 3. 執行應用程式
python main.py
```

### 11.2 打包指令

```shell
pyinstaller --onefile --windowed main.py \
  --additional-hooks-dir=hooks \
  --add-data "uxui;uxui" \
  --add-data "src;src" \
  --add-data "{conda_env}\\Lib\\site-packages\\kp\\lib;kp\\lib"
```

---

## 12. 風險與緩解措施

| 風險 | 可能性 | 影響 | 緩解措施 |
|------|--------|------|----------|
| `script.py` 介面無標準文件，第三方難以開發 Plugin | 高 | 高 | 盡速制定並文件化 `script.py` 介面規範 |
| Purchased Items 功能仍是 Mock 資料，影響客戶體驗 | 中 | 高 | 確認後端 API 規格，完成對接 |
| 缺乏自動化測試，難以安全重構 | 高 | 中 | 補齊關鍵路徑的 unit test（推論 queue、裝置連接） |
| `custom_inference_worker.py` 的 `kp` 引入問題，可能在非 kp 環境崩潰 | 中 | 中 | 修復模組頂層的型別引用問題 |
| 硬體相依性強，無 dongle 時無法測試核心功能 | 高 | 中 | 建立 Mock/Stub 的 kp 測試層 |
| Windows 專屬設計，未來擴展平台成本高 | 低 | 中 | 現階段維持 Windows 優先，抽象化路徑處理為未來鋪路 |

---

## 附錄 A：程式碼結構快速參照

| 模組 | 路徑 | 功能 |
|------|------|------|
| `AppController` | `main.py` | 應用程式入口，管理 QStackedWidget 頁面切換 |
| `SelectionScreen` | `src/views/selection_screen.py` | 首頁選擇畫面 |
| `LoginScreen` | `src/views/login_screen.py` | 登入驗證畫面 |
| `UtilitiesScreen` | `src/views/utilities_screen.py` | 裝置管理工具頁面 |
| `MainWindow` | `src/views/mainWindows.py` | AI 推論主視窗 |
| `DeviceController` | `src/controllers/device_controller.py` | 裝置掃描、連接、中斷 |
| `InferenceController` | `src/controllers/inference_controller.py` | 推論工具選擇、queue 管理 |
| `MediaController` | `src/controllers/media_controller.py` | 攝影機操作 |
| `InferenceWorkerThread` | `src/models/inference_worker.py` | 標準推論 Worker（動態載入 script.py） |
| `CustomInferenceWorkerThread` | `src/models/custom_inference_worker.py` | Custom Model 推論 Worker（YOLOv5 後處理） |
| `VideoThread` | `src/models/video_thread.py` | 攝影機影像擷取 Thread |
| `check_available_device()` | `src/services/device_service.py` | 含 timeout 的裝置掃描服務 |
| `DeviceType`, `DongleModelMap` | `src/config.py` | 支援裝置型號列舉與對應表 |

---

*本 PRD 版本：v1.0（從程式碼反推）*  
*建立日期：2026-04-04*  
*建立者：PM Agent（Autoflow）*  
*狀態：待產品負責人確認標注「⚠️ 待確認」的項目*