4.5 KiB
4.5 KiB
拼图图片与前端规则裁决对齐 2026-04-29
背景
本轮明确调整拼图运行态边界：
- 拼图生成图片重新回到
1:1正方形。 - 拼图中的拖动、交换、合并、拆分与通关判定由前端即时计算。
- 移动端运行时棋盘需要贴近屏幕两侧边缘，减少无效留白。
此前误按 9:16 竖屏统一图片和棋盘，会让拼图块在移动端可操作面积不足，也和拼图素材的切块体验不匹配。本轮回到正方形棋盘与正方形生图。
落地结论
1. 图片生成
- 拼图默认使用 APIMart
gpt-image-2生成图，外部请求尺寸固定为1:1；nanobanana2仍映射为gemini-3.1-flash-image-preview。 - 历史
original或空模型值只做兼容输入，不再进入 DashScope 原模型链路，统一按gpt-image-2路由。 - 文生图和参考图生图共用同一个正方形尺寸口径，禁止一条链路仍生成竖屏或横版图。
- 拼图图片提示词明确写入
1:1 正方形画布，继续保留适配3x3 / 4x4 / 5x5 / 6x6 / 7x7拼图切块、主体清晰、层次明确、无文字水印等约束。 - 文生图正向 prompt 必须由后端压缩到
500字符以内，优先保留玩家画面描述开头与固定拼图约束，避免上游把超长 prompt 判为“请求参数不合法”。 - APIMart 上游失败时，api-server 必须在错误 details 中保留业务 message、
upstreamStatus和截断后的rawExcerpt，日志也要记录同样的摘要，避免生成进度页只能看到通用 HTTP 文案。 - 图片生成仍由
api-server执行。SpacetimeDB reducer 不做网络 I/O。 - 光点预扣失败属于钱包或 SpacetimeDB 服务链路错误，不得映射成
400 BAD_REQUEST。除余额不足返回409 CONFLICT外，其余预扣异常统一按上游/服务错误暴露，避免生成页误提示“请求参数不合法”。
2. 前端规则裁决
- 运行态的交换、拖动、合并、拆分、通关判定由前端基于
PuzzleRunSnapshot即时计算。 - 正式 run 与本地测试 run 复用同一套前端规则函数，避免正式链路和测试链路玩法漂移。
- 后端仍负责开始 run、进入下一关、道具扣费、暂停计时同步、排行榜提交、作品与下一关候选读取。
- 正式 run 的
/drag后端 HTTP 接口已撤出 Rust API；拖动不再有后端入口。/swap暂作点击交换兼容入口，拖动中的交换由前端本地规则完成。
3. 移动端棋盘布局
- 运行时棋盘根容器恢复
aspect-square。 - 移动端横向 padding 收紧到
0.25rem，棋盘宽度使用min(99vw, 可用高度)，尽量贴近屏幕两侧边缘。 - 单格不设置固定最小高度，避免移动端被单格撑破。
- 顶部 HUD 与底部道具仍保留安全区，不能遮挡棋盘可操作区域。
4. 拼块视觉圆角
- 基础单块和合并块都必须使用圆角，不能只让合并后的外轮廓有圆角。
- 基础单块的图片层必须跟随单块容器裁剪，避免图片直角从圆角边框里露出。
- 合并块继续按实际拼块外轮廓描边，内部相邻边不额外显示边框。
- 合并块轮廓必须按真实占据格生成整体路径，再统一处理外凸角与内凹角圆角；不能只依赖单个格子的
border-radius拼接，否则 L 形、阶梯形合并块的凹入角会露出直角。 - 合并块图片层必须使用同一条整体轮廓做裁剪，确保凹入角的图片像素也跟随圆角被裁掉。
验收
- 点击拼图草稿生成或重新生成画面时，后端请求 APIMart 的
size为1:1，默认模型为gpt-image-2。 - 图片提示词包含
1:1 正方形拼图关卡。 - 图片提示词长度不超过
500字符，超长画面描述会被截断，但适配3x3 / 4x4 / 5x5 / 6x6 / 7x7拼图切块、避免文字、水印、边框和 UI 元素等玩法约束不能丢。 - APIMart 返回参数错误、任务失败或非 2xx 时，前端错误优先展示后端 details.message，后端日志能看到
upstreamStatus和rawExcerpt。 - 正式拼图 run 中拖动拼块后，前端立即更新棋盘、合并块和通关状态，不再等待
/drag。 - 移动端运行时棋盘为正方形，并尽量贴近屏幕两侧边缘。
- 基础单块和合并块都能看到圆角，合并块的外凸角与内凹角都不是直角，且图片不会溢出圆角裁剪。
- 下一关、道具、排行榜仍走现有后端链路，不把外部 I/O 或扣费逻辑塞回前端。