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 关键值：

{
  "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}

{
  "job_id": "...",
  "status": "queued|running|success|failed",
  "stage": "...",
  "progress_percent": 0,
  "message": "...",
  "created_at": "...",
  "updated_at": "...",
  "artifacts": {},
  "error": ""
}

GET /api/jobs/{job_id}/result

成功时返回产物地址：

{
  "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 或网络白名单，防止被直接刷任务。

3.4 KiB Raw Blame History Unescape Escape