# 拼图图片与前端规则裁决对齐 2026-04-29

## 背景

本轮明确调整拼图运行态边界：

1. 拼图生成图片重新回到 `1:1` 正方形。
2. 拼图中的拖动、交换、合并、拆分与通关判定由前端即时计算。
3. 移动端运行时棋盘需要贴近屏幕两侧边缘，减少无效留白。

此前误按 `9:16` 竖屏统一图片和棋盘，会让拼图块在移动端可操作面积不足，也和拼图素材的切块体验不匹配。本轮回到正方形棋盘与正方形生图。

## 落地结论

### 1. 图片生成

1. 拼图生成图固定使用 `1024*1024`。
2. 文生图和参考图生图共用同一个尺寸常量，禁止一条链路仍生成竖屏或横版图。
3. 拼图图片提示词明确写入 `1:1 正方形画布`，继续保留 `3x3 或 4x4 拼图切块`、主体清晰、层次明确、无文字水印等约束。
4. 文生图正向 prompt 必须由后端压缩到 `500` 字符以内，优先保留玩家画面描述开头与固定拼图约束，避免 DashScope 旧 text2image 协议把超长 prompt 判为“请求参数不合法”。
5. DashScope 上游失败时，api-server 必须在错误 details 中保留业务 message、`upstreamStatus` 和截断后的 `rawExcerpt`，日志也要记录同样的摘要，避免生成进度页只能看到通用 HTTP 文案。
6. 图片生成仍由 `api-server` 执行。SpacetimeDB reducer 不做网络 I/O。
7. 拼图文生图请求体按 DashScope Wan text2image 协议收口：`input` 放 `prompt` 与非空 `negative_prompt`，`parameters` 放 `n`、`size`、`prompt_extend`、`watermark`。不要在 `input` 与 `parameters` 里重复写入反向提示词，否则上游容易返回参数非法。
8. 陶泥币预扣失败属于钱包或 SpacetimeDB 服务链路错误，不得映射成 `400 BAD_REQUEST`。除余额不足返回 `409 CONFLICT` 外，其余预扣异常统一按上游/服务错误暴露，避免生成页误提示“请求参数不合法”。

### 2. 前端规则裁决

1. 运行态的交换、拖动、合并、拆分、通关判定由前端基于 `PuzzleRunSnapshot` 即时计算。
2. 正式 run 与本地测试 run 复用同一套前端规则函数，避免正式链路和测试链路玩法漂移。
3. 后端仍负责开始 run、进入下一关、道具扣费、暂停计时同步、排行榜提交、作品与下一关候选读取。
4. 正式 run 的 `/drag` 后端 HTTP 接口已撤出 Rust API；拖动不再有后端入口。`/swap` 暂作点击交换兼容入口，拖动中的交换由前端本地规则完成。

### 3. 移动端棋盘布局

1. 运行时棋盘根容器恢复 `aspect-square`。
2. 移动端横向 padding 收紧到 `0.25rem`，棋盘宽度使用 `min(99vw, 可用高度)`，尽量贴近屏幕两侧边缘。
3. 单格不设置固定最小高度，避免移动端被单格撑破。
4. 顶部 HUD 与底部道具仍保留安全区，不能遮挡棋盘可操作区域。

### 4. 拼块视觉圆角

1. 基础单块和合并块都必须使用圆角，不能只让合并后的外轮廓有圆角。
2. 基础单块的图片层必须跟随单块容器裁剪，避免图片直角从圆角边框里露出。
3. 合并块继续按实际拼块外轮廓描边，内部相邻边不额外显示边框。

## 验收

1. 点击拼图草稿生成或重新生成画面时，后端请求 DashScope 的 `size` 为 `1024*1024`。
2. 图片提示词包含 `1:1 正方形拼图关卡`。
3. 图片提示词长度不超过 `500` 字符，超长画面描述会被截断，但 `3x3 或 4x4`、`避免文字、水印、边框和 UI 元素` 等玩法约束不能丢。
4. DashScope 返回参数错误、任务失败或非 2xx 时，前端错误优先展示后端 details.message，后端日志能看到 `upstreamStatus` 和 `rawExcerpt`。
5. 正式拼图 run 中拖动拼块后，前端立即更新棋盘、合并块和通关状态，不再等待 `/drag`。
6. 移动端运行时棋盘为正方形，并尽量贴近屏幕两侧边缘。
7. 基础单块和合并块都能看到圆角，且基础单块图片不会溢出圆角裁剪。
8. 下一关、道具、排行榜仍走现有后端链路，不把外部 I/O 或扣费逻辑塞回前端。