R4 上传 + 词云生成 + 线稿（feat/r4-upload-wordcloud）

Goal: 打通用户图片上传、词云任务生成、DIY 贴纸线稿处理和异步任务状态轮询；这是四条路线中唯一复用 wordcloud 项目的路线，必须通过冻结接口契约的方式隔离它的大量变更。

Architecture: 小程序只与 wxmp_backend 通信；wxmp_backend 实现 COS 上传凭证、词云适配器、 sketch 接口和任务记录/轮询；wordcloud FastAPI 服务作为外部引擎，只暴露并冻结最小契约。小程序页面对词云使用轮询进度，不使用 SSE/EventSource。

Tech Stack: Taro 3.6 + React 18 + TypeScript；NestJS 11 + Prisma/PostgreSQL + Redis/BullMQ；腾讯云 COS；wordcloud FastAPI + EfficientWordCloud。

1. 本分支要开发的内容

前端 `wechat_wc`

文件	职责
`src/utils/api/upload.ts`	`getUploadCredentials/uploadToCos/sketchImage/createWordCloudJob/getWordCloudJob/getWordCloudResult`
`src/pages/wordcloud/index.tsx`	真实上传底图、提交名字清单、创建任务、轮询进度、展示结果图并保存相册
`src/pages/diy/stickerEdit/index.tsx`	把占位域名 `https://your-api-domain.com/api/sketch` 换成 `BASE_URL/api/sketch`；保留前端灰度降级
`src/types/index.ts` 或 `src/types/upload.ts`	`WordCloudJob/WordCloudStatus/SketchResult/CosCredentials`
`src/utils/request.ts` 或新增 `upload.ts`	上传文件统一带 token 与业务 header

后端 `wxmp_backend`

模块	内容
`upload`	`GET /api/upload/credentials?key=...` 返回 STS 临时凭证或 COS 预签名 URL；`Upload` 表记录
`wordcloud`（新增）	`POST /api/wordcloud/generate`、`GET /api/wordcloud/jobs/:id`、`GET /api/wordcloud/jobs/:id/result`
`wordcloud` 适配器	把小程序传入的底图+名字列表转成 wordcloud 契约请求；任务状态入库，用户归属校验
`sketch`（新增）	`POST /api/sketch` 接收图片，返回处理后图片 URL；内部可先做基础处理或接外部 AI
`queue`	BullMQ 消费者把 wordcloud/sketch 任务状态同步到 `CustomizationTask`/`WordCloudJob`
`docs/wordcloud-contract.md`	冻结 wordcloud 三/四个端点、字段、状态与错误语义，含版本号

词云项目 `wordcloud`

需要冻结的接口：POST /api/jobs（建议增加直接传名字列表/JSON 的方式）、GET /api/jobs/{id}、GET /api/jobs/{id}/files/png。
其余 canvas、assets、projects、templates 等接口继续按它自己的节奏演进，小程序后端不依赖。
若契约不变，wordcloud 内部重构无需通知 R4；契约变更时先升版本号，R4 单独出适配器更新。

2. 词云任务模型

小程序侧采用异步任务模型：

interface WordCloudJob {
  id: string
  status: 'queued' | 'running' | 'success' | 'failed'
  progress: number
  imageUrl?: string
  error?: string
}

流程：

前端上传底图，拿到 COS URL 或临时文件。
POST /api/wordcloud/generate 提交底图 + 名字文本，后端创建任务并返回 jobId。
前端每 1-2 秒 GET /api/wordcloud/jobs/:id 轮询，success 后取 imageUrl。
结果图建议由 wxmp_backend 转存 COS 后返回微信可下载域名链接。

3. 设计注意事项

DO

DO 小程序只调用 wxmp_backend，wordcloud 的地址、密钥、内部参数对小程序完全不可见。
DO 上传走临时凭证或预签名 URL，前端拿不到主账号 SecretKey。
DO 文件名与 key 由服务端生成或校验（如 uploads/{userId}/{uuid}.jpg），杜绝用户传路径穿越。
DO 限制文件类型与大小（底图建议 png/jpg ≤ 10MB、名单 ≤ 200 个名字），前后端双重校验。
DO 词云任务在数据库建记录并按用户隔离，用户只能查询自己的 job。
DO 轮询采用普通 HTTP GET，不做 SSE；小程序端 EventSource 支持不稳定。
DO 进度字段以 wordcloud 返回为准，前端只负责展示，不再用随机数模拟进度。
DO sketch 请求带登录态和文件大小校验，失败时前端降级本地灰度，并明确提示“已使用本地线稿”。
DO 长期运行的任务设置超时与失败清理，避免 COS 对象和任务记录无限堆积。
DO 在 docs/wordcloud-contract.md 记录契约版本，并在后端适配器代码里注释依赖版本。

DON'T

DON'T 把 wordcloud 项目 fork 进 wxmp_backend，也不要把它的内部 Python/C++ 代码搬进 NestJS。
DON'T 在小程序前端硬编码 wordcloud 基础地址或直接调用它。
DON'T 上传逻辑使用完整云厂商密钥；密钥只存在于服务端环境变量。
DON'T 接受本地临时路径作为最终结果地址，wordcloud 返回的内部 /api/jobs/... 必须转成 COS 公网 URL。
DON'T 让用户通过猜 jobId 读取他人任务结果，所有查询都带 userId 条件。
DON'T 在密钥未配置时静默跳过上传/词云；返回结构化“未配置”错误，前端给出可理解提示。
DON'T 用假的 setInterval 进度假装生成完成，R4 结束前必须移除当前 wordcloud 页的模拟逻辑。

4. 补充内容

验收标准

小程序端上传图片可拿到 COS 可访问 URL，Upload 表有记录且归属当前用户。
POST /api/wordcloud/generate 可在真实 wordcloud 服务上产出 PNG，前端轮询到结果并保存相册。
POST /api/sketch 返回有效图片 URL；接口失败时前端走降级且不白屏。
词云任务非本人不可访问；上传文件类型/大小校验生效。
docs/wordcloud-contract.md 已冻结并带版本号；前端 wordcloud 页不再有随机进度。

合并与依赖

分支名：前端与后端均为 feat/r4-upload-wordcloud。
与 R1-R3 并行，不依赖商品/订单链路；后端上传基础设施可为后续 R2 的贴纸图片持久化提供能力。
wordcloud 契约若未冻结，R4 先完成“契约文档 + 后端适配层”，联调阶段再补真实 job。

风险

wordcloud 正在大量变更，任务状态/产物路径随时可能变化；这正是契约冻结要解决的问题，联调时先锁定一个部署版本。
COS 与微信 downloadFile/uploadFile 合法域名必须提前配置，否则真机上传下载会失败。
词云生成是 CPU 密集型任务，需要限制并发与单账号频率，防止被刷爆资源。
designData 中的贴纸图片若在 R4 接入上传，需要 R2 的设计 JSON 结构配合增加 uploadedUrl 字段，两分支交接时注意。

测试要求

后端：上传凭证、大小/类型校验、wordcloud 适配器正常/失败/超时、任务归属权限、sketch 接口。
前端：词云上传、轮询进度、fail 重试、结果保存相册；线稿接口失败降级；无 COS 配置提示。
集成：用固定 wordcloud 部署版本跑一次真实生成端到端 smoke。

6.8 KiB Raw Blame History Unescape Escape