diff --git a/.codex/environments/environment.toml b/.codex/environments/environment.toml index a9070d7d..c12cc7b1 100644 --- a/.codex/environments/environment.toml +++ b/.codex/environments/environment.toml @@ -4,6 +4,14 @@ name = "Genarrative" [setup] script = ''' +cp "$CODEX_SOURCE_TREE_PATH/.env.secrets.local" "$CODEX_WORKTREE_PATH/.env.secrets.local" +npm install +npm run codegraph:init +npm run codegraph:index +''' + +[setup.win32] +script = ''' cp "$env:CODEX_SOURCE_TREE_PATH\.env.secrets.local" "$env:CODEX_WORKTREE_PATH\.env.secrets.local" npm install npm run codegraph:init diff --git a/.env.example b/.env.example index b971f513..2a1b98e2 100644 --- a/.env.example +++ b/.env.example @@ -109,6 +109,8 @@ WECHAT_MOCK_USER_ID="wx-mock-user" WECHAT_MOCK_UNION_ID="wx-mock-union" WECHAT_MOCK_DISPLAY_NAME="微信旅人" WECHAT_MOCK_AVATAR_URL="" +WECHAT_MINIPROGRAM_MESSAGE_TOKEN="" +WECHAT_MINIPROGRAM_MESSAGE_ENCODING_AES_KEY="" # Model name for chat completions. VITE_LLM_MODEL="doubao-1-5-pro-32k-character-250715" diff --git a/.gitignore b/.gitignore index c90efe5c..2885233d 100644 --- a/.gitignore +++ b/.gitignore @@ -34,6 +34,7 @@ temp*build*/ /public/generated-character-drafts /public/generated-characters /.codex-temp +/.app/ /target/ /logs /server-rs/crates/*/logs/ diff --git a/.hermes/shared-memory/decision-log.md b/.hermes/shared-memory/decision-log.md index 93ddf685..2a616fff 100644 --- a/.hermes/shared-memory/decision-log.md +++ b/.hermes/shared-memory/decision-log.md @@ -16,12 +16,86 @@ --- -## 2026-05-27 生成页总进度圆弧锁定固定画布 +## 2026-06-03 最近创作只复用创作模板入口 -- 背景：多轮圆环角度微调后，`GenerationProgressHero` 的 SVG 圆弧仍会出现底部开口偏斜的问题，且圆环还会随着容器宽度伸缩，导致 UI 看起来时大时小、位置漂移。 -- 决策：共用 `GenerationProgressHero` 的 SVG 圆弧起始角固定为 `135deg`，轨道和橘黄色填充都从同一个对称起点 `rotate(135 200 200)` 出发；`270deg` 扫描角配合正下方 `90deg` 留空，圆环本体改为固定 `400x400` 画布，不再跟随页面宽度缩放，外层布局只负责定位，不负责改动圆环样式。 +- 背景：底部加号创作入口的“最近创作”最初由真实作品架摘要驱动，但页面曾按作品标题、摘要和生成状态渲染独立最近创作卡，和其它模板页签的卡片样式及点击语义不一致。 +- 决策：“最近创作”仍只由真实后端作品架摘要决定是否展示，但只纳入 `updatedAt` 在最近 7 天内的摘要，且摘要只用于推导最近使用过的模板 ID；实际列表必须从后端入口配置的 `creationTypes` 中筛出对应模板，复用其它页签的模板卡结构、文案和 `onCreateType` 点击行为，不展示具体作品名称、作品摘要或草稿 / 生成状态，也不新增独立最近创作组件。最近创作页签激活时，页面必须显示“仅显示最近7天内使用过的模板”。 +- 影响范围：`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、`src/components/custom-world-home/CustomWorldCreationHub.tsx`、`src/components/platform-entry`、创作入口相关测试与玩法链路文档。 +- 验证方式：`CustomWorldCreationHub` 测试应断言最近创作页签包含 `creation-template-card`、模板标题 / 副标题，并且不出现旧 `creation-recent-work-grid`、作品标题、作品摘要或“打开最近创作”按钮文案；RPG 入口交互测试应断言最近创作默认页签展示“文字冒险”模板卡。 +- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 + +## 2026-06-02 底部加号创作入口页 banner 与最近创作口径 + +- 背景：创作入口页 banner 曾固定为前端两张主题赛卡，且模板分类兜底会产生 `recent` / `最近创作` 页签，和后台配置及真实作品数据口径冲突。 +- 决策：点击底部加号进入的创作入口页 banner 改由后端 `eventBanners` 数组配置，多条自动轮播；旧 `eventBanner` 只保留单条兼容。后台公告配置使用表单维护标题与 HTML 内容，保存时序列化为后端 `eventBannersJson` 传输字段；HTML 只允许经空权限 iframe 展示，不执行 JSX 或直接 DOM 注入。`最近创作` 不再作为模板分类，只由真实草稿 / 作品架后端数据决定是否展示，生成失败草稿也必须进入；模板分类缺失或历史 `recent` 统一归一到 `recommended` / `热门推荐`。移动端草稿页作品卡禁止长按选择文字，但输入框和可编辑区域保留选择能力。 +- 影响范围：`server-rs/crates/module-runtime`、`server-rs/crates/spacetime-module`、`server-rs/crates/spacetime-client`、`server-rs/crates/api-server`、`shared-contracts`、`src/components/custom-world-home`、`src/components/platform-entry`、`apps/admin-web`、`src/index.css`。 +- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、相关 Rust / Vitest 入口配置测试和浏览器点击底部加号截图。 +- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。 + +## 2026-05-26 微信小程序充值全面接入虚拟支付 + +- 背景：泥点和会员都属于小程序内由 Genarrative 控制的虚拟资产/权益，继续走普通小程序支付不符合微信虚拟支付接入口径。 +- 决策：小程序 WebView 内充值商品全部使用渠道 `wechat_mp_virtual` 并由 `miniprogram/pages/wechat-pay` 调用 `wx.requestVirtualPayment`；泥点属于代币（coin），使用 `short_series_coin`，`buyQuantity` 必须取当前充值中心商品快照里的 `points_amount`；会员和后台新增道具类商品使用 `short_series_goods`，`signData` 必须带 `productId` 与 `goodsPrice`。后端保存微信小程序 `session_key`，仅用于生成 `signature`，不下发客户端。客户端 success 只作为支付页返回信号，最终到账仍由后端微信通知或查询确认后写订单。 +- 影响范围：`src/services/payment/paymentPlatform.ts`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`miniprogram/pages/wechat-pay/`、`server-rs/crates/api-server/src/runtime_profile.rs`、`server-rs/crates/shared-contracts/src/runtime.rs`、`packages/shared/src/contracts/runtime.ts`、微信登录态存储。 +- 验证方式：泥点和会员商品在小程序运行态都请求 `wechat_mp_virtual`；小程序页能按 payload 调用 `wx.requestVirtualPayment` / `wx.requestPayment`；`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 与支付相关前端测试通过。 +- 关联文档：`docs/【技术方案】微信虚拟支付接入-2026-05-26.md`。 + +## 2026-05-30 Linux 本地 dev 端口段按系统级注册表分配 + +- 背景：同一台 Linux 开发机上有多个用户同时跑 `npm run dev` 时，单纯靠各自 `GENARRATIVE_DEV_PORT_RANGE` 容易撞段，且同一用户并发起两个 dev 会话时也会把相同端口段重复拿走。 +- 决策：Linux 上的本地 dev 端口段分配统一收口到系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，锁文件为 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。未手动指定时自动从 `10000-10099` 开始按 100 端口块分配，后续块按 `10100-10199`、`10200-10299` 递增；端口段映射固定为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`admin-web = start + 3`；注册表会拒绝不同用户的相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。`GENARRATIVE_DEV_PORT_RANGE` 与 `--port-range` 仍可手动指定端口段，但只在 Linux 生效，Windows 继续沿用原有端口探测与漂移逻辑，不读注册表。 +- 影响范围：`scripts/dev-stack-port-utils.mjs`、`scripts/dev.mjs`、`scripts/dev-stack-port-utils.test.ts`、`scripts/dev.test.ts`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、本条决策记录、`development-workflow.md`。 +- 验证方式：`node --check scripts/dev-stack-port-utils.mjs`、`node --check scripts/dev.mjs`、`node node_modules/vitest/vitest.mjs run scripts/dev-stack-port-utils.test.ts scripts/dev.test.ts` 通过；Linux 下能看到 `[dev] port-range:` 与 `registry.json` 路径日志，自动分配从 `10000-10099` 起步，Windows 不出现注册表分配日志。 +- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + +## 2026-05-30 创作流程统一化门禁扩展为跨玩法矩阵 + +- 背景：统一创作 / 统一生成门禁已经足够覆盖 Phase 2 的入口与壳层，但当前总计划已经推进到 Phase 3-6，继续只保留单页门禁会让 Phase 4 的特殊工作台、Phase 5 的结果页 / 作品架 / 公开详情和 Phase 6 的冻结验收没有统一入口。 +- 决策：`quality-gates/README.md` 继续保留单页门禁与 `dev-stack` 门禁，同时新增跨玩法回归 / 冒烟门禁，按 Phase 2 到 Phase 5 的最小验证集合分层执行；Phase 6 冻结前以这份矩阵为主，不再另外拆新波次。涉及入口配置、统一字段 spec、普通工作台、RPG / Bark Battle / 视觉小说特殊边界、发布 / 公开 / runtime 或本地 smoke 的变更，优先对照这份矩阵补齐验收命令。 +- 影响范围：`quality-gates/README.md`、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md`、`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`、后续 Phase 2-6 玩法接入与冻结流程。 +- 验证方式：按矩阵执行 `npm run check:encoding`、`npm run typecheck`、`npm run admin-web:typecheck`、对应分期 `npm run test`、`npm run check:visual-novel-vn11`，以及需要时的 `npm run dev:api-server` + `/healthz` smoke。 +- 关联文档：`quality-gates/README.md`、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md`、`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`。 + +## 2026-05-30 跳一跳结果页直达必须优先恢复作品而不是白屏 + +- 背景：跳一跳结果页已经接入统一壳，但如果用户直接打开 `/creation/jump-hop/result`，旧路径容易因为缺少 `draft` 恢复信息而看起来像白屏，误导成结果页坏了。 +- 决策：`PlatformEntryFlowShellImpl` 的跳一跳恢复顺序固定为 `profileId -> getWorkDetail`，再 `sessionId -> getSession`；两者都拿不到时必须展示 `跳一跳草稿未恢复` 恢复面板和 `返回创作`，不能继续留空白结果页。进入结果页的 smoke 允许恢复面板，但不允许纯空白。 +- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md`、`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`。 +- 验证方式：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "direct jump hop result route"`；手测 `/creation/jump-hop/result` 和 `/creation/jump-hop/result?profileId=`。 +- 关联文档：`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 + +## 2026-05-29 一期统一创作页必须提供可见统一外壳 + +- 背景：`UnifiedCreationPage` 首版只暴露隐藏 spec 元数据并包裹旧玩法工作台，用户打开拼图创作页时仍只能看到旧工作台外观，无法验收“统一创作页”。 +- 决策：一期统一创作页（拼图、抓大鹅、敲木鱼）必须由 `UnifiedCreationPage` 提供统一标题栏、内容区、页面级纵向滚动和隐藏字段契约；字段元信息只留给测试和代码，不再额外作为可见 chip 占用首屏。玩法工作台只承载具体输入控件、上传、历史素材、校验和提交，不再各自渲染巨大入口标题。拼图、抓大鹅与敲木鱼的实现已经统一收口到 `src/components/unified-creation/workspaces/`，统一壳只依赖 `UnifiedCreationWorkspace`。敲木鱼右侧音效和功德面板不得再套内部滚动容器，移动端应自然跟随页面滚动。 +- 追加决策：`UnifiedCreationPage` 自己负责页面级滚动；拼图、抓大鹅、跳一跳和敲木鱼四条统一创作入口必须在同一页面壳内从统一标题、表单控件一路滑到提交按钮，避免工作台内部或右侧面板形成套滚动。 +- 影响范围：`src/components/unified-creation/UnifiedCreationPage.tsx`、`src/components/unified-creation/UnifiedCreationWorkspace.tsx`、`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx`、`src/components/unified-creation/workspaces/Match3DCreationWorkspace.tsx`、`src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、玩法链路文档。 +- 验证方式：`UnifiedCreationPage` 测试应断言隐藏契约仍在但 UI 不再出现字段 chip；拼图和抓大鹅工作台测试应断言 `unifiedChrome=true` 时不再渲染旧巨大标题且仍保留表单输入；木鱼工作台测试或手测应确认敲击音效和功德词条不再停留在独立滚动窗内。 +- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 + +## 2026-05-31 统一创作壳扩展到跳一跳并接管页面级滚动 + +- 背景：最初的统一创作页只收口拼图、抓大鹅和敲木鱼，跳一跳仍通过独立工作台壳与独立生成壳渲染，导致用户在 `/creation/jump-hop` 看到的可见外壳与其它统一入口不一致。 +- 决策：`jump-hop` 也纳入统一创作壳与统一生成壳；`UnifiedCreationPage` 现在承担页面级滚动和统一标题栏，拼图、抓大鹅、跳一跳、敲木鱼四条入口都通过同一外壳承载各自工作台。`JumpHopCreationWorkspace`、`WoodenFishCreationWorkspace` 也补了 `unifiedChrome` / `showBackButton` 受控能力，避免双标题或双返回按钮。 +- 追加决策：`UnifiedCreationPage` 的统一页头现在承载唯一返回入口，工作台内部的返回按钮全部关闭，避免同一页面出现双返回按钮；`UnifiedCreationWorkspace` 统一把 `onBack` 透传给页头。 +- 追加决策：统一创作页内容区必须保持自然高度，页面级滚动只由 `UnifiedCreationPage` 外层承担，工作台内部只负责内容展开，不再额外包滚动壳。 +- 影响范围：`src/components/unified-creation/UnifiedCreationPage.tsx`、`src/components/unified-creation/unifiedCreationSpecs.ts`、`src/components/unified-creation/unifiedGenerationCopy.ts`、`src/components/unified-creation/workspaces/JumpHopCreationWorkspace.tsx`、`src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`server-rs/crates/shared-contracts/src/creation_entry_config.rs`。 +- 验证方式：`npm run test -- src/components/unified-creation/unifiedCreationSpecs.test.ts src/components/unified-creation/UnifiedCreationPage.test.tsx src/components/unified-creation/UnifiedGenerationPage.test.tsx src/components/unified-creation/workspaces/JumpHopCreationWorkspace.test.tsx src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx`；`npm run test -- src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx`；`npm run test -- src/routing/appPageRoutes.test.ts`。 + +## 2026-05-31 统一创作编排层必须由 UnifiedCreationWorkspace 统一收口 + +- 背景：`PlatformEntryFlowShellImpl` 仍直接 lazy import 并渲染四个旧工作台分支，虽然统一创作页已存在，但入口壳层仍然依赖旧工作台分支。 +- 决策：新增 `UnifiedCreationWorkspace` 作为平台壳唯一依赖的统一创作编排层，由它内部按 `playId` 选择四条入口的真实工作台；平台壳层只再挂这一层，不再直接依赖旧工作台组件。旧工作台已移入 `src/components/unified-creation/workspaces/`，不再作为平台入口编排事实源。 +- 影响范围：`src/components/unified-creation/UnifiedCreationWorkspace.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、统一创作页相关测试与后续入口接入。 +- 验证方式：平台壳源码中不应再直接出现四个旧工作台的入口渲染分支；创作 Tab 与 `/creation/` 仍可正常进入对应工作台。 +- 关联文档：`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 + +## 2026-05-27 生成页总进度圆弧锁定固定 SVG 坐标系 + +- 背景：多轮圆环角度微调后，`GenerationProgressHero` 的 SVG 圆弧仍会出现底部开口偏斜的问题；后来窄屏验收又发现固定 `400px` 外层宽度会让等待页右侧被裁切。 +- 决策：共用 `GenerationProgressHero` 的 SVG 圆弧起始角固定为 `135deg`，轨道和橘黄色填充都从同一个对称起点 `rotate(135 200 200)` 出发；`270deg` 扫描角配合正下方 `90deg` 留空。SVG 内部坐标系固定为 `400x400`，圆弧使用 `r=166` 和 `strokeWidth=18`；外层显示宽度以 `400px` 为上限，窄屏按父容器 `min(400px, calc(100% - 0.75rem))` 等比收缩，避免嵌套页面 padding 或负 margin 下用 `100vw` 误判宽度。预计等待 / 已耗时信息卡在窄屏下落到圆环下方两列，`sm` 及以上再回到左右悬浮。 - 影响范围：`src/components/GenerationProgressHero.tsx`、共用 `CustomWorldGenerationView`、汪汪声浪 `BarkBattleGeneratingView` 以及生成页圆环布局文档。 -- 验证方式：`CustomWorldGenerationView` 和 `BarkBattleGeneratingView` 测试断言 `data-ring-start-degrees=135`、`data-ring-fill-start-degrees=135`，且圆环容器固定为 `h-[400px] w-[400px]`，track / fill transform 都是 `rotate(135 200 200)`。 +- 验证方式：`CustomWorldGenerationView` 和 `BarkBattleGeneratingView` 测试断言 `data-ring-start-degrees=135`、`data-ring-fill-start-degrees=135`，且圆环容器包含 `w-[min(400px,calc(100%_-_0.75rem))]`、`max-w-full` 与 `aspect-square`，track / fill transform 都是 `rotate(135 200 200)`；竖屏 smoke 至少覆盖 `280px / 320px / 360px / 390px` 宽度。 - 关联文档：`docs/【玩法创作】生成页圆环布局口径-2026-05-23.md`。 ## 2026-05-26 平台跨流程错误统一用可复制来源弹窗展示 @@ -47,6 +121,7 @@ - 影响范围：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。 - 验证方式：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx` 应断言任务卡显示 `1 / 1`、领取后显示已完成，且新用户账号也没有 `次级入口` / `填邀请码` 常驻按钮；`npm run typecheck`、`npm run check:encoding` 通过。 - 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。 + ## 2026-05-26 生成页总进度圆弧逆时针回调 5 度 - 背景：创作生成页的总进度圆弧在 `160deg` 位置仍需轻微向左微调，用户要求向左逆时针回调 `5deg`。 @@ -105,10 +180,10 @@ - 验证方式：点击推荐页拼图“下一关”后，在 `advancePuzzleNextLevel` 未返回前，页面仍应保留 `puzzle-board`，且不出现 `加载中...` 占位；返回相似作品后，当前推荐卡的 `作品信息` 应显示新作品标题。 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 -## 2026-05-24 创作 Tab banner 轮播只展示主题赛 +## 2026-05-24 创作入口页 banner 曾固定主题赛 -- 背景：创作 Tab banner 曾经把后端入口配置里的默认活动横幅和两个主题赛一起轮播，导致首屏出现 58000 奖池活动卡，和当前只强调拼图 / 抓大鹅主题赛的产品口径不一致。 -- 决策：创作 Tab 首屏 banner 轮播只展示 `拼图主题创作赛` 与 `抓大鹅主题创作赛` 两张主题卡；后端返回的 `eventBanner` 仅作为开始时间、结束时间等公共字段来源，不再直接作为一张轮播卡渲染。banner 底部顺序固定为开始 / 结束时间条在上、分页点在下，且二者都在封面内容底部。 +- 背景：点击底部加号进入的创作入口页 banner 曾经把后端入口配置里的默认活动横幅和两个主题赛一起轮播，导致出现 58000 奖池活动卡，和当时只强调拼图 / 抓大鹅主题赛的产品口径不一致。 +- 决策：当时固定只展示 `拼图主题创作赛` 与 `抓大鹅主题创作赛` 两张主题卡；该口径已被 2026-06-02 的后台 `eventBanners` 配置决策替代。banner 底部顺序固定为开始 / 结束时间条在上、分页点在下，且二者都在封面内容底部。 - 影响范围：`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、`src/components/custom-world-home/CustomWorldCreationHub.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 - 验证方式：`CustomWorldCreationHub.test.tsx` 应断言默认活动标题不出现在 start-only 创作页，且 `creation-event-banner__timebar` 位于 `creation-event-banner__pager` 前。 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 @@ -132,7 +207,7 @@ ## 2026-05-24 创作 Tab 模板卡点击直达已有玩法入口表单 - 背景：创作 Tab 首屏需要对齐参考图，展示赛事 banner、玩法模板分类和两列模板卡；点击模板卡时，空白入口页会让用户多走一层，占位感也会让人误以为功能未接好。 -- 决策：`/creation/` 直达对应玩法已有的入口创作表单 stage，不再保留空白创作入口页。RPG、拼图、抓大鹅、汪汪声浪、敲木鱼、视觉小说、宝贝识物等都直接进入既有工作台，继续承接草稿恢复和后续编排。创作 Tab 首屏 banner 按参考图拆成右上泥点胶囊、主体宣传封面图文、底部开始/结束时间条和分页点；玩法模板卡使用独立 `creation-template-card` 白底信息区，不复用暗图蒙版 `platform-creation-reference-card`，确保标题、描述和“预计消耗 10-20 泥点”可见。 +- 决策：`/creation/` 直达对应玩法已有的入口创作表单 stage，不再保留空白创作入口页。RPG、拼图、抓大鹅、汪汪声浪、敲木鱼、视觉小说、宝贝识物等都直接进入既有工作台，继续承接草稿恢复和后续编排。点击底部加号进入的创作入口页 banner 按参考图拆成右上泥点胶囊、主体宣传封面图文、底部开始/结束时间条和分页点；玩法模板卡使用独立 `creation-template-card` 白底信息区，不复用暗图蒙版 `platform-creation-reference-card`，确保标题、描述和“预计消耗 10-20 泥点”可见。 - 影响范围：`src/components/platform-entry/platformEntryTypes.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、创作大厅交互测试与平台入口文档。 - 验证方式：`npm test -- src/routing/appPageRoutes.test.ts`、`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t \"create tab opens match3d entry form from the template card|create tab opens puzzle entry form from the template card|create tab opens bark battle entry form from the template card\"`、`npm run typecheck`、`npm run check:encoding` 通过；创作卡片点击后应进入对应工作台，不再出现空白入口页。 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 @@ -156,11 +231,19 @@ ## 2026-05-23 拼图生成页按后端真实进度推进阶段 - 背景：拼图生成页原先会按本地耗时自动推进步骤，容易在后端真实生成尚未完成时跳到后续阶段，导致页面状态和会话进度脱节。 -- 决策：拼图生成页的跨步骤推进只认后端会话 `progressPercent` 的真实里程碑，当前步骤内部再用本地耗时假进度平滑展示；总进度初始必须为 `0%`，之后按 `0-88`、`88-94`、`94-96`、`96-98` 的真实里程碑区间平滑推进。只要当前步骤生成内容未完成，就必须停留在当前步骤。页面只展示当前步骤标题和进度，不展示步骤详细描述。`生成拼图首图` 单独按 4 分钟估算，完整 AI 重绘路径约 448 秒；上传图且关闭 AI 重绘路径跳过首图生成，仍约 208 秒。 +- 决策：拼图生成页的跨步骤推进只认后端会话 `progressPercent` 的真实里程碑，当前步骤内部再用本地耗时假进度平滑展示；`88/94/96` 只切换当前步骤，不直接作为总进度地板。总进度按已完成步骤权重加当前步骤内假进度推导，非完成态最多停在 `98%`。恢复持久化生成中草稿时，展示态 `startedAtMs` 使用后端 session `updatedAt` 或作品摘要 `updatedAt`，保证已耗时不因重新进入页面清零。只要当前步骤生成内容未完成，就必须停留在当前步骤。页面只展示当前步骤标题和进度，不展示步骤详细描述。`生成拼图首图` 单独按 4 分钟估算，完整 AI 重绘路径约 448 秒；上传图且关闭 AI 重绘路径跳过首图生成，仍约 208 秒。 - 影响范围：`src/services/miniGameDraftGenerationProgress.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/CustomWorldGenerationView.tsx`、拼图生成页相关测试与玩法链路文档。 - 验证方式：拼图生成页恢复、轮询和测试都应以 `puzzleProgressPercent` 驱动阶段推进；`npm run test -- src/services/miniGameDraftGenerationProgress.test.ts src/components/CustomWorldGenerationView.test.tsx`、`npm run typecheck`、`npm run check:encoding` 通过。 - 关联文档：`docs/【玩法创作】拼图生成页进度口径-2026-05-23.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 +## 2026-06-02 生成失败草稿必须留在作品架并覆盖生成中摘要 + +- 背景：生成页收到失败回包后会进入重试态，但返回草稿 Tab 时，后端作品摘要可能仍短暂保持 `generationStatus=generating`，导致用户看到“生成中”；连续触发多个拼图生成时，失败后如果清掉 pending 条目，还会少显示新增草稿。后台失败如果只写局部生成页错误，用户离开生成页后也收不到通知。 +- 决策：平台壳在生成失败时必须同时标记草稿 notice 和 pending 作品架条目为 `failed`，不得删除 pending 条目。失败 notice 要保存错误消息并在用户离开生成页后触发带来源的 `PlatformErrorDialog`；作品架本地失败 notice 要覆盖持久化生成中摘要，失败草稿仍显示为草稿卡但不显示“生成中”。点击失败草稿必须优先恢复失败 / 重试页，不能按持久化 `generating` 重新启动生成；拼图契约已允许 `generationStatus=failed`，pending 拼图和后端失败回写都按 session 独立落失败态，跳一跳 / 木鱼 / 抓大鹅等也直接映射为 `failed` 或对应失败态。 +- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/custom-world-home/creationWorkShelf.ts`、`src/components/custom-world-home/CustomWorldCreationHub.tsx`、玩法链路文档和失败态交互测试。 +- 验证方式：`node node_modules/vitest/vitest.mjs run src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "failed parallel puzzle|background match3d"`；失败后返回草稿 Tab 应看到对应新增草稿，且没有“生成中”标记；后台失败应弹出错误来源，点击失败草稿应进入失败 / 重试页。 +- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`.hermes/shared-memory/pitfalls.md`。 + ## 2026-05-23 所有玩法生成页统一圆环主视觉 - 背景：多个玩法生成页分别展示横向总进度条、步骤列表或三槽位列表，和最新参考图里的陶泥儿圆环等待态不一致，也让移动端信息密度偏高。 @@ -276,7 +359,6 @@ - 验证方式：执行 `cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml`、`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx src/components/match3d-runtime/Match3DRuntimeShell.test.tsx src/services/match3dSpritesheetParser.test.ts src/services/match3dGeneratedModelCache.test.ts`、`npm run typecheck`、`npm run check:encoding`。 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 - ## 2026-05-18 Rust 手写模块入口统一不用 mod.rs - 背景：Rust 目录模块同时存在 `mod.rs` 与同名 `.rs` 两种入口形式，前次拆分已让 `spacetime-client/src/mapper.rs` 采用同名入口；继续新增 `mod.rs` 会让文件定位和评审口径不一致。 @@ -307,6 +389,7 @@ ## 2026-05-18 Windows Jenkins PowerShell 统一改为显式 powershell.exe 启动 +- 后续更新：该决策仅适用于历史 Windows Jenkins 节点；当前 `Genarrative-Stdb-Module-Build` 已改为 Linux agent，实际执行路径不再依赖该口径。 - 背景：`Genarrative-Stdb-Module-Build` 在 Windows Jenkins 本地环境里调用裸 `powershell` step 时触发 `CreateProcess error=5, 拒绝访问`，而 `powershell.exe` 本体与 workspace ACL 都正常。 - 决策：Windows Jenkins 上凡是需要执行 PowerShell 逻辑的流水线，优先通过 `bat` 显式调用 `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File ...`，不要再依赖 Jenkins `powershell` step 的隐式启动器。 - 追加决策：`Genarrative-Stdb-Module-Build` 的 Checkout 逻辑应复用 Jenkins GitSCM 已完成的工作区状态。`COMMIT_HASH` 为空或已与当前 `HEAD` 一致时，不再额外执行 `git clean` / `git checkout`；只有需要切到指定且不同的 commit 时才补 fetch、校验和切换，避免在 Windows workspace 里二次清理触发权限拒绝。 @@ -351,6 +434,7 @@ ## 2026-05-19 生产 provision 改为 Windows 下载包后由目标机本地安装 +- 后续更新：该口径已被 `2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost` 取代；当前 `Genarrative-Server-Provision` 不再走 Windows 下载阶段，而是在 Linux build 节点直接准备 `provision-tools/`。 - 背景：当前 `development` provision 目标实际就是 Linux agent `genarrative-build-01`，之前把 `Prepare Provision Tools` 放在 `linux && genarrative-build` 会让目标机自己连 GitHub 和 `install.spacetimedb.com`，违背“Windows 本机先下载再传到目标机”的运维要求。 - 决策：`Genarrative-Server-Provision` 拆成 Windows 下载阶段和 Linux 目标机安装阶段。Windows 节点的 `Download Provision Tool Archives` 只下载 `spacetime-x86_64-unknown-linux-gnu.tar.gz` 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz`，通过 `stash/unstash` 传到目标 Linux 节点；目标机执行 `scripts/prepare-server-provision-tools.sh` 时设置 `PROVISION_REQUIRE_LOCAL_DOWNLOADS=true`，只消费已下载件生成 `provision-tools/`，缺包直接失败，不回退外网下载。 - 追加决策：Server-Provision 的 Windows helper 不再对 Jenkins `writeFile` 刚写出的 `.ps1` 做原地 UTF-8 BOM 重写，而是由显式 `powershell.exe` 按 UTF-8 读入脚本文本，并用 `ScriptBlock::Create(...)` 在内存中执行；这样既保留中文脚本内容，又避免同一个 workspace 脚本被立即重写时触发 `拒绝访问`。 @@ -513,7 +597,7 @@ - 验证方式：草稿页作品卡与分类页列表视觉口径保持一致；`npm run test -- src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx`、`npm run typecheck`、`npm run check:encoding`。 - 关联文档：`docs/design/MOBILE_CREATION_WORK_LIST_TWO_COLUMN_LAYOUT_2026-04-29.md`、`docs/experience/MOBILE_UI_DEV_EXPERIENCE.md`。 -2026-05-14 补充：草稿页作品卡不再用“草稿 / 已发布”文字标识状态，改为图标化 UI 状态点；作品封面直接铺到卡片右半区并从右向左渐隐；已发布作品右上角常驻分享图标；草稿长按弹出删除面板，已发布长按弹出分享和删除面板。 +2026-05-14 补充：草稿页作品卡不再用“草稿 / 已发布”文字标识状态，改为图标化 UI 状态点；作品封面直接铺到卡片右半区并从右向左渐隐；已发布作品右上角常驻分享图标；草稿长按弹出删除面板，已发布长按弹出分享和删除面板。2026-06-02 追加：作品卡片右上角不再放删除按钮；删除只通过左滑、键盘展开或长按 / 右键展开的右侧操作区出现，避免与卡片主点击和分享入口抢占标题区。 ## 2026-05-13 认证运行期同步直接导入正式认证表 @@ -558,8 +642,8 @@ - 背景：抓大鹅草稿素材生成已经收敛为多视角 2D 图片素材，但入口页和旧参考图仍沿用黏土、低多边形、塑料、木雕、体素、金属等偏 3D 素材语言，容易让后续生成链路和用户预期继续漂移。 - 决策：抓大鹅创作入口 `2D素材风格` 固定为 `扁平图标 / 赛璐璐卡通 / 像素复古 / 手绘水彩 / 贴纸描边 / 厚涂图标 / 自定义`；默认风格为 `flat-icon`。入口参考图统一由 `npm run assets:match3d-style-references -- --live` 调用 VectorEngine `gpt-image-2` 生成，输出到 `public/match3d-style-references/`。旧 3D 风格参考图不再保留为入口资产。 -- 影响范围：`Match3DAgentWorkspace`、抓大鹅入口交互测试、Match3D PRD、素材生成流水线技术文档、F1 入口文档和 `public/match3d-style-references/` 静态资产。 -- 验证方式：执行 `npm run test -- src\components\match3d-creation\Match3DAgentWorkspace.interaction.test.tsx`、`cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml`、`npm run typecheck`、`npm run check:encoding`，并人工抽查 `.tmp/match3d-style-preview.png`。 +- 影响范围：抓大鹅统一创作工作台、抓大鹅入口交互测试、Match3D PRD、素材生成流水线技术文档、F1 入口文档和 `public/match3d-style-references/` 静态资产。 +- 验证方式：执行 `npm run test -- src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx`、`cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml`、`npm run typecheck`、`npm run check:encoding`，并人工抽查 `.tmp/match3d-style-preview.png`。 - 关联文档：`docs/prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`、`docs/technical/MATCH3D_F1_CREATION_ENTRY_AND_AGENT_UI_2026-04-30.md`。 ## 2026-05-12 拼图与抓大鹅草稿背景音乐按纯音乐自动生成 @@ -700,6 +784,7 @@ - 验证方式：执行 `npx vitest run src/services/useMocapInput.test.ts src/components/child-motion-demo/ChildMotionWarmupDemo.test.tsx src/components/child-motion-demo/childMotionWarmupModel.test.ts src/services/child-motion-demo/childMotionDebugInput.test.ts src/routing/appRoutes.test.ts`、`npx eslint ...`、`npm run typecheck`、`npm run check:encoding`，并确认 `http://127.0.0.1:8876/stream` WebSocket 可握手、`http://127.0.0.1:3000/child-motion-demo` 可访问。 ## 2026-05-18 寓教于乐频道补充热身关入口 + - 背景：用户希望在发现页的寓教于乐板块里直接看到热身关入口，而不是只依赖独立直达路由。 - 决策：`child-motion-demo` 作为寓教于乐频道的独立卡片展示，点击后直接进入 `/child-motion-demo`；该入口与 `宝贝爱画` 并列，仍复用现有独立热身关路由，不新增新的创作模板或运行态壳层。 - 影响范围：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 @@ -998,12 +1083,29 @@ ## 2026-05-19 server provision 下载件固定由 Windows 节点断点续传 +- 后续更新：该口径已被 `2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost` 取代；当前不再维护 Windows 下载阶段和 `.download` 断点续传 helper。 - 背景：`SpacetimeDB` 和 `otelcol-contrib` release 资产在 Linux 目标机直接下载很慢；改到 Windows Jenkins 节点下载后，GitHub 大文件仍可能出现 `curl: (18)` 响应体截断。 - 决策：`Genarrative-Server-Provision` 的 `Download Provision Tool Archives` 阶段继续只在 Windows 节点下载，再通过 `stash/unstash` 交给目标 Linux agent；下载前查 GitHub release asset `digest`，本地最终文件 SHA256 命中即跳过，`.download` 临时文件用于 `curl -C -` 断点续传，完整返回但 digest 不匹配才清理重下。 - 影响范围：`jenkins/Jenkinsfile.production-server-provision`、目标机 `scripts/prepare-server-provision-tools.sh` 的本地下载件消费路径、生产 provision 运维排障。 - 验证方式：Windows 下载日志应出现 digest 查询、已存在校验跳过或 `curl 断点续传`；Linux 目标机阶段只使用 `provision-tool-downloads/` 中的 tarball，不访问 GitHub 下载地址。 - 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 +## 2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost + +- 背景：生产流水线长期混用 Windows、Linux 和公网 Git 入口，导致构建 / 发布 / provision 的 checkout 口径分叉；同时 `Genarrative-Server-Provision` 还残留过 Windows 下载 helper，和当前 Linux 构建 / 发布部署路径不一致。 +- 决策：生产 Jenkins 流水线统一把执行节点收口到 Linux label，`Pipeline script from SCM` 仍保留公网域名，但所有生产流水线首次 `GitSCM checkout` 先尝试 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后再回退到 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；`Genarrative-Stdb-Module-Build`、`Genarrative-Server-Provision`、`Genarrative-Notify-Email` 也都切到 Linux 节点。`Genarrative-Server-Provision` 的工具准备不再依赖 Windows helper，而是在 Linux build 节点直接生成 `provision-tools/` 后交给后续 Linux 发布阶段。 +- 影响范围：`jenkins/Jenkinsfile.production-*`、`scripts/jenkins-checkout-source.sh`、`scripts/prepare-server-provision-tools.sh`、生产运维文档。 +- 验证方式：扫描 Jenkinsfile 时应看到 `linux && genarrative-*` 节点和 localhost-first checkout 口径；`Genarrative-Server-Provision` 日志不再出现 Windows 相关 helper 输出，工具准备阶段应直接生成 `provision-tools/`。 +- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + +## 2026-06-01 Web Deploy 只从 Jenkins 构建归档取发布包 + +- 背景：`Genarrative-Web-Deploy` 曾在发布阶段读取构建机本地缓存目录，release 目标还可能通过 `rsync` 回构建机拉取 `web.tar.gz`，导致发布依赖机器拓扑和本地路径。 +- 决策：`Genarrative-Web-Build` 直接归档 `build//web.tar.gz`、`web.tar.gz.sha256` 和 `release-manifest.json`；`Genarrative-Web-Deploy` 只使用 Jenkins `copyArtifacts` 从指定上游构建复制完整 Web 发布包，不再维护 `WEB_ARTIFACT_ROOT`、`WEB_ARTIFACT_SYNC_HOST` 或 `web-artifact-pointer.txt`。 +- 影响范围：`jenkins/Jenkinsfile.production-web-build`、`jenkins/Jenkinsfile.production-web-deploy`、Web 发布排障流程。 +- 验证方式：deploy 工作区直接存在 `build//web.tar.gz`、`web.tar.gz.sha256` 和 `release-manifest.json`，随后由 `scripts/deploy/production-web-deploy.sh` 校验 checksum 并解压发布。 +- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + ## 个人任务与埋点首版边界冻结 - 背景：“我的”Tab、任务、奖励、钱包和埋点涉及用户、运营、分析多条链路，需要避免范围泛化。 @@ -1076,7 +1178,7 @@ - 背景：敲木鱼工作台只应保留生成所需输入，作品标题、简介和主题标签适合放在生成草稿后的补录阶段。 - 决策：敲木鱼的 `workTitle`、`workDescription` 和 `themeTags` 从工作台首屏移到结果页；结果页编辑后在试玩或发布前先调用 `update-work-meta` 写回当前作品信息。主题标签编辑样式对齐拼图结果页的胶囊标签编辑器。 -- 影响范围：`WoodenFishWorkspace`、`WoodenFishResultView`、`PlatformEntryFlowShellImpl`、敲木鱼 PRD 和平台入口链路文档。 +- 影响范围：敲木鱼统一创作工作台、`WoodenFishResultView`、`PlatformEntryFlowShellImpl`、敲木鱼 PRD 和平台入口链路文档。 - 验证方式：工作台首屏不再出现标题 / 简介 / 标签输入；结果页修改后点试玩或发布会先写回当前作品信息。 - 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 @@ -1095,13 +1197,14 @@ - 影响范围：`module-auth`、`api-server` 作品作者解析、`AppState` 启动初始化、历史孤儿作品离线回填脚本与相关文档。 - 验证方式：`cargo test -p module-auth --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml work_author`、`npm run test -- scripts/rebind-orphan-work-owners.test.ts`。 - 关联文档：`server-rs/crates/module-auth/src/domain.rs`、`server-rs/crates/module-auth/src/lib.rs`、`server-rs/crates/api-server/src/work_author.rs`、`scripts/rebind-orphan-work-owners.mjs`。 + ## 2026-05-26 敲木鱼发布后作品架与推荐流刷新口径 - 背景：敲木鱼已具备公开广场投影，但草稿 Tab 的作品架没有当前用户作品列表接口，导致已发布作品在发布后不能立即出现在“已发布”筛选和推荐流里。 - 决策：新增 `GET /api/creation/wooden-fish/works` 作为当前用户木鱼作品架事实源，返回 `WoodenFishWorksResponse.items` 摘要；平台壳在发布成功后必须同时刷新作品架和公开广场列表。 - 影响范围：`server-rs/crates/api-server/src/wooden_fish.rs`、`server-rs/crates/api-server/src/modules/wooden_fish.rs`、`src/services/wooden-fish/woodenFishClient.ts`、`src/components/custom-world-home/creationWorkShelf.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`。 - 验证方式：发布一个木鱼作品后，草稿 Tab 的已发布筛选应立刻出现 `WF-*` 作品卡，推荐 / 最新流也应立即刷新出公开卡片。 - - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`。 +- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`。 ## 2026-05-27 认证快照完全去文件化并仅保留行级备查 diff --git a/.hermes/shared-memory/development-workflow.md b/.hermes/shared-memory/development-workflow.md index 3710e85b..6cfb9325 100644 --- a/.hermes/shared-memory/development-workflow.md +++ b/.hermes/shared-memory/development-workflow.md @@ -50,6 +50,8 @@ npm install npm run dev ``` +Linux 多用户共享同一台机器开发时，本地 dev 脚本会为当前 Linux 用户分配一个固定端口段并写入系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，自动分配从 `10000-10099` 开始，每段 100 个端口，四个 dev 服务依次使用 `start` 到 `start + 3`。可用 `GENARRATIVE_DEV_PORT_RANGE` 或 `npm run dev -- --port-range` 手动指定端口段用于特殊场景；注册表会阻止不同用户使用相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。该机制只在 Linux 生效，Windows 仍沿用原有端口探测与漂移逻辑。 + 该命令会启动： - SpacetimeDB standalone @@ -57,6 +59,8 @@ npm run dev - 主站 Vite - 后台 Vite +`npm run dev` 和单模块 `dev:*` 命令会更新根目录 `.app/dev-stack.json`，记录四个本地服务的 pid、端口、URL、启动状态和当前命令。该目录只作本机运行态观测，不提交 Git。 + 开启自动刷新： ```bash @@ -239,7 +243,8 @@ npm run check:server-rs-ddd - 移动端优先，再兼容网页端。 - 页面只展示后端返回的状态，不自行计算结论型业务状态。 -- 创作中心入口配置事实源在 SpacetimeDB，通过 `GET /api/creation-entry/config` 下发；前端只在 `platformEntryCreationTypes.ts` 做展示派生，api-server 路由熔断也使用同一份配置，禁止恢复前端硬编码入口配置文件。 +- 创作中心入口配置事实源在 SpacetimeDB，通过 `GET /api/creation-entry/config` 下发；前端只在 `platformEntryCreationTypes.ts` 做展示派生，api-server 路由熔断也使用同一份配置，禁止恢复前端硬编码入口配置文件。底部加号创作入口页公告位也跟随后端 `eventBanners` 配置，前端只做展示和轮播；后台公告用表单维护标题与 HTML 内容，保存时再序列化为后端 `eventBannersJson` 传输字段。`最近创作` 不属于模板分类，不能作为分类缺失兜底；生成中和生成失败的真实草稿摘要都应进入最近创作。 +- 一期统一创作页字段 spec 同样跟随 `GET /api/creation-entry/config`，由 `creationTypes[].unifiedCreationSpec` 下发；拼图、抓大鹅、敲木鱼之外的模板不接入该扩展位，前端只保留旧后端缺字段时的兜底默认。 - 优先复用现有面板、抽屉、弹窗，不新建独立大系统。 - 不在 UI 中默认写功能说明类文本。 - 弹出独立面板的交互不要实现成在当前面板下方追加内容。 @@ -253,6 +258,8 @@ npm run check:server-rs-ddd ## 提交前建议让 Hermes 执行 +涉及拼图、抓大鹅、敲木鱼统一创作 / 生成链路、Phase 2 之后的跨玩法回归或本地 dev 栈时，先按 `quality-gates/README.md`、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md` 和对应单项门禁文档执行自动脚本与体验检查。 + ```text 请检查当前 git diff，指出： 1. 是否违反 AGENTS.md 或 .hermes/shared-memory 约定； diff --git a/.hermes/shared-memory/document-map.md b/.hermes/shared-memory/document-map.md index 512c5949..a2091763 100644 --- a/.hermes/shared-memory/document-map.md +++ b/.hermes/shared-memory/document-map.md @@ -11,7 +11,9 @@ | 产品、命名、UI、协作和废弃路线 | `docs/【项目基线】当前产品与工程约束-2026-05-15.md` | | 后端、DDD、API、SpacetimeDB schema 和表目录 | `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md` | | 创作入口、草稿架和玩法链路 | `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` | +| 创作流程统一阶段计划 | `docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md` | | 本地启动、验证、部署、埋点和运营查询 | `docs/【开发运维】本地开发验证与生产运维-2026-05-15.md` | +| 微信小程序虚拟支付 | `docs/【技术方案】微信虚拟支付接入-2026-05-26.md` | | UI 像素资产与 9-slice 规范 | `UI_CODING_STANDARD.md` | ## 阅读顺序 @@ -32,8 +34,9 @@ 玩法 / 创作入口 / 运行态： 1. `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md` -2. `docs/【项目基线】当前产品与工程约束-2026-05-15.md` -3. 相关前端组件、service、shared contract 和后端 module +2. 若任务涉及跨玩法创作流程统一，读取 `docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md` +3. `docs/【项目基线】当前产品与工程约束-2026-05-15.md` +4. 相关前端组件、service、shared contract 和后端 module 生产部署 / 服务器 / Jenkins： diff --git a/.hermes/shared-memory/pitfalls.md b/.hermes/shared-memory/pitfalls.md index 3dea8cd4..4aff3fc0 100644 --- a/.hermes/shared-memory/pitfalls.md +++ b/.hermes/shared-memory/pitfalls.md @@ -23,11 +23,20 @@ - 验证：触发任一平台级异步失败时，页面应出现包含“错误来源”和“错误内容”的弹窗；复制内容应包含来源和错误正文；旧页面内错误 banner 不再重复出现。 - 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/PlatformErrorDialog.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 +## 暗色创作进度卡不要被 platform-remap-surface 改成深色文字 + +- 现象：统一创作页里的暗色进度卡背景是深绿 / 深蓝，但“创作进度”、百分比和进度提示显示成深色，移动端几乎看不清。 +- 原因：`platform-remap-surface` 在浅色主题下会把后代 `[class*='text-white']` 强制重映射成 `var(--platform-text-strong)`，并且使用 `!important`；暗色 hero 卡片如果只写通用 `text-white*`，刷新后仍会被全局 remap 覆盖成深色。早期还混用了 `text-white/72`、`text-white/88`、`border-white/14`、`bg-white/12` 等不稳透明度档位，进一步放大了问题。 +- 处理：给暗色 hero 加组件专属 class，例如 `creation-agent-hero__progress-label`、`creation-agent-hero__progress-value`、`creation-agent-hero__progress-hint`，并在 `src/index.css` 的 remap 规则之后用更具体选择器和 `!important` 固定白色透明度、边框和进度条底色。 +- 验证：`CreationAgentWorkspace` 测试应断言进度标题、百分比和提示文本带专属 class；`src/index.test.ts` 应断言这些 class 在 remap surface 内有白色覆盖规则；移动端截图中暗色卡片文字应保持可读。 +- 关联：`src/components/creation-agent/CreationAgentWorkspace.tsx`、`src/components/creation-agent/CreationAgentWorkspace.test.tsx`、`src/index.css`、`src/index.test.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 + ## VectorEngine 图片生成 SendRequest 超时要按传输失败排查 -- 现象：`external_api_call_failure` 里看到 `failureStage=request_send`、`timeout=true`、`statusCode=null`、`errorSource=client error (SendRequest)`，前端只知道图片生成失败。 +- 现象：`external_api_call_failure` 里看到 `failureStage=request_send`、`timeout=true`、`statusCode=null`，`errorSource` 可能是 `client error (SendRequest)` 或更完整的 reqwest 底层错误链，前端只知道图片生成失败。 - 原因：`timeout=true` 来自 `reqwest::Error::is_timeout()`，不是业务代码固定写死；`SendRequest` 是 Hyper 发送请求阶段的错误来源标签，只说明请求未拿到可归类的 HTTP 响应，不会包含上游 JSON 错误体。 -- 处理：先按 `provider/failureStage/statusClass` 聚合，再用 `user_id` / `profile_id` 和 `metadata_json.userId/profileId` 定位触发者与草稿 / 作品；`request_send + timeout=true` 优先查请求体大小、参考图数量、出口网络、代理/Nginx、VectorEngine 当时可用性和同一 request_id 日志。若记录有 `502` 或 `429 moderation_blocked`，按上游网关或审核失败另行处理，不要归到传输超时。 +- 处理：先按 `provider/failureStage/statusClass` 聚合，再用 `user_id` / `profile_id` 和 `metadata_json.userId/profileId/requestId` 定位触发者、草稿 / 作品和同一次 HTTP 请求；`request_send + timeout=true` 优先查 provider 日志的 `source_chain`、请求体大小、参考图数量、出口网络、代理/Nginx、VectorEngine 当时可用性和同一 request_id 日志。若记录有 `502` 或 `429 moderation_blocked`，按上游网关或审核失败另行处理，不要归到传输超时。 +- 拼图关卡资产生成按 `level_scene -> ui_spritesheet -> level_background` 顺序执行，每个资产会输出 `slot`、`asset_kind`、`elapsed_ms`；排查拼图草稿失败时优先看同一 request_id 下最后一个失败 slot。 - 验证：`cargo check -p api-server --manifest-path server-rs/Cargo.toml`；查询 `tracking_event` 时失败记录应能看到触发者 `user_id` 和可用的 `profile_id`。 - 关联：`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 @@ -106,10 +115,25 @@ ## 玩法入口分类字段缺失要前端兜底 - 现象：平台创作入口初始化时，`platformEntryCreationTypes.ts` 直接对 `creationTypes[].categoryId` / `categoryLabel` 调 `trim()`，一旦后端旧数据、局部 mock 或异常返回里缺字段，整个创作页会在 `derivePlatformCreationTypes(...)` 里直接炸掉。 -- 处理：`normalizeCategoryId(...)` 和 `normalizeCategoryLabel(...)` 必须接收可空值，并分别回退到 `recent` / `最近创作`。前端这里是展示派生层，不能要求所有历史配置都先补齐字段。 +- 处理：`normalizeCategoryId(...)` 和 `normalizeCategoryLabel(...)` 必须接收可空值，并分别回退到 `recommended` / `热门推荐`；历史 `recent` / `最近创作` 也要归一到推荐分类。`最近创作` 不属于模板分类页签，只能由真实草稿 / 作品架后端数据决定是否展示。 - 验证：`npm test -- src/components/platform-entry/platformEntryCreationTypes.test.ts`，再打开本地创作页确认能正常进入创作 Tab。 - 关联：`src/components/platform-entry/platformEntryCreationTypes.ts`、`src/components/platform-entry/platformEntryCreationTypes.test.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 +## 创作入口公告不要恢复前端固定两卡 + +- 现象：点击底部加号进入的创作入口页只展示固定的拼图 / 抓大鹅主题卡，后台改公告表单后前台没有变化。 +- 原因：前端重新硬编码 banner 列表，绕过了 `GET /api/creation-entry/config` 的 `eventBanners` 配置。 +- 处理：创作入口页公告位优先读取后端 `eventBanners` 数组，多条自动轮播；旧 `eventBanner` 只做单条兼容兜底。后台主格式是标题与 HTML 内容表单，保存时序列化为后端 `eventBannersJson` 传输字段，只允许受控 HTML 片段经空权限 iframe 展示，不执行 JSX 或直接 DOM 注入。 +- 验证：后台保存两条以上公告后，点击底部加号进入创作入口页应自动轮播这些后台配置项；`CustomWorldCreationHub` 相关测试应断言标题来自后端配置。 +- 关联：`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、`server-rs/crates/module-runtime/src/application.rs`、`apps/admin-web/src/pages/AdminCreationEntrySwitchPage.tsx`。 + +## 移动端草稿卡不要长按选中文字 + +- 现象：移动端草稿页长按作品卡标题或摘要时触发系统文字选区，容易误触并打断作品架操作。 +- 处理：移动端只对 `#platform-tab-panel-saves .creation-work-card` 禁止 `user-select` 和 `-webkit-touch-callout`；输入框、文本域和 `[contenteditable='true']` 保留文本选择能力，避免破坏真实编辑场景。 +- 验证：移动端草稿页长按普通作品卡文字不出现系统选区；`src/index.test.ts` 应覆盖 CSS 选择器和可编辑控件例外。 +- 关联：`src/index.css`、`src/index.test.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 + ## 草稿页未读点不要继续用红色 literal - 现象：草稿页底部 Tab 和作品架的未读点视觉上仍像红点，或 glow 仍带红色阴影，和平台暖棕体系不一致。 @@ -142,6 +166,21 @@ - 验证：浏览器里这三页的根区应仍保留 `platform-remap-surface`，但不再出现 `platform-page-stage`；草稿页顶部筛选样式应和发现页频道标签一致。 - 关联：`src/components/custom-world-home/CustomWorldCreationHub.tsx`、`src/components/custom-world-home/CustomWorldWorkTabs.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/index.css`。 +## 统一创作壳现在自己负责页面滚动和四条入口外壳 + +- 现象：统一创作页最初只包住拼图、抓大鹅和敲木鱼的工作台内容，跳一跳仍然保留独立工作台壳，页面级滚动职责也散落在平台入口 motion wrapper 里，导致移动端不同入口的可见外壳不一致。 +- 原因：`UnifiedCreationPage` 只做了标题和隐藏契约，入口壳还在各自工作台里保留 `platform-remap-surface` / `overflow-y-auto`，`jump-hop` 也没进入统一 spec。 +- 处理：把 `jump-hop` 纳入 `unifiedCreationSpec`，让 `UnifiedCreationPage` 自己承担页面级滚动与统一标题栏；`JumpHopCreationWorkspace`、`WoodenFishCreationWorkspace` 补 `unifiedChrome` / `showBackButton`，平台壳不再给这几条统一入口套额外滚动壳。 +- 验证：`npm run test -- src/components/unified-creation/unifiedCreationSpecs.test.ts src/components/unified-creation/UnifiedCreationPage.test.tsx src/components/unified-creation/UnifiedGenerationPage.test.tsx src/components/unified-creation/workspaces/JumpHopCreationWorkspace.test.tsx src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx` 通过后，`/creation/puzzle`、`/creation/match3d`、`/creation/jump-hop`、`/creation/wooden-fish` 都应由同一套统一创作页外壳承载。 +- 关联：`src/components/unified-creation/UnifiedCreationPage.tsx`、`src/components/unified-creation/unifiedCreationSpecs.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`。 + +## 统一创作编排层不要再让平台壳直挂旧工作台 + +- 现象：平台入口壳已经切到统一创作外壳，但源码里仍直接 lazy import 并渲染四个旧工作台分支，看起来还是四套入口编排。 +- 原因：统一创作页只收口了可见外壳，入口层没有再抽一层统一创作编排组件，导致平台壳依旧要认识各玩法旧工作台。 +- 处理：新增 `UnifiedCreationWorkspace`，由它内部按 `playId` 选择真实工作台；平台壳只依赖这一层，不再直接挂旧工作台分支。旧工作台已迁入 `src/components/unified-creation/workspaces/`，不再是入口编排事实源。 +- 验证：`PlatformEntryFlowShellImpl.tsx` 中不应再出现四个旧工作台的入口渲染分支，创作 Tab 与 `/creation/` 仍能正常进入对应工作台。 +- 关联：`src/components/unified-creation/UnifiedCreationWorkspace.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 ## Jenkinsfile 开头不能带 UTF-8 BOM @@ -151,6 +190,14 @@ - 验证：检查 `jenkins/Jenkinsfile.production-stdb-module-publish` 文件开头字节不再是 `EF BB BF`，并用 Jenkins `validateDeclarativePipeline` 或重放 `Genarrative-Stdb-Module-Publish`，不应再停在 `No such DSL method 'pipeline'`。 - 关联：`jenkins/Jenkinsfile.production-stdb-module-publish`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 +## Linux 多用户 dev 端口冲突先查系统级端口段注册表 + +- 现象：同一台 Linux 机器上多个用户同时开发时，`npm run dev` 报端口段已被其他用户占用、同一用户已有活跃端口段，或 SpacetimeDB 复用记录指向当前用户端口段之外的地址；未手动指定时自动分配应从 `10000-10099` 起步。 +- 原因：Linux dev 脚本会通过 `/var/tmp/genarrative-dev-port-ranges/registry.json` 做系统级端口段分配，避免两个用户配置相同或重叠端口段；同一用户后续启动会继续复用自己已经占用的固定端口段。注册表会保留该用户的段记录，不会因为多开而要求重新分配。 +- 处理：先确认当前用户已经占用的端口段，再让后续 `npm run dev` / `dev:*` 继续沿用这段；如确实要切换段，手动释放或清掉对应 registry 记录后再重启。需要临时隔离测试时用 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR=` 覆盖注册表目录。不要在 Windows 上按这个注册表排查，Windows 仍走原有端口探测与漂移逻辑。未指定端口段时，系统会从 `10000-10099` 开始顺序分配。 +- 验证：重新启动后终端应打印 `[dev] port-range: ()` 与 `[dev] port-range-registry: .../registry.json`；`node node_modules/vitest/vitest.mjs run scripts/dev-stack-port-utils.test.ts scripts/dev.test.ts` 应通过 Linux registry、自动分配 `10000-10099` 与 Windows bypass 用例。 +- 关联：`scripts/dev-stack-port-utils.mjs`、`scripts/dev.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + ## SpacetimeDB 入口迁移 helper 合并时不要只保留调用 - 现象：`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 或 Jenkins `Genarrative-Stdb-Module-Build` 报 `E0425 cannot find function migrate_rpg_entry_from_old_hidden_default in this scope`，位置在 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs` 的默认入口配置播种流程。 @@ -247,7 +294,7 @@ - 原因：通用图像输入是受控输入面板，不是只服务单页的临时实现；图片、提示词、参考图数组、重绘开关等业务真相应由外层页面持有，组件最多持有参考图预览、删除确认这类短生命周期 UI 状态。 - 处理：抽 `CreativeImageInputPanel` 时，保留上传卡、参考图入口、缩略图、预览弹层、删除确认和提交按钮的统一壳，但把主图文件读取、裁剪、历史素材、计费确认和具体提交动作留给外层页面；后续页面接入时只传业务回调和文案。 - 验证：拼图入口测试仍可通过，且新组件可通过不同页面复用而不需要复制上传卡实现。 -- 关联：`src/components/common/CreativeImageInputPanel.tsx`、`src/components/puzzle-agent/PuzzleAgentWorkspace.tsx`。 +- 关联：`src/components/common/CreativeImageInputPanel.tsx`、`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx`。 ## RPG 发布不能只依赖 agent session seed_text @@ -299,6 +346,7 @@ ## Windows provision 下载截断要断点续传而不是回退目标机下载 +- 当前状态：已废弃。2026-06-01 起生产 Jenkins 流水线统一切到 Linux agent，`Genarrative-Server-Provision` 不再维护 Windows 下载阶段。 - 现象：`Genarrative-Server-Provision` 在 `Download Provision Tool Archives` 阶段出现 `curl: (18) end of response ... bytes missing`，常见于 `otelcol-contrib_0.151.0_linux_amd64.tar.gz` 等 GitHub release 大文件。 - 原因：这是 Windows Jenkins 节点到 GitHub 的响应体被截断；若每轮都删除 `.download` 临时文件，就会丢掉已下载部分，下一次又从头开始。 - 处理：Windows 下载函数保留 `${Output}.download`，`curl` 失败时下一轮使用 `-C -` 断点续传；最终只以 GitHub release asset 的 SHA256 `digest` 作为放行条件，完整返回但 digest 不匹配才删除临时文件重新下载。不要把 SpacetimeDB 或 `otelcol-contrib` 下载挪回 Linux 目标机。 @@ -337,12 +385,11 @@ - 验证：`tr '\0' '\n' < /proc/$(systemctl show genarrative-api.service -p MainPID --value)/environ | grep GENARRATIVE_TRACKING_OUTBOX_DIR` 应指向 `/var/lib/genarrative/tracking-outbox`；重启后当前 PID 不再出现 `Permission denied (os error 13)`。 - 关联：`scripts/deploy/production-api-deploy.sh`、`scripts/jenkins-server-provision.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 - ## 外部 API 失败没法追溯先查 external_api_call_failure - 现象：VectorEngine 图片生成 / 编辑接口对前端只表现为 `502` / `504` 或“上游服务请求失败”，但难以区分是请求发送失败、上游 429/5xx、响应解析失败、未返回图片，还是下载图片失败。 - 原因：外部 API 失败如果只靠普通日志，不一定能和 OTLP 指标、trace 与 SpacetimeDB 历史查询稳定关联；重启后也容易丢失上下文。 -- 处理：先查 OTLP 指标 `genarrative.external_api.failures{provider,failure_stage,status_class,retryable}`，再查 `tracking_event` 中 `event_key = 'external_api_call_failure'` 的 `metadata_json`。当前通用 VectorEngine `gpt-image-2-all` 适配器会记录 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel 和 rawExcerpt。 +- 处理：先查 OTLP 指标 `genarrative.external_api.failures{provider,failure_stage,status_class,retryable}`，再查 `tracking_event` 中 `event_key = 'external_api_call_failure'` 的 `metadata_json`。当前通用 VectorEngine `gpt-image-2-all` 适配器会记录 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、errorSource、latencyMs、promptChars、referenceImageCount、imageModel、rawExcerpt 和 requestId。 - 验证：`SELECT event_id, scope_id AS provider, metadata_json, occurred_at FROM tracking_event WHERE event_key = 'external_api_call_failure' ORDER BY occurred_at DESC LIMIT 50;`；如果查不到同时看 tracking outbox 目录权限和 sealed 文件是否堆积。 - 关联：`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 @@ -537,10 +584,18 @@ - 现象：用户通过“忘记密码”重设密码后，接口返回成功或页面进入登录态，但再次使用新密码登录仍提示“手机号或密码错误”；重启后还可能出现 `Bearer JWT 版本已失效`，日志里的 token version 与本地快照不一致。 - 原因：重置/修改密码会更新 `password_hash`、`password_login_enabled` 和 `token_version`，如果 API 层只更新本地 `InMemoryAuthStore`，没有调用 `sync_auth_store_snapshot_to_spacetime()`，`api-server` 重启时可能从旧的 SpacetimeDB 表或旧快照恢复账号状态。 -- 处理：`POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后必须同步认证快照。2026-05-27 起，启动恢复只允许从 SpacetimeDB 正式认证表恢复；`auth_store_snapshot` 只保留行级记录，不再写 `default` 聚合单行，也不再把本地文件 `auth-store.json` / `GENARRATIVE_AUTH_STORE_PATH` 当作恢复源。若启动时连不上 SpacetimeDB，`api-server` 等待启动恢复超时后进入依赖不可用模式，所有请求返回 `503 SERVICE_UNAVAILABLE`，`details.reason = "spacetime_startup_unavailable"`。 +- 处理：`POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后必须同步认证快照。2026-05-27 起，启动恢复只允许从 SpacetimeDB 正式认证表恢复；`auth_store_snapshot` 只保留行级记录，不再写 `default` 聚合单行，也不再把本地文件 `auth-store.json` / `GENARRATIVE_AUTH_STORE_PATH` 当作恢复源。认证创建、登录会话、刷新、退出、改密、重置密码、绑定和资料变更等写操作必须在返回客户端前成功同步 SpacetimeDB；同步失败时接口返回错误，不允许把只存在于当前进程内存的账号或会话当成成功结果。新用户注册奖励、邀请码绑定和登录埋点必须排在认证同步成功之后，避免认证没落库时先写出钱包或邀请关系。若启动时连不上 SpacetimeDB，`api-server` 等待启动恢复超时后进入依赖不可用模式，所有请求返回 `503 SERVICE_UNAVAILABLE`，`details.reason = "spacetime_startup_unavailable"`。 - 验证：执行 `cargo test -p module-auth password --manifest-path server-rs/Cargo.toml` 与 `cargo test -p api-server password --manifest-path server-rs/Cargo.toml`；手测时重设密码后旧密码应失败，新密码应成功，重启后仍应保持。 - 关联：`server-rs/crates/api-server/src/password_management.rs`、`server-rs/crates/api-server/src/state.rs`、`docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md`。 +## 密码登录失败且短信登录提示手机号已存在先查孤儿手机号索引 + +- 现象：老账号用密码登录提示“手机号或密码错误”，改用短信验证码登录又提示“手机号已存在 / 已注册”，用户卡在既不能登录也不能重新创建的状态。 +- 原因：历史版本或停服务时认证同步不完整，可能在 SpacetimeDB `auth_identity(provider=phone)` 或 `module-auth` 快照里留下 `phone_to_user_id` 映射，但对应 `user_account` / `users_by_username` 用户行已经不存在。密码登录按手机号索引找不到真实用户，短信登录尝试创建新用户时又被孤儿手机号索引挡住。 +- 处理：`export_auth_store_snapshot_from_tables` 导出时必须过滤没有 `user_account` 的 phone / wechat identity、union 索引和 refresh session；`module-auth` 从 JSON 快照恢复时也必须二次丢弃指向不存在用户的索引。运行时创建手机号用户前若发现手机号映射指向不存在的用户，应删除孤儿映射后继续创建，避免死锁态继续扩散。 +- 验证：`cargo test -p module-auth snapshot_json_drops_orphan_phone_index_before_phone_login --manifest-path server-rs/Cargo.toml`、`cargo test -p module-auth phone --manifest-path server-rs/Cargo.toml`、`cargo test -p spacetime-module auth --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server phone_login_reuses_existing_user_for_same_phone_number --manifest-path server-rs/Cargo.toml`。 +- 关联：`server-rs/crates/module-auth/src/lib.rs`、`server-rs/crates/spacetime-module/src/auth/procedures.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。 + ## 认证本地文件快照已废弃，旧 procedure 也已删 - 现象：有些旧代码和生成 bindings 里还会残留 `get_auth_store_snapshot`、`upsert_auth_store_snapshot`、`import_auth_store_snapshot`，或者把 `auth-store.json` 误当成认证恢复源。 @@ -685,7 +740,7 @@ - 原因：首图生成只通过 `compile_puzzle_draft.referenceImageSrc` 临时传 Data URL，不持久化到 SpacetimeDB；结果页重新生成则要把当前上传图或关卡 `pictureReference` 作为 `generate_puzzle_images.referenceImageSrc` 继续传给后端。 - 处理：浏览器 Network 里确认 action payload 带 `referenceImageSrc`；api-server 日志按同一 `session_id` 查看 `拼图参考图解析完成`、`拼图 VectorEngine 图片生成 HTTP 返回`、`拼图 VectorEngine 图片下载完成`、`拼图生成图片已写入 OSS 与资产索引`，可定位慢在参考图读取、VectorEngine、下载或 OSS。 - 验证：前端测试覆盖上传图 + AI 重绘、结果页保存的 `pictureReference` 重新生成；后端单测覆盖 VectorEngine 请求体 `image` 字段。 -- 关联：`src/components/puzzle-agent/PuzzleAgentWorkspace.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`server-rs/crates/api-server/src/puzzle.rs`。 +- 关联：`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`server-rs/crates/api-server/src/puzzle.rs`。 ## 拼图首图生成后要把入口参考图写回 `pictureReference` @@ -747,8 +802,8 @@ - 现象：RPG 结果页点击开局 CG 后，`POST /api/runtime/custom-world/opening-cg` 在较长等待后返回“开局 CG 故事板生成失败：创建图片生成任务失败：error sending request for url (https://api.vectorengine.ai/v1/images/generations)”。 - 原因：该故事板会把角色图和首幕背景图作为参考图一起传给 VectorEngine `gpt-image-2-all`，请求体和上游生成耗时都比普通单图更大；若运行中的 `api-server` 仍沿用旧 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`，或者参考图过大，会在请求发送/等待阶段被 reqwest 截断。日志里 `timeout=false connect=false request=true body=false source=client error (SendRequest)` 表示还没拿到上游 HTTP 响应，通常优先怀疑大 JSON 请求体、上游网关中断或 HTTP 协议兼容，而不是业务响应解析失败。直接请求 VectorEngine 若无效 token 可快速返回 401，不能据此判断真实生图不会超时。 -- 处理：开局 CG 参考图入参先压到单边 768 的 JPEG；`/v1/images/generations` 保持 reqwest 默认 HTTP 协商，只有 multipart `/v1/images/edits` 单独强制 HTTP/1.1。后端图片 helper 将 `request_body_bytes`、每张参考图 Data URL 长度、`timeout/connect/body/source/rootSource/sourceChain/endpoint` 分类写入日志和 `error.details`，前端优先展示 `details.reason`。修改 `.env.secrets.local` 后必须重启 `api-server`，`npm run dev` 终端用 `rs api-server`，否则旧进程仍按旧超时运行。 -- 验证：分别运行 `cargo test -p api-server custom_world_ai --manifest-path server-rs/Cargo.toml` 和 `cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml`；真实联调重启后再触发开局 CG，若仍失败看返回的 `details.reason/source/rootSource/sourceChain/timeout/connect/body/endpoint` 和 `logs/api-server/` 同一 request_id。 +- 处理：开局 CG 参考图入参先压到单边 768 的 JPEG；`/v1/images/generations` 保持 reqwest 默认 HTTP 协商，只有 multipart `/v1/images/edits` 单独强制 HTTP/1.1。后端图片 helper 将 `timeout/connect/body/source/source_chain/source_chain_depth/endpoint` 分类写入日志和 `error.details`，失败审计通过 `metadata_json.errorSource/requestId` 保留底层错误链和请求标识。修改 `.env.secrets.local` 后必须重启 `api-server`，`npm run dev` 终端用 `rs api-server`，否则旧进程仍按旧超时运行。 +- 验证：分别运行 `cargo test -p api-server custom_world_ai --manifest-path server-rs/Cargo.toml` 和 `cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml`；真实联调重启后再触发开局 CG，若仍失败看返回的 `details.errorSource/source/timeout/connect/body/endpoint`、`tracking_event.metadata_json.errorSource/requestId` 和 `logs/api-server/` 同一 request_id。 - 关联：`server-rs/crates/api-server/src/custom_world_ai.rs`、`server-rs/crates/api-server/src/custom_world_ai/opening_cg.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 ## 开局 CG 成功后又变空白要保留 profile.openingCg @@ -1122,13 +1177,13 @@ - 验证：发布链路使用当前 `deploy/systemd`、`deploy/nginx`、`scripts/deploy` 和 `jenkins/Jenkinsfile.production-*`。 - 关联：`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。 -## Release Web 产物通过内网 rsync 拉取 +## Web Deploy 只从 Jenkins 构建归档取包 -- 现象：`Genarrative-Web-Deploy` 发布到 `release` 目标时，release agent 本地没有 `/var/cache/genarrative-build/web-artifacts////web.tar.gz`，但 Jenkins controller 又只归档轻量元数据，导致发布阶段找不到 Web 大包。 -- 原因：Web 大包为了避免从 Linux 构建机拉回 Jenkins controller，默认留在构建机稳定缓存目录；development 目标与构建机同机可直接读取，release 目标是独立机器，需要内网同步。 -- 处理：release 服务器的 Jenkins 运行用户配置 SSH Host `genarrative-build-internal` 指向构建机内网地址，`Genarrative-Web-Deploy` 在 `DEPLOY_TARGET=release` 且本地缺少大包时默认执行 `rsync` 拉取同一路径内容；真实内网 IP、用户和私钥路径只放在服务器本机 SSH config，不写入 Jenkinsfile。 -- 验证：在 release 服务器上先手工跑通 `rsync -av --progress "genarrative-build-internal:${SRC}/" "${DST}/"`，再运行 Web Deploy；流水线会继续执行 `web.tar.gz.sha256` 校验。 -- 关联：`jenkins/Jenkinsfile.production-web-deploy`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。 +- 现象：`Genarrative-Web-Deploy` 需要发布 Web 时，不应再在构建机或 release agent 的本地缓存目录查找 `web.tar.gz`。 +- 原因：Web 发布包已经由 `Genarrative-Web-Build` 归档到 Jenkins 构建产物，deploy 阶段继续读本地缓存或通过 `rsync` 回构建机拉包会让 release agent 依赖机器拓扑和本地路径。 +- 处理：`Genarrative-Web-Build` 直接归档 `build//web.tar.gz`、`web.tar.gz.sha256` 和 `release-manifest.json`；`Genarrative-Web-Deploy` 使用 `copyArtifacts` 从指定 `BUILD_JOB_NAME` / `BUILD_NUMBER_TO_DEPLOY` 复制完整产物，不保留 `WEB_ARTIFACT_ROOT`、`WEB_ARTIFACT_SYNC_HOST` 或 `web-artifact-pointer.txt` 口径。 +- 验证：deploy 工作区应直接出现 `build//web.tar.gz` 与 `web.tar.gz.sha256`；后续仍由 `scripts/deploy/production-web-deploy.sh` 执行 checksum 校验和解压 smoke。 +- 关联：`jenkins/Jenkinsfile.production-web-deploy`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 ## Jenkins 生产流水线拉 Git 先本机再域名备用 @@ -1154,12 +1209,12 @@ - 验证：运行 `git ls-files --stage scripts/prepare-server-provision-tools.sh`，确认 mode 为 `100755`；重新跑 `Genarrative-Server-Provision` 时应进入工具下载/打包日志，而不是停在 `Permission denied`。 - 关联：`jenkins/Jenkinsfile.production-server-provision`、`scripts/prepare-server-provision-tools.sh`、`scripts/jenkins-checkout-source.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 -## Server-Provision 下载阶段不要放回 genarrative-build-01 +## Server-Provision 工具准备只在 Linux build 节点做一次 -- 现象：`Genarrative-Server-Provision` 日志里 `Prepare Provision Tools` 显示 `Running on genarrative-build-01 in /root/...`，随后在该节点上下载 GitHub release 或 `install.spacetimedb.com` 失败。 -- 原因：`genarrative-build-01` 在当前 provision 流程里是 Linux 目标发布机/目标 agent，不是用户本地 Windows 下载环境；把下载阶段放在 `linux && genarrative-build` 等于让目标机自己外连。 -- 处理：下载必须发生在 Jenkins `windows` 节点的 `Download Provision Tool Archives` 阶段，先下载 SpacetimeDB Linux release tarball 和 `otelcol-contrib` Linux amd64 包，再 `stash/unstash` 到目标 Linux 节点。目标机执行 `scripts/prepare-server-provision-tools.sh` 时设置 `PROVISION_REQUIRE_LOCAL_DOWNLOADS=true`，缺少下载件直接失败，不回退联网下载。 -- 验证：Jenkins 日志应先出现 `Running on ... windows` 和 `[prepare-provision-downloads] 下载 ...`，目标节点只出现 `[prepare-provision-tools] 使用已下载的 ...`；如果目标节点出现 `下载 otelcol-contrib:` 或 `下载 SpacetimeDB 官方安装器脚本:`，说明又回退到错误路径。 +- 现象：`Genarrative-Server-Provision` 在后续目标发布节点重复执行 `scripts/prepare-server-provision-tools.sh`，或日志里出现目标节点继续访问 GitHub release / `install.spacetimedb.com`。 +- 原因：当前流水线已经改成 Linux build 节点一次性准备 `provision-tools/` 并 stash 给目标发布阶段；如果目标发布阶段又重新准备工具包，就会重复下载并把目标节点暴露到外网依赖。 +- 处理：只允许 `Prepare Provision Tools` 阶段在 `linux && genarrative-build` 节点生成 `provision-tools/`；后续 `Provision Server` 阶段只 `unstash 'server-provision-tools'` 并安装其中的 `spacetime` 与 `otelcol-contrib`，不要再运行 `prepare-server-provision-tools.sh`。 +- 验证：Jenkins 日志应先在 Linux build 节点出现 `[prepare-provision-tools] 工具包已准备`，后续目标发布节点只出现安装 / systemd / Nginx provision 日志；目标节点不应出现 `下载 otelcol-contrib:` 或 `下载 SpacetimeDB 官方安装器脚本:`。 - 关联：`jenkins/Jenkinsfile.production-server-provision`、`scripts/prepare-server-provision-tools.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 ## 个人任务 scope 不得扩成 work/site/module @@ -1439,16 +1494,16 @@ - 现象：拼图创作页或结果页打开“选择历史图片”后，历史列表显示 `账号 user-1` 之类归属文案而不是图片名；`1713686400.000000Z` 这类时间显示为未知；选中后预览或生成参考图可能被怀疑不可用。 - 原因：`/api/assets/history?kind=puzzle_cover_image` 返回的 `ownerLabel` 是资产归属账号，不是图片标题；`createdAt` 可能是 SpacetimeDB / shared-kernel 秒级时间字符串，不能只用浏览器 `new Date(value)` 解析。历史图的 `imageSrc` 是 `/generated-*` 私有兼容路径，浏览器预览必须换签。 - 处理：前端标题和选中标签从 `imageSrc` 路径末尾推导，例如 `image.png`；时间解析兼容 ISO 与 `1713686400.000000Z`；创作页主图、历史列表图和结果页参考图继续用 `ResolvedAssetImage`，提交给后端时仍保留原始 `imageSrc`。 -- 验证：`npm run test -- src/components/puzzle-agent/PuzzleAgentWorkspace.interaction.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`，并执行 `npm run check:encoding`。 -- 关联：`src/services/puzzle-works/puzzleHistoryAsset.ts`、`src/components/puzzle-agent/PuzzleHistoryAssetPickerDialog.tsx`、`docs/technical/ASSET_HISTORY_PUZZLE_COVER_KIND_FIX_2026-04-27.md`。 +- 验证：`npm run test -- src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`，并执行 `npm run check:encoding`。 +- 关联：`src/services/puzzle-works/puzzleHistoryAsset.ts`、`src/components/unified-creation/shared/PuzzleHistoryAssetPickerDialog.tsx`、`docs/technical/ASSET_HISTORY_PUZZLE_COVER_KIND_FIX_2026-04-27.md`。 ## 拼图历史图关闭 AI 重绘不要强制 Data URL - 现象：拼图创作页从历史生成图片中选择主图，再关闭 AI 重绘生成草稿时，后端报“上传图必须是图片 Data URL”。 - 原因：历史图 `imageSrc` 是 `/generated-puzzle-assets/...` 私有兼容路径；AI 重绘开启时后端参考图分支会解析该路径，但关闭 AI 重绘的“直用上传图”分支旧实现只调用 `parse_puzzle_image_data_url`。 - 处理：关闭 AI 重绘时也复用拼图参考图解析入口，允许 Data URL 与 `/generated-*` 历史路径统一转成 `PuzzleDownloadedImage` 后持久化；前端不需要下载历史图再转 base64。 -- 验证：`npm run test -- src/components/puzzle-agent/PuzzleAgentWorkspace.interaction.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`、`cargo test -p api-server puzzle_uploaded_cover_can_reuse_resolved_history_image --manifest-path server-rs\Cargo.toml`、`npm run dev:api-server` 后检查 `/healthz`。 -- 关联：`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`、`src/components/puzzle-agent/PuzzleAgentWorkspace.interaction.test.tsx`。 +- 验证：`npm run test -- src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`、`cargo test -p api-server puzzle_uploaded_cover_can_reuse_resolved_history_image --manifest-path server-rs\Cargo.toml`、`npm run dev:api-server` 后检查 `/healthz`。 +- 关联：`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`、`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx`。 ## 拼图结果页局部生图不要污染草稿生成态 @@ -1466,7 +1521,7 @@ - 原因：上传图直用路径应把 Data URL 或 `/generated-*` 历史图解析后持久化为 `sourceType=uploaded` 的正式候选，再继续生成 9:16 关卡画面、UI spritesheet 和纯背景；如果只把 `aiRedraw=false` 当作“不参考图片生成”，就会误走首图生成。 - 处理：入口页用 payload 的 `aiRedraw` 写入生成页 metadata，`puzzleAiRedraw=false` 时进度跳过 `生成拼图首图`；后端 `compile_puzzle_draft` 和结果页 `generate_puzzle_images` 都在 `aiRedraw=false && referenceImageSrc 非空` 时走上传图直用候选。结果页关卡详情必须复用 `CreativeImageInputPanel`，不要把正式图当成可重绘参考图；本次上传或历史选择的图才显示 AI 重绘开关并可删除。 - 验证：`npm run test -- src/services/miniGameDraftGenerationProgress.test.ts src/components/puzzle-result/PuzzleResultView.test.tsx`、`cargo test -p api-server puzzle_result_level_direct_upload_skips_cover_image_generation --manifest-path server-rs\Cargo.toml`。 -- 关联：`src/services/miniGameDraftGenerationProgress.ts`、`src/components/puzzle-agent/PuzzleAgentWorkspace.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/generation.rs`。 +- 关联：`src/services/miniGameDraftGenerationProgress.ts`、`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/generation.rs`。 ## Jenkins 数据库导入导出脚本先补 Node 工具链 PATH @@ -1478,6 +1533,7 @@ ## Windows Jenkins `powershell` step 在 Stdb module 构建里曾触发 CreateProcess error=5 +- 当前状态：已废弃。`Genarrative-Stdb-Module-Build` 已切到 Linux agent，不再执行 Windows PowerShell 流程。 - 现象：`Genarrative-Stdb-Module-Build` 在 Windows Jenkins 节点上报 `java.io.IOException: Cannot run program "powershell" (in directory "C:\\Users\\DSK\\.jenkins-local\\workspace\\Genarrative-Stdb-Module-Build"): CreateProcess error=5, 拒绝访问。`；日志里能看到 `durable-task` 已写出 `powershellWrapper.ps1`，但在真正启动裸 `powershell` 子进程时失败。 - 原因：Jenkins durable-task 的 `powershell` step 依赖一个隐式命令解析/启动路径，在这台 Windows 本地 Jenkins 环境里会被拒绝。`powershell.exe` 本体和 workspace ACL 都是正常的，问题出在 Jenkins step 的启动方式，而不是 PowerShell 脚本内容。修复后若日志能打印 `[jenkins-powershell] exe:`，但随后仅报 `拒绝访问` / `script returned exit code 5`，通常已经不是 PowerShell 启动失败，而是 Checkout 脚本内部命令在 Windows workspace 里触发权限拒绝。若 `.jenkins-*.ps1` 里中文 `throw '[stdb-build] ...'` 报 `MissingArrayIndexExpression`，则是 Windows PowerShell 5.1 用 `-File` 解析无 BOM UTF-8 脚本时按本地 ANSI 误解码。 - 处理：把 `jenkins/Jenkinsfile.production-stdb-module-build` 的 `Checkout` 和 `Build Stdb Module` 两处 `powershell` step 收口成 `runWindowsPowerShell(...)` helper，先用 `writeFile` 写出临时 `.ps1`，再用显式 `powershell.exe` 把脚本重写成 UTF-8 with BOM，最后通过 `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File ...` 执行。这个 helper 写在 Groovy GString 里时，PowerShell 的 `$path` / `$text` / `$true` 必须写成 `\$path` / `\$text` / `\$true`，否则 Jenkinsfile 会在 Groovy 编译阶段报 `unexpected token: true`。Checkout 阶段优先复用 Jenkins GitSCM 已完成的工作区结果；`COMMIT_HASH` 为空或已经等于当前 `HEAD` 时不再重复 `git fetch` / `git checkout` / `git clean`，只有确实要切到另一个指定 commit 时才补 fetch、归属校验和 checkout。 @@ -1516,14 +1572,30 @@ - 验证：`npm run test -- src/components/rpg-entry/rpgEntryWorldPresentation.test.ts src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`、`npm run check:encoding`。 - 关联：`src/index.css`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/rpg-entry/rpgEntryWorldPresentation.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 -## 生成中草稿刷新后不要复用旧 updatedAt 当展示起点 +## 公开作品卡作者行不要拼手机号或陶泥号 -- 现象：拼图或抓大鹅草稿生成中刷新网页后，作品架卡片能显示等待遮罩，但进入生成页时总进度首帧直接跳到 80%+，看起来像已经跑了一大半。 -- 原因：前端只把持久化 `generationStatus=generating` 当作恢复生成页的条件，但恢复展示时仍沿用了作品摘要 `updatedAt` 作为伪 `startedAtMs`；同时拼图总进度又把后端 `progressPercent` 直接当作 floor，导致 `86%` 之类未到首个里程碑的会话一进页就抬到 80%+。 -- 处理：恢复生成中的草稿时，展示起点改用“进入生成页的当前时间”；`updatedAt` 只保留给作品架排序和摘要，不再参与生成页假进度起算。拼图总进度还要忽略 `88` 以下的后端进度 floor，拼图保留后端里程碑推进，抓大鹅等非拼图玩法则从 `0%` 平滑起步，避免刚进页就看到 4% / 88% / 80%+。 -- 验证：`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating"`、`npm run test -- src/services/miniGameDraftGenerationProgress.test.ts -t "match3d draft generation starts total progress from zero"`。 +- 现象：发现页 / 推荐页公开作品卡作者行显示 `158****3533 · SY-00000003` 这类手机号掩码和陶泥号组合，列表卡片看起来像暴露账号标识。 +- 原因：`resolvePlatformWorkAuthorDisplayName(...)` 曾把公开昵称和 `publicUserCode` 拼接为 `昵称 · SY-*`，并在无法解析公开昵称时直接回退后端卡片里的 `authorDisplayName`；当后端或旧投影把手机号掩码写进展示名时，卡片会原样外露。 +- 处理：公开卡片作者名只取可读公开昵称；识别手机号掩码、单独 `SY-*` 或 `手机号掩码 · SY-*` 时回退为 `玩家`。作品号复制、陶泥号搜索和完整身份展示只放在详情页、搜索或明确复制入口，不塞进卡片作者行。 +- 验证：`npm run test -- src/components/rpg-entry/rpgEntryWorldPresentation.test.ts src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx src/components/platform-entry/PlatformWorkDetailView.test.tsx`。 +- 关联：`src/components/rpg-entry/rpgEntryWorldPresentation.ts`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/platform-entry/PlatformWorkDetailView.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 + +## 生成中草稿恢复要按后端时间戳计时 + +- 现象：拼图或抓大鹅草稿生成中刷新网页后，进入生成页的“已耗时”从 `0 秒` 重新开始；另一类旧问题是后端 `progressPercent=88` 时总进度首帧直接跳到 `88%`。 +- 原因：生成页恢复曾把展示态 `startedAtMs` 重置为进入页面的当前时间，导致计时不跟随后端真实生成时刻；拼图总进度也曾把后端里程碑当作百分比地板，导致步骤刚切换就抬高总进度。 +- 处理：恢复生成中的草稿时，展示起点使用后端 session `updatedAt` 或作品摘要 `updatedAt`；`88/94/96` 只切换当前步骤，不直接作为总进度地板。总进度按已完成步骤权重加当前步骤内假进度推导，非完成态最多停在 `98%`。 +- 验证：`node node_modules/vitest/vitest.mjs run src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating"`、`node node_modules/vitest/vitest.mjs run src/services/miniGameDraftGenerationProgress.test.ts`。 - 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`src/services/miniGameDraftGenerationProgress.ts`、`docs/【玩法创作】拼图生成页进度口径-2026-05-23.md`。 +## 生成失败草稿回到作品架不能继续显示生成中 + +- 现象：拼图生成页已经收到 VectorEngine 图片编辑失败并进入重试态，但用户返回草稿 Tab 后，同一草稿仍显示“生成中”；连续触发多个拼图生成时，失败后还可能只剩一条新增草稿，或者只看到标题为“第1关”的半成品空壳；抓大鹅后台失败时也可能没有任何通知，点击草稿又像重新开始生成。 +- 原因：前端失败 notice 只更新生成页局部状态，pending 作品架条目在失败时被清掉或被非 `generating` 状态误映射为 `ready`；后端作品摘要也可能短暂仍是 `generationStatus=generating`。如果失败消息没有写入 notice，用户离开生成页后不会弹出 `PlatformErrorDialog`；如果打开草稿只看持久化 `generating`，就会绕过失败态恢复。 +- 处理：失败时按 session 保留 pending 作品架条目并标记 `failed`，失败 notice 保存错误消息并触发带来源的 `PlatformErrorDialog`；拼图契约没有 `failed` 枚举，pending 拼图映射为 `idle`，同时用本地失败 notice 覆盖持久化生成中状态和旧的“正在生成”摘要。点击失败草稿应优先用 notice / 后端 session / fallback payload 组装失败生成页，不能重新从 0 秒启动新进度；拼图失败半成品没有有效 `workTitle` 时，作品架标题回退为“拼图草稿”。 +- 验证：`node node_modules/vitest/vitest.mjs run src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "failed parallel puzzle|background match3d"`。 +- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/custom-world-home/creationWorkShelf.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 + ## 汪汪声浪草稿试玩不要写正式 run - 现象：如果草稿结果页试玩和发布后 runtime 共用同一写成绩路径，未发布或未确认资源的草稿试玩会污染正式单局、排行榜和作品统计。 @@ -1537,6 +1609,13 @@ - 现象：移动端创作 Tab 里进入汪汪声浪表单后，页面右侧出现不自然的内层滚动条，最后的形象描述输入框容易被“生成草稿”按钮、键盘或底部 TabBar 挤压 / 遮挡；顶部玩法卡首尾也可能贴边显得被裁。 - 原因：外层 `.platform-tab-panel` 已经是纵向滚动容器，创作页中间又有多层 `overflow-hidden`，旧的 `BarkBattleConfigEditor` 根节点再加 `overflow-y-auto`，形成外层 Tab 面板 + 内层表单的套滚动；底部按钮只预留 safe-area，不预留真实操作区距离；顶部玩法卡横向滚动条隐藏且首尾没有 scroll padding。 - 处理：移动端让 Bark Battle 表单跟随父级滚动，`lg` 以上才恢复表单内滚动；创作页容器移动端使用 `overflow-visible` 和 safe-area 底部 padding；顶部模板 tablist 加 `scroll-px-3` / 横向 padding，移动端卡片宽度收窄，避免首尾 ring 和圆角贴边裁切。 + +## 统一创作页不要把竖屏滚动锁进内部内容区 + +- 现象：竖屏打开拼图、抓大鹅或敲木鱼创作页时，浏览器页面本身无法滚动，生成按钮或右侧表单面板落到视口外；木鱼的敲击音效和功德词条看起来像被塞进单独滑动窗口。 +- 原因：平台根壳固定一屏并隐藏溢出，`UnifiedCreationPage` 又使用 `h-full min-h-0 overflow-hidden` 和内容区 `overflow-y-auto`，导致滚动责任落到内部内容窗，而不是整个创作 stage。 +- 处理：`UnifiedCreationPage` 统一负责标题、隐藏字段契约、内容包装和页面级纵向滚动；拼图、抓大鹅、跳一跳和敲木鱼的外层 `motion.div` 不再额外包 `overflow-y-auto`。各工作台在 `unifiedChrome` 下收起旧 `h-full overflow-hidden` 外壳，让表单主体跟随统一页面滚动。 +- 验证：用竖屏浏览器视口打开 `/creation/wooden-fish`、`/creation/puzzle`、`/creation/match3d` 和 `/creation/jump-hop`，统一创作页应可滚动到生成按钮；`.unified-creation-page` 应包含页面级 `overflow-y-auto`，木鱼工作台内部也不应出现独立纵向滚动容器，拼图 / 抓大鹅可见标题不应重复。 - 验证：`npm run test -- src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "create tab shows template tabs"`、移动端视口检查最后一个输入框与“生成草稿”按钮不重叠。 - 关联：`src/components/bark-battle-creation/BarkBattleConfigEditor.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 @@ -1596,6 +1675,14 @@ - 验证：移动端视口检查视频 `rect` 应覆盖整个视口，`paused` 应最终变为 `false`，`currentTime` 应持续前进。 - 关联：`src/components/GenerationProgressHero.tsx`、`docs/【玩法创作】生成页圆环布局口径-2026-05-23.md`。 +## 跳一跳结果页直达时不要把恢复面板当成空白页 + +- 现象：浏览器直接打开 `/creation/jump-hop/result`，如果没有 `sessionId`、`profileId`、`draftId` 或 `workId`，页面以前会看起来像空白，容易误判成结果页坏了。 +- 原因：跳一跳结果页恢复原先只盯 `jumpHopSession.draft`，没有把“缺恢复信息”明确兜成可见恢复面板；直达结果页时也没有优先用 `profileId -> getWorkDetail` 补回完整作品。 +- 处理：`PlatformEntryFlowShellImpl` 的跳一跳恢复逻辑改成先尝试 `profileId -> getWorkDetail`，再尝试 `sessionId -> getSession`；两者都没有时显示 `跳一跳草稿未恢复` 和 `返回创作`，不再留空白页。 +- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "direct jump hop result route"`，并手测 `/creation/jump-hop/result` 与 `/creation/jump-hop/result?profileId=` 两种情况。 +- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`。 + 2026-05-24 补充：`GenerationPageBackdrop` 不要通过 portal 挂到 `document.body`。body 级 fixed 背景会逃离生成页自己的 stacking context，即使业务内容有局部 `z-10`，真实浏览器里也可能把整页 UI 压住。背景视频应作为生成页根容器子节点保留 `fixed inset-0 z-0`，生成页内容保持 `relative z-10`；相关测试应同时断言背景容器低层级、生成页根容器高层级，以及视频节点仍在生成页 DOM 内部。视觉调整时还要记住：空心圆环的中心块要抽掉，时间卡与总进度标题都应缩小，不要让生成页再回到“纯色底 + 大字号说明卡”的状态。顶部返回和右上状态也不能沿用 `text-lg` / `sm:text-2xl` 这类展示级字号；当前步骤名、步骤状态和底部玩法信息标题要维持普通 UI 字号档位，优先保持 `text-xs` 到 `text-sm` 区间。 2026-05-24 补充：生成页“预计等待 / 已耗时”卡片本身已经有标签，传给 `GenerationProgressHero` 的值只能是纯时间，例如 `4 分钟`、`1 分 15 秒`，不要再拼接“预计还需”或“已耗时”；两张时间卡也要和当前步骤卡一样保持半透明。拼图总进度初始帧必须允许显示 `0%`，不要再用 `Math.max(1, nextProgress)` 之类的保护把启动态抬到 `1%`。 diff --git a/.hermes/shared-memory/project-overview.md b/.hermes/shared-memory/project-overview.md index 45ffc1e4..f1503f39 100644 --- a/.hermes/shared-memory/project-overview.md +++ b/.hermes/shared-memory/project-overview.md @@ -1,6 +1,6 @@ # Genarrative 项目共享概览 -更新时间：`2026-05-15` +更新时间：`2026-05-29` ## 一句话定位 @@ -33,6 +33,8 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A server-rs + Axum + SpacetimeDB ``` +当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.3.0` 对齐。 + 职责边界： - `api-server`：HTTP / SSE / BFF 门面和外部副作用编排。 diff --git a/.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md b/.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md index 9e7e0b86..f2262353 100644 --- a/.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md +++ b/.hermes/skills/genarrative-dev-stack-port-routing/SKILL.md @@ -34,6 +34,8 @@ metadata: 端口不可用时，脚本会从优先端口开始向后寻找可用端口。后续流程必须以解析后的实际端口为准，不能继续使用默认端口。 +Linux 多用户并发开发时，`GENARRATIVE_DEV_PORT_RANGE` 或 `--port-range` 会先向系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json` 申请一个端口段，再把该段映射为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`adminWeb = start + 3`。注册表锁文件是 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。自动分配从 `10000-10099` 起，每次占用 100 个端口块，后续块按 `10100-10199`、`10200-10299` 递增；当前口径是“一个用户固定占用一个段，后续启动继续复用这段并在段内漂移”；该注册表只在 Linux 上生效；Windows 继续沿用原有端口探测、漂移和复用逻辑，不读系统级注册表。 + ## 实现入口 - `package.json` @@ -43,10 +45,12 @@ metadata: - `isPortAvailable(...)`：探测端口是否可监听。 - `findAvailablePort(...)`：从优先端口向后寻找可用端口，`0` 表示申请临时端口。 - `resolveDevStackPorts(...)`：一次性解析 SpacetimeDB、api-server、主站 Vite、后台 Vite 端口，并避免本次解析结果互相冲突。 + - Linux 注册表分配：`reserveLinuxDevPortRange(...)` / `releaseLinuxDevPortRange(...)`，仅在 Linux 上启用系统级端口段登记与用户段复用，自动分配从 `10000-10099` 起。 - CLI 模式：`node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:3101 api:127.0.0.1:8082 web:0.0.0.0:3000 adminWeb:127.0.0.1:3102`。 - `scripts/dev.mjs` - 解析 CLI 参数后统一计算 client host、端口、`SPACETIME_SERVER`、`RUST_SERVER_TARGET`。 - 完整栈按 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 顺序启动。 + - Linux 下会先申请系统级端口段并把它映射成四个 dev 端口；自动分配从 `10000-10099` 起，Windows 则直接沿用原有参数解析与端口漂移逻辑。 - 单模块命令复用同一套参数和 env 解析。 ## 必须保持的传递链路 @@ -60,6 +64,7 @@ metadata: 5. 主站 Vite：`RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET`、`ADMIN_WEB_TARGET`、`ADMIN_WEB_PORT`、`--port=${WEB_PORT}`、`--host=${WEB_HOST}`。 6. 后台 Vite：`ADMIN_API_TARGET`、`GENARRATIVE_API_TARGET`、`GENARRATIVE_API_PORT`、`--port=${ADMIN_WEB_PORT}`。 7. 控制台日志：`[dev:ports]` 和 `[dev] web/admin web/api-server/spacetime` 必须显示最终实际地址。 +8. Linux 端口段注册：`[dev] port-range:` 与 `[dev] port-range-registry:` 只在 Linux 输出，Windows 不应依赖系统级注册表。 如果只改了其中一段，通常会出现：浏览器打开的前端可用，但 `/api/*` 代理到旧端口；后台页面可用但后台 API 失败；SpacetimeDB 启动在新端口但 publish 仍发往旧端口。 @@ -76,6 +81,7 @@ metadata: 4. 修改 watch 时保持模块边界：SpacetimeDB 只监听 `spacetime-module` 且改动后重新 publish，不重启 standalone 宿主；api-server 排除 `spacetime-module`；web/admin-web 源码变化交给 Vite 自身 HMR，外层调度器不要再监听前端目录重启 Vite。 5. 修改 `dev:web` 时不要自动改后端目标策略；`dev:web` 只负责主站 Vite 端口可用性与已有后端目标选择。 6. 同步更新技术文档和团队共享记忆。 +7. 如果修改 Linux 端口段注册口径，确认 Windows 分支仍保持旧行为，不要把系统级注册表逻辑扩散到 Windows。 ## 测试与验证 @@ -113,6 +119,7 @@ node scripts/dev-stack-port-utils.mjs resolve-dev-stack spacetime:127.0.0.1:0 ap ## 验收清单 - [ ] 端口工具有测试覆盖端口被占用和多端口互斥解析。 +- [ ] Linux 注册表分配、同用户复用固定段并继续漂移、自动分配从 `10000-10099` 起、Windows bypass 都有测试覆盖。 - [ ] `scripts/dev.mjs` 通过 `node --check`。 - [ ] `npm run dev` 的 SpacetimeDB、publish、api-server、主站 Vite、后台 Vite 都使用实际端口。 - [ ] `npm run dev:web` 在主站端口不可用时能切换到可用端口。 diff --git a/apps/admin-web/src/api/adminApiClient.ts b/apps/admin-web/src/api/adminApiClient.ts index 1b8d7f9c..ef176285 100644 --- a/apps/admin-web/src/api/adminApiClient.ts +++ b/apps/admin-web/src/api/adminApiClient.ts @@ -1,4 +1,5 @@ import type { + AdminUpsertCreationEntryEventBannersRequest, AdminUpsertCreationEntryTypeConfigRequest, AdminCreationEntryConfigResponse, AdminDebugHttpRequest, @@ -197,6 +198,21 @@ export function upsertAdminCreationEntryConfig( ); } +/** 保存创作入口公告表单序列化后的后端传输字段。 */ +export function upsertAdminCreationEntryBanners( + token: string, + payload: AdminUpsertCreationEntryEventBannersRequest, +) { + return request( + '/admin/api/creation-entry/config/banners', + { + method: 'POST', + token, + body: payload, + }, + ); +} + export function listAdminWorkVisibility(token: string) { return request( '/admin/api/works/visibility', diff --git a/apps/admin-web/src/api/adminApiTypes.ts b/apps/admin-web/src/api/adminApiTypes.ts index 6bcb7c11..83672193 100644 --- a/apps/admin-web/src/api/adminApiTypes.ts +++ b/apps/admin-web/src/api/adminApiTypes.ts @@ -144,10 +144,25 @@ export interface AdminTrackingEventListQuery { } +/** 后台创作入口配置响应，同时包含模板入口和独立公告配置。 */ export interface AdminCreationEntryConfigResponse { entries: AdminCreationEntryTypeConfigPayload[]; + eventBanners: AdminCreationEntryEventBannerPayload[]; } +/** 后台创作入口公告位配置项；旧结构化 banner 字段仅保留兼容。 */ +export interface AdminCreationEntryEventBannerPayload { + title: string; + description: string; + coverImageSrc: string; + prizePoolMudPoints: number; + startsAtText: string; + endsAtText: string; + renderMode: 'structured' | 'html'; + htmlCode?: string | null; +} + +/** 后台单个创作模板入口配置，公告不再绑定在某一个入口上。 */ export interface AdminCreationEntryTypeConfigPayload { id: string; title: string; @@ -161,8 +176,10 @@ export interface AdminCreationEntryTypeConfigPayload { categoryLabel: string; categorySortOrder: number; updatedAtMicros: number; + unifiedCreationSpec?: UnifiedCreationSpecPayload | null; } +/** 后台保存创作模板入口开关与统一创作契约的请求体。 */ export interface AdminUpsertCreationEntryTypeConfigRequest { id: string; title: string; @@ -175,6 +192,31 @@ export interface AdminUpsertCreationEntryTypeConfigRequest { categoryId: string; categoryLabel: string; categorySortOrder: number; + unifiedCreationSpec?: UnifiedCreationSpecPayload | null; +} + +/** 后台保存创作入口公告表单序列化结果的请求体。 */ +export interface AdminUpsertCreationEntryEventBannersRequest { + /** 传输字段沿用后端契约，内容由后台表单生成。 */ + eventBannersJson: string; +} + +/** 后台统一创作工作台契约表单的传输结构。 */ +export interface UnifiedCreationSpecPayload { + playId: string; + title: string; + workspaceStage: string; + generationStage: string; + resultStage: string; + fields: UnifiedCreationFieldPayload[]; +} + +/** 后台统一创作字段契约，保存前会校验字段类型和必填标记。 */ +export interface UnifiedCreationFieldPayload { + id: string; + kind: 'text' | 'select' | 'image' | 'audio'; + label: string; + required: boolean; } export interface AdminWorkVisibilityEntryPayload { diff --git a/apps/admin-web/src/app/AdminApp.tsx b/apps/admin-web/src/app/AdminApp.tsx index e6327c48..9d50f380 100644 --- a/apps/admin-web/src/app/AdminApp.tsx +++ b/apps/admin-web/src/app/AdminApp.tsx @@ -200,6 +200,13 @@ export function AdminApp() { onResultChange={setInviteResult} /> ) : null} + {routeId === 'creation-announcement' ? ( + + ) : null} {routeId === 'creation-entry' ? ( ; diff --git a/apps/admin-web/src/app/adminRoutes.test.ts b/apps/admin-web/src/app/adminRoutes.test.ts new file mode 100644 index 00000000..bae46be8 --- /dev/null +++ b/apps/admin-web/src/app/adminRoutes.test.ts @@ -0,0 +1,16 @@ +import {expect, test} from 'vitest'; + +import {adminRoutes, resolveAdminRoute, routeHash} from './adminRoutes'; + +// 中文注释：后台入口公告必须作为独立导航存在，避免公告表单被误藏在入口开关页。 +test('后台入口公告路由可通过导航和 hash 访问', () => { + expect(adminRoutes).toContainEqual({ + id: 'creation-announcement', + label: '入口公告', + hash: '#creation-announcement', + }); + expect(resolveAdminRoute('#creation-announcement')).toBe( + 'creation-announcement', + ); + expect(routeHash('creation-announcement')).toBe('#creation-announcement'); +}); diff --git a/apps/admin-web/src/app/adminRoutes.ts b/apps/admin-web/src/app/adminRoutes.ts index c84459ae..3b6ed6c3 100644 --- a/apps/admin-web/src/app/adminRoutes.ts +++ b/apps/admin-web/src/app/adminRoutes.ts @@ -1,3 +1,4 @@ +/** 后台单页应用可导航的路由标识，入口公告独立于入口开关维护。 */ export type AdminRouteId = | 'overview' | 'tables' @@ -7,9 +8,11 @@ export type AdminRouteId = | 'invite' | 'tasks' | 'recharge-products' + | 'creation-announcement' | 'creation-entry' | 'work-visibility'; +/** 后台导航项定义，hash 是浏览器地址栏和移动底栏共用入口。 */ export interface AdminRouteDefinition { id: AdminRouteId; label: string; @@ -25,10 +28,12 @@ export const adminRoutes: AdminRouteDefinition[] = [ {id: 'invite', label: '邀请码', hash: '#invite'}, {id: 'tasks', label: '任务配置', hash: '#tasks'}, {id: 'recharge-products', label: '充值商品', hash: '#recharge-products'}, + {id: 'creation-announcement', label: '入口公告', hash: '#creation-announcement'}, {id: 'creation-entry', label: '入口开关', hash: '#creation-entry'}, {id: 'work-visibility', label: '作品可见性', hash: '#work-visibility'}, ]; +/** 根据地址栏 hash 解析后台路由，未知 hash 回落到总览页。 */ export function resolveAdminRoute(hash: string): AdminRouteId { const normalizedHash = hash.trim().toLowerCase().split('?')[0] ?? ''; return ( @@ -37,6 +42,7 @@ export function resolveAdminRoute(hash: string): AdminRouteId { ); } +/** 根据后台路由标识反查 hash，供导航点击时同步地址栏。 */ export function routeHash(routeId: AdminRouteId) { return ( adminRoutes.find((route) => route.id === routeId)?.hash ?? diff --git a/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.test.tsx b/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.test.tsx new file mode 100644 index 00000000..da9362d7 --- /dev/null +++ b/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.test.tsx @@ -0,0 +1,236 @@ +/* @vitest-environment jsdom */ + +import {fireEvent, render, screen, waitFor} from '@testing-library/react'; +import userEvent from '@testing-library/user-event'; +import {beforeEach, expect, test, vi} from 'vitest'; + +import { + getAdminCreationEntryConfig, + upsertAdminCreationEntryBanners, + upsertAdminCreationEntryConfig, +} from '../api/adminApiClient'; +import type { + AdminCreationEntryConfigResponse, + UnifiedCreationSpecPayload, +} from '../api/adminApiTypes'; +import {AdminCreationEntrySwitchPage} from './AdminCreationEntrySwitchPage'; + +vi.mock('../api/adminApiClient', () => ({ + formatAdminApiError: vi.fn((error: unknown) => + error instanceof Error ? error.message : '请求失败', + ), + getAdminCreationEntryConfig: vi.fn(), + isAdminApiError: vi.fn(() => false), + upsertAdminCreationEntryBanners: vi.fn(), + upsertAdminCreationEntryConfig: vi.fn(), +})); + +const puzzleSpec: UnifiedCreationSpecPayload = { + playId: 'puzzle', + title: '想做个什么玩法？', + workspaceStage: 'puzzle-agent-workspace', + generationStage: 'puzzle-generating', + resultStage: 'puzzle-result', + fields: [ + { + id: 'pictureDescription', + kind: 'text', + label: '画面描述', + required: true, + }, + ], +}; + +const configResponse: AdminCreationEntryConfigResponse = { + eventBanners: [ + { + title: '创作公告', + description: '', + coverImageSrc: '', + prizePoolMudPoints: 0, + startsAtText: '', + endsAtText: '', + renderMode: 'html', + htmlCode: '
后台公告
', + }, + ], + entries: [ + { + id: 'puzzle', + title: '拼图', + subtitle: '拼图关卡创作', + badge: '可创建', + imageSrc: '/creation-type-references/puzzle.webp', + visible: true, + open: true, + sortOrder: 30, + categoryId: 'recommended', + categoryLabel: '热门推荐', + categorySortOrder: 20, + updatedAtMicros: 1, + unifiedCreationSpec: puzzleSpec, + }, + ], +}; + +beforeEach(() => { + vi.clearAllMocks(); + vi.mocked(getAdminCreationEntryConfig).mockResolvedValue(configResponse); + vi.mocked(upsertAdminCreationEntryBanners).mockResolvedValue(configResponse); + vi.mocked(upsertAdminCreationEntryConfig).mockResolvedValue(configResponse); +}); + +test('创作入口后台展示并保存统一创作契约', async () => { + const user = userEvent.setup(); + const {container} = render( + , + ); + + await screen.findByText('pictureDescription'); + expect(container.querySelector('.admin-subsection .admin-info-list')).not.toBeNull(); + expect(container.querySelector('.admin-panel .admin-panel')).toBeNull(); + expect(container.querySelector('.admin-muted')).toBeNull(); + + await user.click(screen.getByRole('button', {name: '保存入库'})); + await user.click(screen.getByRole('button', {name: '确认'})); + + await waitFor(() => { + expect(upsertAdminCreationEntryConfig).toHaveBeenCalledWith( + 'admin-token', + expect.objectContaining({ + id: 'puzzle', + unifiedCreationSpec: puzzleSpec, + }), + ); + }); +}); + +test('创作入口后台拒绝 playId 不一致的统一创作契约', async () => { + const user = userEvent.setup(); + render( + , + ); + + const textarea = await screen.findByLabelText('契约 JSON'); + fireEvent.change(textarea, { + target: { + value: JSON.stringify({ + ...puzzleSpec, + playId: 'match3d', + }), + }, + }); + await user.click(screen.getByRole('button', {name: '保存入库'})); + + expect(await screen.findByText('统一创作契约 playId 必须与入口 ID 一致')).toBeTruthy(); + expect(upsertAdminCreationEntryConfig).not.toHaveBeenCalled(); +}); + +test('创作入口后台用表单保存公告配置', async () => { + const user = userEvent.setup(); + render( + , + ); + + expect(await screen.findAllByRole('heading', {name: '创作入口公告'})).toHaveLength(2); + expect(screen.queryByLabelText('公告代码 JSON')).toBeNull(); + fireEvent.change(await screen.findByLabelText('公告 1 标题'), { + target: {value: '周末创作赛'}, + }); + fireEvent.change(screen.getByLabelText('公告 1 HTML'), { + target: {value: '
新的入口公告
'}, + }); + await user.click(screen.getByRole('button', {name: '新增公告'})); + fireEvent.change(screen.getByLabelText('公告 2 标题'), { + target: {value: '第二条公告'}, + }); + fireEvent.change(screen.getByLabelText('公告 2 HTML'), { + target: {value: '
轮播第二条
'}, + }); + await user.click(screen.getByRole('button', {name: '保存公告'})); + await user.click(screen.getByRole('button', {name: '确认'})); + + await waitFor(() => { + expect(upsertAdminCreationEntryBanners).toHaveBeenCalled(); + }); + const [, payload] = vi.mocked(upsertAdminCreationEntryBanners).mock.calls[0]!; + expect(JSON.parse(payload.eventBannersJson)).toEqual([ + { + title: '周末创作赛', + htmlCode: '
新的入口公告
', + }, + { + title: '第二条公告', + htmlCode: '
轮播第二条
', + }, + ]); + expect(JSON.parse(payload.eventBannersJson)[0]).not.toHaveProperty( + 'description', + ); + expect(JSON.parse(payload.eventBannersJson)[0]).not.toHaveProperty( + 'coverImageSrc', + ); +}); + +test('创作入口后台把旧结构化公告回显成 HTML 表单', async () => { + vi.mocked(getAdminCreationEntryConfig).mockResolvedValueOnce({ + ...configResponse, + eventBanners: [ + { + title: '旧公告 <标题>', + description: '旧描述 & 需要转义', + coverImageSrc: '/legacy.png', + prizePoolMudPoints: 120, + startsAtText: '2026-06-01', + endsAtText: '2026-06-30', + renderMode: 'structured', + }, + ], + }); + + render( + , + ); + + expect(await screen.findByLabelText('公告 1 标题')).toHaveProperty( + 'value', + '旧公告 <标题>', + ); + expect(screen.getByLabelText('公告 1 HTML')).toHaveProperty( + 'value', + '

旧公告 <标题>

旧描述 & 需要转义

', + ); +}); + +test('创作入口后台拒绝空公告表单', async () => { + const user = userEvent.setup(); + render( + , + ); + + fireEvent.change(await screen.findByLabelText('公告 1 标题'), { + target: {value: ''}, + }); + fireEvent.change(screen.getByLabelText('公告 1 HTML'), { + target: {value: ''}, + }); + await user.click(screen.getByRole('button', {name: '保存公告'})); + + expect(await screen.findByText('公告 1 标题和 HTML 都不能为空')).toBeTruthy(); + expect(upsertAdminCreationEntryBanners).not.toHaveBeenCalled(); +}); diff --git a/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.tsx b/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.tsx index fb817c65..9de00709 100644 --- a/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.tsx +++ b/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.tsx @@ -1,24 +1,49 @@ -import {RefreshCcw, Save} from 'lucide-react'; -import {FormEvent, useEffect, useState} from 'react'; +import { Plus, RefreshCcw, Save, Trash2 } from 'lucide-react'; +import { FormEvent, useEffect, useState } from 'react'; import { getAdminCreationEntryConfig, + upsertAdminCreationEntryBanners, upsertAdminCreationEntryConfig, } from '../api/adminApiClient'; -import type {AdminCreationEntryTypeConfigPayload} from '../api/adminApiTypes'; -import {useAdminWriteConfirm} from '../components/useAdminWriteConfirm'; -import {handlePageError} from './pageUtils'; +import type { + AdminCreationEntryEventBannerPayload, + AdminCreationEntryTypeConfigPayload, + UnifiedCreationFieldPayload, + UnifiedCreationSpecPayload, +} from '../api/adminApiTypes'; +import { useAdminWriteConfirm } from '../components/useAdminWriteConfirm'; +import { handlePageError } from './pageUtils'; +/** 创作入口后台页面参数；公告模式只展示底部加号入口公告表单。 */ interface AdminCreationEntrySwitchPageProps { token: string; onUnauthorized: (message?: string) => void; + mode?: 'switches' | 'announcements'; } +/** 后台公告表单的一行编辑态，保存时会统一序列化为后端传输字段。 */ +type AnnouncementFormItem = { + id: string; + title: string; + htmlCode: string; +}; + +/** 公告表单保存前的校验与序列化结果。 */ +type AnnouncementFormBuildResult = + | { ok: true; json: string } + | { ok: false; message: string }; + +let announcementFormItemSequence = 0; + export function AdminCreationEntrySwitchPage({ token, onUnauthorized, + mode = 'switches', }: AdminCreationEntrySwitchPageProps) { - const [entries, setEntries] = useState([]); + const [entries, setEntries] = useState< + AdminCreationEntryTypeConfigPayload[] + >([]); const [selectedId, setSelectedId] = useState('puzzle'); const [title, setTitle] = useState(''); const [subtitle, setSubtitle] = useState(''); @@ -27,14 +52,21 @@ export function AdminCreationEntrySwitchPage({ const [visible, setVisible] = useState(true); const [open, setOpen] = useState(true); const [sortOrder, setSortOrder] = useState('30'); - const [categoryId, setCategoryId] = useState('recent'); - const [categoryLabel, setCategoryLabel] = useState('最近创作'); - const [categorySortOrder, setCategorySortOrder] = useState('10'); + const [categoryId, setCategoryId] = useState('recommended'); + const [categoryLabel, setCategoryLabel] = useState('热门推荐'); + const [categorySortOrder, setCategorySortOrder] = useState('20'); + const [unifiedCreationSpecJson, setUnifiedCreationSpecJson] = useState(''); + const [announcementItems, setAnnouncementItems] = useState< + AnnouncementFormItem[] + >([]); const [isLoading, setIsLoading] = useState(false); const [isSaving, setIsSaving] = useState(false); + const [isSavingBanners, setIsSavingBanners] = useState(false); const [listErrorMessage, setListErrorMessage] = useState(''); const [errorMessage, setErrorMessage] = useState(''); - const {confirmWrite, confirmDialog} = useAdminWriteConfirm(); + const [bannerErrorMessage, setBannerErrorMessage] = useState(''); + const { confirmWrite, confirmDialog } = useAdminWriteConfirm(); + const isAnnouncementMode = mode === 'announcements'; useEffect(() => { void refreshEntries(); @@ -48,8 +80,11 @@ export function AdminCreationEntrySwitchPage({ const response = await getAdminCreationEntryConfig(token); const nextEntries = sortEntries(response.entries); setEntries(nextEntries); + setAnnouncementItems(formatEventBannersFormItems(response.eventBanners)); fillForm( - nextEntries.find((entry) => entry.id === selectedId) ?? nextEntries[0] ?? null, + nextEntries.find((entry) => entry.id === selectedId) ?? + nextEntries[0] ?? + null, ); } catch (error: unknown) { handlePageError(error, onUnauthorized, setListErrorMessage); @@ -66,6 +101,14 @@ export function AdminCreationEntrySwitchPage({ const targetId = selectedId.trim(); setErrorMessage(''); + const unifiedCreationSpecResult = parseUnifiedCreationSpecJson( + targetId, + unifiedCreationSpecJson, + ); + if (!unifiedCreationSpecResult.ok) { + setErrorMessage(unifiedCreationSpecResult.message); + return; + } const confirmed = await confirmWrite({ action: '保存创作入口开关', target: targetId, @@ -88,9 +131,11 @@ export function AdminCreationEntrySwitchPage({ categoryId: categoryId.trim(), categoryLabel: categoryLabel.trim(), categorySortOrder: parseInteger(categorySortOrder), + unifiedCreationSpec: unifiedCreationSpecResult.spec, }); const nextEntries = sortEntries(response.entries); setEntries(nextEntries); + setAnnouncementItems(formatEventBannersFormItems(response.eventBanners)); fillForm(nextEntries.find((entry) => entry.id === targetId) ?? null); } catch (error: unknown) { handlePageError(error, onUnauthorized, setErrorMessage); @@ -99,6 +144,40 @@ export function AdminCreationEntrySwitchPage({ } } + /** 保存底部加号创作入口页的多公告表单配置。 */ + async function handleSaveBanners() { + if (isSavingBanners) { + return; + } + + setBannerErrorMessage(''); + const bannerJsonResult = buildEventBannersJsonFromForm(announcementItems); + if (!bannerJsonResult.ok) { + setBannerErrorMessage(bannerJsonResult.message); + return; + } + const confirmed = await confirmWrite({ + action: '保存创作入口公告', + target: 'creation-entry-announcements', + }); + if (!confirmed) { + return; + } + + setIsSavingBanners(true); + try { + const response = await upsertAdminCreationEntryBanners(token, { + eventBannersJson: bannerJsonResult.json, + }); + setEntries(sortEntries(response.entries)); + setAnnouncementItems(formatEventBannersFormItems(response.eventBanners)); + } catch (error: unknown) { + handlePageError(error, onUnauthorized, setBannerErrorMessage); + } finally { + setIsSavingBanners(false); + } + } + function fillForm(entry: AdminCreationEntryTypeConfigPayload | null) { if (!entry) { return; @@ -114,14 +193,53 @@ export function AdminCreationEntrySwitchPage({ setCategoryId(entry.categoryId); setCategoryLabel(entry.categoryLabel); setCategorySortOrder(String(entry.categorySortOrder)); + setUnifiedCreationSpecJson( + formatUnifiedCreationSpecJson(entry.unifiedCreationSpec), + ); + } + + /** 更新单条公告表单字段，避免后台页面直接暴露 JSON 编辑。 */ + function updateAnnouncementItem( + index: number, + patch: Partial>, + ) { + setAnnouncementItems((currentItems) => + currentItems.map((item, itemIndex) => + itemIndex === index ? { ...item, ...patch } : item, + ), + ); + } + + /** 新增一条空公告表单行。 */ + function addAnnouncementItem() { + setAnnouncementItems((currentItems) => [ + ...currentItems, + createAnnouncementFormItem('', ''), + ]); + } + + /** 删除指定公告表单行，至少保留一条空行供继续编辑。 */ + function removeAnnouncementItem(index: number) { + setAnnouncementItems((currentItems) => { + const nextItems = currentItems.filter( + (_, itemIndex) => itemIndex !== index, + ); + return nextItems.length > 0 + ? nextItems + : [createAnnouncementFormItem('', '')]; + }); } return (
-

创作入口开关

-

控制创作中心入口展示与运行态路由可用性

+

{isAnnouncementMode ? '创作入口公告' : '创作入口开关'}

+

+ {isAnnouncementMode + ? '配置底部加号创作入口页的公告轮播' + : '控制创作中心入口展示与运行态路由可用性'} +

- - -
-
- - - - - - - - - - - - {entries.map((entry) => ( - - - - - - - - ))} - -
入口展示开放分类排序
- - {entry.visible ? '是' : '否'}{entry.open ? '是' : '否'}{entry.categoryLabel || entry.categoryId}{entry.sortOrder}
+ {announcementItems.map((item, index) => ( +
+
+ {`公告 ${index + 1}`} + +
+ +