2026-07-21 15:28:55 +08:00
|
|
|
|
# API 接入指南
|
|
|
|
|
|
|
|
|
|
|
|
## 认证方式
|
|
|
|
|
|
|
|
|
|
|
|
工作台网页使用 HttpOnly Cookie 会话。外部客户端使用：
|
|
|
|
|
|
|
|
|
|
|
|
```http
|
|
|
|
|
|
Authorization: Bearer dd_live_xxx
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
API Key 明文只在创建时返回一次，数据库仅保存 SHA-256 哈希。平台管理员创建平台级 Key；组管理员创建本组项目级 Key。失效或越权请求会返回 `401` 或 `403`。
|
|
|
|
|
|
|
|
|
|
|
|
## 主要路由
|
|
|
|
|
|
|
|
|
|
|
|
| 路由组 | 用途 |
|
|
|
|
|
|
|---|---|
|
|
|
|
|
|
| `/api/auth/*` | 登录、退出、当前账号、修改密码 |
|
|
|
|
|
|
| `/api/management/groups` | 运营组创建、改名、启停和管理员更换 |
|
|
|
|
|
|
| `/api/management/users` | 账号创建、改名、启停和重置密码 |
|
|
|
|
|
|
| `/api/management/api-keys` | API Key 创建、查询和吊销 |
|
|
|
|
|
|
| `/api/management/audit-logs` | 审计日志查询 |
|
|
|
|
|
|
| `/api/management/storage-configs` | COS 配置、连接测试和启用 |
|
|
|
|
|
|
| `/api/projects` | 项目创建、查询和编辑 |
|
|
|
|
|
|
| `/api/projects/:projectId/collections` | 作品交付集创建、查询和编辑 |
|
|
|
|
|
|
| `/api/notes` | 作品查询与 multipart 上传 |
|
|
|
|
|
|
| `/api/notes/:noteId/versions` | 上传作品新版本 |
|
|
|
|
|
|
| `/api/notes/:noteId/status` | 草稿与待验收状态切换 |
|
|
|
|
|
|
| `/api/notes/:noteId/text-annotations` | 标题/正文批注 |
|
|
|
|
|
|
| `/api/images/:imageId/annotations` | 图片坐标批注 |
|
|
|
|
|
|
| `/api/review/:slug/*` | 客户登录、浏览、反馈与验收 |
|
|
|
|
|
|
| `/api/health` | 数据库就绪检查 |
|
|
|
|
|
|
|
|
|
|
|
|
## 创建项目
|
|
|
|
|
|
|
|
|
|
|
|
平台级 API Key 可以指定目标运营组。项目级 Key 不能创建项目。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-07-21 17:13:08 +08:00
|
|
|
|
curl -X POST http://localhost:3010/api/projects \
|
2026-07-21 15:28:55 +08:00
|
|
|
|
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
|
|
|
|
|
|
-H "Content-Type: application/json" \
|
|
|
|
|
|
-d '{"name":"7 月内容计划","slug":"july-content","groupId":1,"client_description":"客户可见说明"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
`slug` 仅支持小写字母、数字和连字符，并作为客户验收链接的一部分。
|
|
|
|
|
|
|
|
|
|
|
|
## 创建作品交付集
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-07-21 17:13:08 +08:00
|
|
|
|
curl -X POST http://localhost:3010/api/projects/1/collections \
|
2026-07-21 15:28:55 +08:00
|
|
|
|
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
|
|
|
|
|
|
-H "Content-Type: application/json" \
|
|
|
|
|
|
-d '{"name":"2026 年 7 月交付","client_description":"本月交付内容"}'
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
## 上传作品
|
|
|
|
|
|
|
|
|
|
|
|
作品上传使用 `multipart/form-data`，至少一张、最多 30 张图片，单图最大 20 MB。图片数组顺序就是初始展示顺序，第一张为封面。
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-07-21 17:13:08 +08:00
|
|
|
|
curl -X POST http://localhost:3010/api/notes \
|
2026-07-21 15:28:55 +08:00
|
|
|
|
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
|
|
|
|
|
|
-F "collectionId=1" \
|
|
|
|
|
|
-F "title=作品标题" \
|
|
|
|
|
|
-F "description=正文内容" \
|
|
|
|
|
|
-F "tags=用户填写的标签原文" \
|
|
|
|
|
|
-F "images=@./01.jpg" \
|
|
|
|
|
|
-F "images=@./02.jpg"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
当前接受 JPEG、PNG、GIF、WebP 和 AVIF。标签按一段原文保存和展示，不会自动添加 `#` 或拆分为标签库。
|
|
|
|
|
|
|
|
|
|
|
|
## 创建新版本
|
|
|
|
|
|
|
|
|
|
|
|
```bash
|
2026-07-21 17:13:08 +08:00
|
|
|
|
curl -X POST http://localhost:3010/api/notes/12/versions \
|
2026-07-21 15:28:55 +08:00
|
|
|
|
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
|
|
|
|
|
|
-F "title=修改后的标题" \
|
|
|
|
|
|
-F "description=修改后的正文" \
|
|
|
|
|
|
-F "tags=修改后的标签原文" \
|
|
|
|
|
|
-F "images=@./v2-01.jpg"
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
批注绑定作品版本或具体图片，不会因新版本覆盖历史验收证据。
|
|
|
|
|
|
|
|
|
|
|
|
## 错误响应
|
|
|
|
|
|
|
|
|
|
|
|
错误统一以 JSON 返回：
|
|
|
|
|
|
|
|
|
|
|
|
```json
|
|
|
|
|
|
{ "error": "错误说明" }
|
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
常见状态码：`400` 输入无效、`401` 未认证、`403` 越权、`404` 资源不存在、`409` 唯一性或状态冲突、`500` 服务端错误。
|
