1

docs/experience/MOBILE_UI_DEV_EXPERIENCE.md

@@ -197,3 +197,8 @@
 
 这一轮最关键的经验是：
 **游戏 UI 的移动端优化，本质不是把元素缩小，而是重组视觉重心、固定操作锚点、让焦点内容在一屏内自然成立。**
+
+### 10.1 可扮演角色形象预览保持 1:1
+- 可扮演角色的形象预览容器统一使用 1:1 方形，入口选择轮播、角色资产工坊和结果页角色卡片都不能用纵向长卡片去拉伸预览图。
+- 预览图片本身使用 `object-contain`，保证 AI 生成主形象、模板像素角色和运行时动画都在方形容器内完整显示，不裁切角色主体。
+- 卡片可以在方形预览下方放角色名、称号、状态等信息，但这些文本区不能反向影响预览区比例。

docs/experience/PLAYABLE_ROLE_APPEARANCE_TEMPLATE_FIELD_REMOVAL_2026-04-25.md

@@ -0,0 +1,20 @@
+# 可扮演角色外观模板字段删除经验
+
+## 背景
+
+可扮演角色曾通过 `templateCharacterId` 保存“外观模板”选择。当前角色主形象已经由 `visualDescription`、`imageSrc` 与生成资产链路承接，外观模板不应继续作为可扮演角色档案字段暴露给用户编辑或持久化。
+
+## 落地边界
+
+- 可扮演角色数据结构不再声明 `templateCharacterId`。
+- 可扮演角色编辑面板删除“外观模板”下拉项，保存时不再补默认模板。
+- 草稿规范化与资料库读取时丢弃旧数据中的 `templateCharacterId`，避免旧快照把字段带回新数据。
+- 运行时如需要基础动作、默认立绘或战斗标签，只能通过角色文本、参考 profile 或固定 fallback 规则临时推导模板，不再写回角色字段。
+- 资产工坊可以继续接收运行时临时模板提示，但该提示不得成为可扮演角色的持久字段。
+
+## 验收要点
+
+- 新建或编辑可扮演角色时界面不出现“外观模板”。
+- 保存后的 `playableNpcs` 条目不包含 `templateCharacterId`。
+- 旧存档带有 `templateCharacterId` 时，进入当前规范化链路后会被丢弃。
+- 自定义世界运行角色仍能通过推导模板获得基础动作与默认占位图，不因字段删除而中断。

docs/experience/RPG_DRAFT_IMAGE_PARALLEL_GENERATION_2026-04-24.md

@@ -26,6 +26,7 @@ RPG 草稿生成进入底稿素材阶段后，角色主形象与场景幕背景
 - 幕背景图失败文案必须带第几章、第几幕和幕标题，不能只显示“第1幕 / 第2幕 / 第3幕”，否则多章节同名幕会被用户误认为同一失败项重复上报。
 - 中止或部分失败前必须持久化已经成功生成的部分底稿到会话 `draftProfile`，不能因为某个角色或某一幕失败而丢掉其它已生成的 `imageSrc / generatedVisualAssetId / backgroundImageSrc / backgroundAssetId`。
 - 每一幕自动生图必须记录 operation、session、第几章、第几幕、sceneId、sceneName、attempt、elapsedMs 与供应商真实错误，避免再次出现只看到“生成幕背景图失败”但无法定位哪张图、哪次请求、哪个上游原因的问题。
+- 前端看到 `draft_foundation` operation completed 后，不能只延迟一次就读取 `resultPreview`；SpacetimeDB 写入、API 读模型和前端状态同步之间可能有短暂时差，必须短轮询等待结果页 profile 可用后再自动跳转到草稿页，避免卡在“底稿已整理”。
 - 前端 `CharacterAnimator` 对带 `generatedVisualAssetId` 但尚无 `animationMap` 的自定义角色，所有状态优先渲染生成主图；只有真正发布了动作集后才按动作帧播放，避免运行或战斗状态回落到模板 sprite。
 
 ## 后续注意
@@ -34,3 +35,12 @@ RPG 草稿生成进入底稿素材阶段后，角色主形象与场景幕背景
 
 
 
+
+## 2026-04-25 补充：开局场景也必须逐幕生成背景图
+
+本次排查发现旧草稿合成只从 `landmarks` 编译 `sceneChapterBlueprints`，导致 `camp` 开局场景只有 `camp.imageSrc`，没有进入 `sceneChapterBlueprints[*].acts[*]` 的幕背景生成队列。后续实现必须遵守：
+
+1. `camp` 开局场景必须作为 `sceneChapterBlueprints[0]` 写入，`sceneId` 默认使用 `camp.id`，缺失时使用 `camp-1`。
+2. `camp.actBackgroundPromptTexts` 必须包含 3 条逐幕画面描述，并和普通场景一样生成 `acts[*].backgroundImageSrc`。
+3. 结果页场景目录可用场景图兜底展示旧草稿的幕缩略图，但新草稿不能只依赖兜底，必须让开局场景真实进入幕背景图生成链路。
+4. 手动同步场景资产时，必须同时更新 `sceneChapterBlueprints` 与兼容字段 `sceneChapters`，当前主链以 `sceneChapterBlueprints` 为准。