docs: 冻结 wordcloud WCD 契约（v1.1）与 designData 生产字段

docs/api-contract-v1.md

@@ -162,16 +162,23 @@
     unitPrice: number
     count: number
     designData?: {
+      version?: 1
+      category?: { id: string; mask: object; tone?: number[] }
+      background?: { src: string; color?: string; pos?: { x: number; y: number; scale: number } }
+      wordcloud?: { jobId?: string; imageUrl: string; names: string[] }
       stickers?: unknown[]
-      category?: unknown
-      imageSrc?: string
-      imagePos?: { x: number; y: number; scale: number }
+      imageSrc?: string      // 兼容旧版
+      imagePos?: { x: number; y: number; scale: number }  // 兼容旧版
     }
   }[]
 }
 ```
 
-`items` 为服务端 JSON，需做结构白名单与大小校验（单条 ≤ 1MB）。
+> **designData 结构遵循 `wechat_wc/docs/design-data-contract-v1.md`（R2/R4 冻结契约）。**
+> 该契约保证 R4 下单后能据此构造 `.wcd` 投递到词云平台。要点：
+> 贴纸图 `src` 必须为 COS 持久 URL（禁止 `wxfile://`/`tmp`）、保留 `wordcloud` 分组、
+> 保留 `category.mask`；后端该 JSON 白名单须放行 `version/background/wordcloud/rotation/zIndex`。
+>`items` 为服务端 JSON，需做结构白名单与大小校验（单条 ≤ 1MB）。
 
 ### PATCH /api/design-list/:id
 
@@ -298,6 +305,35 @@ multipart 请求：`image`（底图）+ `names`（文本名单）+ `params?`。
 
 multipart：`image`。返回处理后图片 URL；失败时前端降级本地灰度。
 
+### POST /api/orders/:id/dispatch（R4 新增，下单后 WCD 派单触发）
+
+幂等触发把订单对应设计的 `.wcd` 投递到词云平台形成生产任务。
+
+请求体：`{}`（幂等键 `requestId` 可选）。
+
+响应 `data`：
+
+```ts
+{
+  orderId: string
+  status: 'queued' | 'running' | 'success' | 'failed' | 'not_configured'
+  wordcloudJobId?: string
+  message?: string
+}
+```
+
+- 同一订单重复调用只投递一次（以 `CustomizationTask.orderId` 唯一或状态约束）。
+- `WORDCLOUD_API_URL` 未配置时返回 `status: 'not_configured'` 与可读 `message`，不做假成功。
+- 常规路径：订单进入 `PROCESSING` 时由后端队列自动触发；本接口作为支付未配置期的联调/运营手段。
+- 词云平台侧契约见 `docs/wordcloud-contract.md`（`POST /api/jobs` 可选 `wcd_file`）。
+
+### 环境变量（R4 新增）
+
+| 变量 | 必填 | 说明 |
+|---|---|---|
+| `WORDCLOUD_API_URL` | 否（为空视为未配置） | 词云平台（FastAPI）地址；未配置时派单返回 `not_configured` |
+| `WORDCLOUD_TIMEOUT_MS` | 否 | 请求 wordcloud 超时（毫秒），默认 30000 |
+
 ## 9. 契约维护规则
 
 - 前端与后端同名分支成对开发：`feat/r1-catalog`、`feat/r2-address-design`、`feat/r3-order-pay`、`feat/r4-upload-wordcloud`。