Increase VectorEngine timeouts and add image UI

Add VectorEngine image generation config and raise request timeouts (env + scripts) from 180000 to 1000000ms. Introduce a reusable CreativeImageInputPanel component with tests and wire up mobile keyboard-focus helpers; update generation views and related tests (CustomWorldGenerationView, BarkBattle editor, Match3D, Puzzle flows). Improve API error handling / VectorEngine request guidance (packages/shared http.ts and docs), and apply multiple backend/frontend fixes for puzzle/match3d/prompt handling. Also include extensive docs and decision-log updates describing UI/UX decisions and verification steps.
2026-05-15 02:40:59 +08:00
parent 4642855fd0
commit 74fd9a33ac
87 changed files with 5508 additions and 1261 deletions
--- a/docs/design/MOBILE_CREATION_WORK_LIST_TWO_COLUMN_LAYOUT_2026-04-29.md
+++ b/docs/design/MOBILE_CREATION_WORK_LIST_TWO_COLUMN_LAYOUT_2026-04-29.md
@@ -4,24 +4,24 @@

 草稿页的作品模块需要同时承载 RPG、拼图和大鱼吃小鱼等玩法。不同玩法卡片不能各自展示阶段、素材、主题等细节标签，否则作品列表会在移动端显得拥挤，并且草稿作品会暴露过多编辑态信息。

-本次将作品列表卡片收口成统一信息结构：草稿只用于快速识别和继续创作，已发布作品才展示公开数据；删除与分享等低频操作收进左滑操作层，避免列表常态被按钮挤占。
+本次将作品列表卡片收口成统一信息结构：草稿只用于快速识别和继续创作，已发布作品才展示公开数据；删除与分享等低频操作收进长按动作面板，避免列表常态被按钮挤占。

 ## 落地范围

 - 列表容器：`src/components/custom-world-home/CustomWorldCreationHub.tsx`
 - 作品卡片：`src/components/custom-world-home/CustomWorldWorkCard.tsx`
 - 不改动作品数据聚合、筛选、打开和体验逻辑。
- 已发布作品保留分享能力；可删除作品保留删除能力，但常态不显示为右侧按钮。
+- 已发布作品保留分享能力，卡片右上角常驻分享图标；可删除作品保留删除能力，但常态不显示删除按钮。

 ## 卡片结构规则

-1. 卡片整体对齐发现 / 分类页的横向作品列表结构：左侧为标题、状态、类型、摘要与必要数据，右侧为带透明度的封面图。
+1. 卡片整体对齐发现 / 分类页的横向作品列表结构：内容层承载标题、状态、类型、摘要与必要数据，封面作为不占内容布局的右半区透明背景层。
 2. 不再显示阶段、主题、素材完成度、作者、作品号等额外标签。
-3. 标题区域保留作品状态与游戏类型；生成中的草稿状态显示为“生成中”。
+3. 标题区域保留作品状态与游戏类型；草稿和已发布状态只用图标化 UI 标识，不再在卡片上显示“草稿 / 已发布”文字。
 4. 草稿卡片到作品描述为止，不显示右侧“继续创作”等固定动作、统计、作品号或公开指标。
 5. 已发布卡片在描述下方显示三项公开指标：游玩数、改造数、点赞数。
-6. 已发布卡片的分享入口收进左滑操作层，点击后复制作品分享文案，不触发卡片打开。
-7. 可删除卡片的删除入口收进左滑操作层，常态不显示删除按钮；左滑露出后点击删除不触发卡片打开。
+6. 已发布卡片右上角显示分享图标，点击后复制作品分享文案，不触发卡片打开。
+7. 长按草稿作品弹出独立动作面板，只展示删除作品；长按已发布作品弹出独立动作面板，展示分享和删除。动作按钮点击后不得触发卡片打开。
 8. 卡片不显示最后修改时间；`updatedAt` 只用于作品列表排序。
 9. 生成中的卡片在整卡上叠加半透明蒙版、旋转等待符号和“生成中...”标识；蒙版不能移除标题、状态、类型、摘要、右侧封面等原有信息。

@@ -32,7 +32,7 @@
 3. 用户每次进入创作页时，前端读取上一次进入该页面缓存的公开指标快照；当已发布作品卡片滑动进入视口后，数字从缓存值增长到本次接口返回的最新值。
 4. 若最新值高于缓存值，动画完成后在对应指标右下角展示红色向上箭头和本次上涨的具体数值，字号低于主数字，避免抢占主信息层级。
 5. 若没有缓存值、缓存值不低于最新值或作品仍是草稿，则直接显示最新值，不展示上涨标记。
-6. 每张作品卡片继续使用作品封面作为右侧方形半透明主视觉；封面不能因为列表收缩被拉伸变形。
+6. 每张作品卡片继续使用作品封面作为右侧半区透明背景主视觉；封面从右向左渐隐，不能出现独立方形边界，也不能因为列表收缩挤占正文布局或被拉伸变形。
 7. 作品列表按 `updatedAt` 倒序排列；前端排序需要兼容 ISO 时间和 Rust 后端常用的 `seconds.microsZ` 时间文本。
 8. 若玩法摘要缺少 `coverImageSrc`，允许从同一作品的正式关卡图、背景图或素材图里取第一张可用图片作为卡片背景兜底。
 9. 若作品真实图片为空、私有资源换签失败或浏览器图片加载失败，卡片必须切到对应玩法的 `public/creation-type-references/` 参考图；最终兜底底色使用平台浅粉暖白色系，不允许退回黑色普通面板。
@@ -40,16 +40,16 @@
 ## 移动端布局规则

 1. 作品列表默认使用单列纵向列表，视觉上与发现页分类列表保持一致。
-2. 移动端每张卡片使用固定右列方形半透明封面，右列建议 `5.1rem` 左右；草稿卡即使复用分类页基础类名，也必须用自身选择器覆盖分类页的 `4.3rem + 正文 + action` 三列规则，避免正文被压进窄列。
-3. 已发布作品的公开指标在卡片正文内保留，但需要压缩字号和间距，不能让右侧封面列错位。
+2. 移动端每张卡片使用绝对定位右半区封面背景层，封面在右边缘最清晰、向左渐隐；草稿卡即使复用分类页基础类名，也必须用自身选择器覆盖分类页的 `4.3rem + 正文 + action` 三列规则，避免正文被压进窄列。
+3. 已发布作品的公开指标在卡片正文内保留，但需要压缩字号和间距，不能依赖右侧封面列参与排版。
 4. 小屏卡片降低高度、内边距、标题字号和徽标尺寸，避免长标题或中文描述撑破容器。
-5. 右侧封面容器本身必须带玩法参考图 CSS 背景兜底；`img` 的真实封面或 `ResolvedAssetImage` fallback 加载失败时，也不能出现空白或黑卡。
+5. 右侧封面层本身必须带玩法参考图 CSS 背景兜底；`img` 的真实封面或 `ResolvedAssetImage` fallback 加载失败时，也不能出现空白或黑卡。

 ## 网页端布局规则

 1. 网页端作品架不能继续拉成整行超宽列表；从 `768px` 起使用多列卡片式网格，默认两列，宽屏提升到三列。
 2. 网页端卡片保留移动端同一信息结构，但卡片高度增加，正文区可显示更多摘要与公开指标，右侧封面改为更高的半透明视觉区。
-3. 删除与分享仍然只在左滑或键盘揭示态显示；默认态不得透出红色删除底层或分享底层。
+3. 删除与分享仍然只在长按动作面板或键盘揭示态显示；默认态不得透出红色删除底层。

 ## 文案约束

--- a/docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md
+++ b/docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md
@@ -60,3 +60,5 @@
 3. 风格卡标签使用浅底胶囊，保证图片仍是主体。
 4. 难度等分段选项可以使用主品牌色，但选中态需要降低阴影和饱和度。
 5. UI 中不补充玩法规则说明文案，保持创作入口清爽。
+6. 拼图创作表单在未上传主图时，画面描述输入框右下角保留一个参考图上传入口；支持多选，最多 5 张，上传后以下方小缩略图展示，点击缩略图可放大预览。
+7. 当前拼图后端只消费第一张有效参考图做生成，前端仍需保留数组输入，方便后续扩展多参考图能力。
--- a/docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md
+++ b/docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md
@@ -126,6 +126,7 @@
 - 用户再进入草稿 Tab 并点击同一草稿时，若生成仍未完成，进入对应生成过程页查看最新进度；若已完成，直接进入对应结果页。
 - 草稿作品卡在生成中展示“生成中”状态标记；新生成完成且用户尚未查看的草稿在卡片右上角展示红点。
 - 底部一级“草稿”Tab 在存在未查看新完成草稿时展示红点；用户点击查看带红点的作品后，该作品红点消失。若草稿页已无任何带红点作品，底部“草稿”Tab 红点同步消失。
+- 红点通知链路覆盖所有进入草稿作品架的生成型玩法；宝贝识物等仅有 `profileId` 和 `draftId` 的轻量草稿，也必须把两个 ID 都纳入同一组通知 key，避免卡片红点和底部草稿 Tab 红点漂移。
 - 生成完成时如果用户仍停留在对应生成过程页，可自动进入结果页；如果用户已经回到创作中心或其它功能页，不打断当前操作。
 - 创作 Tab 的模板入口只允许被模板自身的开放状态禁用；某个草稿后台生成中时，不得用该玩法的 busy 状态禁用其它模板入口、同模板再次创建入口或阻止用户继续创建新作品。
 - 同模板再次点击生成时必须创建新的草稿生成任务，不得因为当前玩法已有后台生成 session 就跳回上一条草稿的生成过程页；查看上一条生成进度只能从草稿 Tab 的对应作品卡进入。
--- a/docs/experience/MOBILE_UI_DEV_EXPERIENCE.md
+++ b/docs/experience/MOBILE_UI_DEV_EXPERIENCE.md
@@ -143,13 +143,13 @@
  5. 标签

 ## 6.3 草稿页作品卡对齐分类列表
