# web_academy_prototype

## 專案目標
此 repository 的 PoC 主軸是**線上教學平台核心流程**。
核心流程定義請參考 `docs/PRD-Integrated.md`。

`local_service_win` 是整體 PoC 其中一個模組，負責本機硬體控制與推論流程驗證。

## PoC 範圍與路線圖
- 主目標：線上教學平台核心流程 PoC。
- Local Service PoC：
  - Windows：已在本 repo（`local_service_win/`）。
  - Linux：規劃中（KneronPLUS 已支援）。
  - macOS：規劃中（待 KneronPLUS 支援）。
- 網頁流程 PoC：規劃中（後續加入相關專案或模組）。
- `local_agent_win/`：會納入此專案範圍。

## 目前已存在模組
- `local_service_win/`
  - Python + FastAPI localhost 服務。
  - 透過 KneronPLUS（`kp`）與 Kneron USB 裝置互動。
  - 涵蓋掃描、連線、模型載入、推論流程。
  - 預設位址：`http://127.0.0.1:4398`。

目前 Windows local service 資料流：
`Client (Browser/App) -> LocalAPI (127.0.0.1:4398) -> KneronPLUS kp -> KL520/KL720`

## 版本相容性（目前觀察）
- 你目前環境使用 Python `3.13` 看起來可運作。
- KneronPLUS 既有生態資訊常見以 Python `3.9` 為主。
- 後續建議補上正式相容矩陣（Python / KP 版本）。

## 專案結構（目前）
```text
web_academy_prototype/
|- docs/
|  `- PRD-Integrated.md
|- local_service_win/
|  |- .gitignore
|  |- KneronPLUS-3.1.2-py3-none-any.whl
|  |- requirements.txt
|  |- STRATEGY.md
|  |- LocalAPI/
|  |  |- __init__.py
|  |  `- main.py
|  `- TestRes/
|     `- API 測試素材（模型與圖片；圖片已內嵌為 Base64，可直接放入推論請求）
|     |- TEST_PAIRS.md
|     |- Images/
|     |  |- Pic64View.html
|     |  |- bike_cars_street_224x224.html
|     |  `- one_bike_many_cars_800x800.html
|     `- Models/
|        |- models_520.nef
|        |- kl520_20004_fcos-drk53s_w512h512.nef
|        |- kl520_20005_yolov5-noupsample_w640h640.nef
|        |- kl720_20004_fcos-drk53s_w512h512.nef
|        `- kl720_20005_yolov5-noupsample_w640h640.nef
`- README.md
```

## Pic64View 工具說明
- 檔案：`local_service_win/TestRes/Images/Pic64View.html`
- 用途：本機快速預覽 Base64 圖片字串，方便測試 `/inference/run` 的 `image_base64` 內容是否正確。
- 輸入格式：
  - 可直接貼 `data:image/...;base64,...`。
  - 也可只貼純 Base64，工具會自動補上 `data:image/png;base64,` 前綴再渲染。
- 操作：
  - `Render`：顯示預覽圖。
  - `Clear`：清空輸入與預覽結果。

## 快速開始（local_service_win）
1. 安裝相依套件：
```powershell
cd local_service_win
python -m pip install -r requirements.txt
```

2. 安裝 KneronPLUS wheel：
```powershell
python -m pip install .\KneronPLUS-3.1.2-py3-none-any.whl
```

3. 啟動本機服務：
```powershell
python .\LocalAPI\main.py
```

## 參考文件
- 核心流程與產品規劃：`docs/PRD-Integrated.md`
- Windows local service 策略：`local_service_win/STRATEGY.md`