jim800121chen
fb7da5d180
依 autoflow-agent workspace v2 設計把 PRD / 設計 / 架構 / 交付類 共享文件從個人層 .autoflow/（ignored）搬到 docs/autoflow/（進 git）， 讓團隊可共享產品與架構文件，個人層只留 progress / review / testing 等 per-branch 筆記。 - 02-prd/ 21 個檔（PRD、features、market-analysis 等） - 03-design/ 18 個檔（design-spec、wireframes、flows 等） - 04-architecture/ 31 個檔（TDD、design-doc、ADR×14、API 規格等） - 07-delivery/ 3 個檔（project-summary、phase-0.6-handover、stage-deployment-setup） 合計 73 檔。原檔已從 .autoflow/ 移除（migration 工具執行 git mv， 但因 .autoflow/ 在 .gitignore 中、git 將此操作視為新增、無 rename history）。
146 lines
5.2 KiB
Markdown
146 lines
5.2 KiB
Markdown
# Feature：模型管理（P0）
|
||
|
||
> 父文件：[PRD.md](../PRD.md) | 對應 User Stories：US-08、US-09、US-23
|
||
|
||
---
|
||
|
||
## 概述
|
||
|
||
使用者能瀏覽系統預設的 7 個 Kneron `.nef` 模型，上傳自己的模型，管理模型庫。
|
||
|
||
對比 local-tool：
|
||
- local-tool 的模型存在使用者電腦 `~/Library/Application Support/visiona-local/custom-models/`
|
||
- visionA Cloud 的模型**存在雲端**（Phase 0 用 local filesystem 實作 ObjectStorage 介面，Phase 1 換 S3/MinIO）
|
||
|
||
---
|
||
|
||
## 使用者行為
|
||
|
||
### 模型庫頁（`/models`）
|
||
|
||
UI 沿用 local-tool，但資料來源改為 visionA-backend。
|
||
|
||
**三個區塊**：
|
||
|
||
1. **預設模型**（系統共用，所有使用者都能用）
|
||
- 7 個預置模型（KL520 × 4 + KL720 × 3）
|
||
- Phase 0：seed 到 backend 的 local fs
|
||
- Phase 1：seed 到 S3 的 `public/` prefix
|
||
|
||
2. **我的模型**（使用者上傳的）
|
||
- 空狀態顯示 CTA「上傳模型」
|
||
- 每個模型顯示：名稱、大小、上傳時間、支援硬體、上傳者
|
||
|
||
3. **組織模型**（Phase 2，留介面）
|
||
- 如果使用者在團隊 workspace，能看到團隊共享模型
|
||
|
||
**篩選**：按任務類型（classification / object_detection）、硬體（KL520 / KL720）、關鍵字。
|
||
|
||
### 上傳模型
|
||
|
||
1. 點「上傳模型」→ 拖拽 or 選檔
|
||
2. 檔案類型：`.nef`
|
||
3. 檔案大小限制：**Phase 0 上限 100MB；Phase 1 上限 500MB（後續依付費方案調整）**
|
||
- 此限制必須落在 config（env var 或 config file），**不可硬編碼**，方便跨 Phase 調整
|
||
- 建議 config key：`MODEL_UPLOAD_MAX_SIZE_MB`（預設 100）
|
||
- 前端與後端都要同步使用這個值（前端顯示錯誤提示、後端做實際拒絕）
|
||
4. 上傳進度 bar
|
||
5. 後端儲存到 ObjectStorage 介面實作
|
||
6. 上傳完成後解析 metadata（檔案 header）
|
||
7. Phase 0：metadata 存 in-memory map；Phase 1：存 DB
|
||
|
||
### 模型詳細頁（`/models/[id]`）
|
||
|
||
- 基本資訊：名稱、ID、大小、MD5
|
||
- 支援硬體（KL520 / KL720）
|
||
- Metadata（輸入尺寸、任務類型）
|
||
- 效能數據（推論 FPS、延遲）— Phase 0 預設模型有，自上傳的沒有
|
||
- 下載按鈕（重新下載到本機）
|
||
- 刪除按鈕（只對自上傳模型）
|
||
|
||
---
|
||
|
||
## 技術細節（給 Architect 參考）
|
||
|
||
### ObjectStorage 介面（重點）
|
||
|
||
Phase 0 要定義清楚介面，讓 Phase 1 可直接換 S3/MinIO 不動業務邏輯。
|
||
|
||
```go
|
||
// internal/storage/storage.go
|
||
type ObjectStorage interface {
|
||
Upload(ctx context.Context, key string, reader io.Reader, size int64) error
|
||
Download(ctx context.Context, key string) (io.ReadCloser, error)
|
||
Delete(ctx context.Context, key string) error
|
||
List(ctx context.Context, prefix string) ([]ObjectInfo, error)
|
||
// Phase 1：presigned URL
|
||
GetDownloadURL(ctx context.Context, key string, expiresIn time.Duration) (string, error)
|
||
GetUploadURL(ctx context.Context, key string, expiresIn time.Duration) (string, error)
|
||
}
|
||
|
||
type ObjectInfo struct {
|
||
Key string
|
||
Size int64
|
||
LastModified time.Time
|
||
ETag string
|
||
}
|
||
```
|
||
|
||
**Phase 0 實作：`LocalFSStorage`**
|
||
- 存在 `./data/models/{user_id}/{model_id}.nef`
|
||
- `GetDownloadURL` 回傳 `/api/models/{id}/download`（走 api-server 串流）
|
||
|
||
**Phase 1 實作：`S3Storage`**
|
||
- 用 AWS SDK 或 minio-go
|
||
- `GetDownloadURL` / `GetUploadURL` 回傳真的 presigned URL
|
||
|
||
### 上傳大檔案策略
|
||
|
||
- Phase 0：Multipart form upload 直接進 api-server，api-server 再寫進 local fs
|
||
- 限制：100MB 以下
|
||
- api-server 的記憶體與磁碟 I/O 壓力
|
||
- Phase 1：前端直接用 presigned URL 上傳到 S3，不過 api-server
|
||
- 需要 CORS 設定
|
||
- 上傳完成後通知 api-server 更新 metadata
|
||
|
||
### 預設模型 seed
|
||
|
||
Phase 0：backend 啟動時，檢查 `data/models/system/` 是否有預設模型，沒有就從 bundled resources 複製過去。
|
||
|
||
Phase 1：預設模型在 `s3://visiona-models/system/` 共享給所有 user。
|
||
|
||
---
|
||
|
||
## 驗收條件（Phase 0）
|
||
|
||
- [ ] `/models` 頁面顯示 7 個預設模型
|
||
- [ ] 不同使用者看到自己的「我的模型」，互相隔離
|
||
- [ ] 上傳 `.nef` 檔成功，出現在列表
|
||
- [ ] 上傳進度 bar 顯示正確
|
||
- [ ] 上傳 > 100MB 被拒絕，回傳明確錯誤（Phase 0 限制值）
|
||
- [ ] 上傳大小限制從 config（`MODEL_UPLOAD_MAX_SIZE_MB`，預設 100）讀取，非硬編碼
|
||
- [ ] 前端顯示的大小限制與後端實際拒絕的值一致
|
||
- [ ] 上傳非 `.nef` 檔被拒絕
|
||
- [ ] 能下載已上傳的模型
|
||
- [ ] 能刪除自上傳的模型，不能刪預設模型
|
||
- [ ] ObjectStorage 介面定義完整（有 interface + LocalFSStorage 實作）
|
||
- [ ] 介面層面預留 S3 實作的 hook，切換時不動業務邏輯
|
||
|
||
---
|
||
|
||
## Phase 0 的 TODO
|
||
|
||
- **TODO 1**：presigned URL 上傳（Phase 1）
|
||
- **TODO 2**：模型版本管理（Phase 2）
|
||
- **TODO 3**：模型標籤 / 搜尋增強（Phase 2）
|
||
- **TODO 4**：團隊共享模型（Phase 2）
|
||
- **TODO 5**：模型來源追蹤（是轉檔來的還是使用者上傳的，Phase 2）
|
||
- **TODO 6**：效能數據收集（推論時自動紀錄 FPS / 延遲，Phase 1）
|
||
|
||
---
|
||
|
||
## 連結
|
||
|
||
- 回：[PRD 索引](../PRD.md)
|
||
- 相關：[介面契約 — ObjectStorage](../interface-contracts.md)、[轉檔整合](feature-converter-integration.md)
|