init with react+axum+spacetimedb

docs/experience/MOBILE_UI_DEV_EXPERIENCE.md

@@ -0,0 +1,218 @@
+# 奇幻酒馆 UI 开发经验沉淀
+
+## 1. 总体原则
+
+### 1.1 先保证移动端成立，再兼容网页端
+- 入口页、世界选择、角色选择、冒险页、弹窗面板，都要先按手机竖屏去定义信息密度。
+- 网页端只做“放宽容器、增加留白、补充 hover”，不要反过来让桌面布局压垮手机体验。
+- 任何区域如果在移动端需要滚动，必须明确谁滚动，不能让整页和局部同时争夺滚动。
+
+### 1.2 游戏 UI 要优先“状态清晰”，而不是“文案很多”
+- 开始页应该像主菜单，不像产品介绍页。
+- 角色选择页应该像角色选择器，不像角色说明书。
+- 冒险页应该像战斗/剧情操作台，不像文档阅读器。
+
+### 1.3 一屏内的层级顺序要稳定
+- 上半部分：画面演出。
+- 中间部分：剧情或核心信息。
+- 底部：操作按钮。
+- 玩家必须能快速判断“我在看什么、下一步点哪里”。
+
+## 2. 入口页经验
+
+### 2.1 开始页
+- 极简化是对的。
+- 当前实践证明：开始页只保留“开始游戏”和“开发团队”两个主按钮，体验明显更像游戏。
+- 游戏名和英文副标题可以保留，但不要再加长段描述。
+
+### 2.2 世界选择
+- 纵向焦点轮播比普通列表更适合移动端。
+- 当前居中的卡片应该最大、最清晰、最亮；上下卡片缩放和透明度随滚动连续变化。
+- 世界确认动作应该绑定当前聚焦卡，而不是每张卡都塞太多按钮。
+
+### 2.3 角色选择
+- 横向轮播是正确方向。
+- 中间卡片应承担“主视觉 + 主要信息”。
+- 左右卡片只做预览，不需要承载完整信息。
+- 左右卡片倾斜方向一定要符合透视直觉：
+  左侧卡片向左外倾，右侧卡片向右外倾。
+- 中间卡片不要出现任何模糊，否则会破坏“当前选中”的确认感。
+
+## 3. 角色选择页经验
+
+### 3.1 聚焦卡的表现
+- 中间聚焦卡用角色 `run` 动画是有效的，能明显提升“角色活着”的感觉。
+- 但动画资源和静态立绘的锚点通常不一致，必须单独做位置与缩放修正。
+- 结论：
+  动画版角色不要直接复用静态图样式，要单独给 `transform`、`height`、`transform-origin`。
+
+### 3.2 信息区要紧凑
+- 角色数值和角色背景应该放在轮播下方，但必须压缩高度。
+- 如果下方面板过高，会直接破坏上半部分轮播体验，尤其在手机上。
+- 删除背景面板里的额外动画模块是正确的，因为它与主轮播重复抢视觉焦点。
+
+### 3.3 文案层级
+- 页面标题只保留一句：
+  “选择你扮演的角色”
+- 不要再强调 `CHARACTER SELECT` 之类的开发向分类标签。
+- 聚焦卡下方直接显示角色名，比把名字只放在卡片底部更直观。
+
+### 3.4 按钮位置
+- “确认选择”必须放在角色轮播和信息区之后，作为页面最后的主动作。
+- 按钮不宜过宽过高，否则会抢轮播的视觉重心。
+
+## 4. 冒险页经验
+
+### 4.1 剧情区必须自适应
+- 剧情文本区不应该写死高度。
+- 正确做法是：
+  让它自动填满“上方画面下缘”和“底部按钮区上缘”之间的剩余空间。
+- 这样才能同时保证：
+  1. 上方画面一屏可见
+  2. 下方三个选项一屏可见
+  3. 中间剧情尽量大
+
+### 4.2 底部操作区必须锚定到底
+- 队伍、背包、换一换、选项列表，都应该属于底部控制区。
+- 用户会天然在屏幕底部寻找交互入口，尤其是手机。
+- 因此：
+  不要把这些按钮漂在中间，不要让剧情区把它们挤走。
+
+### 4.3 队伍与背包不应打断主流程
+- 在冒险页内，队伍和背包更适合“弹出面板”而不是“切换整页”。
+- 原因：
+  1. 不会打断当前剧情阅读
+  2. 用户返回成本更低
+  3. 操作像手游副面板，更符合预期
+
+### 4.4 图标优于文字按钮
+- 在底部工具区，队伍/背包改成 icon 后更紧凑。
+- 但必须保留 `aria-label`，保证语义清晰、后续也方便测试。
+
+### 4.5 冒险主场景不要挂右上角账号悬浮条
+- 冒险页右上角属于画面演出和战斗/剧情信息的高频观察区。
+- 全局账号信息条挂在这里，会直接压住场景、敌人血条或顶部提示，手机端尤其明显。
+- 结论：
+  账号入口应收回平台首页、个人页或设置面板，不要在实际冒险主场景常驻悬浮显示。
+- 当前仓库已进一步收口为：
+  不再提供右上角全局账号悬浮条，统一只保留页面内入口与独立账号面板。
+
+### 4.6 冒险主场景双方角色必须按画面中线镜像
+- 非滚动画面的交谈、预览、单体对峙态，主角和对面角色不能分别用左右边距、世界坐标和角色宽度重复推算。
+- 正确做法是先定义“角色容器中心距离画面中线”的统一间距，再让主角中心落在中线左侧、对面角色中心落在中线右侧。
+- 角色容器宽度、角色图片缩放和左右朝向必须各自独立处理，不能用额外 left inset 去修正角色图片，否则会破坏左右对称。
+- 自定义图片 NPC、模板角色和组合式 NPC 都要进入同一 112px 场景容器，再按各自素材锚点做场景缩放，保证视觉大小不漂移。
+
+## 5. 队伍面板经验
+
+### 5.1 移动端成员列表不能太“卡片化”
+- 如果每个成员都再套一层大边框卡片，手机上会显得很挤。
+- 更好的方式是直接在主面板里陈列成员，弱化分隔、强化内容。
+
+### 5.2 队伍列表展示什么
+- 头像
+- 姓名
+- 称号
+- 身份标记（领队/同行）
+- HP / MP
+
+### 5.3 队伍详情弹窗
+- 弹窗必须可滚动。
+- 弹窗宽度不宜太大，手机优先单列或偏单列。
+- 技能、装备、属性三个区块保持稳定结构，便于扫读。
+
+## 6. 背包页经验
+
+### 6.1 格子数要优先适配手机
+- 手机端格子间距要小一号。
+- 图标尺寸和分类角标要跟着缩小。
+- 目标不是“每个格子信息很多”，而是“单屏能看更多格子”。
+
+### 6.2 背包详情弹窗
+- 手机端改成单列/窄宽度布局更合理。
+- 详情窗里的信息顺序建议固定：
+  1. 名称与类别
+  2. 品质与数量
+  3. 大图标
+  4. 说明
+  5. 标签
+
+## 7. 样式与动画经验
+
+### 7.1 轮播动画要连续，不要离散
+- 滚动时应根据“当前位置与当前卡片中心的距离”实时计算：
+  - `scale`
+  - `opacity`
+  - `rotate`
+  - `translate`
+- 不要做成“翻页后才跳变”的效果。
+
+### 7.2 焦点卡与非焦点卡的职责要不同
+- 焦点卡负责可读性与确认感。
+- 非焦点卡负责预告与空间深度。
+- 所以焦点卡不该模糊，非焦点卡可以轻微降透明度、缩放、偏移。
+
+### 7.3 资源锚点要单独校准
+- 静态立绘和动画帧经常不是同一锚点。
+- 只要切换成动画，就需要重新调：
+  - 高度
+  - Y 偏移
+  - 缩放
+  - `transform-origin`
+
+## 8. 工程经验
+
+### 8.1 组件要继续拆
+- 本轮重构证明，把入口页、冒险页、队伍页、背包页拆成独立组件是正确的。
+- 后续新增 UI 需求时，应优先落在：
+  - `GameShell.tsx`
+  - `AdventurePanel.tsx`
+  - `CharacterPanel.tsx`
+  - `InventoryPanel.tsx`
+
+### 8.2 不要相信“服务已经在跑”
+- 这轮出现过“端口上有进程，但浏览器仍然拿到旧模块”的问题。
+- 实际经验：
+  1. 要检查 `src` 文件内容
+  2. 要检查 dev server 实际返回的模块内容
+  3. 要确认启动脚本是否是当前项目真正使用的脚本
+
+### 8.3 本项目当前开发服务入口
+- 本地正确启动脚本是：
+  `node scripts/vite-cli.mjs --port=3000 --host=0.0.0.0`
+- 历史脚本或旧进程会导致“代码已改但 UI 看起来没变”的假象。
+
+## 9. 后续建议
+
+### 9.1 可以继续统一中英混杂文案
+- 当前部分新旧文本仍有历史遗留字符问题。
+- 如果后面继续做 UI 精修，建议单独做一轮文案清洗。
+
+### 9.2 可以把轮播抽成通用组件
+- 世界纵向焦点轮播
+- 角色横向倾斜轮播
+- 这两套逻辑已经足够稳定，适合后续抽成通用 hook 或通用组件。
+
+### 9.3 可以补移动端安全区适配
+- 当前已经偏移动端优先，但还可以继续加：
+  - `safe-area-inset-bottom`
+  - `safe-area-inset-top`
+  - 更细的竖屏断点处理
+
+## 10. 一句话结论
+
+这一轮最关键的经验是：
+**游戏 UI 的移动端优化，本质不是把元素缩小，而是重组视觉重心、固定操作锚点、让焦点内容在一屏内自然成立。**
+
+### 10.1 可扮演角色形象预览保持 1:1
+- 可扮演角色的形象预览容器统一使用 1:1 方形，入口选择轮播、角色资产工坊和结果页角色卡片都不能用纵向长卡片去拉伸预览图。
+- 预览图片本身使用 `object-contain`，保证 AI 生成主形象、模板像素角色和运行时动画都在方形容器内完整显示，不裁切角色主体。
+- 卡片可以在方形预览下方放角色名、称号、状态等信息，但这些文本区不能反向影响预览区比例。
+- 编辑角色弹窗也遵循同一规则：移动端不能用固定高度压扁预览区，预览容器应随宽度保持 `aspect-square`。
+
+### 10.2 运行画面怪物锚点按视觉底边校准
+- 对战预览里主角和对手要沿画面中线成对出现，但纵向不能只共用一个 `bottom` 常量。
+- 怪物精灵帧的空白、体型和脚底位置差异很大，运行画面应按帧高分档下沉，让怪物视觉底边落在主角同一条地面线上。
+- 后续新增怪物资源时，先检查红圈标注的实际落点，再调整锚点分档或单怪物偏移，避免出现“悬在地面上方”的状态。
+- 自定义世界里敌对角色已经先作为场景 NPC 存在，即使它同时携带 `characterId` 和 `monsterPresetId`，画布也不能直接沿用模板角色的 `groundOffsetY`；只要 encounter 自身有 `imageSrc` 或 `visual`，就按场景 NPC 自定义形象锚点处理。
+- 幕预览运行时还会构造“无 `characterId`、但有 `visual` 的场景 NPC”，这类和平相遇分支同样必须套用场景 NPC 自定义形象锚点，否则会停在画面中上部。