momentry_studio/docs/MARKBASE_SEARCH_SESSION_API.md

MarkBase Search Session API 需求

背景

Momentry Studio 需要將搜尋歷史（Search History）升級為以 Session 為單位的管理系統，並整合到 MarkBase 的 SQLite 資料庫中。目前 Studio 使用本地 SQLite 儲存搜尋記錄，現在需要改為透過 MarkBase API 存取。

---

1. SQLite Schema 需求

1.1 新增 search_sessions 表

CREATE TABLE IF NOT EXISTS search_sessions (
    id TEXT PRIMARY KEY,
    user_id TEXT NOT NULL,
    title TEXT NOT NULL DEFAULT '未命名搜尋',
    mode TEXT DEFAULT 'keyword',  -- keyword | visual | people | agent
    created_at TEXT DEFAULT (datetime('now')),
    updated_at TEXT DEFAULT (datetime('now'))
);

CREATE INDEX idx_sessions_user ON search_sessions(user_id);
CREATE INDEX idx_sessions_updated ON search_sessions(user_id, updated_at DESC);

1.2 新增 search_messages 表

CREATE TABLE IF NOT EXISTS search_messages (
    id TEXT PRIMARY KEY,
    session_id TEXT NOT NULL REFERENCES search_sessions(id) ON DELETE CASCADE,
    role TEXT NOT NULL,           -- 'user' | 'assistant'
    content TEXT,                 -- 使用者輸入或 AI 回答
    results TEXT,                 -- JSON 格式的搜尋結果
    mode TEXT DEFAULT 'keyword',  -- 搜尋模式
    created_at TEXT DEFAULT (datetime('now'))
);

CREATE INDEX idx_messages_session ON search_messages(session_id, created_at);

1.3 修改現有 search_history 表（選用）

如果要保留向後相容性：

ALTER TABLE search_history ADD COLUMN session_id TEXT REFERENCES search_sessions(id);

---

2. API 端點需求

所有端點前綴：/api/v2/search-sessions

2.1 列出 Session

端點: GET /api/v2/search-sessions

認證: 需要 Bearer Token

查詢參數:

參數	類型	必填	說明	預設
limit	number	❌	返回數量	30
offset	number	❌	偏移量	0

回應:

{
  "success": true,
  "total": 15,
  "sessions": [
    {
      "id": "sess_abc123",
      "title": "廚房場景搜尋",
      "mode": "visual",
      "message_count": 5,
      "created_at": "2026-10-27T10:00:00Z",
      "updated_at": "2026-10-27T10:30:00Z"
    }
  ]
}

---

2.2 建立 Session

端點: POST /api/v2/search-sessions

認證: 需要 Bearer Token

請求:

{
  "title": "廚房場景搜尋",
  "mode": "visual"
}

回應:

{
  "success": true,
  "session": {
    "id": "sess_abc123",
    "title": "廚房場景搜尋",
    "mode": "visual",
    "created_at": "2026-10-27T10:00:00Z",
    "updated_at": "2026-10-27T10:00:00Z"
  }
}

---

2.3 更新 Session

端點: PUT /api/v2/search-sessions/:id

認證: 需要 Bearer Token

請求:

{
  "title": "重新命名的搜尋"
}

回應:

{
  "success": true,
  "message": "Session updated"
}

---

2.4 刪除 Session

端點: DELETE /api/v2/search-sessions/:id

認證: 需要 Bearer Token

回應:

{
  "success": true,
  "message": "Session deleted"
}

---

2.5 取得 Session 對話

端點: GET /api/v2/search-sessions/:id/messages

認證: 需要 Bearer Token

回應:

{
  "success": true,
  "messages": [
    {
      "id": "msg_001",
      "role": "user",
      "content": "Find kitchen scenes",
      "results": null,
      "created_at": "2026-10-27T10:00:00Z"
    },
    {
      "id": "msg_002",
      "role": "assistant",
      "content": "Found 3 kitchen scenes...",
      "results": "[...]",
      "created_at": "2026-10-27T10:00:01Z"
    }
  ]
}

---

2.6 新增訊息到 Session

端點: POST /api/v2/search-sessions/:id/messages

認證: 需要 Bearer Token

請求:

{
  "role": "user",
  "content": "Find kitchen scenes",
  "mode": "visual",
  "results": null
}

回應:

{
  "success": true,
  "message": {
    "id": "msg_001",
    "role": "user",
    "content": "Find kitchen scenes",
    "created_at": "2026-10-27T10:00:00Z"
  }
}

---

2.7 更新訊息結果（AI 回答後）

端點: PATCH /api/v2/search-sessions/:id/messages/:msgId

認證: 需要 Bearer Token

請求:

{
  "role": "assistant",
  "content": "Found 3 kitchen scenes...",
  "results": [{...}, {...}]
}

回應:

{
  "success": true,
  "message": "Message updated"
}

---

3. 業務邏輯需求

3.1 自動清理

• 未命名的 Session 超過 24 小時自動刪除
• 每個使用者最多保留 50 個 Session
• 超出限制時，刪除最舊的未命名 Session

3.2 使用者隔離

• 所有查詢自動過濾 user_id
• Token 中必須包含 user_id 或從 token 解析

3.3 預設 Session

• 使用者首次進入 Search 頁面時，自動建立 "Default" Session
• 後續搜尋都歸入目前活躍的 Session

---

4. 錯誤處理

統一錯誤格式

{
  "success": false,
  "error": "Session not found",
  "code": "SESSION_NOT_FOUND"
}

錯誤代碼

代碼	HTTP 狀態	說明
SESSION_NOT_FOUND	404	Session 不存在
UNAUTHORIZED	401	無效 Token
VALIDATION_ERROR	400	請求格式錯誤
LIMIT_EXCEEDED	429	超過 Session 數量限制

---

5. 前端整合計劃

5.1 Studio 修改項目

檔案	修改內容
src/composables/useSearchSession.ts	新增 Session 管理 composable
src/views/SearchView.vue	側邊欄改為 Session 列表
src/api/index.ts	新增 search-session 相關 HTTP 呼叫

5.2 移除項目

檔案	移除內容
src-tauri/src/db.rs	search_history 相關函數
src-tauri/src/proxy.rs	search-history handler
src-tauri/src/main.rs	search_history Tauri commands

---

6. 測試清單

6.1 API 測試

• 建立 Session
• 列出 Sessions（分頁）
• 更新 Session 標題
• 刪除 Session
• 新增訊息
• 更新訊息結果
• 取得 Session 對話
• 使用者隔離測試
• 自動清理測試

6.2 前端測試

• 新 Session 建立
• Session 命名
• 切換 Session
• 刪除 Session
• 對話還原
• 自動建立 Default Session

---

7. 優先順序

優先級	任務	說明
P0	SQLite Schema	search_sessions + search_messages 表
P0	CRUD API	Session 增刪改查
P0	Messages API	訊息增刪改查
P1	自動清理	24 小時 + 50 筆限制
P1	使用者隔離	Token 解析 + user_id 過濾
P2	效能優化	索引 + 分頁

---

8. 時間預估

階段	預估工時
Schema 設計 + 實作	30 min
CRUD API 實作	60 min
Messages API 實作	45 min
自動清理邏輯	30 min
測試 + 文檔	30 min
總計	~3 小時