Momentry Studio
59bcd9a9b5
- Created MARKBASE_API_REQUIREMENTS.md with detailed API specs - Requests GET/POST /api/v2/settings endpoints from MarkBase team - Documents current issues with /api/v2/config returning 500 - Defines required fields, error handling, and priority levels
115 lines
2.9 KiB
Markdown
115 lines
2.9 KiB
Markdown
# 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 | 確保輸入值有效 |
|