# MarkBase API 需求 - Studio 整合

## 背景
Momentry Studio 需要透過 API 管理 MarkBase 設定，但目前的 `/api/v2/config` 端點與內部 TOML 設定檔格式緊密耦合，導致：
- 設定檔格式變更時 API 返回 500 錯誤
- PostgreSQL→SQLite 遷移後，舊版設定檔仍要求 `postgresql` 欄位
- Studio Settings 頁面無法正常載入/儲存設定

## 需求規格

### 1. 設定讀取 API

**端點**: `GET /api/v2/settings`

**回應範例**:
```json
{
  "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`

**請求範例**:
```json
{
  "server": {
    "upload_path": "/new/path"
  }
}
```

**回應範例**:
```json
{
  "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. 錯誤處理

**統一錯誤格式**:
```json
{
  "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 | 確保輸入值有效 |