docs: 新增 F14 批次圖片推論、F15 攝影機自動偵測功能文件
PRD B4.5: - 額外功能由 9 項更新為 11 項 - F5 補充批次圖片推論和拖放上傳說明 - 新增 F14（批次圖片推論）功能規格 - 新增 F15（攝影機自動偵測）功能規格 - i18n 翻譯 key 數量更新為 130+ TDD 8.5: - 8.5.1 F5 表格新增批次圖片 API - 新增 8.5.8 自訂模型上傳（F11）技術對照 - 新增 8.5.9 裝置健康狀態（F13）技術對照 - 新增 8.5.10 批次圖片推論（F14）完整技術對照 - 新增 8.5.11 攝影機自動偵測（F15）技術對照 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
parent
edc8355c23
commit
b28aec2589
@ -1087,17 +1087,19 @@ Kneron Dongle Arduino 開發板 非 Kneron 晶片
|
||||
|
||||
### B4.5 已實作的額外功能
|
||||
|
||||
> 以下功能為 MVP 開發過程中額外實作，超出原始 PRD 範圍。共 9 項功能。
|
||||
> 以下功能為 MVP 開發過程中額外實作，超出原始 PRD 範圍。共 11 項功能。
|
||||
|
||||
#### F5 — 多來源推論輸入
|
||||
|
||||
| 項目 | 規格 |
|
||||
|------|------|
|
||||
| **概述** | 除了攝影機之外，支援上傳圖片和影片作為推論輸入來源 |
|
||||
| **輸入來源** | 攝影機（即時）、圖片上傳（JPG/PNG）、影片上傳（MP4/AVI/MOV）、影片 URL（直接連結、YouTube、RTSP） |
|
||||
| **輸入來源** | 攝影機（即時）、圖片上傳（JPG/PNG，支援單張與多張批次）、影片上傳（MP4/AVI/MOV）、影片 URL（直接連結、YouTube、RTSP） |
|
||||
| **圖片推論** | 上傳圖片至後端，送入裝置 NPU 推論後回傳結果 |
|
||||
| **批次圖片推論** | 上傳多張圖片（最多 50 張），後端逐張送入 NPU 推論，結果透過 WebSocket 即時串流回前端；前端提供縮圖列表、進度條、點擊切換瀏覽各張結果 |
|
||||
| **影片推論** | 上傳影片或提供 URL，後端逐幀擷取送入裝置推論，結果透過 WebSocket 即時串流 |
|
||||
| **YouTube 支援** | 透過 yt-dlp 解析 YouTube URL 取得直接影片連結，再進行影片推論 |
|
||||
| **拖放上傳** | 圖片 tab 支援 drag & drop 拖放上傳，拖入時顯示高亮邊框提示 |
|
||||
| **UI 設計** | Tab 式切換（攝影機 / 圖片 / 影片），影片 tab 內再切換上傳檔案或貼上 URL |
|
||||
|
||||
#### F6 — 多語系支援（i18n）
|
||||
@ -1107,7 +1109,7 @@ Kneron Dongle Arduino 開發板 非 Kneron 晶片
|
||||
| **概述** | 完整的前端多語系支援，支援英文與繁體中文切換 |
|
||||
| **支援語言** | English (en)、繁體中文 (zh-TW) |
|
||||
| **實作方式** | 自訂 TypeScript i18n 系統，不依賴外部框架（無 next-intl / react-i18next） |
|
||||
| **翻譯字典** | 約 120+ 翻譯 key，按功能分區（common, nav, dashboard, devices, models, camera, inference, settings, errors） |
|
||||
| **翻譯字典** | 約 130+ 翻譯 key，按功能分區（common, nav, dashboard, devices, models, camera, inference, settings, errors） |
|
||||
| **型別安全** | `TranslationKey` 型別由 `Paths<TranslationDict>` 遞迴產生，提供所有 key 的自動完成，缺 key 時 TypeScript 報錯 |
|
||||
| **切換方式** | Settings 頁面語言下拉選單，切換後即時生效（無需重新整理） |
|
||||
| **持久化** | 語言設定透過 Zustand persist 儲存至 localStorage |
|
||||
@ -1177,6 +1179,26 @@ Kneron Dongle Arduino 開發板 非 Kneron 晶片
|
||||
| **健康狀態** | 狀態、韌體版本、運行時間、最後活動時間 |
|
||||
| **連線歷史** | 按時間排列的連線/斷線事件紀錄 |
|
||||
|
||||
#### F14 — 批次圖片推論
|
||||
|
||||
| 項目 | 規格 |
|
||||
|------|------|
|
||||
| **概述** | 支援一次上傳多張圖片進行批次推論，適用於工業檢測等需要大量圖片驗證的場景 |
|
||||
| **上傳方式** | 檔案選擇器多選、拖放上傳（drag & drop），上限 50 張 |
|
||||
| **處理方式** | 後端逐張送入 NPU 推論（硬體限制），結果透過 WebSocket 即時串流回前端 |
|
||||
| **進度顯示** | 進度條顯示已處理 / 總數，縮圖列表標示完成（✓）/處理中（⏳）/待處理（編號） |
|
||||
| **結果瀏覽** | 水平捲動縮圖列表，點擊切換檢視不同圖片的推論結果（BBox overlay + 分類結果） |
|
||||
| **UI 設計** | 批次模式下自動隱藏手動推論按鈕，inference panel 顯示批次進度卡片 |
|
||||
|
||||
#### F15 — 攝影機自動偵測
|
||||
|
||||
| 項目 | 規格 |
|
||||
|------|------|
|
||||
| **概述** | 進入 workspace 時自動偵測系統是否有可用攝影機，無攝影機時自動停用攝影機功能 |
|
||||
| **偵測方式** | 後端透過 ffmpeg 偵測系統攝影機（macOS: AVFoundation, Windows: DirectShow） |
|
||||
| **無攝影機行為** | Camera tab 自動 disabled、預設切換至 Image tab、顯示「未偵測到攝影機」提示訊息 |
|
||||
| **有攝影機行為** | 維持原有攝影機推論功能不變 |
|
||||
|
||||
---
|
||||
|
||||
## B5. 功能路線圖（Post-MVP）
|
||||
|
||||
69
docs/TDD.md
69
docs/TDD.md
@ -1439,6 +1439,8 @@ MVP 階段不使用資料庫，使用檔案系統：
|
||||
|---------|---------|-----|
|
||||
| `SourceSelector` (Tab: camera/image/video) | `camera/manager` | `POST /api/camera/start` |
|
||||
| Image upload button | `api/handlers/media_handler` | `POST /api/media/upload/image` |
|
||||
| Batch image upload (多選 + drag & drop) | `api/handlers/camera_handler` | `POST /api/media/upload/batch-images` |
|
||||
| Batch image frame viewer | `camera/multi_image_source` | `GET /api/media/batch-images/:index` |
|
||||
| Video upload button | `api/handlers/media_handler` | `POST /api/media/upload/video` |
|
||||
| URL input + submit | `api/handlers/media_handler` | `POST /api/media/url` |
|
||||
|
||||
@ -1458,7 +1460,7 @@ URL 輸入 → 後端分類 URL 類型：
|
||||
```
|
||||
src/lib/i18n/
|
||||
├── types.ts # TranslationDict 介面 + Paths<T> 遞迴型別
|
||||
├── en.ts # 英文字典（~120 keys）
|
||||
├── en.ts # 英文字典（~130+ keys）
|
||||
├── zh-TW.ts # 繁體中文字典
|
||||
└── index.ts # useTranslation() hook + getTranslation() helper
|
||||
```
|
||||
@ -1518,6 +1520,71 @@ src/lib/i18n/
|
||||
|
||||
**Settings Store：** `settings-store.ts` 管理 `theme` ('light' | 'dark') 和 `language` ('en' | 'zh-TW')，persist 至 localStorage。
|
||||
|
||||
#### 8.5.8 自訂模型上傳（F11）
|
||||
|
||||
| 前端元件 | 後端模組 | API |
|
||||
|---------|---------|-----|
|
||||
| `ModelUploadDialog` | `api/handlers/model_handler` | `POST /api/models/upload` |
|
||||
| 表單驗證（檔案、名稱、任務類型、標籤） | 模型元資訊存檔 | `DELETE /api/models/:id` |
|
||||
|
||||
**上傳流程：** 前端 FormData（.nef + 元資訊）→ 後端儲存檔案 + 建立模型紀錄 → 回傳模型 ID → 前端更新模型庫。
|
||||
|
||||
#### 8.5.9 裝置健康狀態與連線歷史（F13）
|
||||
|
||||
| 前端元件 | 資料來源 | 說明 |
|
||||
|---------|---------|------|
|
||||
| `DeviceHealthCard` | `device-store` | 狀態、韌體版本、運行時間（useEffect + setInterval 更新） |
|
||||
| `DeviceConnectionLog` | `device-preferences-store` | 連線/斷線事件紀錄，含時間戳記 |
|
||||
|
||||
**Hydration 安全：** 運行時間使用 `useState(0)` + `useEffect` 避免 `Date.now()` 造成 SSR 不匹配；時間格式化使用 `suppressHydrationWarning`。
|
||||
|
||||
#### 8.5.10 批次圖片推論（F14）
|
||||
|
||||
| 前端元件 | 後端模組 | API |
|
||||
|---------|---------|-----|
|
||||
| `BatchImageThumbnails` | `camera/multi_image_source.go` | `POST /api/media/upload/batch-images` |
|
||||
| `SourceSelector`（多選 + drag & drop） | `api/handlers/camera_handler` | `GET /api/media/batch-images/:index` |
|
||||
| `InferencePanel`（批次進度卡片） | `camera/pipeline.go`（SourceBatchImage 分支） | WebSocket 推論結果串流 |
|
||||
|
||||
**資料流：**
|
||||
|
||||
```
|
||||
前端多選/拖放圖片 → FormData POST 至後端
|
||||
→ 後端建立 MultiImageSource → Pipeline 逐張 ReadFrame
|
||||
→ NPU 推論 → InferenceResult 加入 imageIndex/totalImages/filename
|
||||
→ WebSocket 即時回傳 → 前端 addBatchResult → 更新進度 + 縮圖狀態
|
||||
→ 使用者點擊縮圖 → 切換 batchSelectedIndex → 顯示對應圖片 + BBox overlay
|
||||
```
|
||||
|
||||
**前端 Store 擴展：**
|
||||
- `camera-store`：新增 `batchImages`, `batchSelectedIndex`, `batchProcessedCount`, `uploadBatchImages()`
|
||||
- `inference-store`：新增 `batchResults: Record<number, InferenceResult>`, `addBatchResult()`
|
||||
- `use-inference-stream`：判斷 `imageIndex !== undefined` 走批次處理邏輯
|
||||
|
||||
**型別擴展：**
|
||||
- `SourceType` 新增 `'batch_image'`
|
||||
- `BatchImageInfo`：`{ index, filename, width, height }`
|
||||
- `InferenceResult` 新增 `imageIndex?`, `totalImages?`, `filename?`
|
||||
|
||||
#### 8.5.11 攝影機自動偵測（F15）
|
||||
|
||||
| 前端元件 | 後端模組 | API |
|
||||
|---------|---------|-----|
|
||||
| `workspace-client.tsx`（fetchCameras） | `camera/manager.go` | `GET /api/camera/list` |
|
||||
| `SourceSelector`（cameraDisabled 邏輯） | `camera/ffmpeg_detect.go` | — |
|
||||
|
||||
**偵測流程：**
|
||||
|
||||
```
|
||||
workspace 載入 → fetchCameras() → GET /api/camera/list
|
||||
→ 後端 Manager.ListCameras():
|
||||
├── mockMode=true → 回傳 mock camera
|
||||
└── mockMode=false → ffmpeg 偵測真實攝影機 → 回傳列表或空陣列
|
||||
→ 前端 cameras.length === 0 → useEffect 切換至 Image tab + disable Camera tab
|
||||
```
|
||||
|
||||
**Hydration 安全：** 使用 `useHydrated()` hook 確保 `disabled` 屬性在 SSR 時為 `false`（與 `Tabs value="camera"` 一致），hydration 完成後才根據 cameras 列表設定 disabled 狀態。
|
||||
|
||||
---
|
||||
|
||||
## 9. 開發環境與工具鏈
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user