momentry_studio/docs/MARKBASE_API_REQUIREMENTS.md

MarkBase API 需求 - Studio 整合

背景

Momentry Studio 需要透過 API 管理 MarkBase 設定，但目前的 /api/v2/config 端點與內部 TOML 設定檔格式緊密耦合，導致：

• 設定檔格式變更時 API 返回 500 錯誤
• PostgreSQL→SQLite 遷移後，舊版設定檔仍要求 postgresql 欄位
• Studio Settings 頁面無法正常載入/儲存設定

需求規格

1. 設定讀取 API

端點: GET /api/v2/settings

回應範例:

{
  "success": true,
  "settings": {
    "server": {
      "upload_path": "/Users/accusys/momentry/var/sftpgo/data",
      "port": 11438
    },
    "database": {
      "type": "sqlite",
      "path": "data/auth.sqlite"
    },
    "webdav": {
      "enabled": true,
      "parent_path": "/Users/accusys/momentry/var/sftpgo/data",
      "versioning": true
    },
    "s3": {
      "enabled": false
    }
  }
}

需求:

• 回傳結構化 JSON，不依賴 TOML 格式
• 包含所有 Studio 需要顯示的設定項目
• 如果某個區塊不存在，回傳預設值而非錯誤

2. 設定更新 API

端點: POST /api/v2/settings

請求範例:

{
  "server": {
    "upload_path": "/new/path"
  }
}

回應範例:

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

需求:

• 支援部分更新（只傳需要修改的欄位）
• 驗證輸入值（路徑是否存在、格式是否正確）
• 更新後自動套用（或提示需要重啟）

3. 設定欄位說明

欄位	類型	說明	Studio 使用方式
server.upload_path	string	上傳檔案根目錄	Settings 頁面顯示/編輯
server.port	number	服務端口	僅顯示
database.type	string	資料庫類型 (sqlite/postgresql)	僅顯示
database.path	string	SQLite 資料庫路徑	僅顯示
webdav.enabled	bool	是否啟用 WebDAV	僅顯示
webdav.parent_path	string	WebDAV 根目錄	僅顯示
s3.enabled	bool	是否啟用 S3	僅顯示

4. 錯誤處理

統一錯誤格式:

{
  "success": false,
  "error": "設定檔讀取失敗",
  "details": "TOML parse error..."
}

需求:

• 即使設定檔有問題，也應回傳預設值而非 500 錯誤
• 提供明確錯誤訊息供前端顯示

當前問題

端點	當前狀態	問題
GET /api/v2/config	500	TOML 解析錯誤，缺少 postgresql 欄位
POST /api/v2/config/edit	500	同上
GET /api/v2/admin/users	401	需要 admin token 認證
GET /api/v2/admin/shares	401	需要 admin token 認證

優先順序

優先級	項目	原因
P0	GET /api/v2/settings	Studio Settings 頁面依賴此端點
P0	POST /api/v2/settings	需要儲存 upload_path
P1	Admin token 認證機制	Users/Shares 頁面需要
P2	設定驗證 API	確保輸入值有效