- 草稿 Tab 的作品架要优先对齐发现页分类列表的横向卡片：左侧承载标题/状态/类型/摘要，右侧显示带透明度的方形封面图。
- 草稿卡不能为了视觉对齐丢掉原有信息：删除、分享、已发布统计、拼图积分激励、未读红点都要保留；其中删除和分享属于低频动作，常态不显示按钮，向左划动列表项后露出操作。
+- 草稿 Tab 的作品架要优先对齐发现页分类列表的横向卡片：内容层承载标题/状态/类型/摘要，封面作为右半区半透明背景层。
+- 草稿卡不能为了视觉对齐丢掉原有信息：删除、分享、已发布统计、拼图积分激励、未读红点都要保留；其中删除属于低频动作，常态不显示按钮，长按列表项后进入独立动作面板；已发布作品右上角可以常驻分享图标。
 - 卡片右侧不再常驻“继续创作”“查看详情”“查看进度”等动作按钮，打开作品由整张卡片承担。
 - 移动端保持单列列表；网页端使用多列卡片式网格，避免在宽屏上把作品卡拉成一整行长条。
 - 生成中的状态使用整卡蒙版、旋转等待符号和“生成中...”标识；蒙版只能作为状态层，不能替换或移除卡片本身的信息。
 - 草稿卡复用分类页基础类名时，要用 `.creation-work-card.platform-category-game-item` 覆盖分类页移动端三列规则；否则正文会被当作封面列压缩，中文标题会断成一两个字一行。
- 右侧封面不要只依赖 `img` fallback，容器层也要有玩法参考图 CSS 背景兜底，私有资源换签失败或图片 onerror 时仍能看到封面视觉。
+- 右侧封面不要只依赖 `img` fallback，容器层也要有玩法参考图 CSS 背景兜底，私有资源换签失败或图片 onerror 时仍能看到封面视觉；封面层适合绝对定位铺到卡片右半区，作为半透明背景从右到左渐隐，不应出现独立方形边界或参与内容排版。

 ## 7. 样式与动画经验

@@ -235,3 +235,12 @@
 - 主站移动端以固定游戏画布体验为准，入口 `viewport` 需要锁定 `minimum-scale=1.0`、`maximum-scale=1.0` 和 `user-scalable=no`，同时保留 `viewport-fit=cover` 适配安全区。
 - 浏览器仍可能通过 iOS `gesture*` 或多指 `touchmove` 触发整页缩放，因此主站启动入口应统一调用 `lockMobileViewportZoom()` 拦截页面级捏合与快速双击缩放。
 - 不要在每个画布组件里重复注册缩放拦截；单指滚动、点击、拖拽应继续留给具体页面和玩法处理。
