Files

yuzhe b42f46c182 chore(config): 更新端口配置从3001到3010

- 将 .env.example 中的 PORT 从 3001 更改为 3010
- 将 CORS_ORIGIN 从 http://localhost:5173 更改为 http://localhost:5180
- 更新 compose.yaml 中的服务端口和健康检查端口为 3010
- 修改 Dockerfile 中暴露的端口为 3010
- 更新文档中的 API 端口引用从 3001 到 3010
- 在 Vite 配置中设置开发服务器端口为 5180
- 更新 Vite 代理目标地址为 http://localhost:3010

2026-07-21 17:13:08 +08:00

3.3 KiB

Raw Blame History

API 接入指南

认证方式

工作台网页使用 HttpOnly Cookie 会话。外部客户端使用：

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 不能创建项目。

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":"客户可见说明"}'

slug 仅支持小写字母、数字和连字符，并作为客户验收链接的一部分。

创建作品交付集

curl -X POST http://localhost:3010/api/projects/1/collections \
  -H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"2026 年 7 月交付","client_description":"本月交付内容"}'

上传作品

作品上传使用 multipart/form-data，至少一张、最多 30 张图片，单图最大 20 MB。图片数组顺序就是初始展示顺序，第一张为封面。

curl -X POST http://localhost:3010/api/notes \
  -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。标签按一段原文保存和展示，不会自动添加 # 或拆分为标签库。

创建新版本

curl -X POST http://localhost:3010/api/notes/12/versions \
  -H "Authorization: Bearer $DELIVERY_DESK_API_KEY" \
  -F "title=修改后的标题" \
  -F "description=修改后的正文" \
  -F "tags=修改后的标签原文" \
  -F "images=@./v2-01.jpg"

批注绑定作品版本或具体图片，不会因新版本覆盖历史验收证据。

错误响应

错误统一以 JSON 返回：

{ "error": "错误说明" }

常见状态码：400 输入无效、401 未认证、403 越权、404 资源不存在、409 唯一性或状态冲突、500 服务端错误。

3.3 KiB Raw Blame History Unescape Escape