kneron_model_converter/docs/autoflow/04-architecture/database.md

Database 設計

狀態：Phase 1 完工 — Phase 0.8b 完全不動。

配套：design-doc.md §3.7、api/api-jobs.md。

---

1. 為什麼用 Redis、不用 PostgreSQL

• Phase 1 資料模式簡單：job 是 state machine、user index 是 key-value
• 既有哲學「Crash 即 Reset」對 Redis 友善（PG 引入持久化反而變複雜）
• Redis Set 做 user 索引足夠（單 user 7 天內 < 10 個 job）
• 未來若要跨 Crash recovery / 多 instance HA，再評估 PG

---

2. Key 規劃

Key	類型	用途	TTL
job:{job_id}	String (JSON)	Job 完整 record	7 天
user:{user_id}:jobs	Set	該 user 所有 job_id（不分狀態）	每次寫入時 EXPIRE 7d
user:{user_id}:active_job	String	當前 in-progress job_id（= created 或 running）	隨 job 結束刪除
ratelimit:client:{client_id}	由 express-rate-limit 管理	per-client_id rate limit	5 min
queue:onnx / queue:bie / queue:nef	Redis Stream	Worker 任務佇列	—
queue:done	Redis Stream	Worker 完成事件	—
queue:progress	Redis Stream	Worker stage 內進度（選配，Phase 2）	—

---

3. Job record schema

{
  // 既有欄位
  "job_id": "uuid",
  "created_at": "...",
  "updated_at": "...",
  "status": "ONNX | BIE | NEF | COMPLETED | FAILED",   // 內部仍用大寫
  "stage": "onnx | bie | nef | null",
  "progress": 0,
  "parameters": {
    "model_id": 1001,
    "version": "0001",
    "platform": "520",
    "enable_evaluate": false,
    "enable_sim_fp": false,
    "enable_sim_fixed": false,
    "enable_sim_hw": false
  },
  "output": {                                          // 舊格式（向後相容）
    "bie_path": null,
    "nef_path": null,
    "onnx_path": null
  },
  "result_object_keys": {                              // 新格式
    "onnx": "jobs/{job_id}/output/out.onnx",
    "bie": "jobs/{job_id}/output/out.bie",
    "nef": "jobs/{job_id}/output/out.nef"
  },
  "error": null,
  "origin": "api | web",
  "user_id": "visionA-user-12345",
  "tenant_id": "uuid-or-null",
  "created_by_client_id": "visionA-service",          // API key 模式下固定值
  "source_filename": "model.onnx",                    // Phase 0.8b 新增（/result endpoint filename 用）
  "input": {
    "filename": "model.onnx",
    "object_key": "jobs/{job_id}/input/model.onnx",
    "size_bytes": 204800000,
    "ref_images_count": 0
  },
  "stage_timings": {
    "onnx": { "started_at": "...", "completed_at": "..." },
    "bie": { "started_at": "...", "completed_at": null },
    "nef": null
  },
  "stage_progress": 0,
  "expires_at": "2026-05-23T12:00:00Z",
  "metadata": {},
  "promoted": false,                                  // 冪等性 flag
  "promoted_object_keys": []                          // 已 promote 的目標
}

3.1 source_filename 欄位

Phase 0.8b 新增需求：/result endpoint 需要這個欄位構造 download filename。

寫入點：POST /api/v1/jobs handler 在 multer 接收 model 檔後，把 multipart.filename 寫入 job.source_filename（已 sanitized）。

Backend 端 task：確認 jobService.createJob 寫入這個欄位（檢查既有 code、可能已存在；若沒有則補上）。

---

4. 對外 status 映射（不變）

詳見 api/api-jobs.md §5.3。

---

5. User 索引設計

5.1 Key 寫入時機

建立 job:
  MULTI
  SET job:{id} {...}
  SADD user:{user_id}:jobs {id}
  EXPIRE user:{user_id}:jobs 604800
  SETNX user:{user_id}:active_job {id}
  EXEC

  若 SETNX 回 0 → 衝突，回滾，回 409
  若 SETNX 回 1 → 成功

完成 / 失敗時：
  MULTI
  SET job:{id} {...}
  DEL user:{user_id}:active_job   # 僅在 value == 當前 job_id 時才 DEL
  EXEC

5.2 Lua script（claim_active_job）

-- KEYS[1] = user:{user_id}:active_job
-- KEYS[2] = job:{job_id}
-- KEYS[3] = user:{user_id}:jobs
-- ARGV[1] = job_id
-- ARGV[2] = job_json
-- ARGV[3] = ttl_seconds

if redis.call('EXISTS', KEYS[1]) == 1 then
  return {'conflict', redis.call('GET', KEYS[1])}
end
redis.call('SET', KEYS[1], ARGV[1])
redis.call('SET', KEYS[2], ARGV[2])
redis.call('SADD', KEYS[3], ARGV[1])
redis.call('EXPIRE', KEYS[3], tonumber(ARGV[3]))
return {'ok'}

5.3 避免 KEYS *

錯誤做法：redis.keys('job:*') O(N) 阻塞。

正確做法：

const ids = await redis.smembers(`user:${userId}:jobs`);
const pipeline = redis.pipeline();
for (const id of ids) pipeline.get(`job:${id}`);
const results = await pipeline.exec();

---

6. 記憶體預估

• 每個 job record 約 2-4 KB（含 stage_timings 等）
• 每個 user index Set 每個元素 < 40 bytes
• 1000 並發 user × 10 jobs = 10k job record ≈ 40 MB

Redis 輕鬆。Converter Bucket lifecycle 7 天，Redis 也跟著 TTL 7 天，記憶體上限可控。

---

7. M5 方案 A：先寫 MinIO 後 Lua claim

避免「拿到 Lua claim 但 MinIO 失敗」需要 rollback Redis 的複雜度：

• MinIO 失敗 → 直接回 502，Redis 完全乾淨
• Lua conflict / throw → cleanup MinIO（fire-and-forget，靠 7d lifecycle 兜底）
• enqueue 失敗 → 補償 release Redis + cleanup MinIO

---

8. Phase 0.8b 變動

無。Database 完全不動。

唯一相關變動：

• created_by_client_id 在 API key 模式下會固定為 visionA-service（middleware 設定 req.auth.clientId）— 此為 handler 行為，不是 schema 改變
• source_filename 欄位確認存在（既有實作可能已有；若無，Backend 補上 — 屬於 Phase B 任務）