+
+### 10.4 移动端输入法不要压缩画布
+- 平台主站点击输入框弹出输入法时，不能让 `100dvh` 跟随键盘缩小后重新压缩整页布局。
+- 正确做法是在输入法未打开时记录稳定布局高度，输入法打开期间保持画布高度不变，只根据当前输入框位置计算画面上移量。
+- 该行为应在主站入口统一注册，业务组件只保留普通 `input` / `textarea`，不要在每个输入框里重复写键盘适配逻辑。
+
+### 10.5 移动端创作生成页不要暴露批次视角
+- 拼图、抓大鹅这类轻量玩法的草稿生成页只保留“预计等待”和“计时”两个用户关心的状态，移动端放在同一行；不要默认展示“当前批次”这类模型执行视角。
+- 生成步骤在移动端进入页面时按顺序从左侧滑入，强化“正在推进”的节奏；动画只绑定步骤卡，不影响桌面端密集布局和其它信息卡。
--- a/docs/prd/AI_NATIVE_PUZZLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-22.md
+++ b/docs/prd/AI_NATIVE_PUZZLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-22.md
@@ -348,6 +348,7 @@ interface PuzzleAnchorPack {
 7. 历史拼图素材库读取 `asset_kind = puzzle_cover_image` 的资产记录，只用于选择参考图，不直接替换正式图。
 8. 从历史素材库选择素材后，前端把该素材的 `imageSrc` 作为 `referenceImageSrc` 传入下一次生成请求。
 9. 本地上传参考图与历史素材参考图互斥；后选择者覆盖先选择者。
+10. 历史素材列表的图片名称必须从 `imageSrc` 的路径末尾推导，不能把 `ownerLabel` 账号归属文案当成图片名称；生成时间必须兼容 SpacetimeDB 秒级时间字符串。

 前端 UI 规则：

--- a/docs/prd/MY_TAB_FEATURE_PRD_INDEX_2026-04-16.md
+++ b/docs/prd/MY_TAB_FEATURE_PRD_INDEX_2026-04-16.md
@@ -80,6 +80,7 @@
 - `PlatformHomeView` 继续作为“我的”Tab 首屏承载层
 - 优先采用现有面板、抽屉、弹窗，不新建独立大系统
 - 页面只展示后端返回的状态，不自行计算结论型业务状态
+- 会员中心与充值入口只保留在顶部身份卡右侧按钮，不在“常用功能”区重复展示
 - 每日任务入口放在“常用功能”，点击后弹出独立任务面板

 ### 4.2 后端边界
--- a/docs/prd/MY_TAB_MEMBERSHIP_CENTER_PRD_2026-04-16.md
+++ b/docs/prd/MY_TAB_MEMBERSHIP_CENTER_PRD_2026-04-16.md
@@ -75,6 +75,8 @@
 3. 中部显示权益卡片
 4. 底部显示套餐与购买按钮

+2026-05-14 补充：充值入口只保留在“我的”页顶部身份卡右侧按钮，常用功能区不再重复展示充值卡片，避免同屏出现两个相同业务入口。
+
 ## 4.2 页面内容

 页面展示模块：
--- a/docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md
+++ b/docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md
@@ -42,7 +42,7 @@ APIMART_IMAGE_REQUEST_TIMEOUT_MS=180000
 # VectorEngine / Gemini 原生图片 / GPT-image-2 / Suno / Vidu 生成网关
 VECTOR_ENGINE_BASE_URL=https://api.vectorengine.cn
 VECTOR_ENGINE_API_KEY=
-VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=180000
+VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=1000000
 VECTOR_ENGINE_AUDIO_REQUEST_TIMEOUT_MS=180000

 # Hyper3D Rodin Gen-2 3D 模型生成
@@ -102,14 +102,14 @@ HYPER3D_MODEL_REQUEST_TIMEOUT_MS / RODIN_MODEL_REQUEST_TIMEOUT_MS
 3. 文本 LLM provider 为 `ark` 且未配置 `GENARRATIVE_LLM_BASE_URL` 时，仍回退到 Ark 公开基础 URL。
 4. 角色视频 provider 复用 Ark 且未配置 `ARK_CHARACTER_VIDEO_BASE_URL` 时，仍回退到 Ark 公开基础 URL。
 5. 具体模型名缺失时不在配置层伪造默认模型，调用到对应能力时由下游配置校验返回缺配置错误。
-6. VectorEngine 图片与音频生成只读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY`，其中 GPT-image-2 与抓大鹅 Gemini 素材 sheet 图片生成额外读取 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；不复用 `APIMART_*`、`GENARRATIVE_LLM_*` 或前端变量。拼图 Agent 的生成 action 不做前端自动重试，避免一次点击在上游超时后重复触发外部生图与钱包扣退费；若 VectorEngine 请求达到该超时窗口，api-server 返回 `504 Gateway Timeout`，`error.details.provider` 为 `vector-engine`，并保留具体超时 message。
+6. VectorEngine 图片与音频生成只读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY`，其中 GPT-image-2 与抓大鹅 Gemini 素材 sheet 图片生成额外读取 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；不复用 `APIMART_*`、`GENARRATIVE_LLM_*` 或前端变量。图片请求默认超时窗口为 `1000000ms`，且 api-server 会把旧环境中较小的 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 提升到该下限，避免 500 秒级生图被提前截断。拼图 Agent 的生成 action 不做前端自动重试，避免一次点击在上游超时后重复触发外部生图与钱包扣退费；若 VectorEngine 请求达到该超时窗口，api-server 返回 `504 Gateway Timeout`，`error.details.provider` 为 `vector-engine`，并保留具体超时 message。
 7. 火山引擎语音能力由 `platform-speech` 收口协议帧与上游鉴权，`api-server` 只暴露平台鉴权后的代理路由，不向前端返回任何密钥字段。
 8. Hyper3D Rodin Gen-2 使用公开默认 `https://api.hyper3d.com/api/v2`，API Key 只读取 `HYPER3D_API_KEY` / `RODIN_API_KEY`，不复用文本 LLM、图片或音频网关密钥。
 9. APIMart 当前只保留给创意 Agent 的 `gpt-5` Responses 文本/多模态理解链路；抓大鹅物品素材 sheet、GPT-image-2 图片生成和音频生成都不得读取 APIMart 配置。
 10. 本地 `npm run api-server`、`npm run dev:rust`、`npm run dev` 与 `npm run dev:web` 的环境文件优先级固定为非空外层 shell 变量最高，其后 `.env`、`.env.local`、`.env.secrets.local` 逐层覆盖；真实密钥建议放在 `.env.secrets.local`，防止 `.env` 中的空示例值覆盖私密配置。外层 shell 变量如果是空字符串或全空白，不再遮蔽本地 env 文件中的真实值。
 11. OSS 客户端只在 `ALIYUN_OSS_BUCKET`、`ALIYUN_OSS_ENDPOINT`、`ALIYUN_OSS_ACCESS_KEY_ID`、`ALIYUN_OSS_ACCESS_KEY_SECRET` 四项齐全时初始化。四项全部缺失表示未启用 OSS；部分缺失时 `api-server` 记录 warning 并继续启动，具体上传、换签或读取 generated 私有资产的接口返回 `OSS 未完成环境变量配置`，并在 `error.details.missingEnv` 中列出缺失变量。
 12. 抓大鹅 2D 草稿素材生成需要同时具备 VectorEngine 与 OSS 配置：VectorEngine Gemini `gemini-3-pro-image-preview` 原生 `generateContent` 负责生成 5x5 物品素材 sheet；封面和 `9:16` 背景图走 VectorEngine `/v1/images/generations` 的 `gpt-image-2-all` JSON 链路；`1:1` 容器 UI 图走 VectorEngine `/v1/images/edits` multipart 链路，并把 `public/match3d-background-references/pot-fused-reference.png` 作为 `image` part 上传，不能再用 generations `image` 数组弱参考。OSS 负责保存切割后的五视角图片及其它生成图。缺少 VectorEngine 或 OSS 时应通过 `error.details.reason` 向前端暴露具体缺项，不能只显示泛化“服务暂不可用”。素材图、封面图和背景图生成在调用外部生图前必须先预检 OSS，避免已消耗外部生图后才发现无法落库。
-13. 拼图有参考图且开启 AI 重绘时使用 VectorEngine `POST /v1/images/edits` multipart 接口。若返回 `error sending request for url`，代表后端未收到 HTTP 响应；响应 `details` 会带 `reason`、`source`、`connect`、`body`、`timeout` 和 `endpoint`，排查时优先检查服务器网络、DNS、防火墙、代理和参考图大小。拼图图片客户端强制 HTTP/1.1，以降低上游 multipart HTTP/2 连接中断风险。
+13. 拼图有参考图且开启 AI 重绘时使用 VectorEngine `POST /v1/images/edits` multipart 接口。若返回 `error sending request for url`，代表后端未收到 HTTP 响应；响应 `details` 会带 `reason`、`source`、`connect`、`body`、`timeout` 和 `endpoint`，前端展示优先使用 `details.reason`，排查时优先检查服务器网络、DNS、防火墙、代理和参考图大小。拼图图片客户端强制 HTTP/1.1，以降低上游 multipart HTTP/2 连接中断风险。
 14. 本地排查 `OSS 未完成环境变量配置` 时必须核对键名是否精确为 `ALIYUN_OSS_ACCESS_KEY_SECRET`。常见误写是把 `OSS` 的首字母 `O` 写成数字 `0`，例如 `ALIYUN_0SS_ACCESS_KEY_SECRET`；该键不会被 `api-server` 读取。

 ## 本地配置检查
--- a/docs/technical/ASSET_GENERATION_POINTS_CONSUMPTION_2026-04-27.md
+++ b/docs/technical/ASSET_GENERATION_POINTS_CONSUMPTION_2026-04-27.md
@@ -45,6 +45,8 @@

 所有前端可见且会消耗泥点的按钮，点击后必须先弹出独立确认面板，面板标题使用 `确认消耗泥点`，正文只展示本次消耗数量，例如 `消耗 2 泥点`。用户点击 `确定` 后才允许调用后端扣费动作；点击 `取消` 或关闭面板不得触发接口。

+2026-05-14 补充：创作页入口点击确认后，前端必须先刷新 `/api/profile/dashboard` 钱包余额；余额大于等于本次消耗时才允许创建玩法 session / 草稿，余额不足时停留在创作页并展示不足提示。该预检不替代后端扣费原子校验，只用于避免余额明显不足时先生成半成品草稿。
+
 2026-05-14 当前已覆盖的草稿页入口包括：

 - 拼图入口 `AI重绘=true` 的 `生成拼图游戏草稿`：`2` 泥点；`AI重绘=false` 直接使用上传图，不显示泥点确认。
--- a/docs/technical/ASSET_HISTORY_PUZZLE_COVER_KIND_FIX_2026-04-27.md
+++ b/docs/technical/ASSET_HISTORY_PUZZLE_COVER_KIND_FIX_2026-04-27.md
@@ -13,6 +13,9 @@
 1. `server-rs/crates/api-server/src/assets.rs` 中的历史素材类型白名单统一收口为单一常量源。
 2. HTTP 层错误文案与实际支持列表由同一函数生成，避免后续再出现“校验改了但提示文案还是旧口径”的漂移。
 3. 增加 `puzzle_cover_image` 的回归测试，确保拼图封面素材不会再次被历史接口遗漏。
+4. `ownerLabel` 只表示资产归属账号，不是历史图片标题；前端历史素材卡片标题必须从 `imageSrc` 的路径末尾推导，例如 `/generated-puzzle-assets/history/image.png` 展示为 `image.png`。
+5. `createdAt / updatedAt` 可能来自 SpacetimeDB / shared-kernel 的秒级字符串，例如 `1713686400.000000Z`，前端不得只用 `new Date(value)` 解析后把它显示成未知时间。
+6. 历史素材选中后仍把 `imageSrc` 作为 `referenceImageSrc` 传给生成链路；创作页和关卡详情页的预览必须通过 `ResolvedAssetImage` 换签展示，不直接请求裸 `/generated-*` 路径。

 ## 后续约束

@@ -21,3 +24,7 @@
   - `spacetime-module` 的历史素材白名单
   - 对应前端调用常量与测试
 2. 如果运行态仍返回旧白名单错误，优先检查本地 `api-server.exe` 是否已按最新源码重新编译并重启，而不是先回退前端类型参数。
+3. 历史素材列表的 UI 回归测试应覆盖：
+   - 卡片标题不使用 `账号 user-1` 这类归属文案。
+   - `1713686400.000000Z` 能显示为可读生成时间。
+   - 选中素材后工作台 / 关卡详情展示 `历史素材 · image.png`，并继续提交原始 `imageSrc`。
--- a/docs/technical/AUTH_NEW_ACCOUNT_INVITE_MODAL_2026-05-01.md
+++ b/docs/technical/AUTH_NEW_ACCOUNT_INVITE_MODAL_2026-05-01.md
@@ -53,11 +53,18 @@ POST /api/profile/referrals/redeem-code

 若用户登录的是已有账号，则不会弹出新账号邀请码面板。

-## 5. 完成定义
+## 5. 新账号泥点初始化
+
+当短信登录、开发密码入口或微信激活流程创建新账号时，后端注册链路必须调用 `grant_new_user_registration_wallet_reward`，为该用户写入 `10` 个初始泥点。
+
+该赠送落在 `profile_dashboard_state.wallet_balance` 与 `profile_wallet_ledger` 中，流水来源为 `new_user_registration_reward`，流水 ID 固定为 `new-user-registration:{user_id}`，用于保证重复调用不重复发放。已有账号登录不得再次发放。
+
+## 6. 完成定义

 1. 登录弹窗内不可见注册入口。
 2. 短信登录创建新账号后弹出邀请码面板。
 3. 邀请码为空时按钮为 `跳过`，非空时按钮为 `提交`。
 4. 取消按钮可关闭面板。
 5. 已登录邀请码接口允许提交，并继续由 SpacetimeDB procedure 兜底业务校验。
-6. 前端测试覆盖注册入口删除、新账号弹窗、URL 邀请码预填与提交。
+6. 新账号创建成功后默认获得 `10` 个泥点，且重复登录或重试不得重复发放。
+7. 前端测试覆盖注册入口删除、新账号弹窗、URL 邀请码预填与提交。
--- a/docs/technical/BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md
+++ b/docs/technical/BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md
@@ -52,7 +52,7 @@ Phase 2 的作品配置边界是“轻创作配置作品”：创作者可以配

 建议先支持“本地 runtime + 可发布配置化作品 + 单局结果记录 + 个人历史成绩 / 作品统计 / 最小排行榜”的闭环：

-1. 创作者从玩法选择进入 bark-battle 后创建草稿，通过单页轻配置表单 + 预览卡片配置标题、描述、主题/背景预设、狗狗皮肤预设、难度预设和排行榜开关。
+1. 创作者从玩法选择进入 bark-battle 后创建草稿，通过创作 Tab 内嵌轻配置表单 + 预览卡片配置标题、描述、主题/背景预设、狗狗皮肤预设、难度预设和排行榜开关。
 2. 发布为稳定作品 ID，`playTypeId = "bark-battle"`。
 3. 玩家可从作品详情页 CTA、广场/作品卡片、我的作品/个人作品架进入正式 runtime，前端使用稳定作品 ID 获取发布态 runtime config。
 4. 玩家授权麦克风后在本地完成 30 秒声控对战。
@@ -91,15 +91,15 @@ Phase 2 的个人历史成绩由“最近记录列表 + 个人最佳摘要”组

 ### 2.2.6 正式作品入口闭环

-Phase 2 必须接入 Bark Battle 正式作品入口闭环，但不新增独立专区、活动页、挑战分享页、好友邀请或多人房间入口。入口范围包括：创作入口/玩法选择中出现 `bark-battle`，进入单页轻配置表单 + 预览卡片；作品详情页 CTA 点击“开始游玩”进入正式 runtime；广场/作品卡片可以展示、打开详情并开始游玩；我的作品/个人作品架能看到作者发布的 Bark Battle 作品；runtime 路由使用稳定作品 ID 并从后端发布态 config 拉取配置。
+Phase 2 必须接入 Bark Battle 正式作品入口闭环，但不新增独立专区、活动页、挑战分享页、好友邀请或多人房间入口。入口范围包括：创作入口/玩法选择中出现 `bark-battle`，在创作 Tab 模板条下方直接内嵌轻配置表单 + 预览卡片；作品详情页 CTA 点击“开始游玩”进入正式 runtime；广场/作品卡片可以展示、打开详情并开始游玩；我的作品/个人作品架能看到作者发布的 Bark Battle 作品；runtime 路由使用稳定作品 ID 并从后端发布态 config 拉取配置。

 正式 run start 成功后必须写 `work_play_start`，其中 `scope_kind=work`、`scope_id=稳定作品 ID`，metadata 至少包含 `playType=bark-battle`、`workId`、`sourceRoute`、`userId`。内部试玩入口可以作为开发调试保留，但不得作为 Phase 2 正式入口。

 ### 2.2.7 轻配置编辑流程

-Phase 2 的创作编辑形态是“单页轻配置表单 + 预览卡片”，不是多步骤向导、拖拽编辑器或完整规则编辑器。表单字段包含：标题（必填）、简介（选填）、主题/背景预设（必填枚举）、狗狗皮肤预设（必填枚举）、难度预设（必填，默认 `normal`）、排行榜开关（默认开启）。
+Phase 2 的创作编辑形态是“创作 Tab 内嵌轻配置表单 + 预览卡片”，不是独立配置页面、多步骤向导、拖拽编辑器或完整规则编辑器。表单字段包含：标题（必填）、简介（选填）、主题/背景预设（必填枚举）、狗狗皮肤预设（必填枚举）、难度预设（必填，默认 `normal`）、排行榜开关（默认开启）。

-交互流程：创作者从玩法选择进入后生成草稿；在同一页编辑轻配置并查看预览卡片；支持保存草稿和发布；发布成功后跳转作品详情；可从我的作品再次编辑草稿或基于已发布作品创建新版本。Phase 2 不做 AI 生成配置、多步骤 wizard、规则参数编辑、复杂封面编辑、runtime 内嵌预览或大段玩法说明文案。
+交互流程：创作者从玩法选择进入后保持在创作 Tab；在模板条下方编辑轻配置并查看预览卡片；支持保存草稿和发布；发布成功后跳转作品详情或进入试玩 runtime，runtime 退出时回到创作 Tab 的汪汪声浪模板。可从我的作品再次编辑草稿或基于已发布作品创建新版本。Phase 2 不做 AI 生成配置、多步骤 wizard、规则参数编辑、复杂封面编辑、runtime 内嵌预览或大段玩法说明文案。

 ### 2.2 后续增强路径

@@ -115,7 +115,7 @@ Phase 2 按“契约和领域规则先行，然后最小纵切，再扩展投影

 1. 契约与领域规则：补 `shared-contracts` DTO、`module-bark-battle` 纯领域规则、`rulesetVersion` / `difficultyPreset` / score adjudication，并先写单测。
 2. SpacetimeDB 表与 reducer + api-server BFF：落草稿/config/发布态 config、runtime run start / finish、score record、leaderboard entry、work stats projection、personal summary projection、`migration.rs` 与绑定生成。
-3. 最小前端纵切：接创作入口、单页轻配置表单、发布到稳定 workId、作品详情 CTA、runtime 拉 config、start / finish 串通、结算展示 `serverResult`。
+3. 最小前端纵切：接创作入口、创作 Tab 内嵌轻配置表单、发布到稳定 workId、作品详情 CTA、runtime 拉 config、start / finish 串通、结算展示 `serverResult`。
 4. 投影与列表体验：接排行榜、个人历史最近记录 + 最佳摘要、作品统计、我的作品/广场卡片适配。
 5. 收口验证：把 BDD 场景落到测试，执行编码检查、后端 `/healthz` + API smoke、前端人工验收路径，并更新 README/文档。

--- a/docs/technical/CREATION_WORK_SHELF_UNIFICATION_2026-04-25.md
+++ b/docs/technical/CREATION_WORK_SHELF_UNIFICATION_2026-04-25.md
@@ -55,3 +55,4 @@
 3. 兜底背景底色跟随百梦浅粉、暖白和珊瑚色调，不能继续使用深黑或暗蓝渐变作为草稿卡默认视觉。
 4. 拼图作品列表摘要必须下发 `levels`，草稿页优先用关卡 `coverImageSrc`，再用选中候选图或最后一张候选图作为真实作品封面兜底。
 5. 抓大鹅作品列表摘要必须保留 `generatedBackgroundAsset` 与 `generatedItemAssets` 中的 `imageObjectKey`、`containerImageObjectKey` 和 `imageViews[].imageObjectKey`；前端拿到 object key 后统一交给 `ResolvedAssetImage` 换签，不能因为缺少公开 URL 而退回黑卡。
+6. `coverImageSrc` 若指向 `/creation-type-references/*`，只能视为玩法参考图兜底，不能当作作品真实封面。草稿页遇到这类值时必须继续向下解析同作品真实素材：拼图优先第一关正式图，再取选中候选图或最后一张候选图；抓大鹅优先 UI 背景图 `backgroundImageSrc/backgroundImageObjectKey/generatedBackgroundAsset.image*`，再取容器图，最后才取物品视角图或物品主图。
--- a/docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md
+++ b/docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md
@@ -27,6 +27,8 @@
 5. 生成成功后自动进入 `match3d-result`。
 6. 生成失败时停留在生成过程页，允许重新生成或返回创作中心；重新生成必须复用同一个 session / profile，并从缺失的素材阶段继续，不新建第二份草稿。

+抓大鹅生成过程页不展示“当前批次”模块；移动端只保留“预计等待”和“计时”两张状态卡并排展示，步骤卡进入页面时按顺序从屏幕左侧滑入。
+
 生成页步骤固定为：

 ```text
@@ -52,9 +54,9 @@
 7. 后端从同一份作品生成计划读取当前难度所需数量的短物品名称，并兼容保存历史 `soundPrompt` 字段；当前不生成点击音效。
 8. 调用 VectorEngine Gemini 原生图片接口生成 `1:1` 素材图，请求模型固定为 `gemini-3-pro-image-preview`，走 `POST {VECTOR_ENGINE_BASE_URL}/v1beta/models/gemini-3-pro-image-preview:generateContent?key={VECTOR_ENGINE_API_KEY}`。请求体使用 `contents[].parts[].text` 和 `generationConfig.responseModalities = ["TEXT", "IMAGE"]`、`generationConfig.imageConfig.aspectRatio = "1:1"`，响应从 `candidates[].content.parts[].inlineData.data` / `inline_data.data` 读取 base64 图片。提示词必须合入入口页选择的 `assetStylePrompt`，并强制每格使用统一纯绿色绿幕背景，避免白底或纹理背景进入运行态素材。该调整只作用于抓大鹅物品素材 sheet；封面和 `9:16` 纯背景图继续使用 VectorEngine `/v1/images/generations` 的 `gpt-image-2-all` JSON 链路，`1:1` 容器 UI 图必须使用 VectorEngine `/v1/images/edits` multipart 图生图链路，不能再把参考图作为 generations 的 `image` 数组弱参考。
 9. 每个物品固定需要 `5` 个不同视角。单张素材图固定为 `5*5 = 25` 格，因此单张图承载 `5` 个物品。若用户要求或难度派生的物品种类不是 `5` 的倍数，后端必须向上补齐物品名称和对应图片到最近的 `5` 的倍数；例如标准难度需要 `9` 种玩法物品，实际生成 `10` 个物品名称和对应五视角图片。若草稿物品数超过 `5`，后端按每批 `5` 个物品自动分批，多张素材图并行生成。
-10. 将每张素材图按固定 `5 行 * 5 列` 切割成独立图片，并按物品顺序连续分配 `5` 张视角图。素材图提示词必须要求 `5*5` 严格均匀排布、每格主体完整居中、统一纯绿色绿幕背景、相邻物体主体至少保留 `1/4` 单格宽度空白间距、不得跨格、贴边或越界，避免裁剪后相邻格内容污染。切割前必须先在整张素材图上做透明背景后处理：连通到 sheet 外边缘的绿幕/近白底要清成 alpha；每格内部未连到外边缘但高置信的纯绿绿幕块也必须清成 alpha；物品边缘的绿幕抗锯齿和近白白边要做透明或去污染处理；不够纯的绿色主体像素不得被当作绿幕误删。随后再在每个理论格子内按透明背景/前景像素做内容边界校准，并带少量安全留白导出；不能做固定内缩裁剪，避免贴近格线但未跨格的樱桃、叶片、把手等主体边缘被切掉。每个物品 JSON 写入 `imageViews[]`，同时把第一个视角兼容写入 `imageSrc/imageObjectKey`。
+10. 将每张素材图按固定 `5 行 * 5 列` 切割成独立图片，并按物品顺序连续分配 `5` 张视角图。素材图提示词必须要求 `5*5` 严格均匀排布、每格主体完整居中、统一纯绿色绿幕背景、相邻物体主体至少保留 `1/4` 单格宽度空白间距、不得跨格、贴边或越界，避免裁剪后相邻格内容污染。切割前必须先在整张素材图上做透明背景后处理：连通到 sheet 外边缘的绿幕/近白底要清成 alpha；每格内部未连到外边缘但高置信的纯绿绿幕块也必须清成 alpha；物品边缘的绿幕抗锯齿和近白白边要做透明或去污染处理；较厚的半透明或混色软绿边必须沿整张 sheet 透明背景继续清理，不能先裁剪单格再各自去绿，否则裁剪图会残留绿色描边；不够纯的绿色主体像素不得被当作绿幕误删。随后再在每个理论格子内按透明背景/前景像素做内容边界校准，并带少量安全留白导出；不能做固定内缩裁剪，避免贴近格线但未跨格的樱桃、叶片、把手等主体边缘被切掉。每个物品 JSON 写入 `imageViews[]`，同时把第一个视角兼容写入 `imageSrc/imageObjectKey`。
 11. 将素材图和每张独立视角图片上传到 OSS。每次获得可恢复的图片资产后，都要回写 `match3d_work_profile.generated_item_assets_json`。成功素材状态为 `image_ready`；失败素材保留已成功图片引用并记录 `error`。每个素材 JSON 可继续保存历史 `soundPrompt`；不再写入新的 `backgroundMusicTitle/backgroundMusicStyle/backgroundMusicPrompt`。
-12. UI 背景生成由 `api-server` 分成两张资产：第一张是 `9:16` 纯背景图，走 VectorEngine `/v1/images/generations` 的 `gpt-image-2-all` JSON 请求，不传锅参考图，且必须禁止锅、圆盘、托盘、拼图槽、物品槽、HUD、文字、按钮、倒计时、分数和物品；第二张是 `1:1` 题材容器 UI 图，走 VectorEngine `/v1/images/edits` multipart 请求，把 `public/match3d-background-references/pot-fused-reference.png` 作为 `image` part 上传，只生成一个贴合题材设定的圆形或浅盘状竞技容器，不生成整页背景、文字、按钮或物品。容器图必须沿用参考图的大尺寸轻俯视构图：外轮廓接近画布四边，宽度约占 `86%-92%`、高度约占 `82%-90%`，内口为横向椭圆，禁止生成小容器、正俯视圆盘、侧视碗、餐盘或小托盘。纯背景上传到 `generated-match3d-assets/{sessionId}/{profileId}/background/{taskId}/background.png`，容器 UI 图上传到 `generated-match3d-assets/{sessionId}/{profileId}/ui-container/{taskId}/container.png`，两者都作为 `backgroundAsset` 挂在首个 `generatedItemAssets[]` JSON 上；HTTP DTO 同时顶层输出兼容的 `backgroundPrompt`、`backgroundImageSrc`、`backgroundImageObjectKey` 与 `generatedBackgroundAsset`，容器图通过 `generatedBackgroundAsset.containerImageSrc/containerImageObjectKey` 返回。若作品尚无用户自定义封面，草稿生成完成后默认把容器 UI 图写入 `coverImageSrc`，作为草稿架和作品信息的默认封面。
+12. UI 背景生成由 `api-server` 分成两张资产：第一张是 `9:16` 纯背景图，走 VectorEngine `/v1/images/generations` 的 `gpt-image-2-all` JSON 请求，不传锅参考图，且必须禁止锅、圆盘、托盘、拼图槽、物品槽、HUD、文字、按钮、倒计时、分数和物品；第二张是 `1:1` 题材容器 UI 图，走 VectorEngine `/v1/images/edits` multipart 请求，把 `public/match3d-background-references/pot-fused-reference.png` 作为 `image` part 上传，只生成一个贴合题材设定的圆形或浅盘状竞技容器，不生成整页背景、文字、按钮或物品。容器图必须沿用参考图的大尺寸轻俯视构图：外轮廓接近画布四边，宽度约占 `86%-92%`、高度约占 `82%-90%`，内口为横向椭圆，禁止生成小容器、正俯视圆盘、侧视碗、餐盘或小托盘。容器图入库前必须统一转成带透明 alpha 的 PNG；若上游返回白底、浅色底或抗锯齿底色，`api-server` 在上传 OSS 前清成透明背景。纯背景上传到 `generated-match3d-assets/{sessionId}/{profileId}/background/{taskId}/background.png`，容器 UI 图上传到 `generated-match3d-assets/{sessionId}/{profileId}/ui-container/{taskId}/container.png`，两者都作为 `backgroundAsset` 挂在首个 `generatedItemAssets[]` JSON 上；HTTP DTO 同时顶层输出兼容的 `backgroundPrompt`、`backgroundImageSrc`、`backgroundImageObjectKey` 与 `generatedBackgroundAsset`，容器图通过 `generatedBackgroundAsset.containerImageSrc/containerImageObjectKey` 返回。若作品尚无用户自定义封面，草稿生成完成后默认把容器 UI 图写入 `coverImageSrc`，作为草稿架和作品信息的默认封面；草稿架封面解析也应优先使用容器图，其次才是纯背景图和物品图，完全缺失生成图时使用透明参考容器图兜底。
 13. 在 HTTP 返回的 draft/profile DTO 中附带本次生成的素材资产预览信息、背景资产信息和默认封面；后续重进草稿页时从 work profile 的持久化 `generatedItemAssets` 与 `coverImageSrc` 恢复同一批素材、UI 与封面。历史音频字段只做兼容传递。

 若文本模型不可用或返回无法解析，后端必须降级为 `{themeText}抓大鹅`、本地作品描述与本地标签兜底，不阻断素材生成；标签仍通过作品标签生成器优先生成，失败后再用兜底标签补齐。
@@ -100,7 +102,7 @@ public/match3d-style-references/painterly-icon.png
 public/match3d-background-references/pot-fused-reference.png
 ```

-这张图只作为容器 UI 图的 VectorEngine `/v1/images/edits` multipart `image` part，用来锁定“大尺寸轻俯视浅盘容器”的构图。参考图本身是 `1:1` 透明底容器素材，外轮廓接近画布四边，内口为横向椭圆；结果页没有真实生成容器时也只把它作为容器预览兜底，不能再作为 `9:16` 背景预览。每次草稿生成仍会根据 `backgroundPrompt` 生成新的题材化纯背景图；纯背景图不再传入该参考图，也不得生成锅或 UI 元素。
+这张图只作为容器 UI 图的 VectorEngine `/v1/images/edits` multipart `image` part，用来锁定“大尺寸轻俯视浅盘容器”的构图。参考图本身是 `1:1` 透明底容器素材，外轮廓接近画布四边，内口为横向椭圆；结果页、草稿预览和运行态没有真实生成容器时都把它作为容器兜底，不能再作为 `9:16` 背景预览。每次草稿生成仍会根据 `backgroundPrompt` 生成新的题材化纯背景图；纯背景图不再传入该参考图，也不得生成锅或 UI 元素。

 ## 5. OSS 路径

@@ -140,7 +142,7 @@ Match3DWorkProfile / PlatformMatch3DGalleryCard

 运行态按运行快照中的 `itemTypeId` 稳定排序后，把 `generatedItemAssets` 顺序映射到对应类型。加载某个物品实例时，从该类型素材的 `imageViews[]` 中按实例 id 稳定随机选择一个视角；若历史数据没有 `imageViews[]`，则回退到 `imageSrc/imageObjectKey`。没有生成图片或图片加载失败时，继续使用默认积木图标兜底。

-运行态背景优先读取 `backgroundImageSrc` / 顶层 `generatedBackgroundAsset.imageSrc/imageObjectKey`，为空时从 `generatedItemAssets[].backgroundAsset.imageSrc/imageObjectKey` 兜底。中心容器优先读取顶层 `generatedBackgroundAsset.containerImageSrc/containerImageObjectKey`，再读取 `generatedItemAssets[].backgroundAsset.containerImageSrc/containerImageObjectKey`；为空或换签/图片加载失败时继续使用默认圆形容器样式。容器图成功加载后，`Match3DRuntimeShell` 的棋盘容器必须切换为透明、可溢出承载，不再叠加默认 `rounded-full` 圆形锅壳、金色边框和默认径向背景，避免 AI 生成的大尺寸轻俯视容器被裁切或被默认锅视觉覆盖。运行态入口判断是否需要补读作品详情时，只能把 `imageViews[]` 或 `imageSrc/imageObjectKey` 视为“已有物品图片素材”；`backgroundMusic.audioSrc`、`clickSound.audioSrc`、`generatedBackgroundAsset`、`backgroundAsset.image*` 和 `backgroundAsset.containerImage*` 是随物品素材一起传入的附属运行态资产，不能单独证明物品素材已完整。也不能继续只用历史 `modelSrc/modelObjectKey` 判断，否则新 2D 草稿会在试玩或推荐流中被当成“无素材”并回退默认积木。`Match3DRuntimeShell` 只保留顶部返回、倒计时、重开三个控件；这些顶部控件和底部备选栏统一使用题材无关的半透明玻璃组件样式，不能随背景题材改成木质、金属、果园、科幻等主题皮肤，也不能重新烘进 AI 背景图。进度、组数、版本等状态信息不得再作为顶部常驻 UI 出现，避免遮挡生成背景和中心容器。
+运行态背景优先读取 `backgroundImageSrc` / 顶层 `generatedBackgroundAsset.imageSrc/imageObjectKey`，为空时从 `generatedItemAssets[].backgroundAsset.imageSrc/imageObjectKey` 兜底。中心容器优先读取顶层 `generatedBackgroundAsset.containerImageSrc/containerImageObjectKey`，再读取 `generatedItemAssets[].backgroundAsset.containerImageSrc/containerImageObjectKey`；为空或换签/图片加载失败时使用 `public/match3d-background-references/pot-fused-reference.png` 作为透明容器图兜底，不再回退到默认圆形锅壳。容器图成功加载后，`Match3DRuntimeShell` 的棋盘容器必须切换为透明、可溢出承载，不再叠加默认 `rounded-full` 圆形锅壳、金色边框和默认径向背景，避免 AI 生成的大尺寸轻俯视容器被裁切或被默认锅视觉覆盖。移动端棋盘宽度应接近屏幕宽度并居中，容器图片允许略超出棋盘承载盒以保留大尺寸浅盘轮廓。运行态入口判断是否需要补读作品详情时，只能把 `imageViews[]` 或 `imageSrc/imageObjectKey` 视为“已有物品图片素材”；`backgroundMusic.audioSrc`、`clickSound.audioSrc`、`generatedBackgroundAsset`、`backgroundAsset.image*` 和 `backgroundAsset.containerImage*` 是随物品素材一起传入的附属运行态资产，不能单独证明物品素材已完整。也不能继续只用历史 `modelSrc/modelObjectKey` 判断，否则新 2D 草稿会在试玩或推荐流中被当成“无素材”并回退默认积木。`Match3DRuntimeShell` 只保留顶部返回、倒计时、重开三个控件；这些顶部控件和底部备选栏统一使用题材无关的半透明玻璃组件样式，不能随背景题材改成木质、金属、果园、科幻等主题皮肤，也不能重新烘进 AI 背景图。进度、组数、版本等状态信息不得再作为顶部常驻 UI 出现，避免遮挡生成背景和中心容器。

 前端加载规则：

@@ -184,7 +186,7 @@ Match3DWorkProfile / PlatformMatch3DGalleryCard
 1. `作品名称` 对应 Match3D `gameName`。
 2. `作品描述` 对应 Match3D `summary`，草稿生成阶段由同一次作品生成计划自动填入。
 3. `作品标签` 对应 Match3D `tags`，草稿生成阶段在写入名称和描述后自动调用标签生成器填入；结果页仍允许用户继续编辑或再次 AI 生成。
-4. 封面图与作品名称不再拆成左右两个大模块；封面只作为同一 Tab 内的可选入口，避免和作品基础信息割裂。旧称“碰面图”统一改为“封面图”。草稿生成默认使用生成出的中心容器 UI 图作为 `coverImageSrc`。点击封面图必须弹出独立编辑面板，不允许在当前作品信息面板下方展开。封面面板布局对齐拼图创作页上传卡：移动端优先，左侧/上方为方形预览卡，预览卡本身就是上传热区；上传图片后，预览卡内出现和拼图入口一致的 `AI重绘` 开关与删除按钮，面板底部不再额外展示旧 `AI重绘` 选项。已有上传图时，右侧/下方输入框标题为 `AI重绘要求`；关闭 AI 重绘时只把上传图 Data URL 写入封面字段，不调用生图模型。没有上传图时，输入框标题为 `封面描述`，可选择多张参考图后调用 VectorEngine `gpt-image-2-all` 文生图链路，参考图通过请求体 `image` 数组传入；参考图来源支持直接引用 `物品素材` / `UI素材` 中已有图片，也支持自定义上传。上传图 AI 重绘与无上传图多参考图生成都通过 `api-server` 的 Match3D 作品封面生成接口完成，生成结果转存到 `generated-match3d-assets/{sessionId}/{profileId}/cover/{taskId}/cover.png` 后再写回 `coverImageSrc`。
+4. 封面图修改归入发布面板，不再作为 `作品信息` Tab 内的独立入口。结果页底部 `发布` 按钮对齐拼图：非忙碌态始终可点击，点击后打开独立 `发布抓大鹅作品` 面板；面板上方集中展示发布检查和阻断项，面板内承载封面编辑，满足门槛后再点击 `发布到广场`。旧称“碰面图”统一改为“封面图”。草稿生成默认使用生成出的中心容器 UI 图作为 `coverImageSrc`。封面编辑布局对齐拼图创作页上传卡：移动端优先，左侧/上方为方形预览卡，预览卡本身就是上传热区；上传图片后，预览卡内出现和拼图入口一致的 `AI重绘` 开关与删除按钮，面板底部不再额外展示旧 `AI重绘` 选项。已有上传图时，右侧/下方输入框标题为 `AI重绘要求`；关闭 AI 重绘时只把上传图 Data URL 写入封面字段，不调用生图模型。没有上传图时，输入框标题为 `封面描述`，可选择多张参考图后调用 VectorEngine `gpt-image-2-all` 文生图链路，参考图通过请求体 `image` 数组传入；参考图来源支持直接引用 `物品素材` / `UI素材` 中已有图片，也支持自定义上传。上传图 AI 重绘与无上传图多参考图生成都通过 `api-server` 的 Match3D 作品封面生成接口完成，生成结果转存到 `generated-match3d-assets/{sessionId}/{profileId}/cover/{taskId}/cover.png` 后只写回 `coverImageSrc` / `coverAssetId` 相关字段。封面生成或上传后发布面板保持打开，方便继续完成发布。封面生成接口不得复用草稿编译流程，不得重算题材、难度、消除次数或 `generated_item_assets_json`；前端收到封面生成回包时也只能把 `coverImageSrc` 合并到当前结果页 profile，不能用回包中的旧 `generatedItemAssets`、`clearCount` 或 `difficulty` 覆盖当前页面状态。

 结果页 `难度配置` Tab 取代旧 `玩法配置`，不再展示旧的分散输入项。该 Tab 顶部使用横向离散拖动条调整难度，四个刻度分别为 `轻松 / 标准 / 进阶 / 硬核`；拖动条只能落在这四个点上，刻度标签可点击切换。该 Tab 必须与创作入口页使用同一组难度选项，并统一把原“类型素材图片 / 局内类型”等口径归一为 `物品种类`：

@@ -211,7 +213,7 @@ Match3DWorkProfile / PlatformMatch3DGalleryCard
 2. 素材名称输入。
 3. 不展示点击音效提示词输入或点击音效生成入口。

-五视角预览区采用“上方大预览 + 底部缩略图栏”的布局：上方是方形焦点预览区，中间横向排列当前物品的各视角图片，并用内框标出当前焦点；底部缩略图栏固定露出 `4` 个方形槽位，多出的第 `5` 个视角通过横向滚动访问。点击缩略图只切换焦点视角，不在面板内新增说明文案或额外规则区。
+五视角预览区采用“上方大预览 + 底部缩略图栏”的布局：上方方形焦点预览区只显示当前选中的单张大图，用于详细查看物品形象，图片在方格内放大显示，不再渲染素材自带缩略图框、焦点内框或横向五图带；底部缩略图栏固定露出 `4` 个方形槽位，多出的第 `5` 个视角通过横向滚动访问。点击缩略图只切换焦点视角，不在面板内新增说明文案或额外规则区。

 详情页不再展示参考图、用途、模型提示词、文生/图生切换、状态查询、下载列表、taskUuid 或 subscriptionKey。

--- a/docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md
+++ b/docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md
@@ -29,7 +29,7 @@
 | AIRP | 是 | 否 | 保留入口，显示敬请期待 |
 | 视觉小说 | 是 | 否 | 保留入口，显示敬请期待，暂不允许创建视觉小说草稿 |
 | 智能创作 | 否 | 是 | 入口隐藏，既有 `creative-agent` 链路保留 |
-| 汪汪声浪 | 是 | 是 | `bark-battle` 正式轻创作入口，进入单页配置表单并发布后启动声控对战 runtime |
+| 汪汪声浪 | 是 | 是 | `bark-battle` 正式轻创作入口，选中模板后直接在创作 Tab 内嵌轻配置表单，发布后启动声控对战 runtime |
 | 宝贝识物 | 是 | 是 | 寓教于乐首关模板，必须由 `creation_entry_type_config` 默认种子或后台入口开关保持存在 |

 ## 排障约束
@@ -53,5 +53,6 @@
 3. 未开放玩法点击态保持禁用，不应进入鉴权或创建会话链路。
 4. 已开放玩法点击后必须进入对应创建链路；若用户未登录，先走登录保护。
 5. 创作 Tab 首屏应显示“10分钟创作一个精品互动玩法”，并默认展示拼图创作表单。
-6. 智能创作入口隐藏后，不应出现“Hi, 朋友”“问一问陶泥儿”或“一句话生成闪应用”等旧首页入口。
-7. 方洞挑战入口隐藏后，不应出现在创作 Tab 模板入口、创作中心顶部卡带、平台创作类型弹层和创作页作品架中；既有 `SH-` 作品号、广场详情和试玩 runtime 链路不因此删除。
+6. 汪汪声浪、拼图和抓大鹅都应在创作 Tab 的模板条下方内嵌展示对应创作表单；汪汪声浪不得再跳到独立配置阶段或弹出整页配置页面。
+7. 智能创作入口隐藏后，不应出现“Hi, 朋友”“问一问陶泥儿”或“一句话生成闪应用”等旧首页入口。
+8. 方洞挑战入口隐藏后，不应出现在创作 Tab 模板入口、创作中心顶部卡带、平台创作类型弹层和创作页作品架中；既有 `SH-` 作品号、广场详情和试玩 runtime 链路不因此删除。
--- a/docs/technical/PLATFORM_MOBILE_RECOMMEND_CARD_SAFE_SWIPE_LAYOUT_2026-05-12.md
+++ b/docs/technical/PLATFORM_MOBILE_RECOMMEND_CARD_SAFE_SWIPE_LAYOUT_2026-05-12.md
@@ -11,6 +11,7 @@
 3. 推荐页运行态画面保持独立可交互区域，不挂平台切换作品的 pointer 手势。
 4. 切换作品的纵向手势只绑定在卡片底部作品信息区；底部信息区可以扩大触控高度，但不得绝对定位覆盖运行态画面。
 5. 点赞、分享、改造按钮继续阻止 pointer 事件冒泡，避免按钮点击误触发切换作品。
+6. 作品信息区默认只保留紧凑一行身份和一组操作按钮，底部热区不再占用过高固定高度，避免挤压运行态画面。

 ## 验收

@@ -19,3 +20,4 @@
 3. 在作品运行态画面内点击、拖拽或滑动，只触发作品自身交互。
 4. 在底部作品信息区上下滑动，可以切换推荐作品。
 5. 点赞、分享、改造按钮可正常点击，不触发作品切换。
+6. 推荐卡片的视觉主体高度应明显高于底部信息区，且信息区不应明显压缩首屏运行态。
--- a/docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md
+++ b/docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md
@@ -66,7 +66,7 @@
 ```text
 VECTOR_ENGINE_BASE_URL="https://api.vectorengine.ai"
 VECTOR_ENGINE_API_KEY="YOUR_VECTOR_ENGINE_API_KEY"
-VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=180000
+VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=1000000
 ```

 `VECTOR_ENGINE_API_KEY` 只能存在于本地或部署环境，不写入 Git 跟踪文件。若缺少 key，后端返回服务不可用错误，前端展示现有错误面板。
--- a/docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md
+++ b/docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md
@@ -4,7 +4,7 @@

 拼图创作入口不再使用 Agent 对话收集题材锚点。新流程让玩家填写作品名称、作品描述、画面描述三类信息，其中画面描述只服务首关画面生成与关卡画面语义，不再作为作品详情页的作品描述。画面描述支持上传参考图。玩家确认后直接进入草稿生成进度页，后续草稿生成、首图生成、正式图选择、结果页编辑和发布沿用现有后端编排。

-2026-05-03 后入口进一步收口为画面描述直创：入口表单只保留画面描述、参考图和图片模型选择；作品名称、作品描述、作品标签全部进入结果页补全。若本文件早期段落仍提到入口必填作品名称或作品描述，以 `PUZZLE_PICTURE_ONLY_CREATION_AND_AI_TAGS_2026-05-03.md` 为准。
+2026-05-03 后入口进一步收口为画面描述直创：入口表单只保留画面描述、参考图和图片模型选择；作品名称、作品描述、作品标签由草稿生成阶段默认补齐，并继续允许玩家在结果页编辑。若本文件早期段落仍提到入口必填作品名称或作品描述，以 `PUZZLE_PICTURE_ONLY_CREATION_AND_AI_TAGS_2026-05-03.md` 为准。

 ## 首访新手引导隐藏

@@ -18,9 +18,13 @@

 1. 入口表单只展示 `画面描述`、参考图和图片模型选择；`画面描述` 是唯一必填字段。
 2. 表单自动保存只保存 `pictureDescription`，不再保存入口作品名称、作品描述或推断标签。
-3. 点击“生成草稿”后进入生成进度页，步骤固定对齐后端当前编排：“编译首关草稿 -> 生成关卡名称与 UI 背景提示词 / 生成首关画面 -> 生成UI背景 -> 写入正式草稿”。其中关卡名称文本生成、UI 背景提示词生成与首关画面生成可并行；首关最终名称确定后生成 UI 背景。背景音乐生成已于 2026-05-14 临时关闭。
+3. 点击“生成草稿”后进入生成进度页，步骤固定对齐后端当前编排：“编译首关草稿 -> 生成关卡名称、作品描述、6 个作品标签与 UI 背景提示词 / 生成首关画面 -> 生成UI背景 -> 写入正式草稿”。其中关卡名称文本生成、作品元信息生成、UI 背景提示词生成与首关画面生成可并行；首关最终名称确定后生成 UI 背景。背景音乐生成已于 2026-05-14 临时关闭。
 4. 生成进度页“当前拼图信息”只展示画面描述；不得展示空作品名称、空作品描述或旧五锚点结构。
-5. 结果页打开后，作品名称默认使用首关名称，作品描述与作品标签保持为空，等待用户在作品信息 Tab 补全或触发 AI 标签生成。
+5. 生成进度页不展示“当前批次”模块；移动端只保留“预计等待”和“计时”两张状态卡并排展示，步骤卡进入页面时按顺序从屏幕左侧滑入。
+6. 结果页打开后，作品名称默认使用首关名称，作品描述默认使用首关命名请求返回的 `workDescription`，作品标签默认使用同次请求返回的 6 个 `workTags`。若模型不可用或返回非法字段，才保留空描述 / 空标签，等待用户在作品信息 Tab 补全或触发 AI 标签生成。
+7. 入口存在两类图片输入：左侧 `拼图画面` 是主图上传入口，仍按现有正方形裁剪和 `aiRedraw` 逻辑生成或直接使用；当未上传主图时，`画面描述` 输入框右下角展示 `上传参考图` icon，可一次选择多张参考图，最多 5 张。
+8. 参考图上传后只以小缩略图展示在画面描述框下方，点击缩略图放大预览；每张缩略图可单独移除。上传主图后隐藏这组描述参考图，避免主图与参考图职责混淆。
+9. 前端提交 `referenceImageSrcs` 数组；api-server 兼容旧 `referenceImageSrc` 单图字段，并把旧单图和新数组去重后最多保留 5 张。当前拼图 VectorEngine 图生图链路仍只使用第一张有效参考图作为实际编辑参考图，数组字段用于入口体验和后续多参考图生成能力扩展。

 ### 2026-04-30 初始表单草稿保存补充

@@ -90,18 +94,19 @@
 12. `compile_puzzle_draft` 中的图片上游失败不得映射成 `400 BAD_REQUEST`。DashScope 返回 `InvalidParameter` 或任务失败时，api-server 统一按 `502 UPSTREAM_ERROR` 暴露，并在 `details.message` 中保留“拼图图片生成失败：...”的业务原因，避免生成页只显示“请求参数不合法”。
 13. `compile_puzzle_draft` 前置泥点预扣失败不得映射成 `400 BAD_REQUEST`。余额不足返回 `409 CONFLICT`，SpacetimeDB procedure 不可用、绑定不匹配、钱包服务异常等统一按 `502 UPSTREAM_ERROR` 暴露，并在 `details.message` 中保留真实钱包错误。
 14. 生成拼图作品草稿动作涉及的表单 seed prompt 与首图 prompt 来源选择统一收口在 `server-rs/crates/api-server/src/prompt/puzzle/draft.rs`；`puzzle.rs` 只负责调用 SpacetimeDB、计费、图片服务和持久化，不再直接拼草稿 prompt 文本。
-15. `compile_puzzle_draft_with_initial_cover` 中，首关文本名称生成与首关图片生成互不等待：首图 prompt 只读取画面描述，OSS 临时路径使用已有名或确定性兜底名；同一次首关命名 LLM 请求必须返回 `levelName` 与 `uiBackgroundPrompt`，首图返回后再用图片语义尝试精修最终关卡名与 UI 背景提示词。最终关卡名确定后，必须继续用 AI 返回的 `uiBackgroundPrompt` 生成首关 UI 背景图；若命名模型未返回可用提示词，才按作品、关卡和标签拼接确定性兜底提示词。写入正式草稿前校验 `levels[0].uiBackgroundImageSrc/uiBackgroundImageObjectKey` 不为空；UI 背景失败时 `compile_puzzle_draft` 返回上游错误，生成页停留失败态。背景音乐生成临时关闭，不再作为草稿完成门槛。
+15. `compile_puzzle_draft_with_initial_cover` 中，首关文本名称生成与首关图片生成互不等待：首图 prompt 只读取画面描述，OSS 临时路径使用已有名或确定性兜底名；同一次首关命名 LLM 请求必须返回 `levelName`、`workDescription`、6 个 `workTags` 与 `uiBackgroundPrompt`，首图返回后再用图片语义尝试精修最终关卡名、作品元信息与 UI 背景提示词。解析层必须拒绝 `levelNam`、`levelName` 这类字段名片段被当成关卡名。最终关卡名确定后，必须继续用 AI 返回的 `uiBackgroundPrompt` 生成首关 UI 背景图；若命名模型未返回可用提示词，才按作品、关卡和标签拼接确定性兜底提示词。写入正式草稿前校验 `levels[0].uiBackgroundImageSrc/uiBackgroundImageObjectKey` 不为空；UI 背景失败时 `compile_puzzle_draft` 返回上游错误，生成页停留失败态。背景音乐生成临时关闭，不再作为草稿完成门槛。
 16. `compile_puzzle_draft_with_uploaded_cover` 中，上传图解析后，文本名称生成、图片语义名称生成和上传图转存 OSS 可并行；上传图转存失败必须立即返回，不得继续触发 UI 背景生成。上传图转存成功且最终关卡名确定后，同样必须生成并校验首关 UI 背景图。自动草稿阶段不再触发音乐资产生成。
+17. `CreatePuzzleAgentSessionRequest` 与 `ExecutePuzzleAgentActionRequest` 兼容新增 `referenceImageSrcs: string[]`。`aiRedraw = true` 且未上传主图时，api-server 从 `referenceImageSrc` 与 `referenceImageSrcs` 中按顺序取第一张有效参考图进入现有图生图分支；`aiRedraw = false` 时仍必须依赖 `referenceImageSrc` 主图，不能用描述参考图绕过主图上传。

 ## 结果页

 拼图草稿结果页分为三个一级 Tab：

-1. 拼图关卡列表：默认展示草稿生成出的第一关。列表项参考 RPG 草稿卡片样式，显示画面图、关卡名称和轻量状态。支持新增关卡、删除关卡。点击列表项进入独立关卡详情页，不在列表项下方展开。关卡详情页可编辑关卡名称、画面描述、生成或重新生成画面，并在已有正式图后支持关卡测试。
-2. 作品信息：展示并编辑作品名称、作品描述、作品标签。
+1. 作品信息：默认打开，展示并编辑作品名称、作品描述、作品标签。
+2. 拼图关卡列表：展示草稿生成出的第一关。列表项参考 RPG 草稿卡片样式，显示画面图、关卡名称和轻量状态。支持新增关卡、删除关卡。点击列表项进入独立关卡详情页，不在列表项下方展开。关卡详情页可编辑关卡名称、画面描述、生成或重新生成画面，并在已有正式图后支持关卡测试。
 3. 素材配置：对齐抓大鹅草稿页结构，当前只包含 `UI` 子 Tab；`背景音乐` 子 Tab 已临时隐藏。

-`素材配置 > UI` 展示并编辑拼图运行态 UI 背景提示词。`compile_puzzle_draft` 草稿编译完成首图后，`api-server` 会优先使用首关命名 LLM 同次返回的 `uiBackgroundPrompt` 自动生成首关 9:16 纯背景图；只有模型未返回可用提示词时，才基于作品名称、作品描述、标签和首关信息拼接兜底提示词。结果页继续支持用户修改提示词并通过 `generate_puzzle_ui_background` 重新生成。图片生成调用 VectorEngine `gpt-image-2-all` 的 `9:16` 图片生成链路。生成结果写入首关 `levels_json` 的 `uiBackgroundPrompt`、`uiBackgroundImageSrc`、`uiBackgroundImageObjectKey`，不新增 SpacetimeDB 表字段。
+`素材配置 > UI` 展示并编辑拼图运行态 UI 背景提示词。`compile_puzzle_draft` 草稿编译完成首图后，`api-server` 会优先使用首关命名 LLM 同次返回的 `uiBackgroundPrompt` 自动生成首关 9:16 纯背景图，并用同次返回的 `workDescription` 与 `workTags` 默认填充作品信息。只有模型未返回可用提示词时，才基于作品名称、作品描述、标签和首关信息拼接兜底提示词。结果页继续支持用户修改提示词并通过 `generate_puzzle_ui_background` 重新生成。图片生成调用 VectorEngine `gpt-image-2-all` 的 `9:16` 图片生成链路。生成结果写入首关 `levels_json` 的 `uiBackgroundPrompt`、`uiBackgroundImageSrc`、`uiBackgroundImageObjectKey`，不新增 SpacetimeDB 表字段。

 历史 `levels_json[0].backgroundMusic` 字段继续兼容读取和运行态播放，但结果页暂不提供编辑或生成入口。拼图结果页不再保留一级 `UI` 或一级 `音乐` Tab。

@@ -125,6 +130,12 @@
 3. 自动试玩只在当前仍处于 `puzzle-generating` 时触发；若玩家已返回草稿 Tab 或切到其它页面，后台生成完成只标记草稿已生成，不得强行抢屏进入试玩。
 4. 若自动启动试玩失败，前端保留草稿结果页作为兜底查看入口，并展示已有错误态，不应丢失已生成草稿。

+### 2026-05-14 运行态合并块拖拽补充
+
+1. 合并块拖拽时，真实视觉只由 `mergedGroups` 生成的整体绝对层承载；棋盘格里的单块 DOM 只作为透明定位占位。
+2. 合并格即使在 `pointerdown` 后同步写入了 `selectedPieceId`，也不得应用单块选中填充色，否则整体合并块被拖起后会在原位置露出粉红 / 红色底块。
+3. 单块未合并时仍保留选中态；合并格样式优先级必须高于选中态，回归测试覆盖 `拖拽合并大块时底层单格不显示选中色块`。
+
 ### 2026-04-30 关卡列表卡片交互补充

 1. 关卡列表卡片的删除按钮与关卡名称放在同一信息行，按钮固定在卡片右下角；不得再单独占用一整条底部分隔栏。
@@ -161,7 +172,7 @@
 1. 从拼图创作入口只能看到作品名称、作品描述、画面描述和参考图上传，不出现 Agent 聊天输入、补齐设定、锚点问答。
 2. 点击确认后进入拼图草稿生成进度页，并自动完成草稿编译、首图生成、正式图选择和首关 UI 背景图生成。
 3. 首图生成请求使用玩家画面描述作为 prompt；上传参考图时走图生图；作品详情页展示玩家作品描述。
-4. 结果页包含“拼图关卡”“作品信息”“素材配置”三个一级 Tab；`素材配置` 内当前只包含 `UI` 子 Tab，不展示背景音乐生成入口。关卡列表默认至少一关，支持新增、删除和进入关卡详情。
+4. 结果页一级 Tab 顺序为“作品信息”“拼图关卡”“素材配置”，默认打开“作品信息”；`素材配置` 内当前只包含 `UI` 子 Tab，不展示背景音乐生成入口。关卡列表默认至少一关，支持新增、删除和进入关卡详情。
 5. 关卡详情页支持生成或重新生成画面；已有正式图后显示吸底“关卡测试”入口。
 6. 发布、作品测试、自动保存作品名称、作品描述、作品标签和关卡列表仍可用。
 7. 草稿初次生成后首关默认带 `uiBackgroundImageSrc`；若后端只返回 `uiBackgroundImageObjectKey` 也必须能在结果页、试玩和运行态正常预览；UI Tab 可修改提示词并重新生成背景图；生成后运行态应显示 `uiBackgroundImageSrc` 或换签后的 `uiBackgroundImageObjectKey`，拼图槽位和棋盘边界仍由默认运行态样式绘制。
--- a/docs/technical/PUZZLE_IMAGE_ASSET_PROXY_FIX_2026-04-27.md
+++ b/docs/technical/PUZZLE_IMAGE_ASSET_PROXY_FIX_2026-04-27.md
@@ -2,7 +2,7 @@

 日期：`2026-04-27`

-更新：`2026-05-08`
+更新：`2026-05-14`

 ## 背景

@@ -20,6 +20,7 @@
 4. `refreshKey` 只能用于跳过前端签名 URL 缓存并重新请求 `/api/assets/read-url`，不能再给 OSS V4 签名 URL 追加 `_v` 等额外 query；OSS 会把 query 纳入签名，额外参数会让新生成图变成 403/破图。
 5. 历史素材被选为参考图后，参考图小预览也必须走 `ResolvedAssetImage`，不能使用裸 `<img src="/generated-*">`。
 6. 禁止恢复 `/generated-puzzle-assets/{*path}` Axum 路由或 Vite 直读代理；正式读取统一走 `/api/assets/read-url`。
+7. 历史素材卡片的标题和选中标签只从 `imageSrc` 解析图片文件名；`ownerLabel` 是账号归属信息，不能作为图片名展示。`createdAt` 需要兼容 `1713686400.000000Z` 这类 SpacetimeDB 时间字符串。

 ## 后续约束

--- a/docs/technical/README.md
+++ b/docs/technical/README.md
@@ -4,12 +4,14 @@

 ## 文档列表

+- [【前端体验】图像组件统一封装与复用边界-2026-05-14.md](./【前端体验】图像组件统一封装与复用边界-2026-05-14.md)：冻结创作页统一图像输入面板 `CreativeImageInputPanel` 的受控边界、主图上传、画面描述、多参考图、AI 重绘开关、预览和提交口径，供拼图、抓大鹅封面和后续创作页复用。
 - [WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md](./WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md)：记录微信小程序 `web-view` 壳的最小接入范围、需要填写的 H5 业务域名、微信后台配置、`npm run check:wechat-miniprogram-auth` 可重复登录链路 smoke 和后续原生化边界。
 - [BABY_LOVE_DRAWING_RUNTIME_DEMO_IMPLEMENTATION_2026-05-13.md](./BABY_LOVE_DRAWING_RUNTIME_DEMO_IMPLEMENTATION_2026-05-13.md)：冻结寓教于乐 `宝贝爱画` 独立本地 Demo 运行态实现方案，明确发现页默认卡片、`/runtime/baby-love-drawing` 路由、画板交互、mocap/键鼠调试映射、本地保存和 VectorEngine image-2 绘画魔法后端代理。
 - [BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md](./BARK_BATTLE_BACKEND_DDD_TECHNICAL_PLAN_2026-05-11.md)：冻结“汪汪声浪大作战 / bark-battle”后端 DDD 技术方案，明确 `server-rs + Axum + SpacetimeDB` 分层边界、shared contracts、作品配置、runtime run、派生成绩、排行榜、`work_play_start` 埋点、migration/绑定生成策略，以及不保存原始麦克风音频的隐私与反作弊约束。
 - [BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md](./BARK_BATTLE_2D_RUNTIME_TECHNICAL_PLAN_2026-05-11.md)：冻结“汪汪声浪大作战 / bark-battle”2D 浏览器 runtime 技术方案，明确 Phaser + TypeScript + Vite 选型、纯 TS simulation 与 Phaser renderer/DOM HUD 边界、Web Audio 输入适配、移动端权限降级和后续测试验证命令。
 - [PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md](./PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md)：记录直接访问公开作品详情深链时作品不存在或已下架的回首页修复，避免关闭提示后停在 `work-detail` 空状态白屏。
 - [PLATFORM_MOBILE_RECOMMEND_CARD_SAFE_SWIPE_LAYOUT_2026-05-12.md](./PLATFORM_MOBILE_RECOMMEND_CARD_SAFE_SWIPE_LAYOUT_2026-05-12.md)：冻结移动端推荐页隐藏顶部品牌栏、扩大推荐卡片可用高度，以及只在底部作品信息区承接切换作品手势的布局口径。
+- [【前端体验】移动端输入法不压缩画布聚焦方案-2026-05-14.md](./【前端体验】移动端输入法不压缩画布聚焦方案-2026-05-14.md)：记录移动端输入法弹出时平台画布保持稳定高度，只通过画面位移聚焦当前输入框的实现口径。
 - [BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md](./BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md)：冻结寓教于乐 `宝贝识物` 模板创作发布线程的前端入口、契约、service、结果页、发布标签和后端 image-2 接口预留边界。
 - [CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md](./CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md)：冻结儿童动作识别互动玩法 Demo 固定热身关的开发落地规格，覆盖横屏展示、摄像头背景虚化、角色剪影、绿色圆环 2 秒保持、动作教学、当前会话内空间边界记录和后续关卡安全暂停规则。
 - [RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md](./RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md)：记录运行态输入设备抽象层，明确鼠标、触控、mocap 等设备统一归一为通用拖拽语义，玩法组件只负责解释目标和落点。
--- a/docs/technical/RPG_IMAGE_GENERATION_GPT_IMAGE_2_MIGRATION_2026-05-02.md
+++ b/docs/technical/RPG_IMAGE_GENERATION_GPT_IMAGE_2_MIGRATION_2026-05-02.md
@@ -60,7 +60,7 @@ model = gpt-image-2-all
 ```text
 VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai
 VECTOR_ENGINE_API_KEY=...
-VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=180000
+VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=1000000
 ```

 `VECTOR_ENGINE_API_KEY` 缺失时，角色主图与场景图返回 `SERVICE_UNAVAILABLE`，`details.provider = "vector-engine"`。
--- a/docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md
+++ b/docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md
@@ -89,7 +89,7 @@ VectorEngine 文档要求使用像素尺寸，不再使用 APIMart 的比例写
 ```text
 VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai
 VECTOR_ENGINE_API_KEY=
-VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=180000
+VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=1000000
 ```

 说明：
--- a/docs/technical/【前端体验】图像组件统一封装与复用边界-2026-05-14.md
+++ b/docs/technical/【前端体验】图像组件统一封装与复用边界-2026-05-14.md
@@ -0,0 +1,32 @@
+# 图像组件统一封装与复用边界 2026-05-14
+
+## 背景
+
+拼图创作页、抓大鹅封面页以及后续更多创作页，都需要同一套图像输入能力：未上传图片时可用画面描述生成图片，也可叠加多张参考图；上传图片后可选择重绘或直接使用当前图片。以前这些能力分散在各页内联实现，重复了上传、预览、移除、参考图展示和文案布局。
+
+## 组件边界
+
+1. 图像组件负责统一承载图片上传卡、画面描述输入、参考图入口、参考图缩略图、参考图预览、AI 重绘开关和提交按钮。
+2. 图像组件只做交互与表现层，不决定具体生图接口，也不直接耦合某个玩法的草稿提交逻辑、计费逻辑或历史素材查询逻辑。
+3. 主图读取、裁剪、参考图转 Data URL、历史素材选择、生成请求提交、自动保存和后端契约透传仍由外层页面负责。
+4. 图像组件采用受控模式，外层页面传入当前图片、画面描述、参考图数组、AI 重绘状态和图片模型等业务真相，组件只回调变更与提交动作。
+
+## 统一交互口径
+
+1. 未上传主图时，画面描述输入框右下角显示参考图上传 icon，允许多选，默认最多 5 张。
+2. 参考图只以小缩略图展示，点击缩略图可放大预览，单张可移除。
+3. 主图上传后隐藏这组画面描述参考图入口，避免主图与参考图职责混淆。
+4. 主图存在时，组件显示 AI 重绘开关；关闭后只保留当前图片直接提交的路径，不再展示画面描述输入。
+5. 组件只负责把提交按钮、错误提示、预览弹层和确认弹层组织成统一 UI，具体按钮文案和费用提示由外层页面传入。
+
+## 复用约定
+
+1. 拼图入口先接入该组件，保留画面描述直生图、参考图生图、上传图重绘和不重绘四种路径。
+2. 后续抓大鹅封面、其他创作页和模板页复用时，只替换外层的提交动作、图片模型选择和外部错误来源。
+3. 如未来某页不需要历史素材入口、参考图入口或图片模型选择，应通过 props 关闭，不要复制一套新的图像输入实现。
+
+## 验收
+
+1. 拼图创作页的图像输入模块改为独立组件后，行为与原有页面一致。
+2. 参考图多选、缩略图预览、移除、主图上传、AI 重绘开关和提交按钮行为不退化。
+3. 组件可以在不改内部实现的情况下接入其它页面，只替换外层业务回调和文案。
--- a/docs/technical/【前端体验】移动端输入法不压缩画布聚焦方案-2026-05-14.md
+++ b/docs/technical/【前端体验】移动端输入法不压缩画布聚焦方案-2026-05-14.md
@@ -0,0 +1,22 @@
+# 移动端输入法不压缩画布聚焦方案
+
+## 背景
+
+平台主站采用游戏式固定画布体验，根壳原本优先使用 `100dvh`。手机浏览器弹出输入法时，`dvh` 会跟随可见视口变小，导致上方页面、推荐卡、创作首页和底部输入区一起被压缩，画面层级失真。
+
+用户预期是：点击输入框后，画面本身不要重新压缩排版，只把当前画面位置向输入框聚焦，让输入框避开输入法。
+
+## 落地口径
+
+1. 主站启动时统一调用 `stabilizeMobileViewportKeyboardFocus()`，只在触控或粗指针设备上启用。
+2. `.platform-viewport-shell` 的高度优先读取 `--platform-layout-viewport-height`，该值在输入法未打开时记录稳定布局高度；输入法打开期间不跟随 `visualViewport.height` 缩小。
+3. 输入框聚焦且 `visualViewport` 明显变小时，计算当前输入框与可见视口底部的距离，只通过 `--platform-keyboard-focus-offset` 对平台根壳做 `translateY`。
+4. 输入法打开期间隐藏移动端底部 dock，避免 dock 被整体位移后遮住输入框。
+5. 该方案不新增 UI 说明文案，不改变业务组件结构，也不要求每个输入框单独适配。
+
+## 验收
+
+- 手机竖屏点击创作首页底部输入框时，页面内容不被压缩变矮。
+- 输入框随画面位移出现在输入法上方，可继续输入和发送。
+- 输入法关闭后，平台画布回到原位，底部 dock 恢复显示。
+- 未聚焦输入框时，平台首页仍保持原有移动端 `100dvh` / 固定 dock 行为。