feat(backend): implement task creation and admin web

This commit is contained in:
QiuSW
2026-07-26 14:03:32 +08:00
parent 2b265c92fc
commit c5d3b215ff
58 changed files with 8773 additions and 83 deletions
+29 -4
View File
@@ -13,6 +13,11 @@
- 分页使用 `limit` 和不透明 `cursor`;MVP `limit` 最大 100。
- 客户端不得根据 HTTP 超时判断操作失败,必须查询资源最终状态。
T-204 管理会话完成前,T-203 的管理 Web 和管理 API 只接受来源地址为 loopback 的
请求,Web 写操作还要求 SameSite Cookie 与表单字段匹配的随机双提交 CSRF token。
该门禁只用于阻止业务路由被提前暴露,不是正式身份认证;`/login`、管理会话和
局域网访问仍由 T-204 实现。
通用错误:
```json
@@ -113,7 +118,8 @@ HTTP 语义:
表单字段:
- `file`:必填,MVP 允许 JPEG/PNG/WebP;实际大小上限在配置中固定。
- `file`:必填,MVP 允许可解码 JPEG/PNG/WebP;请求最多 20 MiB、最长边最多
10000 px、总像素最多 25 MP。
- `purpose`:`TASK_REFERENCE` 或 `EXECUTION_EVIDENCE`。
- `task_id`:证据图片必填;参考图创建时为空。
@@ -129,6 +135,13 @@ HTTP 语义:
}
```
T-203 成功返回 `201`。使用相同 `Idempotency-Key` 和相同图片内容重试时返回同一
资产;同 key 不同内容返回 `409`。
`TASK_REFERENCE` 在后端统一白底合成、缩放到最长边不超过 2048 px,并以质量 90
编码为匿名 JPEG。响应的 `media_type`、`size_bytes` 和 `sha256` 都描述规范化结果,
不描述原始上传文件。T-203 尚不接受 `EXECUTION_EVIDENCE`。
### `GET /api/v1/assets/{asset_id}/content`
受鉴权的文件流。只能读取用户有权查看的任务资产;不返回服务端文件路径。
@@ -143,6 +156,7 @@ HTTP 语义:
{
"source_ref": "external-admin-task-10001",
"title": "黑色双肩包",
"sku": "BLACK-20L",
"description": "容量约20L,外观接近参考图",
"image_asset_id": "2bbc1bf2-30f7-497e-a52b-bcb4c61d57c3",
"quantity": 2,
@@ -152,9 +166,12 @@ HTTP 语义:
规则:
- `title` 或 `description` 至少一个非空,`image_asset_id` 必填。
- `title`、`sku` 和 `image_asset_id` 必填,`description` 可为空。
- `title` 最多 120 个 Unicode 字符且不超过 2048 个 UTF-8 字节;`sku` 不超过
512 个 UTF-8 字节;`description` 不超过 8192 个 UTF-8 字节。
- `quantity` 是正整数。
- `max_budget` 可为空,否则为大于零、最多两位小数的 CNY 金额。
- `max_budget` 可为空,否则为大于零、最多两位小数的 CNY 金额,表示当前任务全部
数量的最高商品总预算,不含尚无法确认的运费或优惠。
- 同一调用方的 `source_ref` 如填写必须唯一。
成功返回 `201`:
@@ -164,6 +181,7 @@ HTTP 语义:
"id": "37c9c715-9b51-4ed5-984e-66dad2710c71",
"status": "PENDING",
"title": "黑色双肩包",
"sku": "BLACK-20L",
"quantity": 2,
"max_budget": "200.00",
"created_at": "2026-07-25T08:30:00Z"
@@ -172,7 +190,9 @@ HTTP 语义:
### `GET /api/v1/tasks`
管理端列表。可选参数:`status`、`created_from`、`created_to`、`limit`、`cursor`。
管理端列表。可选参数:`q`、`status`、`created_from`、`created_to`、`limit`、
`cursor`。`q` 匹配任务 ID、`source_ref`、标题或 SKU;默认 `limit=20`,最大 100。
排序固定为 `created_at DESC, id DESC`,不透明 cursor 同时编码这两个字段。
```json
{
@@ -180,6 +200,7 @@ HTTP 语义:
{
"id": "37c9c715-9b51-4ed5-984e-66dad2710c71",
"title": "黑色双肩包",
"sku": "BLACK-20L",
"status": "RUNNING",
"quantity": 2,
"device_name": "pdd-phone-01",
@@ -212,6 +233,9 @@ HTTP 语义:
}
```
T-203 只实现 `PENDING -> CANCELED`;其他状态返回 `409`。执行中设置取消请求及 App
安全检查点响应属于 T-205。
## 设备与领取
### `POST /api/v1/devices/heartbeat`
@@ -249,6 +273,7 @@ App 空闲或运行时上报设备状态;运行时任务续租使用任务专
"id": "37c9c715-9b51-4ed5-984e-66dad2710c71",
"status": "CLAIMED",
"title": "黑色双肩包",
"sku": "BLACK-20L",
"description": "容量约20L,外观接近参考图",
"image_asset_id": "2bbc1bf2-30f7-497e-a52b-bcb4c61d57c3",
"quantity": 2,