# 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. 词云任务模型

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

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

流程：

1. 前端上传底图，拿到 COS URL 或临时文件。
2. `POST /api/wordcloud/generate` 提交底图 + 名字文本，后端创建任务并返回 `jobId`。
3. 前端每 1-2 秒 `GET /api/wordcloud/jobs/:id` 轮询，`success` 后取 `imageUrl`。
4. 结果图建议由 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。