129 lines
4.3 KiB
Markdown
129 lines
4.3 KiB
Markdown
# API 接入指南
|
||
|
||
## 认证
|
||
|
||
工作台使用 HttpOnly Cookie；外部客户端使用：
|
||
|
||
```http
|
||
Authorization: Bearer dd_live_xxx
|
||
```
|
||
|
||
平台级 Key 可跨组创建和查询项目。项目级 Key 只能操作绑定项目，包括在该项目中新建作品和验收轮次。密钥明文只在创建时返回一次。
|
||
|
||
## 发现资源
|
||
|
||
```bash
|
||
# 查询 Key 可访问的项目，响应包含 group_id、group_name 和项目 id
|
||
curl http://localhost:3010/api/projects \
|
||
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
|
||
|
||
# 查询项目作品
|
||
curl http://localhost:3010/api/projects/1/works \
|
||
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
|
||
```
|
||
|
||
调用方不再需要作品交付集 ID。`externalId` 在项目内唯一，可用于安全重试和找回作品。
|
||
|
||
## 创建项目
|
||
|
||
只有平台级 Key 可以创建项目。
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3010/api/projects \
|
||
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"name":"7 月内容计划","slug":"july-content","groupId":1,"client_description":"客户可见说明"}'
|
||
```
|
||
|
||
## 创建作品
|
||
|
||
JSON 请求中的 `images` 为 1–30 个公开 HTTP/HTTPS URL。服务只保存 URL，不下载也不转存 COS；数组顺序就是展示顺序，第一张为封面。
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3010/api/projects/1/works \
|
||
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"externalId":"client-work-20260722-001",
|
||
"title":"作品标题",
|
||
"description":"正文内容",
|
||
"tags":["#夏日","用户原文"],
|
||
"images":["https://cdn.example.com/01.jpg","https://cdn.example.com/02.jpg"]
|
||
}'
|
||
```
|
||
|
||
相同 `projectId + externalId` 的重试不会重复创建，响应包含 `idempotent: true`。调用方负责保证外部图片 URL 长期公开可用。
|
||
|
||
## 创建新验收轮次
|
||
|
||
每轮只能提交一个方案。标题、正文、标签和图片会形成不可修改的轮次快照；新轮次自动锁定上一轮。
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3010/api/works/12/rounds \
|
||
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"title":"修改后的标题",
|
||
"description":"修改后的正文",
|
||
"tags":["#第二轮"],
|
||
"images":["https://cdn.example.com/round-2.jpg"]
|
||
}'
|
||
```
|
||
|
||
## 查询作品与全部反馈
|
||
|
||
```bash
|
||
# 当前轮或指定轮
|
||
curl "http://localhost:3010/api/works/12?round=2" \
|
||
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
|
||
|
||
# 按轮返回该作品全部反馈和验收事件
|
||
curl http://localhost:3010/api/works/12/annotations \
|
||
-H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
|
||
```
|
||
|
||
标题、正文和 Tag 选区批注使用：
|
||
|
||
```json
|
||
{
|
||
"round_number": 2,
|
||
"target": "description",
|
||
"start_offset": 4,
|
||
"end_offset": 8,
|
||
"selected_text": "选中文字",
|
||
"content": "这里需要调整"
|
||
}
|
||
```
|
||
|
||
服务会校验偏移量和所选文字是否匹配当前轮次快照。历史轮次或已完成项目返回 `409`。
|
||
|
||
批注、文字批注和总体反馈都可回复，类型分别为 `image_annotation`、`text_annotation`、`comment`：
|
||
|
||
```http
|
||
POST /api/works/:workId/feedback/:type/:feedbackId/replies
|
||
POST /api/works/:workId/feedback/:type/:feedbackId/withdraw
|
||
```
|
||
|
||
撤回只允许原作者执行，不会删除数据库记录。客户入口在路径前增加 `/api/review/:slug`，并执行相同的项目归属与身份校验。
|
||
|
||
## 客户验收
|
||
|
||
客户输入项目密码和姓名后使用 Cookie 调用：
|
||
|
||
```bash
|
||
curl -X POST http://localhost:3010/api/review/july-content/works/12/decision \
|
||
-b cookies.txt \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"round_number":2,"decision":"approved"}'
|
||
```
|
||
|
||
`decision` 为 `approved` 或 `changes_requested`；退修必须填写 `reason`。只允许决定活动轮次。
|
||
|
||
客户侧全部反馈接口为 `/api/review/:slug/works/:workId/annotations`，仍会校验客户会话绑定的项目。
|
||
|
||
## 兼容接口
|
||
|
||
旧的 `/api/notes`、`/api/notes/:id/versions`、`/api/notes/:id/review-rounds` 与 `/api/projects/:id/collections` 暂保留一个兼容周期。旧交付集 URL 会跳转到项目页；旧多候选稿请求会返回 `400`，不会再创建多方案轮次。新接入必须使用项目、作品和轮次接口。
|
||
|
||
错误统一为 `{ "error": "错误说明" }`。常见状态码：`400` 输入无效、`401` 未认证、`403` 越权、`404` 不存在、`409` 状态冲突。
|