docs: add API and wordcloud contract v1

2026-08-10 02:08:50 +08:00
parent 1d946046d2
commit d39c619c41
2 changed files with 415 additions and 0 deletions
@@ -0,0 +1,109 @@
+# wordcloud 外部服务契约 v1
+
+本文档冻结 `wxmp_backend` 与 `/Users/broccoli/Project/wordcloud` 之间依赖的最小接口。
+wordcloud 项目内部仍在大量变更，但只要不违反本文档，`wxmp_backend` 的适配层不受影响。
+
+## 1. 版本与状态
+
+- 契约版本：`v1`
+- 状态：*.xlsx 名单模式冻结；`names` 直接文本/JSON 模式为推荐扩展点，尚未冻结。
+- 服务地址：由 `wxmp_backend` 环境变量配置，禁止硬编码到代码或小程序前端。
+- 小程序前端永远不直接访问 wordcloud，只访问 `wxmp_backend`。
+
+## 2. 冻结接口
+
+### POST /api/jobs
+
+创建词云任务，`multipart/form-data`：
+
+| 字段 | 必填 | 说明 |
+|---|---|---|
+| `name_list` | 是 | `.xlsx` 名单文件，v1 必填 |
+| `mask_image` | IMAGE 模式必填 | `.png/.jpg/.jpeg` 掩膜 |
+| `font_file` | 否 | `.ttf/.ttc/.otf` 临时字体 |
+| `font_id` | 否 | 已上传字体 id |
+| `params` | 否 | JSON 字符串，顶层必须是对象 |
+
+`params` 关键值：
+
+```json
+{
+  "MODE": "IMAGE",
+  "DATA_COL_INDEX": 1,
+  "SEED": 42,
+  "N_REPETITIONS": 20,
+  "ENABLE_STROKE_WEIGHTS": false,
+  "FONT_COLOR": "#000000"
+}
+```
+
+响应：`{ "job_id": "..." }`。
+
+### GET /api/jobs/{job_id}
+
+返回：
+
+```json
+{
+  "job_id": "...",
+  "status": "queued|running|success|failed",
+  "stage": "...",
+  "progress_percent": 0,
+  "message": "...",
+  "created_at": "...",
+  "updated_at": "...",
+  "artifacts": {},
+  "error": ""
+}
+```
+
+### GET /api/jobs/{job_id}/result
+
+成功时返回产物地址：
+
+```json
+{
+  "job_id": "...",
+  "status": "success",
+  "image_url": "/api/jobs/{job_id}/files/png",
+  "svg_url": "/api/jobs/{job_id}/files/svg",
+  "svg_stroke_url": "/api/jobs/{job_id}/files/svg_stroke",
+  "db_url": "/api/jobs/{job_id}/files/db",
+  "metrics_url": "/api/jobs/{job_id}/files/metrics"
+}
+```
+
+### GET /api/jobs/{job_id}/files/{kind}
+
+`kind` 支持 `png/svg/svg_stroke/db/metrics`。wxmp_backend 只消费 `png` 并把结果转存 COS。
+
+## 3. 状态语义
+
+| status | 含义 | 小程序映射 |
+|---|---|---|
+| `queued` | 已入队，未开始 | `queued` |
+| `running` | 生成中 | `running` |
+| `success` | 完成 | `success` |
+| `failed` | 失败 | `failed` |
+
+进度以 `progress_percent` 为准，`wxmp_backend` 原样透传；小程序轮询间隔 1-2 秒。
+
+## 4. 错误语义
+
+- 4xx：参数错误，错误信息在 `detail` 或 `message`。
+- 5xx：服务/任务异常，wxmp_backend 将任务标记 `failed` 并在超时后清理。
+- wxmp_backend 适配层应设置请求超时（例如 30s），任务超时上限（例如 10 分钟）。
+
+## 5. 稳定性规则
+
+- 上述 4 个端点的路径、字段名、状态枚举、分页/轮询语义冻结为 v1。
+- wordcloud 内部重构、新增 canvas/assets/projects/templates 能力不影响本契约。
+- 契约变更流程：定义 v2 -> 更新本文档 -> wxmp_backend 在 R4 分支升级适配器 -> 双版本并存一个发布周期。
+- 若 wordcloud 希望新增“直接传名字列表”能力，默认视为 v1 兼容扩展，字段必须是 optional。
+
+## 6. 集成要点
+
+- `wxmp_backend` 负责把小程序文本名单转换为 `.xlsx` 再调用 `POST /api/jobs`。
+- `wxmp_backend` 保存 `job_id -> userId` 映射，轮询与结果查询必须校验归属。
+- 结果图由 wxmp_backend 下载并转存 COS，返回给小程序的是 COS 公网 URL。
+- wordcloud 若对外暴露公网，需要加访问 token 或网络白名单，防止被直接刷任务。