diff --git a/.hermes/shared-memory/decision-log.md b/.hermes/shared-memory/decision-log.md index 084009e7..2c4a975c 100644 --- a/.hermes/shared-memory/decision-log.md +++ b/.hermes/shared-memory/decision-log.md @@ -16,6 +16,22 @@ --- +## 2026-06-10 公开作品互动能力进入后台全局配置 + +- 背景：作品详情页的点赞和改造能力原本由前端和各玩法 handler 的硬编码能力矩阵决定，后台无法临时关闭某类公开作品的互动入口，直接关闭创作入口又会误伤已有作品读取和游玩。 +- 决策：公开作品点赞 / 改造能力作为 `creation_entry_config.public_work_interactions_json` 的全局矩阵保存，不进入单个 `creation_entry_type_config`。`GET /api/creation-entry/config` 下发 `publicWorkInteractions`；后台通过 `/admin/api/creation-entry/config/interactions` 按 `sourceType` 保存点赞、改造开关和关闭提示；api-server 只对已经接入后端动作的 RPG / custom-world、大鱼吃小鱼和拼图 like / remix 路由做同源熔断，公开列表、详情读取、已发布作品启动和运行态请求不受影响。 +- 影响范围：`CreationEntryConfigResponse`、`AdminCreationEntryConfigResponse`、`module-runtime` 默认矩阵、`spacetime-module` 表字段和 procedure、`spacetime-client` 绑定、后台入口开关页、平台作品详情点赞 / 改造意图解析。 +- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo test -p module-runtime public_work_interaction_config_defaults_and_overrides --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server public_work_interactions --manifest-path server-rs/Cargo.toml`、后台和前台作品详情互动相关前端测试。 +- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 + +## 2026-06-10 dev Gitea 提供内网 HTTP 入口 + +- 背景：release / dev 目标 agent 需要从 dev 自托管 Gitea 拉取仓库；继续走 `https://git.genarrative.world/...` 会绕公网链路，`10.2.0.10:3000` 又受云侧端口策略影响不能作为稳定入口。 +- 决策：dev 上 Gitea 进程保持 `HTTP_ADDR = 127.0.0.1`、`HTTP_PORT = 3000`，公网 `ROOT_URL = https://git.genarrative.world/` 不变；新增 Nginx 内网 vhost `/etc/nginx/conf.d/gitea-internal.conf`，只允许 `10.2.0.0/16` 与本机访问，并把 `http://10.2.0.10/` 反代到本机 Gitea。内网 agent 统一使用 `http://10.2.0.10/GenarrativeAI/Genarrative.git` 作为可直连 Git 源。 +- 影响范围：dev Gitea / Nginx 运维配置、Jenkins `SOURCE_GIT_REMOTE_URL`、release / dev 目标 agent checkout 口径。 +- 验证方式：从 release 执行 `git ls-remote http://10.2.0.10/GenarrativeAI/Genarrative.git HEAD` 应返回 HEAD；公网来源伪造 `Host: 10.2.0.10` 访问 dev 公网 80 应返回 `403`；`https://git.genarrative.world/` 原入口应保持 `200`。 +- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + ## 2026-06-08 微信能力按领域收口 - 背景：微信登录、订阅消息、普通微信支付和小程序虚拟支付能力曾分散在 `api-server` 根模块、`platform-auth` 与 `platform-wechat`，支付协议细节和业务 handler 边界不够清晰。 @@ -24,6 +40,14 @@ - 验证方式：执行 `cargo check --manifest-path server-rs/Cargo.toml -p platform-wechat`、`cargo check --manifest-path server-rs/Cargo.toml -p api-server`、微信相关定向测试和编码检查；新增微信协议细节优先落到 `platform-wechat`。 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【技术方案】微信虚拟支付接入-2026-05-26.md`。 +## 2026-06-08 后端创作 / 游玩流程先统一主干再领域分发 + +- 背景：前端平台入口、作品架、公开详情和推荐运行态已经持续收口，但 `api-server` 仍在 `app.rs` 逐玩法合并创作 / 运行态路由，入口开关路径判断也独立维护，新增玩法容易复制出平行链路。 +- 决策：后端所有创作 / 游玩相关 HTTP 路由先进入 `server-rs/crates/api-server/src/modules/play_flow.rs` 统一主干；主干注册 `playId`、领域模块 key、创作路由前缀、运行态路由前缀和新建创作入口开关匹配规则，并在进入领域 handler 前统一挂载 `PlayFlowRequestContext`，再在最后一步分发到各玩法领域 HTTP Adapter。创作入口配置、AI task、runtime chat、运行态设置 / 存档、运行态库存、游玩历史、存档归档、游玩统计、历史素材、角色资产工坊、角色图像 / 动画生成和 Hyper3D 代理也作为创作 / 游玩支撑能力从 `play_flow` 进入；`modules/platform.rs` 只保留通用 LLM / 语音代理。`app.rs` 只合并 `modules::play_flow::router(state)`，不再逐玩法 merge；`creation_entry_config.rs` 复用 `play_flow` 的入口开关解析，不维护第二份路径表。 +- 影响范围：`api-server` 路由组织、入口开关、玩法接入 SOP、后端契约文档、后续新增 / 迁移玩法。 +- 验证方式：`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`，并确认旧 `/api/creation//*`、历史 `/api/runtime//agent/*` 与公开 runtime 路由外部契约不变。 +- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 + ## 2026-06-07 推荐页运行态先封面预载再 ready 渐隐 - 背景：移动端推荐页上下切换公开作品时，如果运行态和封面资源没有明确准备边界，用户会看到未加载完成的 runtime、黑底闪动，或切卡后反向回弹。 @@ -93,6 +117,7 @@ - 背景：`Genarrative-Server-Provision` 的 `DEPLOY_TARGET=development` 语义是部署到 dev 服务器，不是构建机 dry-run。旧流水线把 development 映射到 `linux && genarrative-build`，还先在 build 节点准备 `provision-tools/` 再 stash 给后续阶段，导致真实 dev 初始化可能跑到 Jenkins controller / build 节点；脚本还安装 clang / lld / pkg-config / OpenSSL headers / sccache 等构建链依赖，超出了服务器初始化职责。 - 决策：Server-Provision 只做服务器初始化，全程运行在目标部署 agent：development 使用 `linux && genarrative-dev-deploy`，release 使用 `linux && genarrative-release-deploy`。`Prepare Provision Tools` 与 `Provision Server` 在同一个目标 agent workspace 顺序执行，不再切到 `linux && genarrative-build`，不再 `stash/unstash` 工具包。`scripts/jenkins-server-provision.sh` 不再安装 clang / lld / pkg-config / libssl-dev / sccache；当前 OpenSSL 3.2 独立运行时自举会安装 `build-essential` 等最小工具，这是满足 api-server/libcurl 运行时符号的受控例外，不代表 provision 承担 api-server 构建职责。非 dry-run 仍要求目标 dev / release agent 具备 root 权限，因为 provision 会写 systemd、Nginx、`/etc` 和系统用户。Job 的 `Pipeline script from SCM` 与 Jenkinsfile 参数 `SOURCE_GIT_REMOTE_URL` 都必须使用本机路径或目标 agent 可访问的内网 Git 源，不允许公网 Git fallback。 +- 追加决策（2026-06-10）：`Prepare Provision Tools` 必须先读取目标机现状，再准备需要的文件。目标机 `/usr/local/bin/otelcol-contrib` 版本匹配 `OTELCOL_VERSION` 时直接复用；`${SPACETIME_ROOT}/bin/current/spacetimedb-cli` 和 `spacetimedb-standalone` 存在且 CLI 版本匹配 `SPACETIME_EXPECTED_VERSION` 或 `SPACETIME_DOWNLOAD_ROOT` 中的版本时，直接复用当前安装生成 `provision-tools/`。只有目标机缺失、不可执行或版本不匹配时，才消费 `PROVISION_DOWNLOADS_DIR` 中的本地包或进入下载分支。 - 影响范围：`jenkins/Jenkinsfile.production-server-provision`、`scripts/jenkins-server-provision.sh`、生产运维文档、Server-Provision 排障口径。 - 验证方式：Jenkins 日志中 Server-Provision 的 `Prepare`、`Checkout Provision Files`、`Prepare Provision Tools` 和 `Provision Server` 都在目标 dev / release agent 上执行；日志不出现 `Running on Jenkins`、`linux && genarrative-build`、`stash 'server-provision-tools'`、`Git 主地址拉取失败...改用备用地址`、`https://git.genarrative.world/GenarrativeAI/Genarrative.git` 或构建依赖 / sccache 安装步骤；`bash -n scripts/jenkins-server-provision.sh` 和编码检查通过。 - 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 @@ -1407,10 +1432,10 @@ - 验证方式：从平台推荐或公开详情进入跳一跳作品时，路由 source type 为 `jump-hop`、public code 为 `JH-*`，运行态启动消费后端返回的完整 profile / run 数据；后端 smoke 统一使用 `npm run dev:api-server` 启动并检查 `/healthz`。 - 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 -## 2026-05-28 跳一跳重设计为 5x5 地块图集与弹弓拖拽 +## 2026-05-28 跳一跳重设计为 UV 地板图集与长按蓄力 - 背景：旧跳一跳模板仍保留角色生图、有限路径、score/combo 和 `2x3` 地块图集口径，和当前“俯视角平台跳跃 + 主题生成地块池 + 无限路径”的产品需求不一致。 -- 决策：`jump-hop` v1 创作端只保留主题输入；image2 生成一张 `5x5`、共 25 个 2D 地块图标的图集，后端按均匀网格切出 25 个 `JumpHopTileAsset`。角色不再单独生图，运行态使用陶泥儿 logo 透明 PNG 角色；运行态输入为按住后拉蓄力、松手反向弹出，前端提交 `chargeMs + dragVectorX + dragVectorY`，后端裁决落点。草稿试玩必须使用 `runtimeMode=draft`，正式作品使用 `runtimeMode=published`；排行榜按作品维度每玩家只保留 1 条最佳记录，排序为成功跳跃次数降序、游戏时长升序、更新时间升序。 +- 决策：`jump-hop` v1 创作端只保留主题输入；image2 只生成一张 `1024x1536` 竖版图集，按 `3列*6行` 容纳 18 个立方体主题物体 UV 展开包装，每个大单元内部固定 `4列*3行` UV 网并切出 `top/front/right/back/left/bottom` 六张面贴图，后端共持久化 108 张 `256x256` 不透明 PNG。`JumpHopTileAsset.faceAssets` 保存六面贴图，历史 `imageSrc/imageObjectKey/assetObjectId` 写 top 面作为旧单贴图 fallback；旧作品没有 `faceAssets` 时运行态仍可把单张贴图应用到立方体所有面。角色不再单独生图，运行态使用陶泥儿 logo 透明 PNG 角色；运行态输入为长按蓄力、松手起跳，前端只提交蓄力值，后端始终沿当前地块中心到下一块地块中心方向裁决真实落点；`dragVectorX/dragVectorY` 仅作为旧客户端兼容字段保留且不参与裁决。草稿试玩必须使用 `runtimeMode=draft`，正式作品使用 `runtimeMode=published`；排行榜按作品维度每玩家只保留 1 条最佳记录，排序为成功跳跃次数降序、游戏时长升序、更新时间升序。 - 决策补充：跳一跳创作入口的事实源仍是 SpacetimeDB `creation_entry_type_config`。默认种子和旧默认行都必须同步迁移到 `subtitle=主题驱动平台跳跃`、`image_src=/creation-type-references/jump-hop.webp`；后端只在系统默认旧值命中时自动纠偏，避免覆盖后台手动配置。 - 影响范围：`jump-hop` PRD、`api-server` 生成编排、`module-jump-hop` 领域规则、`spacetime-module` / `spacetime-client` 跳一跳契约、前端工作台 / 结果页 / runtime / 平台壳调用链。 - 验证方式：`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`、`cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、跳一跳工作台和 runtime 定向前端测试。 @@ -1424,10 +1449,10 @@ - 验证方式：`npm test -- src/services/jump-hop/jumpHopRuntimeModel.test.ts src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx`、`cargo test -p module-jump-hop --manifest-path server-rs/Cargo.toml -- --nocapture`。 - 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 -## 2026-06-02 跳一跳起跳距离减半并加入飞行动画缓冲 +## 2026-06-02 跳一跳飞行动画缓冲与真实落点展示 -- 背景：用户反馈当前跳跃到目标位置需要拖得太远，且松手后缺少角色翻腾到目标地块的过渡动画，导致跳跃手感偏硬。 -- 决策：`jump-hop` 的 `chargeToDistanceRatio` 统一从 `0.004` 提升到 `0.008`，让同等跳跃距离所需拖动距离减半；前端 runtime 把“后端真实 run”和“当前屏幕显示态”拆开，松手瞬间先生成 `visualJump`，用当前角色位置作为起点、前端预测落点作为终点，播放约 `560ms` 的飞行动画；该路径不得等待后端新 run。角色弹到预测落点后若新 run 尚未返回，必须停在预测落点等待，再进入约 `1440ms` 的相机层推进过渡。推进期间地块 DOM 层和 DOM 角色层统一包在同一个 camera layer 下移动，旧当前地块自然离开视野，新预览地块从上方露出，避免 p1/p2 单独 top/left 过渡导致角色和地块不同步。相机推进必须同时使用 X/Y 偏移，从旧目标地块位置斜向滑到新当前地块聚焦位置，不能先横向瞬切居中再纵向推进。地块保留当前 / 目标 / 预览的深度尺寸差异，但该差异通过固定基准宽高上的 CSS transform scale 表达，并在相机推进期间同样使用 `1440ms` 缓动；当前态不再额外叠 CSS scale。 +- 背景：用户反馈长按蓄力版本的跳跃手感偏硬，成功后角色容易被吸回地块中心，且后端回包或相机推进时会出现飞过很远再瞬间拉回的闪现。 +- 决策：`jump-hop` 当前长按蓄力统一使用 `chargeToDistanceRatio=0.004`，相同蓄力时间的世界跳跃距离比上一轮 `0.008` 降低一半。前端 runtime 把“后端真实 run”和“当前屏幕显示态”拆开，松手瞬间先生成 `visualJump`，用当前角色位置作为起点、前端预测真实落点作为终点，播放约 `560ms` 的飞行动画；该路径不得等待后端新 run。角色弹到预测真实落点后若新 run 尚未返回，必须停在预测真实落点等待。成功落地后角色位置必须保留 `lastJump.landedX/landedY` 映射出的真实偏移，不得吸附回目标地块中心。相机推进以旧窗口真实落点和新窗口真实落点为锚点，使用约 `1440ms` 过渡；推进期间地块 DOM 层和 DOM 角色层统一包在同一个 camera layer 下移动，旧当前地块自然离开视野，新预览地块从上方露出，避免 p1/p2 单独 top/left 过渡导致角色和地块不同步。相机推进必须同时使用 X/Y 偏移，不能先横向瞬切居中再纵向推进。地块保留当前 / 目标 / 预览的深度尺寸差异，但该差异通过固定基准宽高上的 CSS transform scale 表达，并在相机推进期间同样使用 `1440ms` 缓动；当前态不再额外叠 CSS scale。 - 影响范围：`server-rs/crates/module-jump-hop/src/application.rs`、`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、跳一跳运行态定向测试。 - 验证方式：`npm test -- src/services/jump-hop/jumpHopRuntimeModel.test.ts src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx`、`cargo test -p module-jump-hop --manifest-path server-rs/Cargo.toml -- --nocapture`、`npm run check:encoding`。 - 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 @@ -1435,7 +1460,7 @@ ## 2026-06-03 跳一跳角色形象改为陶泥儿 logo 透明 PNG - 背景：跳一跳运行态此前仍使用旧内置 / CSS 角色形象，和用户要求的陶泥儿 logo 角色不一致，也容易和 DOM 地块层出现遮挡层级问题。 -- 决策：`jump-hop` v1 不再渲染内置 3D 角色几何体；运行态和结果页统一使用 `public/branding/jump-hop-taonier-character.png`，该文件由陶泥儿 logo 处理为透明 PNG 后接入。蓄力时角色沿拖拽方向明显拉长，落地后向反方向回弹两次。`characterAsset` 继续仅作为历史兼容描述字段，不能重新打开角色生图槽或把角色图片作为创作者可配置输入。 +- 决策：`jump-hop` v1 不再渲染内置 3D 角色几何体；运行态和结果页统一使用 `public/branding/jump-hop-taonier-character.png`，该文件由陶泥儿 logo 处理为透明 PNG 后接入。蓄力时角色只做垂直压缩，落地后保留真实落点并轻量回弹。`characterAsset` 继续仅作为历史兼容描述字段，不能重新打开角色生图槽或把角色图片作为创作者可配置输入。 - 影响范围：`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/components/jump-hop-result/JumpHopResultView.tsx`、跳一跳 PRD 和平台链路文档。 - 验证方式：跳一跳运行态 / 结果页测试需要断言角色图片 src 为 `/branding/jump-hop-taonier-character.png`，并确认旧默认角色 fallback 不再出现。 - 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 diff --git a/.hermes/shared-memory/development-workflow.md b/.hermes/shared-memory/development-workflow.md index 9fad4640..f34cf07f 100644 --- a/.hermes/shared-memory/development-workflow.md +++ b/.hermes/shared-memory/development-workflow.md @@ -101,6 +101,8 @@ npm run dev:admin-web 生产 `Genarrative-Stdb-Module-Publish` 的备份默认使用 `DATABASE_BACKUP_MODE=async`：流水线在 publish 前先生成本地冷备份，随后继续 publish，并把同一份发布前备份交给后台 Node 进程上传 OSS，避免低带宽 OSS 上传长时间占住部署窗口。需要强制在 publish 前等待打包和上传并让失败阻断发布时，手动选择 `DATABASE_BACKUP_MODE=sync`；已有其他备份窗口且明确接受风险时才选择 `skip`。 +生产 API / Web / Stdb 发布流水线不在目标机器 checkout Git。对应 Build 流水线必须把发布产物、校验文件、`release-manifest.json` 和部署 / 发布脚本一起归档；Deploy / Publish 流水线只通过 `copyArtifacts` 复制上游构建归档并执行随产物归档的脚本，避免目标机器 Git 访问和产物 commit 与部署脚本 commit 漂移。 + 查看本地 Rust/SpacetimeDB 日志： ```bash diff --git a/.hermes/shared-memory/pitfalls.md b/.hermes/shared-memory/pitfalls.md index 8d528ac4..78adbe07 100644 --- a/.hermes/shared-memory/pitfalls.md +++ b/.hermes/shared-memory/pitfalls.md @@ -47,6 +47,22 @@ - 验证：`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server asset_operation_billing_does_not_refund_stale_worker_lease_errors --manifest-path server-rs/Cargo.toml`，并在 smoke 时确认 queued 任务被 worker 消费后 session 真实更新。 - 关联：`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/generation.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。 +## 生产冷备份后 API 不能只依赖 SpacetimeDB 自恢复 + +- 现象：release 机器 `03:20` 冷备份后，`spacetimedb.service` 已恢复，但作品列表、创作入口配置或公开 gallery 继续超时 / 502 / 504，`genarrative-api.service` 保持 stopped。 +- 原因：`genarrative-api.service` 配置了 `Requires=spacetimedb.service`，冷备份停止 `spacetimedb.service` 时 API 会被 systemd 依赖关系一并停止；如果 `genarrative-database-backup.service` 只传 `--stop-service spacetimedb.service` 而漏掉 `--restart-service-after genarrative-api.service`，备份脚本只会恢复数据库，不会再拉起 API。 +- 处理：生产冷备份 unit 和发布脚本必须带 `--restart-service-after genarrative-api.service`；仓库用 `npm run check:production-ops` 检查 systemd 模板、API build/deploy 归档和健康巡检链路。现场修复后执行 `systemctl daemon-reload`，但不要为了验证而手动触发冷备份。 +- 验证：`systemctl cat genarrative-database-backup.service` 应包含该参数；`systemctl is-active spacetimedb.service genarrative-api.service nginx.service` 全为 `active`；`curl -fsS http://127.0.0.1:3101/v1/ping`、`/healthz`、`/readyz` 和代表性 `/api/runtime/puzzle/gallery` 均成功。 +- 关联：`deploy/systemd/genarrative-database-backup.service`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + +## SpacetimeDB 45 秒超时要看 api-server 记录的阶段 + +- 现象：release 上 Nginx 能立刻连到 `api-server`，但 `/api/runtime/*/gallery`、`/api/creation-entry/config` 等请求在约 `GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS` 后返回 `502` / `504`。 +- 原因：旧日志只能看到 HTTP 总耗时和最终状态，无法区分卡在连接池、SDK 建连、等待 `on_connect`、订阅 read model、等待 procedure / reducer 回调还是本地订阅 cache 读取。 +- 处理：`spacetime-client` 内置阶段化健康检查和失败日志；`/readyz` 用 `GENARRATIVE_SPACETIME_HEALTH_CHECK_TIMEOUT_SECONDS` 短窗口检查 SpacetimeDB 连接租约，业务失败日志包含 `operation_kind`、`operation_name`、`spacetime_stage`、`elapsed_ms`。 +- 验证：`/readyz` 失败时看 `details.spacetime.stage`；业务请求超时时查 `journalctl -u genarrative-api.service` 中同一时间窗口的 `SpacetimeDB client operation failed`，优先按 `pool_acquire`、`connect_build`、`connect_handshake`、`read_model_subscribe`、`procedure_result`、`reducer_result`、`read_cache` 分阶段处理。 +- 关联：`server-rs/crates/spacetime-client/src/lib.rs`、`server-rs/crates/api-server/src/health.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + ## 新建草稿扣费不能和入口卡泥点配置分离 - 现象：后台修改创作入口的 `mudPointCost` 后，入口卡和前置余额提示可能显示新数值，但用户真实钱包流水仍按代码常量扣除。 @@ -103,13 +119,13 @@ - 验证：`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 超时要按传输失败排查 +## VectorEngine 图片生成 request_send 传输错误要按可重试网络抖动排查 -- 现象：`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/requestId` 定位触发者、草稿 / 作品和同一次 HTTP 请求；`request_send + timeout=true` 优先查 provider 日志的 `source_chain`、请求体大小、参考图数量、出口网络、代理/Nginx、VectorEngine 当时可用性和同一 request_id 日志。当前 `platform-image` 对 `request_send` 的 `timeout` / `connect` 错误最多重试 3 次，multipart `/v1/images/edits` 每次重试都必须重建 form；看到 `VectorEngine 图片请求发送失败，准备重试` 只是单次 attempt 失败，最终 `external_api_call_failure` 才代表该用户请求整体失败。若记录有 `502` 或 `429 moderation_blocked`，按上游网关或审核失败另行处理，不要归到传输超时。 +- 现象：`external_api_call_failure` 里看到 `failureStage=request_send`、`statusCode=null`，`errorSource` 可能是 `client error (SendRequest)`、`[35] SSL connect error (Recv failure: Connection reset by peer)`、`[56] Failure when receiving data from the peer (... unexpected eof while reading ...)`；也可能看到 `failureStage=upstream_status`、`statusCode=502`、错误体是 Nginx HTML `502 Bad Gateway`。前端只知道图片生成失败。 +- 原因：`request_send` 表示请求未拿到可归类的 HTTP 响应，不会包含上游 JSON 错误体；`upstream_status=502/5xx/429/408` 表示拿到了上游错误响应但仍属于可重试的过载 / 网关抖动。`timeout=true` 来自超时判定，`connect=true` 会同时覆盖 DNS / connect 失败以及 libcurl 35 SSL 握手、libcurl 56 收包提前 EOF、connection reset 这类临时传输错误。 +- 处理：先按 `provider/failureStage/statusClass` 聚合，再用 `user_id` / `profile_id` 和 `metadata_json.userId/profileId/requestId` 定位触发者、草稿 / 作品和同一次 HTTP 请求；`request_send + timeout/connect=true` 或 `upstream_status + statusCode=408/429/5xx` 优先查 provider 日志的 `source_chain`、请求体大小、参考图数量、出口网络、代理/Nginx、VectorEngine 当时可用性和同一 request_id 日志。当前 `platform-image` 对 request_send 的 timeout / connect / SSL connect reset / recv error / unexpected eof / send error，以及 upstream_status 的 408 / 429 / 5xx 最多发送 5 次，multipart `/v1/images/edits` 每次重试都会重新构造 form；看到 `VectorEngine 图片请求发送失败，准备重试` 或 `VectorEngine 图片上游状态可重试，准备重试` 只是单次 attempt 失败，最终 `external_api_call_failure` 才代表该用户请求整体失败。若记录有 `429 moderation_blocked` 或明确审核错误，按审核失败另行处理，不要归到网络抖动。 - 拼图关卡资产生成按 `level_scene -> ui_spritesheet -> level_background` 顺序执行，每个资产会输出 `slot`、`asset_kind`、`elapsed_ms`；排查拼图草稿失败时优先看同一 request_id 下最后一个失败 slot。 -- 验证：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml vector_engine_image_edit_retries_send_timeout_once_and_succeeds`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`；查询 `tracking_event` 时失败记录应能看到触发者 `user_id` 和可用的 `profile_id`。 +- 验证：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml vector_engine_send_retry_policy -- --nocapture`、`cargo test -p platform-image --manifest-path server-rs/Cargo.toml vector_engine_image_edit_retries_send_timeout_once_and_succeeds`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`；查询 `tracking_event` 时失败记录应能看到触发者 `user_id` 和可用的 `profile_id`。 - 关联：`server-rs/crates/platform-image/src/vector_engine/client.rs`、`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`。 ## “我的”页每日任务卡不要硬编码进度，也不要跨日保留旧状态 @@ -489,6 +505,14 @@ - 验证：未登录推荐页可以直接进入跳一跳运行态，且 `work_play_start` 事件仍会落库或出现在 outbox 中，metadata 含匿名标记。 - 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`server-rs/crates/api-server/src/auth.rs`、`server-rs/crates/api-server/src/work_play_tracking.rs`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`。 +## 跳一跳直接打开空 runtime 路由不能停在加载态 + +- 现象：直接访问 `/runtime/jump-hop` 时页面看起来一直停在“正在载入游戏 / 正在加载内容”，DOM 内部只有空的跳一跳运行态，没有平台、地块或 run 数据。 +- 原因：`appPageRoutes` 会把该路径解析为 `jump-hop-runtime`，但裸路径没有 `work=JH-*` 公开作品码，也没有从详情页启动后写入的 `jumpHopRun`，平台壳仍挂载 `JumpHopRuntimeShell`。 +- 处理：平台壳在 `jump-hop-runtime` 且缺少 run 时先看 `work` 参数；有 `JH-*` 则通过公开 gallery detail 回读 profile 并启动 published run，没有则回到平台首页。全局作品码恢复 effect 在跳一跳 runtime 阶段要跳过，避免和运行态恢复互相抢路由。 +- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "direct jump hop runtime route"`；浏览器 smoke 分别打开 `/`、`/runtime/jump-hop` 和 `/runtime/jump-hop?work=JH-*`。 +- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/routing/appPageRoutes.ts`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`。 + ## release tracking outbox 权限错误先查 env 缺失 - 现象：release 机器 `journalctl -u genarrative-api.service` 每秒刷 `tracking outbox 定时封存 active 文件失败 error=Permission denied (os error 13)` 和 `tracking outbox 批量写入 SpacetimeDB 失败`。 @@ -1143,6 +1167,8 @@ - 现象：刷新网页后，用户明明有本地 access token，却回到未登录状态。 - 原因：`AuthGate` hydrate 曾先强制调用 `refreshStoredAccessToken()`；当 refresh cookie 临时失效、代理错配或后端返回 `401` 时，该方法会先清空本地 access token，随后 `/api/auth/me` 只能恢复成未登录。 - 处理：`refreshStoredAccessToken()` 增加 `clearOnFailure` 选项；`AuthGate` 在已有本地 access token 时先用 `/api/auth/me` 确认用户，确认成功后再后台 refresh 续期与写每日登录埋点，后台 refresh 失败不清 token。 +- 追加处理：`/api/auth/refresh` 只有明确返回 `401` / `403` 时才代表登录态权威失效，可以清本地 access token 并触发全局 auth 变化；服务器重启、Nginx 502/503/504、浏览器 `Failed to fetch` 或 refresh 响应契约异常都属于暂时不可用，不能把已有本地 token 清掉，否则重启窗口会把所有打开页面踢成未登录。 +- 契约：`/api/auth/refresh` 成功响应按共享契约 `RefreshSessionResponse { token }` 解析；测试 mock 不要额外塞 `{ ok: true, token }` 遮住真实恢复路径。 - 验证：`npm run test -- src/services/apiClient.test.ts src/components/auth/AuthGate.test.tsx -t "explicit refresh opts out|auth gate keeps a valid local token login"`。 - 关联：`src/services/apiClient.ts`、`src/components/auth/AuthGate.tsx`、`docs/technical/AUTH_RESTORE_AND_RECOMMEND_LOADING_FIX_2026-05-09.md`。 @@ -1338,6 +1364,14 @@ - 验证：Jenkins 日志中 `Provision Target` 下的 `Prepare`、`Checkout Provision Files`、`Prepare Provision Tools` 和 `Provision Server` 都应运行在目标 dev / release agent；日志不应出现 `stash 'server-provision-tools'`、目标阶段 `unstash`、`Git 主地址拉取失败...改用备用地址` 或 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。 - 关联：`jenkins/Jenkinsfile.production-server-provision`、`scripts/prepare-server-provision-tools.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 +## Server-Provision 不要无条件下载工具包 + +- 现象：目标 dev / release 机器已经安装正确版本的 SpacetimeDB 或 `otelcol-contrib`，但 `Prepare Provision Tools` 仍每次下载 release tarball，网络慢或 GitHub 不稳时会把服务器初始化卡在准备阶段。 +- 原因：工具准备阶段如果只按“生成交付包”理解，会忽略它已经运行在目标部署 agent 上这一事实；此时目标机本地的 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current` 就是可信状态源。 +- 处理：`scripts/prepare-server-provision-tools.sh` 必须先检查目标机状态：`otelcol-contrib --version` 命中 `OTELCOL_VERSION` 时复制现有二进制；`spacetimedb-cli --version` 命中 `SPACETIME_EXPECTED_VERSION` 或 `SPACETIME_DOWNLOAD_ROOT` 推导出的版本且 standalone 同时存在时，复制 `${SPACETIME_ROOT}/bin` 并生成 wrapper。只有缺失、不可执行或版本不匹配时，才查 `PROVISION_DOWNLOADS_DIR` 或下载源。 +- 验证：运行 `bash scripts/check-server-provision-tools.sh`；Jenkins 日志应先出现“检查目标机 ...”，已有版本命中时出现“复用目标机已有 ...”，且不出现“下载 ...”。 +- 关联：`scripts/prepare-server-provision-tools.sh`、`jenkins/Jenkinsfile.production-server-provision`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + ## 个人任务 scope 不得扩成 work/site/module - 现象：个人任务配置为 `work` / `site` / `module` 后进度串桶或静默按 0 处理。 @@ -1772,18 +1806,18 @@ - 验证：`npm run typecheck`，并跑 `npm test -- src/routing/appPageRoutes.test.ts` 覆盖 JumpHop 阶段路径。 - 关联：`src/components/platform-entry/platformEntryTypes.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 -## 跳一跳地块图集固定走 5x5 地块池 +## 跳一跳地块图集固定走 18 个 UV 大单元 - 现象：跳一跳初始草稿生成时报 `系列素材图集的物品行数不能超过 n。`，或者生成完成后只有 atlas 预览路径，地块切片没有真正落盘。 -- 原因：旧模板先后尝试过通用系列素材 helper 和 `2x3` 六格固定 tileType，但当前跳一跳已经重设计为“主题 -> 5x5 地块图集 -> 25 个等权地块池 -> 无限路径”，旧的物品行数 / 固定类型模型都会把创作链路带偏。 -- 处理：跳一跳地块固定生成一张 `5x5` 主题图集，后端按均匀网格切出 25 张 PNG，并对每张切片各自走 OSS 上传、asset_object 确认和 entity bind；不要再恢复 `2行*3列`、`start / normal / target / finish / bonus / accent` 六格口径。 -- 验证：`jump_hop.rs` 不应再调用通用物品行数模型处理地块图集；公开结果里应能拿到 25 个独立 `JumpHopTileAsset`，运行态无限路径从地块池随机取材。 +- 原因：旧模板先后尝试过通用系列素材 helper、`2x3` 六格固定 tileType 和 `5x5` 单贴图池，但当前跳一跳已经重设计为“主题 -> 一张 `1024x1536` 图集 -> 18 个 `3列*6行` UV 大单元 -> 每格 `4列*3行` 六面贴图 -> 无限路径”，旧的物品行数 / 固定类型模型都会把创作链路带偏。 +- 处理：跳一跳地块固定只生成一张 `1024x1536` 主题 UV 展开图集，后端先切出 18 个大单元，再从每格固定 UV 网切出 top/front/right/back/left/bottom 六张 `256x256` 不透明 PNG，并对 108 张面贴图各自走 OSS 上传、asset_object 确认和 entity bind；不要再恢复 `2行*3列`、`5x5` 单贴图、`start / normal / target / finish / bonus / accent` 六格口径。 +- 验证：`jump_hop.rs` 不应再调用通用物品行数模型处理地块图集；公开结果里应能拿到 18 个独立 `JumpHopTileAsset` 且每个新资产包含 `faceAssets` 六面贴图，运行态无限路径从地块池随机取材；旧资产没有 `faceAssets` 时仍能用 `imageSrc` 单贴图 fallback。 - 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 ## 跳一跳宝可梦主题地块图集 safety rejection 只做专项改写 - 现象：跳一跳草稿使用“宝可梦 / Pokemon / 皮卡丘 / 精灵球”等主题时，背景底图和返回按钮可能已生成成功，但地块图集的 VectorEngine 请求返回 `Your request was rejected by the safety system`，日志里 `failure_context="跳一跳地块图集生成失败"`、`status=429`、`code="invalid_prompt"`。 -- 原因：25 个落点图集 prompt 会把这些词放进“主题物体图集”语境，容易被上游理解为要求生成具体宝可梦角色或标志道具，触发安全拦截；这不是普通平台造型词、抠图或超时问题。 +- 原因：18 个立方体主题物体 UV 展开图集 prompt 会把这些词放进“主题物体图集”语境，容易被上游理解为要求生成具体宝可梦角色或标志道具，触发安全拦截；这不是普通平台造型词、抠图或超时问题。 - 处理：仅在跳一跳图片生成 prompt 文本命中宝可梦相关词时做生成侧替换，把 `宝可梦 / 神奇宝贝 / 口袋妖怪 / Pokemon` 改为“原创幻想萌宠冒险道具”，把 `精灵球` 改为“彩色冒险能量球”，把 `皮卡丘 / Pikachu` 改为“黄色闪电萌宠符号”；不要把所有主题都加全局 IP 禁止约束，用户草稿标题和主题展示也不改。 - 验证：`cargo test -p api-server jump_hop --manifest-path server-rs/Cargo.toml` 应覆盖宝可梦词专项替换；真实联调时同一草稿重试后，地块图集请求的 prompt 不再包含宝可梦相关词。 - 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 @@ -1791,9 +1825,9 @@ ## 跳一跳地块切片不要按 tileType 复用资产槽位 - 现象：跳一跳生成完成后，运行态看起来仍像在显示默认几何地块，或者地块图片在加载时频闪；结果页地块池也可能只看到少量重复素材。 -- 原因：`tileType` 只是路径平台的玩法类型标签，25 个 atlas 切片里会重复出现 `normal / target / bonus / accent` 等类型。若后端持久化时用 `tileType` 生成 slot/path，同类型切片会写入同一个 `/generated-jump-hop-assets///image.png`，后上传的切片覆盖先上传的切片，前端换签缓存也会读到重复或旧对象。 -- 处理：后端切图后必须按 atlas 单元格写入 `tile-01` 到 `tile-25` 的唯一 slot/path；前端结果页和运行态展示生成图时用 `assetObjectId` 作为 `refreshKey`，避免重生成后复用旧签名或旧图片缓存。 -- 验证：`cargo test -p api-server jump_hop --manifest-path server-rs/Cargo.toml -- --nocapture` 应包含 `jump_hop_tile_asset_slots_are_unique_for_twenty_five_slices`；前端运行态测试应断言地块换签带 `assetObjectId` 刷新键。 +- 原因：`tileType` 只是路径平台的玩法类型标签，18 个 atlas 大单元里会重复出现 `normal / target / bonus / accent` 等类型。若后端持久化时用 `tileType` 生成 slot/path，同类型切片会写入同一个 `/generated-jump-hop-assets///image.png`，后上传的切片覆盖先上传的切片，前端换签缓存也会读到重复或旧对象。 +- 处理：后端切图后必须按 atlas 单元格写入 `tile-01` 到 `tile-18` 的唯一 tile slot，并把六面贴图写入 `tile-XX-top/front/right/back/left/bottom` 唯一 face slot；前端结果页和运行态展示生成图时用 `assetObjectId` 作为 `refreshKey`，避免重生成后复用旧签名或旧图片缓存。 +- 验证：`cargo test -p api-server jump_hop --manifest-path server-rs/Cargo.toml -- --nocapture` 应包含 `jump_hop_tile_asset_slots_are_unique_for_eighteen_slices`；前端运行态测试应断言地块换签带 `assetObjectId` 刷新键，并覆盖新 UV 资产会解析六张面贴图。 - 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/components/jump-hop-result/JumpHopResultView.tsx`。 ## 跳一跳落点辅助标识不要再用舞台高度常量拍脑袋投影 @@ -1804,12 +1838,12 @@ - 验证：拖拽半程时辅助点应落在当前地块和目标地块之间，完整拖拽时应逼近目标地块中心；运行态截图里辅助点必须始终压在地块与角色之上。 - 关联：`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`。 -## 跳一跳落点辅助和后端裁决必须统一坐标换算 +## 跳一跳长按蓄力不能再消费拖拽方向 -- 现象：落点辅助标识已经压在目标地块图片上，松手后后端仍判定失败，玩家看到的是“明明瞄准了却没落上去”。 -- 原因：前端辅助标识使用屏幕像素坐标绘制，而后端裁决使用世界坐标。屏幕 y 轴向下为正、世界 y 轴向上为正；同时屏幕 x/y 每个世界单位对应的像素比例不同。若前端直接把屏幕像素拖拽向量发给后端，辅助点和后端落点方向会不一致。 -- 处理：前端运行态保留原始屏幕拖拽向量用于画弹弓和辅助点，但提交后端前必须按当前地块到目标地块的屏幕跨度 / 世界跨度把 x、y 分别换算成世界尺度一致的向量；后端继续只负责反向弹射和落点裁决。 -- 验证：前端回归测试要同时覆盖辅助点完整拖拽到目标地块，以及提交给后端的向量已完成世界尺度换算；后端领域测试覆盖屏幕向后下拉时应向世界 y 正方向跳出并命中。 +- 现象：跳一跳改成长按蓄力后，如果前端或后端仍消费 `dragVectorX/dragVectorY`，玩家手指轻微移动就会改变跳跃方向，和“始终朝下一块中心跳”的体验不一致。 +- 原因：历史弹弓拖拽版本把屏幕拖拽方向作为正式裁决输入，契约字段仍为兼容旧客户端保留，容易被误认为仍是当前玩法规则。 +- 处理：前端运行态只用长按时长提交 `dragDistance` 兼容字段，不再发送方向字段；落点预测按当前地块中心到下一块地块中心的方向投影。后端 `module-jump-hop` 即使收到旧客户端 `dragVectorX/dragVectorY` 也必须忽略，只按当前地块到下一块地块中心的单位向量裁决。 +- 验证：前端回归测试覆盖手指移动不改变提交方向、预测落点忽略旧方向字段；后端领域测试覆盖旧客户端传错误方向时仍按下一块中心命中。 - 关联：`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`server-rs/crates/module-jump-hop/src/application.rs`。 ## 跳一跳创作入口旧文案先查 SpacetimeDB 配置 @@ -2087,24 +2121,32 @@ - 现象：跳一跳松手后如果后端很快返回下一帧 run，地块窗口会立刻前移，角色翻腾动画看起来像没播放；若同时刷新图片资产，还可能被误认为地块频闪。 - 原因：后端 run 是规则真相，前端 runtime 又需要低延迟表现。如果 DOM 平台层直接用最新 `run.currentPlatformIndex` 渲染，后端回包会抢在动画前完成视觉切换。 -- 处理：前端保留独立 `displayRun`，松手后先进入 `isJumpAnimating=true`，角色在当前窗口内插值飞向目标地块；约 `300ms` 后再把 `displayRun` 切到最新后端 run，并进入约 `1440ms` 的 `platformAdvancing` 表现态。推进期间地块 DOM 层和 Three.js 角色层必须统一包在同一个 camera layer 下移动，旧当前地块用相机偏移自然离开视野，新预览地块从上方露出；不要再让 p1/p2 各自 top/left 过渡。相机层必须同时设置 `--jump-hop-camera-shift-x` 与 `--jump-hop-camera-shift-y`，从旧目标地块位置斜向滑到新当前地块聚焦位置，避免先横向瞬切居中再纵向推进。地块保留当前 / 目标 / 预览的深度尺寸差异，但深度差异必须用固定宽高 + CSS transform scale 缓动实现，不能直接改宽高瞬切；当前态不要额外叠 CSS scale。相机推进期间角色自身也不能保留 `left/top` transition，否则 `displayRun` 切换造成的角色局部坐标变更会和父级 camera layer 位移叠加，视觉上像落地后又从屏幕外飞回；角色推进期只允许 transform / opacity transition。正式胜负、成功跳跃次数、时长和排行榜仍以后端 run 为准，前端只延迟显示态。 -- 验证：`npm test -- src/services/jump-hop/jumpHopRuntimeModel.test.ts src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx` 应覆盖动画期间平台仍停在旧窗口，动画结束后进入 `data-platform-advancing=true`，Three 角色层与地块层同在 `jump-hop-camera-layer` 内，通过 `--jump-hop-camera-shift-x` 和 `--jump-hop-camera-shift-y` 完成相机斜向推进，并校验可见地块按深度保留不同视觉尺寸、运行态平台宽高使用固定基准值、推进态 transform transition 为 `1440ms`、推进态角色 transition 不包含 `left/top`。 +- 处理：前端保留独立 `displayRun`，松手后先进入 `isJumpAnimating=true`，角色在当前显示窗口内飞向前端预测真实落点；视觉预测必须用当前显示窗口的 current/next 地块作为方向来源，不能拿已经提前返回的后端新 run 目标配旧窗口角色，否则下一跳会朝实际目标反方向飞。飞行动画完成后再把 `displayRun` 切到最新后端 run，并进入约 `1440ms` 的 `platformAdvancing` 表现态。成功后的角色显示必须使用 `lastJump.landedX/landedY` 映射出的真实偏移，不要吸附到目标地块中心。推进期间地块 DOM 层和 DOM 角色层必须统一包在同一个 camera layer 下移动，旧当前地块先跟随相机偏移离开主视野，之后只保留在屏幕后方；不要给旧地块加独立向上 / 向下飞走 keyframes，也不要因为旧地块还在保留列表里阻塞下一跳。玩家继续向前跳时，已完成旧地块继续被新的相机推进自然带离屏幕，超过离屏阈值后销毁。相机层必须同时设置 `--jump-hop-camera-shift-x` 与 `--jump-hop-camera-shift-y`，并以旧窗口真实落点和新窗口真实落点为锚点，避免先横向瞬切居中再纵向推进；运行态相机层当前为约 `1.3x` 近距缩放。地块保留当前 / 目标 / 预览的深度尺寸差异，但深度差异必须用固定宽高 + CSS transform scale 缓动实现，不能直接改宽高瞬切；当前态不要额外叠 CSS scale。相机推进期间角色自身也不能保留 `left/top` transition，否则 `displayRun` 切换造成的角色局部坐标变更会和父级 camera layer 位移叠加，视觉上像落地后又从屏幕外飞回；角色推进期只允许 transform / opacity transition。正式胜负、成功跳跃次数、时长和排行榜仍以后端 run 为准，前端只延迟显示态。 +- 验证：`npm test -- src/services/jump-hop/jumpHopRuntimeModel.test.ts src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx` 应覆盖动画期间平台仍停在旧窗口，成功落地保留真实落点偏移，动画结束后进入 `data-platform-advancing=true`，DOM 角色层与地块层同在 `jump-hop-camera-layer` 内，通过 `--jump-hop-camera-shift-x` 和 `--jump-hop-camera-shift-y` 完成相机斜向推进，并校验可见地块按深度保留不同视觉尺寸、运行态平台宽高使用固定基准值、推进态 transform transition 为 `1440ms`、推进态角色 transition 不包含 `left/top`、旧地块没有独立 `jump-hop-platform-exit-drift` keyframes 且下一跳不会被旧地块保留态阻塞。 - 关联：`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/services/jump-hop/jumpHopRuntimeModel.ts`、`server-rs/crates/module-jump-hop/src/application.rs`。 ## 跳一跳相机推进不要让地块图片回退到原型方块 - 现象：角色落到下一块后，相机推进时旧地块图片突然消失，或新预览地块先露出浅色原型方块，随后真实 image2 切片才出现。 -- 原因：旧地块进入 exiting 状态时如果 React key 从 `platformId` 变成 `platformId-exiting`，图片组件会重新挂载并丢失已加载状态；同时 `JumpHopTileImage` 曾在真实图片 URL 已存在但 `onLoad` 尚未触发时显示 fallback 原型地块。 -- 处理：exiting 地块继续使用稳定 `platformId` key，让旧图片组件在推进期复用；有真实 `resolvedUrl` 且未错误时直接保留真实 ``，只在无 URL 或加载失败时显示 fallback；当前 3 块之外的后续地块通过隐藏预加载图片提前解析签名 URL 和浏览器缓存。 +- 原因：旧地块进入 exiting 状态时如果 React key 从 `platformId` 变成 `platformId-exiting`，图片组件会重新挂载并丢失已加载状态；同时 `JumpHopTileImage` 曾在真实图片 URL 已存在但 `onLoad` 尚未触发时显示 fallback 原型地块。Three.js 平台层接入后，如果隐藏预加载只让浏览器缓存 ``，但没有把未来 `platformId` 的纹理 URL 写入 `platformTextureUrlsByRenderKey`，相机推进时新预览地块会短暂缺 Three 贴图；若旧 blob 贴图在空 URL 回调时先被 revoke，再继续保留在 state 中，也会留下一个看似 ready、实际已失效的贴图地址。 +- 处理：exiting 地块继续使用稳定 `platformId` key，让旧图片组件在推进期复用；有真实 `resolvedUrl` 且未错误时直接保留真实 ``，只在无 URL 或加载失败时显示 fallback；当前 3 块之外的后续地块通过隐藏预加载图片提前解析签名 URL 和浏览器缓存，并同步按未来 `platformId` 发布 Three 纹理 URL。Three 平台层在当前 render items 全部有贴图 URL 后继续承接包含 exiting 地块在内的 3D 渲染；退出地块只随相机推进自然离屏，不播放独立飞走动画，避免退出期露出被放大的平面贴图或重复飞多次；贴图 URL 替换必须等新 URL 到达后再释放旧 parent-owned blob，空 URL 回调不得清空或 revoke 仍在活跃 / 预加载 key 上的旧贴图。 - 验证：`npm run test -- src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx src/services/jump-hop/jumpHopRuntimeModel.test.ts` 应覆盖真实 tile URL 不露出 `.jump-hop-runtime__fallback-tile`，并存在 `jump-hop-tile-preload-image`。 - 关联：`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx`。 -## 跳一跳地块抠图不要用绿幕或近白底识别 +## 跳一跳 Three.js 平台层不能左右镜像 DOM 坐标 -- 现象：跳一跳生成草地、花、雪地、白石或云朵地块时，透明化会把绿色 / 白色主体局部扣掉，运行态看到平台缺口、变薄或主体消失。 -- 原因：通用图集默认按绿幕和近白底做透明化，适合 UI / 普通物品，但跳一跳地块天然高频包含绿色和白色；如果继续用 `#00FF00` 绿幕或近白背景识别，素材本体会落入背景分数。旧逻辑还会清理非边缘连通的高置信 key 色块，遇到主体内部撞色时也可能误伤。 -- 处理：跳一跳地块图集 prompt 固定要求单一纯洋红 `#FF00FF` key 背景；切片前后透明化调用 `GeneratedAssetSheetAlphaOptions::jump_hop_magenta_screen()`，只扣洋红 key，关闭近白扣除，并且不清理非边缘连通 key 色像素。通用绿幕函数保持默认绿幕 / 近白兼容，避免影响拼图、抓大鹅和敲木鱼。 -- 验证：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml generated_asset_sheet -- --nocapture` 覆盖洋红 key 保留绿色、白色和非边缘连通 key 色主体；`cargo test -p api-server jump_hop --manifest-path server-rs/Cargo.toml -- --nocapture` 覆盖跳一跳洋红 prompt 与绿 / 白地块切片。 +- 现象：视觉上下一块地块在角色右侧，但蓄力引导和角色飞行动画朝左侧；后端回包后地块窗口又闪现摆回正确位置，像是先按反方向飞、再由快照刷新纠正。 +- 原因：Three.js 平台层如果把相机 `up` 设置成反向，或在 Three 容器上做左右镜像，会让 WebGL 地块的屏幕 X 轴和 DOM 角色 / 落点预测的屏幕 X 轴相反。规则层仍沿当前地块中心到下一块中心裁决，所以后端快照会把状态纠正回来，表现为跳后刷新。 +- 处理：Three 相机保持 `up=(0, 1, 0)`，再用内部投影公式抵消 45° 下压导致的 Y 轴压缩；不要通过反向 `camera.up` 解决上下方向。DOM 角色、蓄力引导、落点预测和 Three 平台层必须共用同向屏幕坐标。 +- 验证：`npm run test -- src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx src/services/jump-hop/jumpHopRuntimeModel.test.ts` 应覆盖 `JUMP_HOP_THREE_CAMERA_UP_Y=1`，并断言 Three 投影与 DOM 屏幕坐标同向。 +- 关联：`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx`。 + +## 跳一跳立方体贴图不要走透明主体切片 + +- 现象：水果等主题生成成功后，运行态地块看起来像薄的纯水果 PNG、果切贴纸、透明 cutout；或者反过来六个面都是同一张平铺果皮 / 果肉材质，无法组合成方块苹果 / 方块香蕉这类完整主题对象表达。 +- 原因：跳一跳地板已经改为 Three.js 标准 `1x1x1` 等比极小倒角立方体复用几何体，运行态视角固定为近距相机和 45° 下压视角；image2 应生成 `1024x1536` 的 18 个 cube object UV unwrap，每个大单元内的 top/front/right/back/left/bottom 六面要共同包装同一个主题物体。只强调 full-bleed 容易让水果主题退化成果皮、果肉、叶脉等表面纹理；如果仍把一张图贴给六个面，模型也不需要理解正反和跨面连续特征。旧切图链路若把洋红 key 转 alpha、裁边、只保留最大 alpha 连通主体并补透明安全边，会把整格贴图重新抠成苹果 / 香蕉 / 果切等居中主体，贴到立方体上后四角和侧面都变透明。 +- 处理：跳一跳地板图集 prompt 固定要求 `cube object UV unwrap atlas / 立方体主题物体六面展开图集`，一张图只生成 18 个大单元，每个大单元固定 `4列*3行` UV 网：第 1 行第 2 列 top，第 2 行 left/front/right/back，第 3 行第 2 列 bottom；水果主题要明确生成能一眼说出名称的方块苹果、方块香蕉、方块橙子、方块西瓜等可识别对象，并要求果柄叶片、剥皮条带、放射切面、红瓤黑籽等身份特征跨面连续。禁止自然圆形水果、自然长条香蕉、非方块化完整水果、果切小贴纸、居中小物体、透明背景和留白，同时也禁止“单纯平铺材质 / 抽象纹理 / 只铺主题颜色 / 纯果皮材质 / 纯果肉纹理 / 纯叶脉纹理”。后端按 3x6 大单元和 4x3 UV 网切出 108 张 `256x256` 不透明面贴图，不再调用透明化、最大 alpha 连通主体保留或透明补边。洋红 `#FF00FF` 只作为图集安全缝 / UV 空位 / 外圈 key 色，裁切后若仍有极少残留则转成不透明材质底色；绿色、白色、雪地、云朵、草地、花朵、果肉粉色和浅黄色等主题颜色必须完整保留。 +- 验证：`cargo test -p api-server jump_hop --manifest-path server-rs/Cargo.toml -- --nocapture` 覆盖跳一跳 UV unwrap prompt、18 个大单元、108 张不透明面贴图、绿色 / 白色材质不被透明化、洋红 key 残留不作为透明洞；前端 `JumpHopRuntimeShell` 测试覆盖新 UV 资产会解析六张面贴图，旧单贴图资产仍可 fallback。 - 关联：`server-rs/crates/platform-image/src/generated_asset_sheets/alpha.rs`、`server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs`、`server-rs/crates/api-server/src/jump_hop.rs`。 ## 含中文 image2 live 验证不要用 PowerShell 管道喂 Node 源码 @@ -2170,3 +2212,12 @@ - 处理：`api-server` 构造生成结果订阅消息时，`time4` 固定格式化为北京时间 `YYYY-MM-DD HH:mm`；不要复用 `shared_kernel::format_timestamp_micros`。 - 验证：`cargo test --manifest-path server-rs\Cargo.toml -p api-server generation_result_template -- --nocapture`；dev 日志中不应再出现 `data.time4.value invalid`。 - 关联：`server-rs/crates/api-server/src/wechat_subscribe_message.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。 + +## 待解决：跳一跳生成超时后可能后台继续成功 + +- 风险程度：高。 +- 现象：跳一跳生成页可能在 `98% 写入正式草稿` 后报“请求超时，请稍后重试”，但后端仍在继续生成，稍后才把同一 session 写成 `DraftCompiled=100`。2026-06-08 排查 `jump-hop-session-6db8fa7af57c4fa2a71e6430cc808412` 时，背景底图 image2 成功但耗时约 `18分25秒`，返回按钮约 `2分44秒`，地板图集约 `1分46秒`，总耗时超过前端 20 分钟等待窗口，最终在前端超时后约 3 分钟写草稿成功。 +- 原因：跳一跳创作链路仍把背景、返回按钮、地板图集、切片和 OSS 写入串在一次 HTTP 请求里；VectorEngine image2 单步 timeout/connect 失败会在后端重试，单步耗时可能超过前端总等待窗口。中间资产和真实阶段没有落库，session 在完成前仍显示 `Collecting`、`progress_percent=0`，前端只能按时间显示假进度；超时后重试同一 session 时，后端还可能因为 session 没有中间素材而重新从背景开始生成。 +- 待处理：将跳一跳生成改为后端任务化 / 可轮询真实阶段进度，按背景、返回按钮、图集、切片、持久化、写草稿分阶段落库；统一后端全局生成 deadline、VectorEngine 重试预算、前端等待窗口和失败态回写。超时后再次进入同一 session 应优先恢复正在运行或已完成的任务，不应重复生图。 +- 验证：模拟首张 image2 超长耗时或超时重试时，生成页应显示真实阶段和可恢复状态；前端请求超时不应把最终成功草稿标记为失败；刷新 `/creation/jump-hop/generating?sessionId=` 后应能恢复到后端真实状态；同一 session 重试不得重复生成已完成阶段。 +- 关联：`src/services/jump-hop/jumpHopClient.ts`、`src/services/miniGameDraftGenerationProgress.ts`、`server-rs/crates/api-server/src/jump_hop.rs`、`server-rs/crates/platform-image/src/vector_engine/client.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。 diff --git a/apps/admin-web/src/api/adminApiClient.ts b/apps/admin-web/src/api/adminApiClient.ts index ef176285..0a3a1792 100644 --- a/apps/admin-web/src/api/adminApiClient.ts +++ b/apps/admin-web/src/api/adminApiClient.ts @@ -20,6 +20,7 @@ import type { AdminUpsertProfileRechargeProductRequest, AdminUpsertProfileRedeemCodeRequest, AdminUpsertProfileTaskConfigRequest, + AdminUpsertPublicWorkInteractionConfigRequest, AdminWorkVisibilityListResponse, ApiErrorEnvelope, ApiMeta, @@ -129,16 +130,16 @@ export async function request( export function loginAdmin(username: string, password: string) { return request('/admin/api/login', { method: 'POST', - body: {username, password}, + body: { username, password }, }); } export function getAdminMe(token: string) { - return request('/admin/api/me', {token}); + return request('/admin/api/me', { token }); } export function getAdminOverview(token: string) { - return request('/admin/api/overview', {token}); + return request('/admin/api/overview', { token }); } export function getAdminDatabaseTables(token: string) { @@ -154,7 +155,7 @@ export function getAdminDatabaseTableRows( ) { return request( `/admin/api/database/tables/${encodeURIComponent(tableName)}/rows${buildDatabaseTableRowsQuery(query)}`, - {token}, + { token }, ); } @@ -172,15 +173,14 @@ export function listAdminTrackingEvents( ) { return request( `/admin/api/tracking/events${buildQueryString(query)}`, - {token}, + { token }, ); } - export function getAdminCreationEntryConfig(token: string) { return request( '/admin/api/creation-entry/config', - {token}, + { token }, ); } @@ -213,10 +213,25 @@ export function upsertAdminCreationEntryBanners( ); } +/** 保存公开作品详情页点赞 / 改造能力配置。 */ +export function upsertAdminPublicWorkInteractions( + token: string, + payload: AdminUpsertPublicWorkInteractionConfigRequest, +) { + return request( + '/admin/api/creation-entry/config/interactions', + { + method: 'POST', + token, + body: payload, + }, + ); +} + export function listAdminWorkVisibility(token: string) { return request( '/admin/api/works/visibility', - {token}, + { token }, ); } @@ -237,7 +252,7 @@ export function updateAdminWorkVisibility( export function listProfileRedeemCodes(token: string) { return request( '/admin/api/profile/redeem-codes', - {token}, + { token }, ); } @@ -258,7 +273,7 @@ export function upsertProfileRedeemCode( export function listProfileInviteCodes(token: string) { return request( '/admin/api/profile/invite-codes', - {token}, + { token }, ); } @@ -293,7 +308,7 @@ export function disableProfileRedeemCode( export function listProfileTaskConfigs(token: string) { return request( '/admin/api/profile/tasks', - {token}, + { token }, ); } @@ -325,7 +340,7 @@ export function disableProfileTaskConfig( export function listProfileRechargeProducts(token: string) { return request( '/admin/api/profile/recharge-products', - {token}, + { token }, ); } @@ -414,13 +429,13 @@ function buildAdminApiError( ) { const envelope = isRecord(payload) ? (payload as ApiErrorEnvelope) : null; const errorPayload = envelope?.error; - const details = isRecord(errorPayload?.details) - ? errorPayload.details - : null; + const details = isRecord(errorPayload?.details) ? errorPayload.details : null; const detailsMessage = typeof details?.message === 'string' ? details.message.trim() : ''; const payloadMessage = - typeof errorPayload?.message === 'string' ? errorPayload.message.trim() : ''; + typeof errorPayload?.message === 'string' + ? errorPayload.message.trim() + : ''; const topLevelMessage = typeof envelope?.message === 'string' ? envelope.message.trim() : ''; const message = diff --git a/apps/admin-web/src/api/adminApiTypes.ts b/apps/admin-web/src/api/adminApiTypes.ts index 2eb58477..d3cb8ebe 100644 --- a/apps/admin-web/src/api/adminApiTypes.ts +++ b/apps/admin-web/src/api/adminApiTypes.ts @@ -107,12 +107,7 @@ export interface AdminDebugHeaderInput { value: string; } -export type AdminDebugHttpMethod = - | 'GET' - | 'POST' - | 'PUT' - | 'PATCH' - | 'DELETE'; +export type AdminDebugHttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'; export interface AdminDebugHttpRequest { method: AdminDebugHttpMethod; @@ -143,11 +138,11 @@ export interface AdminTrackingEventListQuery { limit?: number; } - /** 后台创作入口配置响应，同时包含模板入口和独立公告配置。 */ export interface AdminCreationEntryConfigResponse { entries: AdminCreationEntryTypeConfigPayload[]; eventBanners: AdminCreationEntryEventBannerPayload[]; + publicWorkInteractions: PublicWorkInteractionConfigPayload[]; } /** 后台创作入口公告位配置项；旧结构化 banner 字段仅保留兼容。 */ @@ -201,6 +196,20 @@ export interface AdminUpsertCreationEntryEventBannersRequest { eventBannersJson: string; } +/** 后台公开作品详情页互动能力配置项。 */ +export interface PublicWorkInteractionConfigPayload { + sourceType: string; + likeEnabled: boolean; + remixEnabled: boolean; + likeDisabledMessage: string; + remixDisabledMessage: string; +} + +/** 后台保存公开作品点赞 / 改造能力配置请求体。 */ +export interface AdminUpsertPublicWorkInteractionConfigRequest { + publicWorkInteractions: PublicWorkInteractionConfigPayload[]; +} + /** 后台统一创作工作台契约表单的传输结构。 */ export interface UnifiedCreationSpecPayload { playId: string; diff --git a/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.test.tsx b/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.test.tsx index 4400b5da..0022c263 100644 --- a/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.test.tsx +++ b/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.test.tsx @@ -1,19 +1,26 @@ /* @vitest-environment jsdom */ -import {fireEvent, render, screen, waitFor, within} from '@testing-library/react'; +import { + fireEvent, + render, + screen, + waitFor, + within, +} from '@testing-library/react'; import userEvent from '@testing-library/user-event'; -import {beforeEach, expect, test, vi} from 'vitest'; +import { beforeEach, expect, test, vi } from 'vitest'; import { getAdminCreationEntryConfig, upsertAdminCreationEntryBanners, upsertAdminCreationEntryConfig, + upsertAdminPublicWorkInteractions, } from '../api/adminApiClient'; import type { AdminCreationEntryConfigResponse, UnifiedCreationSpecPayload, } from '../api/adminApiTypes'; -import {AdminCreationEntrySwitchPage} from './AdminCreationEntrySwitchPage'; +import { AdminCreationEntrySwitchPage } from './AdminCreationEntrySwitchPage'; vi.mock('../api/adminApiClient', () => ({ formatAdminApiError: vi.fn((error: unknown) => @@ -23,6 +30,7 @@ vi.mock('../api/adminApiClient', () => ({ isAdminApiError: vi.fn(() => false), upsertAdminCreationEntryBanners: vi.fn(), upsertAdminCreationEntryConfig: vi.fn(), + upsertAdminPublicWorkInteractions: vi.fn(), })); const puzzleSpec: UnifiedCreationSpecPayload = { @@ -55,6 +63,15 @@ const configResponse: AdminCreationEntryConfigResponse = { htmlCode: '
后台公告
', }, ], + publicWorkInteractions: [ + { + sourceType: 'puzzle', + likeEnabled: true, + remixEnabled: true, + likeDisabledMessage: '拼图点赞暂不可用。', + remixDisabledMessage: '拼图作品改造暂不可用。', + }, + ], entries: [ { id: 'puzzle', @@ -79,16 +96,24 @@ beforeEach(() => { vi.mocked(getAdminCreationEntryConfig).mockResolvedValue(configResponse); vi.mocked(upsertAdminCreationEntryBanners).mockResolvedValue(configResponse); vi.mocked(upsertAdminCreationEntryConfig).mockResolvedValue(configResponse); + vi.mocked(upsertAdminPublicWorkInteractions).mockResolvedValue( + configResponse, + ); }); test('创作入口后台展示并保存统一创作契约', async () => { const user = userEvent.setup(); - const {container} = render( - , + const { container } = render( + , ); await screen.findByText('pictureDescription'); - expect(container.querySelector('.admin-subsection .admin-info-list')).not.toBeNull(); + expect( + container.querySelector('.admin-subsection .admin-info-list'), + ).not.toBeNull(); expect( container.querySelector('.admin-subsection .admin-info-list')?.textContent, ).toContain('拼图'); @@ -97,22 +122,22 @@ test('创作入口后台展示并保存统一创作契约', async () => { expect(screen.queryByLabelText('契约 JSON')).toBeNull(); expect(screen.queryByText('puzzle-generating')).toBeNull(); - await user.click(screen.getByRole('button', {name: '修改契约'})); - const dialog = screen.getByRole('dialog', {name: '统一创作契约'}); + await user.click(screen.getByRole('button', { name: '修改契约' })); + const dialog = screen.getByRole('dialog', { name: '统一创作契约' }); expect(within(dialog).queryByLabelText('玩法 ID')).toBeNull(); expect(within(dialog).queryByLabelText('工作台阶段')).toBeNull(); expect(within(dialog).queryByLabelText('生成阶段')).toBeNull(); expect(within(dialog).queryByLabelText('结果阶段')).toBeNull(); fireEvent.change(within(dialog).getByLabelText('泥点消耗'), { - target: {value: '12'}, + target: { value: '12' }, }); - await user.click(within(dialog).getByRole('button', {name: '应用修改'})); + await user.click(within(dialog).getByRole('button', { name: '应用修改' })); - expect(screen.queryByRole('dialog', {name: '统一创作契约'})).toBeNull(); + expect(screen.queryByRole('dialog', { name: '统一创作契约' })).toBeNull(); expect(screen.getByText('12泥点数')).toBeTruthy(); - await user.click(screen.getByRole('button', {name: '保存入库'})); - await user.click(screen.getByRole('button', {name: '确认'})); + await user.click(screen.getByRole('button', { name: '保存入库' })); + await user.click(screen.getByRole('button', { name: '确认' })); await waitFor(() => { expect(upsertAdminCreationEntryConfig).toHaveBeenCalledWith( @@ -150,9 +175,11 @@ test('创作入口后台拒绝 playId 不一致的统一创作契约', async () ); await screen.findByText('pictureDescription'); - await user.click(screen.getByRole('button', {name: '保存入库'})); + await user.click(screen.getByRole('button', { name: '保存入库' })); - expect(await screen.findByText('统一创作契约 playId 必须与入口 ID 一致')).toBeTruthy(); + expect( + await screen.findByText('统一创作契约 playId 必须与入口 ID 一致'), + ).toBeTruthy(); expect(upsertAdminCreationEntryConfig).not.toHaveBeenCalled(); }); @@ -166,23 +193,25 @@ test('创作入口后台用表单保存公告配置', async () => { />, ); - expect(await screen.findAllByRole('heading', {name: '创作入口公告'})).toHaveLength(2); + expect( + await screen.findAllByRole('heading', { name: '创作入口公告' }), + ).toHaveLength(2); expect(screen.queryByLabelText('公告代码 JSON')).toBeNull(); fireEvent.change(await screen.findByLabelText('公告 1 标题'), { - target: {value: '周末创作赛'}, + target: { value: '周末创作赛' }, }); fireEvent.change(screen.getByLabelText('公告 1 HTML'), { - target: {value: '
新的入口公告
'}, + target: { value: '
新的入口公告
' }, }); - await user.click(screen.getByRole('button', {name: '新增公告'})); + await user.click(screen.getByRole('button', { name: '新增公告' })); fireEvent.change(screen.getByLabelText('公告 2 标题'), { - target: {value: '第二条公告'}, + target: { value: '第二条公告' }, }); fireEvent.change(screen.getByLabelText('公告 2 HTML'), { - target: {value: '
轮播第二条
'}, + target: { value: '
轮播第二条
' }, }); - await user.click(screen.getByRole('button', {name: '保存公告'})); - await user.click(screen.getByRole('button', {name: '确认'})); + await user.click(screen.getByRole('button', { name: '保存公告' })); + await user.click(screen.getByRole('button', { name: '确认' })); await waitFor(() => { expect(upsertAdminCreationEntryBanners).toHaveBeenCalled(); @@ -206,6 +235,42 @@ test('创作入口后台用表单保存公告配置', async () => { ); }); +test('创作入口后台用表单保存作品互动配置', async () => { + const user = userEvent.setup(); + render( + , + ); + + await screen.findByText('作品互动'); + const likeToggle = screen.getAllByRole('checkbox')[0]!; + await user.click(likeToggle); + fireEvent.change(screen.getByLabelText('拼图 / puzzle 点赞关闭提示'), { + target: { value: '拼图点赞维护中。' }, + }); + await user.click(screen.getByRole('button', { name: '保存作品互动' })); + await user.click(screen.getByRole('button', { name: '确认' })); + + await waitFor(() => { + expect(upsertAdminPublicWorkInteractions).toHaveBeenCalledWith( + 'admin-token', + { + publicWorkInteractions: [ + { + sourceType: 'puzzle', + likeEnabled: false, + remixEnabled: true, + likeDisabledMessage: '拼图点赞维护中。', + remixDisabledMessage: '拼图作品改造暂不可用。', + }, + ], + }, + ); + }); +}); + test('创作入口后台把旧结构化公告回显成 HTML 表单', async () => { vi.mocked(getAdminCreationEntryConfig).mockResolvedValueOnce({ ...configResponse, @@ -251,12 +316,12 @@ test('创作入口后台拒绝空公告表单', async () => { ); fireEvent.change(await screen.findByLabelText('公告 1 标题'), { - target: {value: ''}, + target: { value: '' }, }); fireEvent.change(screen.getByLabelText('公告 1 HTML'), { - target: {value: ''}, + target: { value: '' }, }); - await user.click(screen.getByRole('button', {name: '保存公告'})); + 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 e00c848b..8a674650 100644 --- a/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.tsx +++ b/apps/admin-web/src/pages/AdminCreationEntrySwitchPage.tsx @@ -5,10 +5,12 @@ import { getAdminCreationEntryConfig, upsertAdminCreationEntryBanners, upsertAdminCreationEntryConfig, + upsertAdminPublicWorkInteractions, } from '../api/adminApiClient'; import type { AdminCreationEntryEventBannerPayload, AdminCreationEntryTypeConfigPayload, + PublicWorkInteractionConfigPayload, UnifiedCreationFieldPayload, UnifiedCreationSpecPayload, } from '../api/adminApiTypes'; @@ -129,14 +131,28 @@ const DEFAULT_UNIFIED_CREATION_STAGE_MAP: Record< let announcementFormItemSequence = 0; let unifiedCreationSpecFieldSequence = 0; +const PUBLIC_WORK_SOURCE_LABELS: Record = { + 'custom-world': 'RPG', + 'big-fish': '摸鱼', + puzzle: '拼图', + 'puzzle-clear': '拼消消', + 'jump-hop': '跳一跳', + 'wooden-fish': '敲木鱼', + match3d: '抓大鹅', + 'square-hole': '方洞挑战', + 'visual-novel': '视觉小说', + 'bark-battle': '汪汪声浪', + edutainment: '宝贝识物', +}; + export function AdminCreationEntrySwitchPage({ token, onUnauthorized, mode = 'switches', }: AdminCreationEntrySwitchPageProps) { - const [entries, setEntries] = useState< - AdminCreationEntryTypeConfigPayload[] - >([]); + const [entries, setEntries] = useState( + [], + ); const [selectedId, setSelectedId] = useState('puzzle'); const [title, setTitle] = useState(''); const [subtitle, setSubtitle] = useState(''); @@ -157,12 +173,17 @@ export function AdminCreationEntrySwitchPage({ const [announcementItems, setAnnouncementItems] = useState< AnnouncementFormItem[] >([]); + const [publicWorkInteractions, setPublicWorkInteractions] = useState< + PublicWorkInteractionConfigPayload[] + >([]); const [isLoading, setIsLoading] = useState(false); const [isSaving, setIsSaving] = useState(false); const [isSavingBanners, setIsSavingBanners] = useState(false); + const [isSavingInteractions, setIsSavingInteractions] = useState(false); const [listErrorMessage, setListErrorMessage] = useState(''); const [errorMessage, setErrorMessage] = useState(''); const [bannerErrorMessage, setBannerErrorMessage] = useState(''); + const [interactionErrorMessage, setInteractionErrorMessage] = useState(''); const { confirmWrite, confirmDialog } = useAdminWriteConfirm(); const isAnnouncementMode = mode === 'announcements'; @@ -179,6 +200,7 @@ export function AdminCreationEntrySwitchPage({ const nextEntries = sortEntries(response.entries); setEntries(nextEntries); setAnnouncementItems(formatEventBannersFormItems(response.eventBanners)); + setPublicWorkInteractions(response.publicWorkInteractions ?? []); fillForm( nextEntries.find((entry) => entry.id === selectedId) ?? nextEntries[0] ?? @@ -234,6 +256,7 @@ export function AdminCreationEntrySwitchPage({ const nextEntries = sortEntries(response.entries); setEntries(nextEntries); setAnnouncementItems(formatEventBannersFormItems(response.eventBanners)); + setPublicWorkInteractions(response.publicWorkInteractions ?? []); fillForm(nextEntries.find((entry) => entry.id === targetId) ?? null); } catch (error: unknown) { handlePageError(error, onUnauthorized, setErrorMessage); @@ -269,6 +292,7 @@ export function AdminCreationEntrySwitchPage({ }); setEntries(sortEntries(response.entries)); setAnnouncementItems(formatEventBannersFormItems(response.eventBanners)); + setPublicWorkInteractions(response.publicWorkInteractions ?? []); } catch (error: unknown) { handlePageError(error, onUnauthorized, setBannerErrorMessage); } finally { @@ -276,6 +300,41 @@ export function AdminCreationEntrySwitchPage({ } } + /** 保存公开作品详情页点赞 / 改造能力开关。 */ + async function handleSavePublicWorkInteractions() { + if (isSavingInteractions) { + return; + } + + setInteractionErrorMessage(''); + const confirmed = await confirmWrite({ + action: '保存作品互动配置', + target: 'public-work-interactions', + }); + if (!confirmed) { + return; + } + + setIsSavingInteractions(true); + try { + const response = await upsertAdminPublicWorkInteractions(token, { + publicWorkInteractions: publicWorkInteractions.map((item) => ({ + ...item, + sourceType: item.sourceType.trim(), + likeDisabledMessage: item.likeDisabledMessage.trim(), + remixDisabledMessage: item.remixDisabledMessage.trim(), + })), + }); + setEntries(sortEntries(response.entries)); + setAnnouncementItems(formatEventBannersFormItems(response.eventBanners)); + setPublicWorkInteractions(response.publicWorkInteractions ?? []); + } catch (error: unknown) { + handlePageError(error, onUnauthorized, setInteractionErrorMessage); + } finally { + setIsSavingInteractions(false); + } + } + function fillForm(entry: AdminCreationEntryTypeConfigPayload | null) { if (!entry) { return; @@ -361,7 +420,10 @@ export function AdminCreationEntrySwitchPage({ currentForm ? { ...currentForm, - fields: [...currentForm.fields, createUnifiedCreationSpecFieldFormItem()], + fields: [ + ...currentForm.fields, + createUnifiedCreationSpecFieldFormItem(), + ], } : currentForm, ); @@ -377,7 +439,10 @@ export function AdminCreationEntrySwitchPage({ ); return { ...currentForm, - fields: fields.length > 0 ? fields : [createUnifiedCreationSpecFieldFormItem()], + fields: + fields.length > 0 + ? fields + : [createUnifiedCreationSpecFieldFormItem()], }; }); } @@ -414,6 +479,26 @@ export function AdminCreationEntrySwitchPage({ }); } + /** 更新单条公开作品互动配置。 */ + function updatePublicWorkInteraction( + index: number, + patch: Partial< + Pick< + PublicWorkInteractionConfigPayload, + | 'likeEnabled' + | 'remixEnabled' + | 'likeDisabledMessage' + | 'remixDisabledMessage' + > + >, + ) { + setPublicWorkInteractions((currentItems) => + currentItems.map((item, itemIndex) => + itemIndex === index ? { ...item, ...patch } : item, + ), + ); + } + return (
@@ -515,191 +600,288 @@ export function AdminCreationEntrySwitchPage({ ) : null} {!isAnnouncementMode ? ( -
-
-
- - - + <> +
+
+

作品互动

+ {`${publicWorkInteractions.length} 类`}
- -
- - -
- - - - - - - -
- - -
- - - -
-
- 统一创作契约 - - {unifiedCreationSpec ? '已配置' : '未配置'} - -
-
- - {unifiedCreationSpec ? ( - - ) : null} -
- {unifiedCreationSpec ? ( - - ) : ( -
未配置统一创作页契约
- )} -
- - {errorMessage ? ( -
- {errorMessage} -
- ) : null} - -
- -
- - -
- - - - - - + + + + + - {entries.map((entry) => ( - + {publicWorkInteractions.map((item, index) => ( + + + + + - - - - - ))}
入口展示开放统一契约分类排序作品类型点赞点赞关闭提示改造改造关闭提示
{formatPublicWorkSourceLabel(item.sourceType)} - + + + + updatePublicWorkInteraction(index, { + likeDisabledMessage: event.target.value, + }) + } + /> + + + + + updatePublicWorkInteraction(index, { + remixDisabledMessage: event.target.value, + }) + } + /> {entry.visible ? '是' : '否'}{entry.open ? '是' : '否'}{entry.unifiedCreationSpec ? '是' : '否'}{entry.categoryLabel || entry.categoryId}{entry.sortOrder}
+ {interactionErrorMessage ? ( +
+ {interactionErrorMessage} +
+ ) : null} +
+ +
-
+ +
+
+
+ + + +
+ +
+ + +
+ + + + + + + +
+ + +
+ + + +
+
+ 统一创作契约 + {unifiedCreationSpec ? '已配置' : '未配置'} +
+
+ + {unifiedCreationSpec ? ( + + ) : null} +
+ {unifiedCreationSpec ? ( + + ) : ( +
未配置统一创作页契约
+ )} +
+ + {errorMessage ? ( +
+ {errorMessage} +
+ ) : null} + +
+ +
+
+ +
+
+ + + + + + + + + + + + + {entries.map((entry) => ( + + + + + + + + + ))} + +
入口展示开放统一契约分类排序
+ + {entry.visible ? '是' : '否'}{entry.open ? '是' : '否'}{entry.unifiedCreationSpec ? '是' : '否'}{entry.categoryLabel || entry.categoryId}{entry.sortOrder}
+
+
+
+ ) : null} {confirmDialog} @@ -776,7 +958,10 @@ export function AdminCreationEntrySwitchPage({
{unifiedCreationSpecForm.fields.map((field, index) => ( -
+
{`字段 ${index + 1}`}