feat(api): 支持外部客户端创建作品和更新版本

docs/handoff.md

@@ -16,7 +16,7 @@
 以下需求尚未在代码中完整落地，不应在交付时宣称可用：
 
 - ZIP + CSV 批量导入和最多 100 个作品的异步批量 API
-- `externalId` 幂等创建项目、作品交付集和作品
+- `externalId` 幂等创建作品（项目和作品交付集暂未支持）
 - webhook 与站内未读通知
 - PDF 验收报告和最终原图 ZIP 导出
 - 批注/回复的参考图片附件
@@ -34,4 +34,3 @@
 2. 轮换所有在聊天、截图或开发数据库中出现过的云密钥和临时密码。
 3. 在 HTTPS 域名下验证平台管理员、组管理员、光影叙事和客户四条核心流程。
 4. 根据真实交付承诺，从上方未完成清单中选定必须进入初版的项目。
-

docs/integration-guide.md

@@ -22,14 +22,34 @@ API Key 明文只在创建时返回一次，数据库仅保存 SHA-256 哈希。
 | `/api/management/storage-configs` | COS 配置、连接测试和启用 |
 | `/api/projects` | 项目创建、查询和编辑 |
 | `/api/projects/:projectId/collections` | 作品交付集创建、查询和编辑 |
-| `/api/notes` | 作品查询与 multipart 上传 |
-| `/api/notes/:noteId/versions` | 上传作品新版本 |
+| `/api/notes` | 作品查询与创建 |
+| `/api/notes/:noteId/versions` | 创建作品新版本 |
 | `/api/notes/:noteId/status` | 草稿与待验收状态切换 |
 | `/api/notes/:noteId/text-annotations` | 标题/正文批注 |
 | `/api/images/:imageId/annotations` | 图片坐标批注 |
 | `/api/review/:slug/*` | 客户登录、浏览、反馈与验收 |
 | `/api/health` | 数据库就绪检查 |
 
+## 查询运营组、项目、作品交付集和作品
+
+调用方不需要预先知道数据库 ID。使用 API 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/collections \
+  -H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
+
+# 查询交付集中的作品，响应包含作品 id、external_id 和 version_number
+curl "http://localhost:3010/api/notes?collectionId=1" \
+  -H "Authorization: Bearer $DELIVERY_DESK_API_KEY"
+```
+
+项目级 Key 的项目列表只会返回绑定项目；平台级 Key 可以查询全部运营组的项目。创建作品时只传 `collectionId`，服务会据此确定项目和运营组并校验权限，不需要重复传递 `projectId` 或 `groupId`。
+
 ## 创建项目
 
 平台级 API Key 可以指定目标运营组。项目级 Key 不能创建项目。
@@ -54,34 +74,62 @@ curl -X POST http://localhost:3010/api/projects/1/collections \
 
 ## 上传作品
 
-作品上传使用 `multipart/form-data`，至少一张、最多 30 张图片，单图最大 20 MB。图片数组顺序就是初始展示顺序，第一张为封面。
+外部客户端使用 JSON 创建作品，`images` 直接传入 1–30 个公开可读的 HTTP/HTTPS 图片 URL。服务只保存 URL，不会下载图片或再次上传到 COS。数组顺序就是展示顺序，第一张为封面。
 
 ```bash
 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"
+  -H "Content-Type: application/json" \
+  -d '{
+    "collectionId": 1,
+    "externalId": "client-work-20260721-001",
+    "title": "作品标题",
+    "description": "正文内容",
+    "tags": ["用户填写的标签原文"],
+    "images": [
+      "https://cdn.example.com/works/01.jpg",
+      "https://cdn.example.com/works/02.jpg"
+    ]
+  }'
 ```
 
-当前接受 JPEG、PNG、GIF、WebP 和 AVIF。标签按一段原文保存和展示，不会自动添加 `#` 或拆分为标签库。
+`externalId` 是调用方在当前作品交付集内的作品唯一标识，支持字母、数字、点、下划线、冒号和横线，最长 128 位。相同 `collectionId + externalId` 的重复请求不会重复创建作品，而会以 `200` 返回原作品并包含 `"idempotent": true`。创建成功响应中的 `id` 是后续上传版本所需的 `workId`；如果调用方丢失了该 ID，可以通过 `GET /api/notes?collectionId=1&externalId=client-work-20260721-001` 找回。
+
+URL 图片不会进入当前配置的 COS，也不会由服务检查其内容或长期可用性，因此调用方需要保证链接公开、稳定且确实指向图片。工作台手动上传仍接受 JPEG、PNG、GIF、WebP 和 AVIF。标签按原文保存和展示，不会自动添加 `#` 或拆分为标签库。
 
 ## 创建新版本
 
 ```bash
 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"
+  -H "Content-Type: application/json" \
+  -d '{
+    "title": "修改后的标题",
+    "description": "修改后的正文",
+    "tags": ["修改后的标签原文"],
+    "images": [
+      "https://cdn.example.com/works/v2-01.jpg",
+      "https://cdn.example.com/works/v2-02.jpg"
+    ]
+  }'
 ```
 
 批注绑定作品版本或具体图片，不会因新版本覆盖历史验收证据。
 
+## Python 冒烟脚本
+
+项目自带 `tests/api_create_work.py`，只使用 Python 标准库。推荐通过环境变量提供项目级 API Key：
+
+```powershell
+$env:DELIVERY_DESK_API_KEY = 'dd_live_xxx'
+python tests/api_create_work.py --project-id 1 --collection-id 1
+
+# 为已有作品创建新版本
+python tests/api_create_work.py --project-id 1 --collection-id 1 --work-id 12
+```
+
+如果项目级 Key 只能访问一个项目，并且项目下只有一个作品交付集，可以省略两个 ID。脚本也支持不传 Key、改用 `--username` 后交互输入密码。
+
 ## 错误响应
 
 错误统一以 JSON 返回：