Compare commits
1 Commits
codex/puzz
...
codex/oss-
| Author | SHA1 | Date | |
|---|---|---|---|
| 5daeef21bf |
@@ -111,9 +111,6 @@ WECHAT_MOCK_DISPLAY_NAME="微信旅人"
|
||||
WECHAT_MOCK_AVATAR_URL=""
|
||||
WECHAT_MINIPROGRAM_MESSAGE_TOKEN=""
|
||||
WECHAT_MINIPROGRAM_MESSAGE_ENCODING_AES_KEY=""
|
||||
WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_ENABLED="true"
|
||||
WECHAT_MINIPROGRAM_GENERATION_RESULT_TEMPLATE_ID="m5z7BkkBhJGbcH0cdDeHaeRU2tViDEguP38XdrRRCdU"
|
||||
WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_STATE="formal"
|
||||
|
||||
# Model name for chat completions.
|
||||
VITE_LLM_MODEL="doubao-1-5-pro-32k-character-250715"
|
||||
|
||||
@@ -16,500 +16,12 @@
|
||||
|
||||
---
|
||||
|
||||
## 2026-06-11 本地服务器管理入口采用 SSH alias + egui 桌面面板
|
||||
|
||||
- 背景：release / dev 等服务器的日常巡检已有 systemd、健康巡检 timer 和 HTTP 探测口径，但开发者本地仍需要在多个 SSH alias 间手工切换命令并重复执行启停操作。
|
||||
- 决策：新增 `server-rs/crates/server-manager-panel` 作为本地 egui 桌面工具；服务器来源只读取本机 `~/.ssh/config` 的具体 `Host` alias，不保存服务器密钥或凭据；巡检通过 `ssh <alias> sh -s` 执行只读脚本，服务操作只允许 `start`、`stop`、`restart` 并限制 systemd unit 名字符集。
|
||||
- 影响范围：本地运维工具入口、`package.json` 的 `server-manager:panel`、开发运维文档和团队共享工作流。
|
||||
- 验证方式：`cargo check -p server-manager-panel --manifest-path server-rs/Cargo.toml`、`cargo test -p server-manager-panel --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md`。
|
||||
|
||||
## 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 通用分享统一为作品分享卡片
|
||||
|
||||
- 背景：已发布作品的分享入口需要同时支持网页复制链接、下载可传播的分享卡，以及微信小程序内的九宫切图；推荐页在小程序内直接使用系统“分享到聊天”时，宿主快照只截页面中部，容易裁掉游戏主体，且原生分享默认只能拿到小程序页面启动参数。
|
||||
- 决策：统一分享入口继续收口到 `PublishShareModal`，分享卡展示作品封面、作品类型、作品名称和公开作品号，底部提供“复制链接”和“下载卡片”。普通 H5 复制公开作品 H5 URL；微信小程序 WebView 内复制小程序 `pages/web-view/index` 路径，缺少直达参数时补 `targetPath=/works/detail` 与 `work=<公开作品号>`，由小程序原生 WebView 页转成 H5 作品详情 URL。当 H5 运行在微信小程序 WebView 内且存在封面图时，额外显示“九宫切图”，跳转小程序原生 `pages/share-grid/index`，由原生页按 3x3 从左到右、从上到下裁切并保存。推荐页当前作品会通过 `wx.miniProgram.postMessage` 同步给小程序原生 `web-view` 页，右上角系统分享优先使用该目标生成带作品参数的小程序路径。小程序运行态通过根节点标记启用推荐页 runtime 快照安全区，把游戏画面等比缩放到分享快照中部。
|
||||
- 影响范围：`src/components/common/PublishShareModal.tsx`、`src/components/common/publishShareModalModel.ts`、`src/components/common/publishShareCardImage.ts`、`src/services/wechatMiniProgramShareGrid.ts`、`src/services/wechatMiniProgramShareTarget.ts`、`miniprogram/pages/web-view/`、`miniprogram/pages/share-grid/`、推荐页 runtime CSS 和平台玩法链路文档。
|
||||
- 验证方式：`npm run test -- src/components/common/PublishShareModal.test.tsx miniprogram/pages/web-view/index.test.js src/services/wechatMiniProgramShareTarget.test.ts`、`npm run test -- miniprogram/pages/share-grid/index.test.js`、`npm run test -- src/index.test.ts -t "mini program recommend runtime"`、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
## 2026-06-08 微信能力按领域收口
|
||||
|
||||
- 背景：微信登录、订阅消息、普通微信支付和小程序虚拟支付能力曾分散在 `api-server` 根模块、`platform-auth` 与 `platform-wechat`，支付协议细节和业务 handler 边界不够清晰。
|
||||
- 决策：`api-server` 内微信相关 HTTP/BFF 适配统一收在 `server-rs/crates/api-server/src/wechat.rs` 与 `wechat/*`；`platform-wechat` 负责微信订阅消息、微信支付 V3、虚拟支付消息推送的协议 client、header、签名、验签、解密、mock 和 payload 解析；`api-server::wechat` 只负责 AppConfig 映射、Axum handler、用户 / 订单 / 钱包 / SSE / 错误 envelope 编排。微信 OAuth / 小程序登录 provider 暂继续在 `platform-auth`，通过 `api-server::wechat::provider` 作为组合根 adapter 接入。
|
||||
- 影响范围：`server-rs/crates/api-server/src/wechat.rs`、`server-rs/crates/api-server/src/wechat/*`、`server-rs/crates/platform-wechat/src/*`、微信支付 / 订阅消息 / 小程序消息推送文档。
|
||||
- 验证方式：执行 `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/<play>/*`、历史 `/api/runtime/<play>/agent/*` 与公开 runtime 路由外部契约不变。
|
||||
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-08 PlatformUiKit 弹窗与复制反馈收口
|
||||
|
||||
- 背景：前端已有 `UnifiedModal` 统一遮罩和无障碍外壳，但业务页面仍反复手写“知道了”“确认 / 取消”“危险确认”的 footer 按钮和关闭禁用逻辑。
|
||||
- 决策：简单提示、确认 / 取消和危险确认统一使用 `src/components/common/UnifiedConfirmDialog.tsx`；剪贴板复制反馈统一使用 `src/components/common/useCopyFeedback.ts`，可点击复制按钮统一使用 `src/components/common/CopyFeedbackButton.tsx` 承载图标、三态文案、可访问名称、纯图标模式和动作按钮外观入口，作品号 / 用户号等短代码 chip 统一使用 `src/components/common/CopyCodeButton.tsx` 承载代码、三态后缀和默认可访问名称，非按钮复制提示统一使用 `src/components/common/CopyFeedbackMessage.tsx`，白底平台状态提示统一使用 `src/components/common/PlatformStatusMessage.tsx`，无操作空态 / 轻量读取态统一使用 `src/components/common/PlatformEmptyState.tsx`，平台动作按钮统一使用 `src/components/common/PlatformActionButton.tsx` 承载 platform / profile 两类样式族、尺寸、圆角、对齐、宽度和禁用态；认证表单的提交、验证码、第三方登录和邀请码提交按钮使用 `size="lg"` 复用 48px 高度，统一创作工作台、统一创作页壳层、玩法创作工作台、结果页返回按钮和反馈页 header 返回使用 `tone="ghost"`，生成 / 提交 / 发布按钮使用主动作，自定义世界实体目录、RPG 首页作品卡删除、创作中心错误重试和素材槽的小动作使用 `size="xs"` 或 `shape="pill"` 收口，推荐回复和列表内动作使用 `align="start"` 承接左对齐，上传控件等需要 label 语义时使用 `PlatformActionButton asChild="label"`，不把文件输入伪装成普通 button。普通平台图标动作按钮和图标上传 label 统一使用 `src/components/common/PlatformIconButton.tsx` 承载 `platform-icon-button` 外观、可访问名称、默认 `type="button"`、`asChild="label"` 和可选 title；历史图片选择弹窗、RPG 发布检查弹窗、RPG 首页搜索结果清空、creative-agent 侧边栏关闭 / 外观 / 设置入口、creation-agent 参考图移除、敲木鱼结果页新增主题标签入口、拼图结果页标签生成 / 标签新增 / 关卡详情关闭 / 发布弹窗关闭 / 删除关卡入口、视觉小说结果页素材选择 / 音频生成 / 保存草稿 / 运行配置入口，以及抓大鹅结果页标签生成 / 标签新增 / 物品素材删除 / 参考图上传入口已先迁移；图标上传控件必须保留 label + file input 语义。平台 / 个人中心弹窗关闭按钮统一使用 `src/components/common/PlatformModalCloseButton.tsx` 承载 profile / profileCompact / floating / floatingPlain / platformIcon 五类圆形关闭按钮、默认图标和可访问名称；认证入口、邀请码弹窗、抓大鹅结果页弹窗关闭等平台头部关闭按钮使用 `variant="platformIcon"`，不在业务 JSX 中手写 `platform-icon-button` + X 图标。RPG / 拼图 / 抓大鹅 / 跳一跳 / 敲木鱼 / 拼消消 / 宝贝识物 / 方洞 / 汪汪声浪结果页，拼消消 / 宝贝识物 / 视觉小说 / 汪汪声浪创作工作台，发布检查、素材生成面板和自定义世界实体目录中的错误 / 成功 / 信息 / 警告 / 中性提示使用 `PlatformStatusMessage surface="platform"` 复用平台 banner token；个人中心弹窗、账号安全弹窗、认证入口、验证码提示、统一创作工作台和通用创作输入区的错误 / 成功 / 信息 / 警告提示使用 `PlatformStatusMessage surface="profile"` 复用 profile token，不再把 `platform-profile-error` / `platform-profile-success` 或 `platform-banner--danger / success / info / warning / neutral` 作为业务 JSX 接口。`UnifiedModal` 继续作为底层模态窗口 Module。已有弹窗栈内的二级确认使用 `UnifiedConfirmDialog portal={false}` 内嵌到当前层级。特殊确认按钮外观通过 `confirmClassName` 适配，不让业务页重新手写 footer；`UnifiedConfirmDialog` 自身的 footer 按钮也复用 `PlatformActionButton`。带复制状态、渠道按钮、媒体预览或复杂网格的弹窗可以保留专用 Module，但普通确认按钮、普通动作按钮、普通图标动作按钮、复制按钮动作外观、复制状态机、copied / failed 按钮 / toast 分支、基础错误 / 成功提示条、无操作空态和普通弹窗关闭按钮不再直接写进业务页面。运行态 HUD、输入 Composer 发送 / 上传按钮、复制三态图标按钮或需要专用交互禁用语义的图标按钮先保留专用布局，等对应场景验证时再迁移。业务代码中的阻断提示、删除确认和公开作品失效恢复不得继续调用浏览器原生 `window.alert` / `window.confirm`，应由页面壳层或编辑器壳层用 `UnifiedConfirmDialog` 承接。简单确认需要像素风时使用 `UnifiedConfirmDialog variant="pixel"`，不再为同类确认单独维护壳层和按钮。
|
||||
- 2026-06-10 追加：推荐页运行态卡片底部的点赞 / 分享 / 改造入口，以及创作中心公开作品卡右上角分享入口统一迁移到 `PlatformIconButton`；这类和 swipe / drag 手势耦合的图标动作必须继续保留业务局部 class 与 `onPointerDown` / `onClick` 里的 `stopPropagation`，只把按钮语义、可访问名称和默认 `type="button"` 收口到共享组件，避免图标动作误触推荐卡切换、整卡打开或残留左滑状态。
|
||||
- 2026-06-10 追加：标准泥点消耗确认弹窗统一收口到 `src/components/common/PlatformMudPointConfirmDialog.tsx`；该 Module 专门承接“确认消耗泥点 + 消耗 N 泥点”的同形态确认骨架，当前已覆盖 `PuzzleCreationWorkspace.tsx`、`Match3DCreationWorkspace.tsx`、`PuzzleResultView.tsx` 与 `Match3DResultView.tsx`。后续遇到同形态泥点确认时，业务页只传点数、补充说明和确认回调，不再重复拼接 `UnifiedConfirmDialog` 正文；`RpgCreationRoleAssetStudioModalImpl` 这类节奏和内容结构不同的泥点弹层继续单独评估，留作后续轮次处理。
|
||||
- 2026-06-10 追加：`RpgCreationRoleAssetStudioModalImpl.tsx` 的角色形象生成 / 动作草稿生成确认也并入 `PlatformMudPointConfirmDialog`；共享组件通过自定义 title 与补充说明承接工坊语义，工坊页不再单独维护 `UnifiedConfirmDialog` 的标准泥点文案骨架。后续同类“确认消耗泥点 + 补充说明”场景继续优先复用该 Module。
|
||||
- 2026-06-10 追加：平台危险确认统一收口到 `src/components/common/PlatformDangerConfirmDialog.tsx`；该 Module 专门承接“确认 / 取消 + 危险主动作”的标准骨架，当前已覆盖 `PlatformEntryFlowShellImpl.tsx` 的删除作品确认、`RpgCreationResultViewImpl.tsx` 的重新生成确认和 `CustomWorldEntityCatalog.tsx` 的删除角色 / 批量删除确认。后续删除、覆盖、清空等危险动作优先复用该 Module，不再在业务页重复拼接 `UnifiedConfirmDialog` 的 `showCancel + confirmTone=\"danger\"` 组合。
|
||||
- 2026-06-10 追加：平台未保存离开确认统一收口到 `src/components/common/PlatformUnsavedLeaveConfirmDialog.tsx`；该 Module 专门承接“继续编辑 + 确认离开”的标准骨架，当前已覆盖 `RpgCreationEntityEditorShared.tsx` 里的关闭未保存修改、生成结果未保存退出和普通结果未保存退出确认。后续同类未保存离开场景优先复用该 Module，不再在业务页重复拼接 `UnifiedConfirmDialog` 的 `showCancel + cancelLabel=\"继续编辑\"` 组合和重复壳层 class。
|
||||
- 2026-06-10 追加：平台单按钮已读状态统一收口到 `src/components/common/PlatformAcknowledgeStatusDialog.tsx`；该 Module 专门承接“状态提示 + 知道了”的单按钮确认已读语义，当前已覆盖 `BigFishResultView.tsx` 的发布失败提示、`RpgEntryHomeView.tsx` 的支付结果提示、`RpgCreationEntityEditorShared.tsx` 的编辑器 notice、`PlatformEntryFlowShellImpl.tsx` 的泥点提示 / 作品不可用 / 搜索未命中提示，以及 `CustomWorldEntityCatalog.tsx` 的“无法删除”阻断提示。后续同类 status-dialog 场景优先复用该 Module，不再在业务页重复拼装 `action={{ label: '知道了', onClick: onClose }}`。
|
||||
- 2026-06-10 追加：RPG 首页个人中心里的统计卡、统计骨架、常用功能入口、设置行和法律信息入口统一抽到 `src/components/platform-entry/PlatformProfilePrimitives.tsx`；这组纯展示原子以后优先通过 props 接收图片资源、点击回调和展示文案，不再继续塞回 `RpgEntryHomeView` 的账户控制逻辑里。新建 `PlatformProfilePrimitives.test.tsx` 作为组件级护栏，页面级布局与法律入口继续由 `RpgEntryHomeView.recharge.test.tsx` 兜底。
|
||||
- 2026-06-10 追加：RPG 首页个人中心的充值 / 钱包 / 每日任务 / 邀请 / 兑换码等商业与账户控制逻辑统一收口到 `src/components/platform-entry/usePlatformProfileCenterController.ts`；controller 负责账户动作分流、商业状态派生与相关面板控制，`RpgEntryHomeView` 只保留展示、昵称头像编辑、扫码入口和页面级交互编排，不在页面组件里继续堆叠账户控制分支。验证命令：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`。
|
||||
- 2026-06-10 追加：RPG 首页个人中心的“玩过 / 可继续”历史弹层统一抽到 `src/components/platform-entry/PlatformProfilePlayedWorksModal.tsx`；`RpgEntryHomeView` 不再内联 `SaveArchiveCard`、`ProfilePlayedWorksModal` 和未连通的 `ProfileSaveArchivesModal`。当前产品语义已经把存档恢复并入“玩过”弹层的“可继续”分区，因此 controller 里的 `ProfilePopupPanel` 也去掉了没有真实入口的 `saveArchives` 分支。验证命令：`npm run test -- src/components/platform-entry/PlatformProfilePlayedWorksModal.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`。
|
||||
- 2026-06-10 追加：个人中心标准头部弹窗与白底副弹层的共享壳层统一抽到 `src/components/platform-entry/PlatformProfileModalShell.tsx`；标准头部弹窗优先复用 `PlatformProfileModalShell`，白底副弹层优先复用 `PlatformProfileSecondaryModalShell`，不再在业务页重复手写 profile overlay、header、title、description、floating close 和关闭策略。昵称修改、账户充值、每日任务、兑换码、泥点账单、“玩过 / 可继续”以及邀请相关弹层已接入这套壳层。
|
||||
- 2026-06-10 追加：RPG 首页个人中心的邀请好友 / 填邀请码 / 玩家社区三态弹层统一抽到 `src/components/platform-entry/PlatformProfileReferralModal.tsx`；首页不再内联邀请码规范化、社区二维码卡片和邀请用户头像行，后续 profile 侧同类二级弹层优先按“独立组件 + `PlatformProfileSecondaryModalShell`”继续收口。
|
||||
- 2026-06-10 追加：RPG 首页个人中心的账户充值弹层统一抽到 `src/components/platform-entry/PlatformProfileRechargeModal.tsx`；充值 tab、套餐卡片、Native 二维码生成和确认支付入口不再内联在 `RpgEntryHomeView`，后续 profile 侧充值入口优先复用同一个组件。
|
||||
- 2026-06-10 追加：RPG 首页个人中心的泥点账单、每日任务和兑换码弹层统一抽到 `src/components/platform-entry/PlatformProfileWalletLedgerModal.tsx`、`src/components/platform-entry/PlatformProfileTaskCenterModal.tsx` 与 `src/components/platform-entry/PlatformProfileRewardCodeRedeemModal.tsx`；`RpgEntryHomeView` 只保留打开条件和数据流，标准 profile 弹层内容以后优先沉到 `platform-entry` 独立组件，不在首页继续堆叠。
|
||||
- 2026-06-10 追加：个人中心支付结果提示与支付确认遮罩统一抽到 `src/components/common/PlatformStatusDialog.tsx`，扫码面板统一抽到 `src/components/platform-entry/PlatformProfileQrScannerModal.tsx`；`RpgEntryHomeView` 只保留支付结果 kind 到 `success / loading / cancel / error` 的映射、确认遮罩开关和扫码结果写回，不再内联 profile 状态弹层壳层、二维码摄像头启动或 `BarcodeDetector` 轮询。后续 profile 侧同类“状态图标 + 标题正文 + 可选主动作”弹层优先复用 `PlatformStatusDialog`，扫码类弹层优先复用 `PlatformProfileQrScannerModal`。
|
||||
- 2026-06-10 追加：`PlatformStatusDialog` 支持自定义图标、图标可访问标签以及动作按钮 surface / size / className 透传，用来承接玩法结果页里保留品牌视觉但语义仍是“状态结果弹层”的场景；大鱼吃小鱼结果页的发布失败弹层已迁移到这套组件，业务页不再保留 `UnifiedConfirmDialog + PlatformIconBadge` 的专用组合。
|
||||
- 2026-06-10 追加：`PlatformStatusDialog` 继续支持 header notice 布局、body content、close button、backdrop / Escape 关闭路径，用来承接“提示 / 规则阻断 / 作品不可用 / 泥点不足”这类带标题栏的状态 notice；平台入口的 `draftGenerationPointNotice`、`workNotFoundRecoveryDialog` 和 RPG 大编辑器里的 `EditorNoticeDialog` 已迁移到这套共享组件，不再各自维护 `UnifiedConfirmDialog` 壳层和关闭策略。
|
||||
- 2026-06-10 追加：`CustomWorldEntityCatalog` 的 `minimum-playable` 规则阻断提示也统一迁到 `PlatformStatusDialog`，不再和删除角色 / 批量删除共用 `UnifiedConfirmDialog` 配置；同日平台入口公开编号搜索把 error 分支从用户摘要 modal 中拆出，未命中结果单独走 `PlatformStatusDialog`，命中用户继续保留 `UnifiedModal + PlatformSubpanel` 信息布局。
|
||||
- 2026-06-11 追加：`PlatformAsyncStatePanel` 继续从 profile modal 与作品架扩展到 RPG 首页公开分区；`RpgEntryHomeView.tsx` 的移动端排行、发现页寓教于乐 / 默认公开 feed、桌面首页“今日游戏 / 推荐”、桌面发现页寓教于乐 / 默认公开 feed，以及“我的创作”分区已统一改成 `loadingState / emptyState / children` 三态 slot。页面级 `platformError` 继续留在状态壳外层，保证错误提示可以和内容并存；`recommend runtime`、分类筛选等含运行态或二级筛选语义的分支暂不硬并入这一轮。
|
||||
- 2026-06-11 追加：暗色 / 像素 modal 的标准 footer 布局统一抽到 `src/components/common/PlatformDarkModalFooter.tsx`；该组件只负责 dark footer 的分隔线、padding 和常见动作区排布，不持有“取消 / 确认”业务语义。`NpcModals.tsx` 的交易 / 赠礼 / 招募 footer、`SelectionCustomizationModals.tsx` 的 `SelectionModal` footer、`RpgAdventurePanelOverlays.tsx` 的 goal panel footer，以及 `InventoryItemViews.tsx` 的详情 footer wrapper 已接入；sticky 工作台 footer、正文内单 CTA 收尾和 runtime HUD 工具条暂不并入这一抽象。
|
||||
- 2026-06-11 追加：桌面首页里的轻量可点击扁平行开始统一收口到 `src/components/common/PlatformNavigableListItem.tsx`；目前已覆盖 `RpgEntryHomeView.tsx` 的搜索结果行、桌面“最近作品”、桌面“最近浏览”以及桌面“今日游戏”趋势行。组件只承接 `button + left content + right affordance` 结构、默认 `type="button"` 与 `leading / trailing` 插槽，暂不扩成覆盖教培 promo card、分类卡片、世界卡或 runtime 列表项的万能 row primitive。
|
||||
- 2026-06-11 追加：`PlatformNavigableListItem` 继续扩展到 profile 设置行；`src/components/platform-entry/PlatformProfilePrimitives.tsx` 的 `ProfileSettingsRow` 已改成委托共享 `button + leading + trailing` 骨架，继续保留本地 `platform-profile-settings-row` class 承接分隔线、icon 胶囊和字号微调。后续 profile / 账户中心里的同类轻量导航行优先直接复用共享行骨架，不再回退成原生 `<button>` 手写布局。
|
||||
- 2026-06-11 追加：`PlatformNavigableListItem` 继续扩展到 RPG 首页公开列表里的排行行与分类行；`RpgEntryHomeView.tsx` 的 `PlatformRankingItem`、`PlatformCategoryGameItem` 已改成委托共享 `button + leading + body + trailing` 骨架，同时保留 `platform-ranking-item__*` 与 `platform-category-game-item__*` 局部 class 承接封面、metric、badge、摘要和右侧 `试玩 / 进入` affordance。后续首页 / 发现页里同类浅色导航行优先沿“共享骨架 + 本地皮肤 class”推进，不再为了这类 row 回退成原生 `<button>` 手写布局。
|
||||
- 2026-06-11 追加：`PlatformAsyncStatePanel` 继续补齐 RPG 首页分类分支；移动端“发现 -> 分类”、桌面发现页“分类”和桌面首页“作品分类”模块现在都统一委托共享状态壳切换外层 `loading / empty / content`，分类控制条与排序按钮继续留在内容 slot 中。筛选后无结果的“当前筛选下没有作品。”也统一改成内层 `PlatformAsyncStatePanel` 切换，不再在三处 JSX 中各自维护嵌套 ternary。
|
||||
- 2026-06-11 追加：`PlatformDarkModalFooter` 不只收动作按钮区，也继续覆盖纯内容 footer；`CompanionCampModal.tsx` 底部“营地气氛”区域已改成 `layout="content"` + `padding="roomy"` 的共享 footer frame，保留原有文案和卡片布局，不再单独手写 `border-t border-white/10 px-5 py-4`。
|
||||
- 2026-06-11 追加：`PlatformDarkModalFooter` 继续从标准双按钮 footer 扩到 detail / confirm 收尾；`NpcModals.tsx` 的交易详情 footer 和 `MapModal.tsx` 的场景切换确认 footer 已改成复用同一个 dark footer frame，即使只有单个“关闭”按钮也不再手写 `flex justify-end`。这条抽象继续只覆盖 dark / pixel modal 里的底部分隔线与常规动作区排布，不向白底 profile 弹窗 footer、sticky 工作台 footer 或运行态 HUD 工具条扩张。
|
||||
- 2026-06-11 追加：`PlatformFilterToolbar.tsx` 作为薄结构组件收口 RPG 首页分类工具条；组件只承接“筛选按钮 + tabs + 排序按钮”的排布与 `mobile / desktop` 两种布局差异，不持有筛选状态、空态或排序逻辑。后续只有在同构壳层真的复现时才继续往 `common` 扩覆盖面；如果只是单页内局部重复、接口会越抽越胖，就优先退回文件内 helper。
|
||||
- 2026-06-11 追加：`SquareImageCropModal.tsx` 的白底弹窗壳层改为复用 `UnifiedModal.tsx`，同时给 `UnifiedModal` 薄补 `titleId` 与 `closeIcon` 透传，让裁剪弹窗继续保留自定义 close icon、无 backdrop / Escape 关闭和两列 footer，而不把 `PlatformProfileModalShell` 这类带页面语义的壳层倒灌回 `common/`。这条规则适用于 `common` 级工具弹窗：先看 `UnifiedModal` 能不能承接，再决定是否需要新的薄壳。
|
||||
- 2026-06-11 追加：`CreativeImageInputPanel.tsx` 里参考图预览、主图预览和移除图片确认都继续并回 `UnifiedModal` 体系：两个预览弹窗直接复用 `UnifiedModal`，删除确认直接复用 `UnifiedConfirmDialog`，不再在图片面板里手写三段 `platform-modal-backdrop + platform-modal-shell`。当前没有新增 `PlatformImagePreviewModal`，因为这批差异还只在尺寸与文案层，继续组合已有 modal 原语的 leverage 更高。
|
||||
- 2026-06-11 追加：`src/components/common/PlatformUtilityInfoModal.tsx` 作为 `UnifiedModal` 之上的薄壳，统一承接 `PlatformReportDialog.tsx` 与 `PublishShareModal.tsx` 共同的工具信息弹窗骨架：平台主题 overlay、白底 panel，以及 body / footer 间距与标准 footer frame。该壳层不继续向上吸收报告字段列表、分享正文、复制逻辑、渠道按钮或品牌 icon；后续 `common` 级工具信息弹窗若只是重复这套白底信息壳，优先复用 `PlatformUtilityInfoModal`，业务正文和 footer 交互继续留在调用方。验证命令：`npx vitest run src/components/common/PlatformUtilityInfoModal.test.tsx src/components/common/PlatformReportDialog.test.tsx src/components/common/PublishShareModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
- 2026-06-11 追加：profile 白底副弹层里的摘要头、列表骨架和内容行继续沉到 `PlatformProfileSummaryHeader.tsx`、`PlatformProfileSkeletonList.tsx` 与 `PlatformProfileContentRow.tsx`；这组组件只承接 `kicker + title + badge` 摘要层次、重复 skeleton 行以及 `PlatformSubpanel` 上的 `div / button` 内容行语义，不持有账单金额、任务进度、邀请用户信息、充值商品结构或状态切换逻辑。后续 profile modal 若只是重复这三类白底内容骨架，优先复用这组薄组件，不再把 skeleton、摘要头和 row chrome 写回各自 modal。验证命令：`npx vitest run src/components/common/PlatformProfileModalContent.shared.test.tsx src/components/platform-entry/PlatformProfileTaskCenterModal.test.tsx src/components/platform-entry/PlatformProfileWalletLedgerModal.test.tsx src/components/platform-entry/PlatformProfilePlayedWorksModal.test.tsx src/components/platform-entry/PlatformProfileReferralModal.test.tsx src/components/platform-entry/PlatformProfileRechargeModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
- 2026-06-11 追加：`PlatformProfileModalShell` 继续补齐标准 footer 插槽，直接透传 `UnifiedModal.footer` 与 `footerClassName`；`RpgEntryHomeView.tsx` 的昵称修改弹窗已改成标准 profile footer，不再把双按钮动作区手写在 body 末尾。后续个人中心里同类“表单内容 + 底部双按钮”弹窗优先走壳层 footer 接法。
|
||||
- 2026-06-11 追加：`PlatformProfileModalShell` 的标准 footer 接法继续扩展到单 CTA 表单收尾；`PlatformProfileRewardCodeRedeemModal.tsx` 的兑换按钮已迁到壳层 footer，body 只保留输入和反馈消息。`PlatformAsyncStatePanel` 同日继续扩展到 `PlatformAssetPickerGrid`、`VisualNovelSavePanel.tsx` 与 `AccountModal.tsx` 的账号安全三个子区块；其中公共素材网格继续把 `error` banner 放在状态壳外层，保持错误提示可与加载态或内容并存的原语义。
|
||||
- 2026-06-11 追加：按钮层继续补齐轻量漏网项。`PlatformTagEditor.tsx` 的标签 chip 删除入口已改成紧凑 `PlatformIconButton`，保留透明背景和原 chip 高度；`RpgEntryCharacterSelectView.tsx` 的两处“返回”按钮统一沉到局部 `CharacterSelectBackButton`，底层委托 `PlatformActionButton surface="editorDark"`。同日 `GenerationProgressHero.tsx` 新增 `GenerationHeaderBackButton`，`CustomWorldGenerationView.tsx` 与 `BarkBattleGeneratingView.tsx` 已开始复用这套暖色生成页返回入口骨架；后续同类轻量返回按钮与 chip 删除按钮优先继续沿共享按钮 + 薄包装的方向推进。
|
||||
- 2026-06-09 追加：通用输入 Composer 的上传参考图、发送和移除参考图已迁移到 `PlatformIconButton`；图标上传仍使用 `asChild="label"` 保留 label + file input 语义，公共组件会自动写入隐藏文本，确保内嵌 file input 继承可访问名称。
|
||||
- 2026-06-10 追加：creation-agent composer 的上传文档 / 上传参考图入口使用 `PlatformIconButton` 默认 `platformIcon`；工作台只保留动态 label、title、busy 状态和 picker 回调，发送按钮继续保留主题色动作布局。验证命令：`npm run test -- src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformIconButton.test.tsx`。
|
||||
- 2026-06-10 追加：作品详情顶部返回 / 分享和封面轮播上一张 / 下一张入口使用 `PlatformIconButton variant="platformIcon"`；详情页保留原 `platform-work-detail__*` 局部 class 控制位置和尺寸，点赞、复制三态等专用动作暂不迁移。验证命令：`npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformIconButton.test.tsx`。
|
||||
- 2026-06-09 追加：通用输入 Composer 普通 panel 外壳迁移到 `PlatformSubpanel`，文本域迁移到 `PlatformTextField variant="textarea"`，读图错误迁移到 `PlatformStatusMessage surface="profile"`；浮动胶囊 Composer 保留专用外壳和 CSS 覆盖。
|
||||
- 2026-06-10 追加：`PlatformStatusMessage` 根节点固定带 `platform-status-message` 类名，供业务测试断言公共状态条接入；RPG 大编辑器中的场景背景生成、作品封面生成和封面上传错误 / 成功提示先使用 `surface="tinted"` 加局部暗色 class 保留编辑器视觉，后续普通暗色编辑 / 运行面板状态提示统一迁入 `surface="editorDark"`。
|
||||
- 2026-06-10 追加：`PlatformStatusMessage surface="editorDark"` 承接 RPG 暗色面板里的普通错误 / 成功 / 信息 / 警告 / 中性提示；背包故事档案 QA 提示、角色聊天错误提示、营地编组战斗中提示和自定义选择弹窗错误 / 生成中提示已迁移，业务 JSX 不再手写暗色 `border-*-300/15 bg-*-500/10 text-*-50/90` 状态条 chrome。
|
||||
- 2026-06-10 追加：NPC 交易 / 赠礼 / 招募弹窗里的叙事提示使用 `PlatformStatusMessage surface="editorDark"`；弹窗只保留 introText 数据和业务 tone 选择，不再手写暗色提示条边框、底色、圆角、字号和换行 class。
|
||||
- 2026-06-10 追加：creation-agent composer 错误条使用 `PlatformStatusMessage surface="platform"`；工作台只保留错误来源合并和局部外边距 / 圆角，不再手写红色边框、底色和文字 class。验证命令：`npm run test -- src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformStatusMessage.test.tsx`。
|
||||
- 2026-06-10 追加：creative-agent 首页错误提示使用 `PlatformStatusMessage tone="error" surface="platform" size="md"`；首页只保留宽度对齐局部 class 和错误文案，不再手写 danger panel chrome。验证命令：`npm run test -- src/components/creative-agent/CreativeAgentHome.test.tsx src/components/common/PlatformStatusMessage.test.tsx`。
|
||||
- 2026-06-10 追加：大鱼吃小鱼结果页发布校验阻断项使用 `PlatformStatusMessage tone="warning" surface="platform" size="xs"`；结果页只保留阻断项裁剪和文案，不再手写 amber 文本列表。验证命令：`npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx src/components/common/PlatformStatusMessage.test.tsx`。
|
||||
- 2026-06-09 追加：通用创作图片面板中覆盖在图片或输入区上的更换主图、移除主图、历史入口短标签按钮和提示词参考图上传入口，以及抓大鹅封面编辑中覆盖在封面图上的移除入口，使用 `PlatformIconButton variant="surfaceFloating"`；白底圆形 / 短标签浮动图标动作的 `border-white/80`、`bg-white/94`、`backdrop-blur`、hover 和禁用态不再在业务 JSX 中重复拼。
|
||||
- 2026-06-10 追加：`PlatformIconButton variant="darkMini"` 承接覆盖在缩略图上的暗色小型图标动作；`PlatformUploadPreviewCard` 的 square 右上移除按钮已迁移到该 variant，上传预览卡不再手写黑底圆形移除按钮 chrome。
|
||||
- 2026-06-09 追加：图片编辑面板中的白底胶囊开关统一使用 `src/components/common/PlatformPillSwitch.tsx` 承载 label + `role="switch"` 输入语义、轨道、圆点、白底浮层和禁用态；通用创作图片面板和抓大鹅封面编辑的 `AI重绘` 已先迁移，业务页只保留受控布尔值和状态变更回调。
|
||||
- 2026-06-09 追加：设置面板、结果页配置和工作台白底配置项里的整行开关统一使用 `src/components/common/PlatformToggleRow.tsx` 承载 label、checkbox、只读状态 pill、可选 icon、可选点击状态行、禁用态和 soft / plain 两类白底 surface；视觉小说结果页运行配置 / 玩家可见开关、视觉小说 runtime 设置面板和拼消消创作工作台 AI 生成底图开关已先迁移，业务页只保留字段写回和点击动作。
|
||||
- 2026-06-09 追加：公开编号搜索结果弹窗关闭按钮使用 `PlatformModalCloseButton variant="platformIcon"`，平台壳不再手写 `platform-icon-button` + 关闭文本。
|
||||
- 2026-06-10 追加：RPG 大编辑器主壳层和紧凑对话壳层的右上角关闭入口使用 `PlatformModalCloseButton variant="platformIcon"`，暗色编辑器保留 `platform-icon-button` 视觉 token，但业务 JSX 不再手写关闭按钮 aria、默认 X 图标和禁用态拼接。
|
||||
- 2026-06-10 追加：`PlatformModalCloseButton variant="editorDark"` 承接 RPG 暗色弹窗中非像素风的圆形 X 关闭入口，根节点固定带 `platform-modal-close-button--editor-dark` 稳定类名；自定义选择弹窗头部关闭按钮已迁移，并补齐 `aria-label`，业务 JSX 不再手写暗色关闭按钮边框、底色、hover 和默认 X 图标。验证命令：`npm run test -- src/components/common/PlatformModalCloseButton.test.tsx src/components/SelectionCustomizationModals.test.tsx`。
|
||||
- 2026-06-10 追加：`PlatformModalCloseButton variant="pixel"` 承接 `UnifiedModal variant="pixel"` 头部圆形关闭入口；`UnifiedModal` 只选择 `platformIcon / pixel` 变体并保留 closeDisabled、Backdrop、Escape 和 portal 语义，不再手写 X 图标、aria 和关闭按钮 class。验证命令：`npm run test -- src/components/common/UnifiedModal.test.tsx src/components/common/PlatformModalCloseButton.test.tsx src/components/common/UnifiedConfirmDialog.test.tsx`。
|
||||
- 2026-06-10 追加：`UnifiedModal` 新增 `closeVariant`、`closeOnEscape`、`titleClassName` 和 `descriptionClassName`，用于在收口标准平台弹窗壳层时保留个人中心 `profile / profileCompact` 关闭按钮、原有标题层级和“不响应 Escape / backdrop”的交互语义；RPG 首页个人中心里的昵称修改、账户充值、每日任务和兑换码弹窗已迁移到 `UnifiedModal`，支付结果 / 支付确认遮罩 / 泥点账单这类头部结构不同的弹窗继续保留专用实现。验证命令：`npm run test -- src/components/common/UnifiedModal.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`。
|
||||
- 2026-06-10 追加：`UnifiedModal` 新增 `showHeader`，用于收口不需要标准头部但仍要保留 dialog 无障碍语义、遮罩和层级控制的轻量弹窗；RPG 首页个人中心的支付结果提示与支付确认遮罩已迁移到 `showHeader={false}` 模式，业务页只保留 icon badge、文案与按钮，不再手写 backdrop、aria 和白底壳层。个人中心移动端顶栏“扫码”“打开设置”入口统一使用 `PlatformIconButton`，并继续保留 `.platform-profile-header__icon-button` 局部 class 控制位置与主题色。验证命令：`npm run test -- src/components/common/UnifiedModal.test.tsx src/components/common/PlatformIconButton.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`。
|
||||
- 2026-06-10 追加：RPG 首页发现页分类筛选弹窗和个人中心扫码面板改用 `UnifiedModal` 承接 backdrop、dialog 语义和层级；分类筛选保留本地选项 / 动作布局，扫码面板继续使用 `showHeader={false}` 保留深色自定义头部与摄像头 viewport，并显式维持 `closeOnBackdrop={false}`、`closeOnEscape={false}`。验证命令：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx src/components/common/UnifiedModal.test.tsx`。
|
||||
- 2026-06-10 追加：RPG 首页个人中心泥点账单改用 `UnifiedModal showHeader={false}` 承接 `dialog` 语义和遮罩层级，同时保留渐变面板、`PlatformModalCloseButton variant="floating"`、余额 badge 与账单列表布局；账单继续显式维持 `closeOnBackdrop={false}`、`closeOnEscape={false}`，测试改为直接断言具名 dialog 和关闭后卸载。验证命令：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "opens wallet ledger modal from narrative coin card|wallet ledger modal shows empty and error states" src/components/common/UnifiedModal.test.tsx`。
|
||||
- 2026-06-10 追加：RPG 首页个人中心“玩过作品”面板改用 `UnifiedModal showHeader={false}` 承接 `dialog` 语义和遮罩层级，同时保留 `PLAYED` kicker、总时长 badge、`PlatformModalCloseButton variant="floating"`、`可继续 / 玩过` 双分区与作品卡布局；存档入口继续留在同一个“玩过”面板内，不再回退成独立 `SAVE ARCHIVE` / `ARCHIVE` 壳层。验证命令：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile played modal summary and work type use platform pill badges|profile played modal empty state uses platform empty state" src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "authenticated users can open save archives from the profile played panel|profile page keeps save archives inside played stats panel" src/components/common/UnifiedModal.test.tsx`。
|
||||
- 2026-06-10 追加：RPG 首页个人中心邀请相关弹层里的 live `community / redeem` 分支改用 `UnifiedModal showHeader={false}` 承接 `dialog` 语义和遮罩层级，同时保留 `PlatformModalCloseButton variant="floatingPlain"`、居中标题、社区二维码卡片、邀请码输入 / 已填写空态和成功 / 失败提示；历史 `invite` 分支没有新的入口，当前只随同一壳层维持现状。验证命令：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile community shortcut shows reward subtitle and invited users|invite query opens redeem modal directly for logged in users|profile redeem invite query modal submits code after login" src/components/common/UnifiedModal.test.tsx`。
|
||||
- 2026-06-10 追加：RPG 首页个人中心昵称旁的铅笔入口改用 `PlatformIconButton`，继续保留 `.platform-profile-edit-button` 局部尺寸、边框和浅色底样式；昵称编辑入口不再手写原生 `<button>` 的 `type`、`aria-label` 和图标壳。验证命令：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile nickname modal uses platform text field and submits with Enter" src/components/common/PlatformIconButton.test.tsx`。
|
||||
- 2026-06-09 追加：RPG 大编辑器暗色面板内的保存和角色槽动作继续走本地 `ActionButton`，不再混用白底平台 `platform-button` class；平台白底动作收口和编辑器暗色动作收口保持两套视觉边界。
|
||||
- 2026-06-10 追加：`PlatformActionButton surface="editorDark"` 承接 RPG 暗色弹窗 / 运行面板里的普通取消、确认、刷新和编组动作，支持 `size="xxs"` 与 `tone="success" | "warning"`；`tone="accent"` 承接暗色壳层内的琥珀实心 CTA，`tone="accentSoft"` 承接依赖局部 accent 变量的柔和强调按钮。角色自定义 footer、自定义世界生成 footer、地图切换确认、营地编组普通动作和角色聊天刷新动作已迁移。暗色可选项卡仍使用 `PlatformDarkOptionCard`，像素风发送 / 强品牌动作继续保留专用布局。验证命令：`npm run test -- src/components/common/platformActionButtonModel.test.ts src/components/common/PlatformActionButton.test.tsx src/components/SelectionCustomizationModals.test.tsx src/components/CompanionCampModal.test.tsx src/components/MapModal.test.tsx src/components/CharacterChatModal.test.tsx`。
|
||||
- 2026-06-10 追加：RPG 首页创作 / 草稿顶栏的钱包快捷入口通过同文件 `TopbarWalletShortcutButton` 复用 `PlatformActionButton tone="accentSoft" shape="pill" size="xs"` 与 `PlatformIconBadge`；移动端 / 桌面端继续保留 `.platform-mobile-create-wallet-chip`、`.platform-desktop-create-wallet-chip` 和 `.platform-desktop-search` 兼容 class，承接余额截断、桌面顶栏胶囊壳和既有测试锚点，点击语义仍统一走 `openRechargeOrRewardCodeModal`。验证命令：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`。
|
||||
- 2026-06-10 追加：RPG 大编辑器里的当前角色、可选角色、预设背景和场景连接关系等暗色信息面板通过本地 `EditorInfoPanel` 复用 `PlatformSubpanel surface="dark"`；有右侧动作的面板也只向适配器传 actions，不再在业务 JSX 中重复手写暗色面板边框、底色、圆角、标题行和内容间距。验证命令：`npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx -t "场景编辑器会在场景内展示槽位化多幕配置并保存"`。
|
||||
- 2026-06-10 追加：作品详情底部“作品改造 / 作品编辑”和“启动”使用 `PlatformActionButton surface="platform" shape="pill" size="lg" fullWidth`；详情页保留 `platform-work-detail__remix / start` 局部 class 控制 sticky 底部栏位置、比例和品牌背景。验证命令：`npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformActionButton.test.tsx`。
|
||||
- 2026-06-10 追加：作品详情点赞按钮使用 `PlatformActionButton tone="accentSoft"`；详情页只保留纵向排布、尺寸和 `--platform-action-accent` 局部变量，不再手写点赞按钮边框、底色、文字和阴影 chrome。验证命令：`npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformActionButton.test.tsx src/components/common/platformActionButtonModel.test.ts`。
|
||||
- 2026-06-09 追加：大鱼吃小鱼结果页白底平台动作迁移到 `PlatformActionButton shape="pill" size="xs"`；资产工坊关闭 / 生成正式图、关卡主图 / 待机 / 移动入口和场地背景生成只保留业务回调，深色 hero 返回 / 测试 / 发布按钮继续保留玩法品牌布局。
|
||||
- 2026-06-10 追加：大鱼吃小鱼结果页 hero 顶部的玩法摘要 chip 使用 `PlatformPillBadge tone="lightOverlay"`，并只保留局部 `bg-white/10` 覆盖；hero 只保留 `coreFun / ecologyTheme / levelCount` 文案，不再手写三段白色静态标签。验证命令：`npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx -t "renders generated formal previews with accurate status copy"`。
|
||||
- 2026-06-10 追加：反馈页“查看反馈与投诉记录”这类页面内次级文本动作使用 `PlatformActionButton tone="ghost" shape="pill" size="xs"`；反馈页只保留提示回调，不再手写居中、字号、内边距和冷色文本按钮 class。验证命令：`npm run test -- src/components/platform-entry/PlatformFeedbackView.test.tsx src/components/common/PlatformActionButton.test.tsx`。
|
||||
- 2026-06-10 追加：创作中心作品卡积分激励的“领取积分 / 领取中”按钮使用 `PlatformActionButton tone="secondary" size="xxs"`；作品卡保留 `creation-work-card-incentive__button` 局部 class 承接三列布局、移动端跨列、紧凑高度和玻璃底，同时保留点击 / 键盘冒泡拦截，避免触发整卡打开。验证命令：`npm run test -- src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/common/PlatformActionButton.test.tsx src/index.test.ts`。
|
||||
- 2026-06-09 追加：敲木鱼 fallback 返回、跳一跳结算、拼消消 runtime header / 结算弹窗等白底 HUD 动作使用 `PlatformActionButton`，拼消消 runtime 白底错误条使用 `PlatformStatusMessage surface="platform"`；深色半透明游戏提示和强品牌按钮仍可保留 runtime 专用布局。
|
||||
- 2026-06-10 追加：运行态短错误 / 成功 / 命中反馈 chip 使用 `PlatformRuntimeStatusToast` 承接圆角、字号、阴影、色值和 `role="alert/status"` 语义；跳一跳、拼图、敲木鱼、方洞和宝贝爱画运行态短 toast 已迁移。玩法专属返回按钮、计分牌、蓄力提示和强品牌主按钮仍留在 runtime 壳层，不把位置和玩法资产耦合进公共 Module。验证命令：`npm run test -- src/components/common/PlatformRuntimeStatusToast.test.tsx src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx src/components/wooden-fish-runtime/WoodenFishRuntimeShell.test.tsx src/components/square-hole-runtime/SquareHoleRuntimeShell.test.tsx src/components/edutainment-runtime/BabyLoveDrawingRuntimeShell.test.tsx`。
|
||||
- 2026-06-09 追加：历史图片 / 历史素材 / 可引用素材选择统一使用 `src/components/common/PlatformAssetPickerCard.tsx` 中的 `PlatformAssetPickerCard` 与 `PlatformAssetPickerGrid`，由该 Module 承载缩略图、禁用态、选中态、边框、hover、主副文案、`ResolvedAssetImage` 壳层、错误态、读取态、空态和网格布局；拼图历史图片弹窗、方洞历史生成、视觉小说历史素材选择器、RPG 大编辑器历史素材弹窗和抓大鹅封面编辑可引用素材网格已先迁移，业务页只传素材数组、素材地址、文案、可访问名称、surface、选中判断和选择回调。RPG 大编辑器等暗色弹窗使用 `surface="editorDark"`，不混用白底平台卡片视觉；场景横图通过 `imageShellClassName` 保留 16:9。
|
||||
- 2026-06-09 追加：平台白底圆角输入框和文本域统一使用 `src/components/common/PlatformTextField.tsx` 承载 input / textarea 语义、基础边框、背景、内边距、字号 / 行高、密度和禁用态；同组下拉框使用 `PlatformSelectField` 复用同一输入 chrome。抓大鹅结果页作品名称 / 描述、封面描述、素材名称、批量新增 / 批量重生成物品名称，方洞结果页主信息表单和形状 / 洞口选项字段，拼图结果页作品信息 / 关卡名称 / 智能修订输入，敲木鱼结果页作品标题 / 简介，敲木鱼创作工作台功德词条输入，creative-agent 模板确认调整弹层关卡数输入，拼消消创作工作台作品标题 / 简介 / 主题词、跳一跳创作工作台主题，以及视觉小说结果页音乐生成、作品信息、开场、运行配置、角色、场景、阶段和世界观普通文本 / 下拉字段已先迁移，业务页只保留受控值、事件、可访问名称、占位符、选项和局部布局 class。同一面板内的主图上传和提示词参考图上传必须使用不同可访问名称，避免多个同名“上传参考图”入口让测试和读屏语义混淆；拼图关卡编辑中的描述参考图入口使用“上传描述参考图”。
|
||||
- 2026-06-09 追加：通用创作图片输入面板的提示词文本域也使用 `PlatformTextField variant="textarea" density="roomy"`；图片面板只通过局部 class 保留高度、`pb-14` 和浮动参考图上传按钮避让，不再自己维护白底 textarea 边框、背景、字号和禁用态。
|
||||
- 2026-06-09 追加：`PlatformTextField` / `PlatformSelectField` 的 `tone="warm" | "rose" | "emerald"` 统一承接平台表单焦点色；视觉小说创作工作台、统一抓大鹅创作工作台、汪汪声浪轻配置编辑器和宝贝识物工作台普通输入 / 文本域 / 下拉框已先迁移，玩法调性焦点色通过 tone 表达，不在业务 JSX 中重复拼 `focus:border-* focus:ring-*`。
|
||||
- 2026-06-10 追加：`PlatformTextField` / `PlatformSelectField` 支持 `surface="editorDark"` 和 `tone="sky"`，承接 RPG 暗色弹窗 / 运行面板里的普通输入框、文本域、下拉框、禁用态、密度、字号和焦点色；自定义选择弹窗角色名字 / 背景补充 / 生成模式 / 世界描述和角色聊天草稿已迁移，业务 JSX 不再手写暗色 `border-white/10 bg-black/30 px-4 py-3` 或 `focus:border-*` 输入 chrome。验证命令：`npm run test -- src/components/common/PlatformTextField.test.tsx src/components/SelectionCustomizationModals.test.tsx src/components/CharacterChatModal.test.tsx`。
|
||||
- 2026-06-10 追加：`PlatformTagEditor` 内部新增标签输入框也使用 `PlatformTextField density="compact" size="xs"`；标签编辑器只保留新增状态、解析、Enter / Escape 行为和按钮组合，不再手写白底 input chrome。
|
||||
- 2026-06-10 追加：认证图形验证码答案输入使用 `PlatformTextField density="compact"`；验证码组件只保留 challenge 展示、答案受控值和变更回调，不再手写 `platform-input` 输入框 chrome。
|
||||
- 2026-06-10 追加：认证入口的短信 / 密码登录、重置密码、绑定手机号、邀请码和账号安全表单字段使用 `PlatformTextField surface="platform"` 与 `PlatformFieldLabel variant="form"`；认证业务组件只保留受控值、登录 / 绑定流程、原生 input 属性和校验提示，字段可访问名称继续由外层原生 `label` 承接，不再手写 `platform-input` 或表单标题 class。
|
||||
- 2026-06-10 追加：个人中心兑换码和邀请兑换输入使用 `PlatformTextField surface="platform"`；业务组件只保留兑换 / 邀请码提交、归一化、大写展示、Enter 提交和原生可访问名称，不再手写 `platform-profile-input` 或白底 input chrome。
|
||||
- 2026-06-10 追加：个人中心昵称弹窗输入框使用 `PlatformTextField surface="editorDark" size="lg" density="roomy"`；业务组件保留原生 `label` / sr-only “新昵称”、`autoFocus`、`maxLength`、Enter 提交、昵称校验和保存流程，不再手写暗色 input chrome。
|
||||
- 2026-06-10 追加：平台反馈页问题描述和联系电话字段使用 `PlatformTextField surface="platform"`，标题使用 `PlatformFieldLabel variant="form"`；反馈页保留外层原生 label、受控值、长度限制、透明嵌入式局部 class 和提交校验，不再手写 textarea / input / 字段标题 chrome。验证命令：`npm run test -- src/components/platform-entry/PlatformFeedbackView.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformFieldLabel.test.tsx`。
|
||||
- 2026-06-09 追加：平台字段标签统一使用 `src/components/common/PlatformFieldLabel.tsx` 承载 `field`、`section`、`form`、`pill` 与 `accentPill` 五类字段标题视觉；视觉小说结果页、汪汪声浪轻配置编辑器和宝贝识物工作台已先迁移，业务页只保留字段文案和必要局部布局 class，不再重复拼普通字段名、分区标题、表单标题、普通胶囊和强调胶囊 class。
|
||||
- 2026-06-10 追加：通用创作图片输入面板的主图标题和提示词标题使用 `PlatformFieldLabel variant="form"`；提示词字段保留外层原生 `label htmlFor`，业务组件只保留字段文案、布局和上传 / 生成交互，不再手写 `mb-2 block text-sm font-black` 标题 class。
|
||||
- 2026-06-10 追加：个人中心存档 / 玩过弹窗里的简单空态使用 `PlatformEmptyState surface="subpanel" size="inline"`，玩过弹窗的“可继续 / 玩过”分区标题使用 `PlatformFieldLabel variant="section"`，已玩作品白底按钮卡使用 `PlatformSubpanel as="button" surface="flat" radius="sm" padding="md" interactive`；`SaveArchiveCard` 因含图片遮罩和加载态暂不并入本轮。
|
||||
- 2026-06-10 追加：creative-agent 首页抽屉无创作记录使用 `PlatformEmptyState surface="subpanel" size="inline"`；抽屉只保留历史记录分组和点击行为，不再手写 bordered empty chrome。验证命令：`npm run test -- src/components/creative-agent/CreativeAgentHome.test.tsx src/components/common/PlatformEmptyState.test.tsx`。
|
||||
- 2026-06-10 追加：平台入口壳纯 Suspense fallback 使用 `PlatformSubpanel radius="sm" padding="none"` 承接原 `platform-subpanel` 外壳；带恢复动作、错误语义或运行态遮罩的提示面板不和纯加载 fallback 同批迁移。
|
||||
- 2026-06-10 追加：平台入口作品详情读取 / 错误提示、Agent 工作区恢复提示和生成结果恢复面板也迁移到 `PlatformSubpanel`；普通提示使用 `radius="sm" padding="none"`，带恢复动作的 `CreationResultRecoveryPanel` 使用 `radius="xl" padding="none"`，玩法 runtime overlay 继续保留专用层级语义。验证命令：`npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/platform-entry/PlatformEntryFlowShellImpl.test.ts`。
|
||||
- 2026-06-10 追加：RPG runtime 主阶段路由里的平台首页、角色选择和冒险面板懒加载提示使用 `PlatformSubpanel radius="sm" padding="none"`；路由器只保留 Suspense 分流和提示文案，运行态 HUD / overlay 不并入该普通提示面板规则。验证命令：`npm run test -- src/components/rpg-runtime-shell/RpgRuntimeStageRouter.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 追加：个人中心钱包账单弹窗的“暂无账单记录”使用 `PlatformEmptyState surface="subpanel" size="inline"`，账单行使用 `PlatformSubpanel as="div" surface="flat" radius="xs" padding="none"`；业务 JSX 只保留来源、时间、收支色值、余额右对齐和局部间距 / 阴影。
|
||||
- 2026-06-10 追加：个人中心邀请弹窗里的社区二维码卡、邀请码展示卡、成功邀请容器和邀请用户行使用 `PlatformSubpanel`，简单空态使用 `PlatformEmptyState`，小标题使用 `PlatformFieldLabel variant="section"`；外层弹窗、query 自动打开、复制邀请和提交邀请码状态机不随 UI chrome 收口改动。
|
||||
- 2026-06-10 追加：个人中心邀请弹窗里的邀请奖励说明使用 `PlatformStatusMessage tone="warning" surface="profile" size="md"`；弹窗只保留奖励文案和两行排版，不再手写 amber 提示块。验证命令：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile community shortcut shows reward subtitle and invited users"`。
|
||||
- 2026-06-10 追加：个人中心任务中心任务条目使用 `PlatformSubpanel radius="sm" padding="md"` 承接原 `platform-subpanel` 外壳；业务组件只保留任务标题、进度、奖励、状态和领取按钮逻辑。
|
||||
- 2026-06-10 追加：个人中心充值弹窗微信 Native 支付二维码确认面板使用 `PlatformSubpanel radius="sm" padding="md"`；业务组件只保留二维码生成、扫码展示和确认支付按钮流程。
|
||||
- 2026-06-10 追加：个人中心充值弹窗商品整卡按钮使用 `PlatformSubpanel as="button" surface="platform" radius="sm" padding="none" interactive`；商品标题、金额、角标、购买中态和购买回调留在业务组件，按钮壳、hover、focus、默认 type 与 disabled chrome 归公共组件。验证命令：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile recharge modal trusts per-product first bonus display after points recharge"`、`npm run test -- src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 追加：个人中心充值商品卡里的“购买 / 处理中”胶囊暂不抽共享组件；该胶囊位于 `PlatformSubpanel as="button"` 内部，直接复用 `PlatformActionButton` 会形成嵌套交互，当前也还没有第二个同形态的非交互 action chip 证明需要单独沉淀共享展示基元。
|
||||
- 2026-06-09 追加：抓大鹅结果页作品信息、发布封面和物品素材详情中的 section 字段标题迁移到 `PlatformFieldLabel variant="section"`；业务页不再重复拼 `text-xs font-bold tracking-[0.18em] text-[var(--platform-text-soft)]`。
|
||||
- 2026-06-09 追加：方洞结果页主信息、形状选项、洞口选项和历史生成标题迁移到 `PlatformFieldLabel variant="section"`；业务页只保留字段文案、图标和按钮布局，不再重复拼 section 标题 class。
|
||||
- 2026-06-09 追加：拼图结果页关卡详情的“关卡名称”和发布弹窗的“发布检查 / 封面关卡”标题迁移到 `PlatformFieldLabel variant="section"`；业务页保留 label 关联和弹窗布局，不再重复拼 section 标题 class。
|
||||
- 2026-06-09 追加：拼消消创作工作台作品标题 / 简介 / 主题词、跳一跳创作工作台主题、大鱼素材弹窗 prompt 和 RPG 发布弹窗发布检查 / 封面设置迁移到 `PlatformFieldLabel variant="section"`；业务组件内不再直接出现 `text-xs font-bold tracking-[0.18em] text-[var(--platform-text-soft)]` section 标题 class，后续同类标题只从公共 Module 扩展。
|
||||
- 2026-06-09 追加：平台白底分段 Tab / 二选一统一使用 `src/components/common/PlatformSegmentedTabs.tsx` 承载选项、当前 id、变更回调、响应式列数、尺寸、圆角、surface、截断标签、禁用态和 `aria-pressed`；拼图结果页、抓大鹅结果页、抓大鹅素材配置、视觉小说结果页和 creative-agent 模板确认弹窗已先迁移，业务页不再重复拼 `grid + border + bg-white/62 + button aria-pressed`。
|
||||
- 2026-06-09 追加：`PlatformSegmentedTabs` 支持 `columns="four"`、`size="choice"`、`tone="warm" | "rose"`、`surface="transparent"` 和 `frame="bare"`，用于承接创作 / 结果页里的四选一配置项；抓大鹅创作工作台和结果页难度选择已迁移，业务页只保留难度选项、当前值和派生回调。
|
||||
- 2026-06-09 追加：`PlatformSegmentedTabs` 支持 `columns="one"`、`size="tab"`、`tone="underline"` 和 `semantics="tabs"`，用于承接认证入口短信 / 密码登录切换的真实 Tab 语义；认证页不再维护本地 `LoginTabButton`、`role="tab"`、`aria-selected` 和下划线选中态。登录入口不可用的白底提示也迁移到 `PlatformSubpanel`。
|
||||
- 2026-06-09 追加：平台结果页统计小卡和轻量状态 chip 统一使用 `src/components/common/PlatformStatGrid.tsx` 承载 `items`、响应式列数、密度、surface、对齐和 label/value 顺序；拼消消结果页素材摘要、方洞结果页封面状态 chip 和抓大鹅结果页难度摘要已迁移，业务页不再重复拼统计卡 `grid + rounded + bg-white/* + text-xl/text-xs`。
|
||||
- 2026-06-09 追加：平台单个胶囊状态 / 标签 chip 统一使用 `src/components/common/PlatformPillBadge.tsx` 承载 tone、尺寸、图标、圆角、边框、底色和字号；宝贝识物结果页发布状态、主题标签与占位资源 overlay，宝贝识物 / 拼图 / 抓大鹅 / 视觉小说工作台 BETA chip、汪汪声浪轻配置 chip、汪汪声浪结果页草稿 chip、汪汪声浪预览 VS chip、敲木鱼结果页飘字 chip、creative-agent 过程计数 / 条目 meta chip、通用音频输入面板限制标签、抓大鹅 / RPG / 拼图 / 方洞结果页自动保存状态、抓大鹅结果页当前难度 badge、拼图结果页关卡生成中 overlay / 列表 badge、大鱼吃小鱼结果页终局 / 关卡元信息 / 发布校验成功 badge、汪汪声浪生成页和通用生成页右上状态 badge、RPG 开发资产诊断数量 / 加载状态 badge、RPG 发布弹窗封面来源 badge、账号弹窗主题状态 / 会话数量 / 设备状态 badge、创作类型弹层锁定 badge、拼图图库详情页题材标签、自定义世界作品卡二级 badge 和生成失败 chip 已先迁移，业务页不再重复拼 `rounded-full border bg-* text-* px-* py-*`。多项数值 / 标签摘要仍归 `PlatformStatGrid`，可交互标签编辑仍归 `PlatformTagEditor`。
|
||||
- 2026-06-09 追加：`PlatformPillBadge` 支持 `profile` / `profileAccent` 个人中心玫瑰色 chip tone；泥点账单余额、玩过总时长和玩过作品类型 chip 已迁移，个人中心后续轻量状态 / 分类胶囊不再在业务 JSX 中重复拼 rose / zinc 胶囊 class。
|
||||
- 2026-06-10 追加：`PlatformPillBadge` 支持 `neutralSolid` 实心中性 tone，承接无强调的只读状态胶囊；`PlatformToggleRow mode="status"` 的开启 / 关闭状态已迁移到 `platformPillBadgeModel`，整行开关不再手写中性 pill class。
|
||||
- 2026-06-10 追加：`PlatformPillBadge` 支持 `lightOverlay` 浅色叠层 tone，承接主动作按钮内部的泥点消耗等小胶囊；通用创作图片面板和抓大鹅创作工作台提交按钮内的消耗标签已迁移，业务 JSX 不再手写 `rounded-full bg-white/24 px-2 py-0.5`。
|
||||
- 2026-06-10 追加：`PlatformPillBadge` 支持 `size="xxs"` 承接密集目录元信息 chip；自定义世界实体目录的新生成、生成中进度、开局 CG 消耗 / 时长 / 已生成、批量删除已选数量和可扮演角色元信息 chip 已迁移，实体目录不再手写 `platform-pill platform-pill--* px-2.5 py-1 text-[10px]`。
|
||||
- 2026-06-10 追加：creative-agent 工作台顶部阶段状态 chip 迁移到 `PlatformPillBadge tone="cool" size="xs"`；工作台只保留阶段枚举到文案的映射，不再手写 `platform-pill platform-pill--cool` 外观。
|
||||
- 2026-06-10 追加：RPG 首页公开作品卡标签、趋势卡标签、公开作品搜索结果类型、充值商品角标、移动端创建入口、桌面发现 hero / 今日 / 最近作品 / 最近浏览 chip 迁移到 `PlatformPillBadge`，首页不再手写 `platform-pill platform-pill--neutral / warm / cool`。
|
||||
- 2026-06-10 追加：RPG 世界详情页的发布状态、主题、作者、发布时间 / 可见性和展示标签等静态元信息 chip 迁移到 `PlatformPillBadge`；作品号复制和分享入口仍保留 `CopyCodeButton` / `CopyFeedbackButton` 管复制状态。
|
||||
- 2026-06-10 追加：`CopyFeedbackButton` 支持 `actionAppearance="pill"`，`CopyCodeButton` 透传同一入口，并复用 `platformPillBadgeModel.ts` 的 `getPlatformPillBadgeClassName` 视觉 chrome；可点击复制 / 分享胶囊 chip 不再在业务 JSX 中手写 `platform-pill`，RPG 世界详情作品号复制 / 分享入口和抓大鹅批量新增 / 重生成物品名称预览已迁移。
|
||||
- 2026-06-10 追加：平台作品详情页主题标签使用 `PlatformPillBadge tone="neutralSolid" size="sm"`，作品号复制按钮使用 `CopyCodeButton actionAppearance="pill" actionPillTone="neutralSolid" actionPillSize="sm"`；详情页只保留标签映射、作品号复制状态和顶部外边距，不再手写 `platform-work-detail__chip / code` 基础 chrome。验证命令：`npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformPillBadge.test.tsx src/components/common/CopyCodeButton.test.tsx`。
|
||||
- 2026-06-10 追加：平台作品详情页分享复制反馈使用 `PlatformStatusMessage surface="platform"`，按 `shareState` 映射 `success / error`；详情页保留 `useCopyFeedback` 状态机和文案，不再让失败态复用成功 toast chrome。验证命令：`npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformStatusMessage.test.tsx`。
|
||||
- 2026-06-10 追加：平台错误弹窗和生成完成弹窗的“字段展示 + 复制整段报告”能力统一收口到 `src/components/common/PlatformReportDialog.tsx`；`PlatformErrorDialog` 与 `PlatformTaskCompletionDialog` 只保留标题、字段语义和错误黑名单过滤，不再各自组合 `UnifiedModal`、`PlatformInfoBlock`、`CopyFeedbackButton` 与 `useCopyFeedback`。验证命令：`npm run test -- src/components/common/PlatformReportDialog.test.tsx src/components/platform-entry/PlatformErrorDialog.test.tsx src/components/platform-entry/PlatformTaskCompletionDialog.test.tsx`。
|
||||
- 2026-06-10 追加：`CopyFeedbackButton` 支持 `actionShape`，用于共享复制状态按钮直接对齐 `PlatformActionButton` 的圆角外观；拼图广场详情页 hero 的分享按钮已使用 `actionSurface="editorDark" actionShape="pill"`，修改作品 / 进入第 1 关动作使用 `PlatformActionButton`，返回和封面轮播前后按钮使用 `PlatformIconButton darkMini`。验证命令：`npm run test -- src/components/common/CopyFeedbackButton.test.tsx src/components/puzzle-gallery/PuzzleGalleryDetailView.test.tsx`。
|
||||
- 2026-06-10 追加：creative-agent 首页的侧边栏菜单、账号入口、开启新对话、我的创作、首页激励 CTA 和 prompt suggestion 按钮迁移到 `PlatformIconButton` / `PlatformActionButton`，但继续保留 `creative-agent-home__*` 本地 class 承接透明顶栏和抽屉品牌视觉；收口按钮语义时不强行同时抹平定制视觉。验证命令：`npm run test -- src/components/creative-agent/CreativeAgentHome.test.tsx`。
|
||||
- 2026-06-10 追加：像 `creative-agent-drawer__history-item` 这种纯文本轻量列表行，当前不为了单点场景单独新建共享组件；现阶段优先沿用 `PlatformActionButton` 承接动作行、`PlatformSubpanel as="button" interactive` 承接有壳列表行，等出现更多同构透明列表行再评估独立 row primitive。
|
||||
- 2026-06-10 追加：绑定手机号页左侧“当前登录身份”提示块迁移到 `PlatformSubpanel radius="sm" padding="md"`；认证页只保留身份文案和绑定流程，不再手写 `platform-subpanel` 信息块壳。验证命令：`npm run test -- src/components/auth/BindPhoneScreen.test.tsx`。
|
||||
- 2026-06-10 追加：大鱼吃小鱼结果页 hero 的返回入口迁移到 `PlatformIconButton darkMini`，测试 / 发布动作迁移到 `PlatformActionButton surface="editorDark"`；结果页只保留测试运行、发布状态和提交语义，不再手写 hero 顶栏按钮壳。验证命令：`npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx`。
|
||||
- 2026-06-10 追加：`PlatformPillBadge` 支持 `darkSoft` / `darkNeutral` / `darkSky` / `darkEmerald` / `darkAmber` / `darkRose` 暗色 tone，用于 RPG 暗色弹窗和角色详情里的纯展示 chip；角色身份 / 等级、技能列表出手方式、技能详情方式 / 风格 / 状态标签、地图节点方向标签、地图场景切换方向标签和营地编组状态数值已迁移。暗色动作按钮、runtime HUD、属性加成动态 pill 和按钮内部消耗 chip 暂不直接套静态 badge。
|
||||
- 2026-06-10 追加：背景故事已解锁 / 需好感状态和好感等级 badge 也使用 `PlatformPillBadge` 的 `dark*` tone；好感进度时间轴刻度、runtime HUD 和带点击卡片视觉的标签仍保留专用布局。
|
||||
- 2026-06-10 追加：RPG 角色资产工作室动作列表的生成中 / 已生成 / 待生成状态 chip 直接使用 `PlatformPillBadge` 的 `darkAmber` / `darkEmerald` / `darkNeutral` tone；父弹窗不再维护本地 `StatusBadge` 浅封装，动作生成按钮仍保留工作室专用暗色按钮布局。
|
||||
- 2026-06-10 追加：NPC 交易物品数量、赠礼好感增量和背包工坊材料需求状态使用 `PlatformPillBadge` 的 `dark*` tone；这些只是纯展示 chip，交易 / 赠礼列表按钮和工坊锻造 / 合成动作按钮继续保留各自交互布局。
|
||||
- 2026-06-10 追加：RPG 角色编辑器技能列表里的动作已生成 / 待生成动作状态直接使用 `PlatformPillBadge` 的 `darkEmerald` / `darkNeutral` tone；本地 `StatusBadge` 浅封装删除，技能编辑按钮卡片仍保留原有点击布局。
|
||||
- 2026-06-10 追加：RPG 角色编辑器两处重复的已应用主图 / 已应用动作 chip 合并为局部 `RoleAssetAppliedBadges`，内部复用 `PlatformPillBadge darkEmerald / darkAmber`；场景角色选择列表的选择 / 已选中和地标连接列表的当前连接也使用 `PlatformPillBadge dark*`，但外层按钮卡片仍保留原交互语义。
|
||||
- 2026-06-10 追加：RPG 作品封面来源状态使用 `PlatformPillBadge darkNeutral`，角色开局物品标签合并为局部 `RoleInitialItemTagBadges` 并复用 `PlatformPillBadge darkNeutral`；物品编辑弹窗和开局物品列表不再重复维护标签 chip class。
|
||||
- 2026-06-10 追加：RPG 世界地图节点中的当前状态使用 `PlatformPillBadge tone="muted"` 复用平台白底柔和 badge chrome；地图节点位置、连线和整体卡片仍保留地图专用布局。
|
||||
- 2026-06-10 追加：媒体 / 舞台预览上的非交互悬浮短标签使用 `src/components/common/PlatformOverlayBadge.tsx`，复合控件内部的紧凑槽位编号使用 `src/components/common/PlatformSlotBadge.tsx`；RPG 场景幕预览左上幕标签和每幕角色槽位“主 / 2 / 3”已迁移。普通状态 chip 继续使用 `PlatformPillBadge`，外层按钮卡片、人物舞台位置和运行态 HUD 不迁入这两个小 Module。
|
||||
- 2026-06-10 追加：拼图结果页智能修订条的白底图标圆槽使用 `PlatformIconBadge tone="soft" size="sm"`，外层编辑条使用 `PlatformSubpanel radius="lg"`；结果页只保留提交、禁用和错误提示语义，不再手写 `platform-subpanel rounded-[1.35rem] p-3 sm:p-4` 或 `hidden h-9 w-9 rounded-full bg-white/72`。
|
||||
- 2026-06-10 追加：拼图结果页关卡卡片外壳使用 `PlatformSubpanel radius="lg" padding="none"`，关卡列表只保留图片、生成中状态、标题打开和删除动作，不再手写 `platform-subpanel overflow-hidden rounded-[1.35rem] p-0`。
|
||||
- 2026-06-10 追加：`PlatformOverlayBadge` 支持 `tone="muted"`、`size="compact"` 和 `offset="tight"`，用于素材缩略图右上角“占位图”等紧凑非交互浮层；宝贝识物结果页占位资源标记已从绝对定位的 `PlatformPillBadge` 迁移到 overlay badge。
|
||||
- 2026-06-10 追加：`PlatformSlotBadge` 支持 `tone="soft"` 和 `size="md"`，用于 creative-agent 阶段时间线的白底柔和步骤圆点；阶段卡片本体与 active / done / idle 语义仍保留在 `CreativeAgentStageTimeline`。
|
||||
- 2026-06-10 追加：物品格、奖励格等缩略图右下角数量使用 `src/components/common/PlatformQuantityBadge.tsx`；背包物品格和 RPG 冒险面板 / 覆盖层奖励物品数量已迁移。该 Module 只承接数量角标 chrome，物品按钮、稀有度边框、选中态和详情弹窗仍归业务 Module。
|
||||
- 2026-06-10 追加：RPG 冒险面板和覆盖层里的任务目标状态、任务日志状态、当前幕、剩余交谈等暗色纯展示 chip 使用 `PlatformPillBadge dark*`；任务 presentation / 日志状态只返回语义 tone，不再直接返回整段 `border / bg / text` class。运行态动作按钮、任务面板打开按钮和带 hover / click 语义的胶囊仍保留专用布局。任务日志状态补充验证命令：`npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx src/components/common/PlatformPillBadge.test.tsx -t "quest offer accept button|supports dark RPG badge tones"`。
|
||||
- 2026-06-10 追加：RPG 角色面板里的标签数、适配倍数、性别和装备稀有度等暗色纯展示 chip 使用 `PlatformPillBadge darkNeutral / darkEmerald / darkAmber`；角色面板只保留标签数和 multiplier 计算，不再手写这些胶囊 chrome。
|
||||
- 2026-06-10 追加：RPG 首页作品卡里的发布状态、元信息、主标签，以及存档卡右上恢复 / 最近游玩时间等暗色静态 chip 使用 `PlatformPillBadge dark*`；作品卡 / 存档卡只保留可点击卡片、删除动作、进入 / 继续创作箭头和业务文案。
|
||||
- 2026-06-10 追加：自定义世界实体目录里的基础设定词条标签使用 `PlatformPillBadge darkSoft`；目录页只保留词条解析和空值展示逻辑，不再手写白字暗底 tag chrome。
|
||||
- 2026-06-10 追加：RPG 实体编辑器基本设定里的拆分标签也使用 `PlatformPillBadge darkSoft`；编辑器只保留字段草稿、文本解析和保存逻辑，不再手写暗色静态 tag chrome。
|
||||
- 2026-06-10 追加：`PlatformSubpanel` 支持 `surface="dark"`、`radius="xs"` 和 `padding="xs"`，用于 RPG 暗色编辑器 / 运行态里的非交互小信息卡；任务目标、区域、进度、描述、角色维度和角色形象状态已先迁移。暗色 HUD、动作按钮、可点击卡片和强玩法品牌面板继续保留业务布局。
|
||||
- 2026-06-10 追加：`PlatformSubpanel` 支持 `surface="darkSky" | "darkEmerald" | "darkAmber" | "darkRose"`，用于 RPG 暗色编辑器 / 运行态里带业务色强调的结构化信息面板；实体详情私聊提示、队友收束、玩家等级进度、角色面板等级 / 收束状态、任务奖励好感度 / 货币 / 经验数值卡、RPG 大编辑器上传封面中提示、地图场景切换目标场景面板和 `CharacterInfoShared.MultiplierContributionList` 状态标签外壳已迁移。地图场景切换当前 / 前往摘要、营地编组分区、同行者卡和营地气氛小卡走 `surface="dark"` 非强调信息卡。后续同类 sky / emerald / amber / rose 暗色信息壳不再手写 `border-*-400/18 bg-*-500/8`，普通暗色信息卡不再手写 `border-white/* bg-black/*`。
|
||||
- 2026-06-10 追加：自定义选择弹窗当前角色信息块使用 `PlatformSubpanel surface="dark"`；弹窗只保留角色标签文案，不再手写 `rounded-2xl border border-white/10 bg-black/20 px-4 py-3` 暗色纯展示块。验证命令：`npm run test -- src/components/SelectionCustomizationModals.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 追加：RPG 队伍面板和实体详情弹窗里的构筑标签效果详情统一由 `CharacterInfoShared.BuildContributionDetailPanel` 承接；标签概览、属性加成明细和无明细提示组合 `PlatformSubpanel surface="dark"`，业务弹窗只保留选中状态和属性 rows，不再复制同一段标签效果暗色面板 JSX。
|
||||
- 2026-06-10 追加：`CharacterInfoShared.CharacterSkillsList` 的空态使用 `PlatformEmptyState surface="editorDark"`，可点击和只读技能卡使用 `PlatformSubpanel surface="dark"`；角色信息共享模块只保留技能 render id、选择回调、数值字段和标签展示语义，不再手写技能空态 / 技能卡暗色外壳。验证命令：`npm run test -- src/components/CharacterInfoShared.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformEmptyState.test.tsx -t "CharacterSkillsList|supports dark compact subpanel cards"`。
|
||||
- 2026-06-10 验证补充：共享构筑状态标签外壳收口到 `PlatformSubpanel surface="darkSky"` 后，补跑 `npm run test -- src/components/CharacterInfoShared.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 追加：RPG 实体详情弹窗的物品空态使用 `PlatformEmptyState surface="editorDark"`，技能预览 fallback、技能数值卡、技能说明和附带状态标签区使用 `PlatformSubpanel surface="dark"`；实体详情只保留技能 / 物品数据和业务文案，不再手写这些暗色小卡 chrome。
|
||||
- 2026-06-10 追加：RPG 实体详情弹窗最近回响中的后果、编年、载体和场景残留纯展示卡使用 `PlatformSubpanel surface="dark"`；实体详情只保留 story memory / 场景 residue 数据映射，队友收束等强调态继续保留业务语义样式。验证命令：`npm run test -- src/components/AdventureEntityModal.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "最近回响|supports dark compact subpanel cards"`。
|
||||
- 2026-06-10 追加：RPG 实体详情弹窗本地 `Section` 适配到 `PlatformSubpanel surface="dark"`；立绘、关系、私聊、最近回响、属性、技能和物品等主分区只保留标题与内容插槽，不再由业务组件维护 `rounded-2xl border border-white/8 bg-black/20 p-4` 外壳。验证命令：`npm run test -- src/components/AdventureEntityModal.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "主分区|supports dark compact subpanel cards"`。
|
||||
- 2026-06-10 追加：RPG 冒险统计弹窗的总览和统计卡使用 `PlatformSubpanel surface="dark"`；统计弹窗只保留统计字段、图标和总览文案，设置弹窗里的 range input、保存退出按钮和入口按钮继续保留运行态专用交互布局。验证命令：`npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "adventure statistics panel|supports dark compact subpanel cards"`。
|
||||
- 2026-06-10 追加：RPG 覆盖层里的任务完成领奖提示、任务奖励缓存、战斗结束提示、战利品缓存和奖励物品详情描述 / 效果 / 标签使用 `PlatformSubpanel surface="dark"`，战斗结算敌人名使用 `PlatformPillBadge darkEmerald`；覆盖层只保留奖励数据、物品选择和弹窗层级语义，不再手写奖励缓存暗色面板和敌人名胶囊 chrome。验证命令：`npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx -t "quest offer accept button|quest completion notice|battle reward modal|supports dark compact subpanel cards|supports dark RPG badge tones"`。
|
||||
- 2026-06-10 追加：RPG 覆盖层里的任务摘要卡和任务奖励条使用 `PlatformSubpanel surface="dark"`，奖励条内物品数量使用 `PlatformQuantityBadge`；覆盖层只保留任务文案、奖励数据和物品选择语义，不再手写任务摘要 / 奖励条暗色外壳或数量角标 chrome。验证命令：`npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformQuantityBadge.test.tsx -t "quest reward strip|supports dark compact subpanel cards|renders a dark bottom-right quantity badge"`。
|
||||
- 2026-06-10 追加：RPG 覆盖层里的任务奖励好感度、货币和经验数值卡使用 `PlatformSubpanel surface="darkRose" | "darkAmber" | "darkSky"`；覆盖层不再手写三套 `rounded-xl border bg-* px-3 py-2.5` 数值卡 chrome，也不再通过局部 class 覆盖 tint 调性。验证命令：`npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 追加：RPG 角色详情弹窗的装备格、背包格、旅程原因 / 目标、背景和性格小卡使用 `PlatformSubpanel surface="dark"`，候选人和性别静态 badge 使用 `PlatformPillBadge dark*` tone；角色详情只保留资料、属性、技能和动画展示语义，立绘框与属性网格暂保留原布局。验证命令：`npm run test -- src/components/CharacterDetailModal.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx`。
|
||||
- 2026-06-10 追加：RPG 角色面板详情里的个人线阶段、背景故事、性格纯展示块和装备行使用 `PlatformSubpanel surface="dark"`；角色面板只保留选中成员、个人线状态、展示文本和装备字段映射，像素外层面板与动作入口继续保留业务布局。验证命令：`npm run test -- src/components/CharacterPanel.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx`。
|
||||
- 2026-06-10 追加：好感状态卡的等级摘要和好感进度外壳使用 `PlatformSubpanel surface="dark"`；好感卡只保留等级推导、进度刻度和文案，不再手写 `rounded-xl border border-white/8 bg-black/20 px-* py-*` 暗色面板 chrome。验证命令：`npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/AffinityStatusCard.test.tsx`。
|
||||
- 2026-06-10 追加：背景故事公开印象、已解锁章节和锁定章节外壳使用 `PlatformSubpanel surface="dark"`，无背景线索空档案使用 `PlatformEmptyState surface="editorDark"`；背景档案只保留章节状态、好感阈值和故事文案，不再手写这些暗色小卡 / 空态 chrome。验证命令：`npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/BackstoryArchive.test.tsx`。
|
||||
- 2026-06-10 追加：NPC 交易弹窗的数量 stepper 外壳、库存计数条、详情容器和总价卡使用 `PlatformSubpanel surface="dark"`；交易弹窗只保留交易数量、库存、价格和禁用原因语义，交易物品 / 礼物 / 招募可选列表按钮改由 `PlatformDarkOptionCard` 承接暗色 selected / idle / hover chrome。验证命令：`npm run test -- src/components/NpcModals.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "NPC 交易静态信息卡|supports dark compact subpanel cards"`。
|
||||
- 2026-06-10 追加：背包文书、故事档案和工坊分区外壳，以及文书按钮、故事档案条目和工坊配方卡使用 `PlatformSubpanel surface="dark"`；工坊材料需求状态使用 `PlatformPillBadge dark*` tone，故事档案 QA 提示使用 `PlatformStatusMessage surface="editorDark"`。锻造 / 合成动作按钮继续保留业务交互布局。验证命令：`npm run test -- src/components/InventoryPanel.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformStatusMessage.test.tsx -t "背包文书|背包工坊|supports dark compact subpanel cards|supports editor dark surface"`。
|
||||
- 2026-06-10 追加：NPC 交易详情里的装备位、即时使用和标签属性格使用 `PlatformSubpanel surface="dark" padding="row"`，使用效果提示使用 `PlatformStatusMessage surface="editorDark"`；物品详情弹窗只保留物品属性、效果和标签计算，不再手写 `rounded-lg border border-white/8 bg-black/20 px-3 py-2` 或 emerald 提示条 chrome。
|
||||
- 2026-06-10 追加：新增 `PlatformDarkOptionCard` 承接 RPG 暗色弹窗 / 面板中的可选项按钮卡 selected / idle / hover / disabled chrome；NPC 交易模式、交易物品行、赠礼候选、招募替换候选、角色素材工作室动作预览格和营地编组替换位按钮已迁移。业务组件只保留选中判断、tone、点击回调和卡片内容，不再手写 `rounded-* border px-3 py-*`、`border-*-400/* bg-*-500/10` 或 `border-white/* bg-black/20 hover:border-white/15`。
|
||||
- 2026-06-10 追加：角色聊天弹窗的状态 / 总结卡使用 `PlatformSubpanel surface="dark"`，空聊天记录使用 `PlatformEmptyState surface="editorDark"`，建议回复按钮使用 `PlatformDarkOptionCard tone="sky"`；弹窗只保留角色状态、聊天记录和建议语义，不再手写这些暗色信息卡、空态或建议按钮 chrome。验证命令：`npm run test -- src/components/CharacterChatModal.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformDarkOptionCard.test.tsx`。
|
||||
- 2026-06-10 追加：拼图首访 onboarding 提示词文本域使用 `PlatformTextField surface="editorDark"`，输入错误和登录保存错误使用 `PlatformStatusMessage surface="editorDark"`，生成 / 登录 CTA 使用 `PlatformActionButton surface="editorDark" tone="accent"`，跳过按钮使用 `PlatformActionButton surface="editorDark" tone="ghost" shape="pill"`；onboarding 保留全屏沉浸壳层、登录 / 生成状态机和跳过行为，不再手写 textarea / 错误条 / 按钮 chrome。验证命令：`npm run test -- src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleOnboardingView.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformActionButton.test.tsx src/components/common/platformActionButtonModel.test.ts`。
|
||||
- 2026-06-10 追加：RPG 大编辑器本地 `SectionPanel` 适配到 `PlatformSubpanel surface="dark"`；可扮演角色背景故事 / 关系 / 技能 / 物品、世界基础设定等编辑分区只保留标题、subtitle、右侧动作和内容插槽，不再由本地适配器手写外层暗色面板 chrome。验证命令：`npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "可扮演角色技能动作状态|supports dark compact subpanel cards"`。
|
||||
- 2026-06-10 验证补充：RPG 大编辑器上传封面中提示收口到 `PlatformSubpanel surface="darkSky"` 后，补跑 `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "作品封面上传|tinted dark information panels"`。
|
||||
- 2026-06-10 追加：RPG 角色形象参考图缩略框使用 `PlatformMediaFrame surface="editorDark"`；角色形象面板只保留参考图数组、上传 / 清空回调和状态文案，不再手写 `img + overflow-hidden + border` 缩略图 chrome。
|
||||
- 2026-06-10 追加：营地编组同行者头像框使用 `PlatformMediaFrame surface="editorDark"` 和固定尺寸 class，保留角色图片 `object-contain`、放大比例与 pixelated 渲染；编组卡只保留角色数据和操作语义，不再手写头像框 `border-white/10 bg-black/25` 外壳。验证命令：`npm run test -- src/components/CompanionCampModal.test.tsx src/components/common/PlatformMediaFrame.test.tsx`。
|
||||
- 2026-06-09 追加：平台普通进度条统一使用 `src/components/common/PlatformProgressBar.tsx` 承载 `progressbar` 语义、`platform-progress-track` 壳、填充宽度、最小可见宽度、尺寸、条内覆盖层、未知进度语义和局部主题色；creation-agent 主进度 / operation banner、RPG 结果页生成提示、RPG 实体目录生成中提示、开场 CG 生成占位、拼图关卡画面生成进度、生成页当前步骤线性进度、抓大鹅批量物品素材生成进度和自定义世界生成选择弹窗进度提示已先迁移，业务页只保留进度值、显示文案、状态配色和必要覆盖内容。没有准确百分比的脉冲占位条使用 `indeterminate`，不暴露假的 `aria-valuenow`；生成页环形总进度继续保留 `GenerationProgressHero` 专用 SVG。
|
||||
- 2026-06-09 追加：creation-agent operation banner 的状态外壳迁移到 `PlatformStatusMessage surface="platform" remapSurface`，进度条继续使用 `PlatformProgressBar`；局部 platform token 作用域需要重映射时由 `remapSurface` 承接，不在业务 JSX 中继续手写 `platform-remap-surface platform-banner` 和 `platform-banner--*`。
|
||||
- 2026-06-09 追加：平台只读信息块统一使用 `src/components/common/PlatformInfoBlock.tsx` 承载短标签、无标签纯正文、白底圆角边框、单行 / 多行正文排版和横向只读信息行的标签 / 值局部排版；错误弹窗和生成完成弹窗的来源、错误、状态展示、分享弹窗正文，以及汪汪声浪预览卡场景 / 形象 / 难度 / 声浪信息行已迁移，业务页不再重复拼 `rounded-[1rem] border ... bg-white/72 px-3 py-2`、`rounded-[1.25rem] border ... bg-white/72 p-4` 或 `rounded-[0.85rem] bg-white/74 px-* py-*`。
|
||||
- 2026-06-10 追加：`PlatformInfoBlock` 支持 `variant="compactRow"` 承接预览卡密集横向 label / value 行；汪汪声浪预览卡四个信息行只保留 label 和内容，不再维护本地 `PREVIEW_INFO_*` class 常量。
|
||||
- 2026-06-09 追加：平台白底子面板统一使用 `src/components/common/PlatformSubpanel.tsx` 承载 `platform-subpanel` 外壳、标题行、右侧动作区、强标题、圆角和响应式内边距；静态 element 透传 `aria-*` / `data-*` 等原生属性，便于结果页预览卡保留可访问名称。拼图结果页作品信息 / 标签编辑 / 智能修订条 / 关卡卡片、拼图图库详情页封面轮播壳 / 题材标签 / 关卡摘要、拼图图片生成模式选择器菜单外壳、敲木鱼结果页元信息 / 标签 / 飘字 / 音效、汪汪声浪结果页草稿摘要 / 素材槽 / 预览卡、通用音频输入面板和 RPG 个人中心未登录提示已先迁移。`surface="soft" padding="tight"` 用于标签编辑新增输入行等白底柔和紧凑行，不再手写 `rounded-[1rem] border ... bg-white/68 p-2`；`surface="soft" padding="row"` 用于上传预览横向已选素材条等白底柔和横向行，不再手写 `rounded-[1rem] border ... bg-white/68 px-3 py-2`；静态封面轮播壳使用 `radius="xl" padding="none"` 保留内部固定比例和轮播按钮；抓大鹅物品详情五视角面板使用 `radius="xl" padding="sm"` 加局部 `sm:p-5` 保留响应式间距。后续仅表达“白底子面板 + 标题 / 右侧动作 + 内容”或小型浮层菜单的片段优先使用该 Module；暗色运行态 HUD、媒体预览和强玩法品牌面板继续保留专用布局。
|
||||
- 2026-06-10 追加：发布分享弹窗渠道 tile 按钮使用 `PlatformSubpanel as="button" surface="flat" radius="sm" padding="tight" interactive`；弹窗只保留渠道枚举、品牌图标和复制分享文本回调，不再手写白底 tile 圆角、边框、底色、hover 或 focus chrome。验证命令：`npm run test -- src/components/common/PublishShareModal.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 追加：平台入口创作类型弹层玩法卡片使用 `PlatformSubpanel as="button" surface="platform" radius="xl" padding="none"`；弹层只保留玩法图片、蒙版、锁定 badge、标题副标题和分流回调，外层按钮语义、标准圆角和已开放卡 hover / focus chrome 归公共子面板。验证命令：`npm run test -- src/components/platform-entry/PlatformEntryCreationTypeModal.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 追加：creation-agent 工作台聊天区外壳使用 `PlatformSubpanel radius="xl" padding="none"`；工作台只保留消息列表、引用图预览、错误提示和输入区语义，不再手写聊天面板外层圆角、边框和底色。验证命令：`npm run test -- src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 追加：creation-agent 无 session / 加载提示块迁移到 `PlatformSubpanel radius="sm" padding="lg"`；工作台只保留提示文案，不再手写 `platform-subpanel rounded-2xl px-5 py-4` 普通居中提示面板。
|
||||
- 2026-06-10 追加：拼图结果页空草稿提示块迁移到 `PlatformSubpanel radius="sm" padding="lg"`；结果页只保留提示文案，不再手写 `platform-subpanel rounded-2xl px-5 py-4` 普通居中提示面板。
|
||||
- 2026-06-09 追加：敲木鱼结果页主预览面板也迁移到 `PlatformSubpanel`，页面只保留标题、简介和资源叠放语义，不再手写 `platform-subpanel rounded-[1.25rem] p-4`。
|
||||
- 2026-06-09 追加：拼消消创作工作台左侧结构化表单面板迁移到 `PlatformSubpanel`，工作台只保留字段、开关、错误和提交语义，不再手写 `platform-subpanel rounded-[1.25rem] p-4`。
|
||||
- 2026-06-09 追加：抓大鹅创作工作台难度选择小面板迁移到 `PlatformSubpanel surface="flat"`，工作台只保留难度选项和 payload 派生，不再手写小白底面板边框、圆角、内边距和 inset 高光。
|
||||
- 2026-06-09 追加：视觉小说创作工作台画风选择小面板迁移到 `PlatformSubpanel surface="flat"`，横向滚动、选中态和移动端 touch 行为仍由业务滚动区与样式按钮承接，不再手写外层白底面板 chrome。
|
||||
- 2026-06-09 追加：创作中心作品架整块无作品 / 无筛选结果空态迁移到 `PlatformEmptyState surface="soft" size="panel"`，加载骨架卡迁移到 `PlatformSubpanel as="div"`；Hub 只保留筛选、列表和打开 / 删除 / 分享语义，不再直接拼空态 `platform-subpanel` 或 skeleton 卡片外壳。
|
||||
- 2026-06-09 追加：视觉小说上传资产弹窗的无历史素材本地上传占位迁移到 `PlatformEmptyState surface="dashed"`；弹窗只保留上传、AI 生成、历史素材和选择回调语义，不再手写 dashed 空态面板 chrome。
|
||||
- 2026-06-09 追加：creative-agent 工作台目录、目标就绪、空消息、过程、关卡计划和模板确认理由等标准白底面板迁移到 `PlatformSubpanel`；模板确认的“关卡模式 / 计划关卡”摘要迁移到 `PlatformStatGrid`，creative-agent 内不再直接拼 `platform-subpanel rounded-[1.35rem] p-4` / `rounded-[1.25rem] p-4` / `rounded-[1.15rem] p-4`。
|
||||
- 2026-06-09 追加：拼消消结果页预览、统计和操作三个标准白底面板迁移到 `PlatformSubpanel`；页面只保留图片预览、统计项和动作回调，不再直接拼 `platform-subpanel rounded-[1.25rem] p-4` 或 `platform-subpanel mt-auto rounded-[1.25rem] p-4`。
|
||||
- 2026-06-09 追加：跳一跳结果页预览和结果操作两个标准白底面板迁移到 `PlatformSubpanel`，公开排行榜小卡迁移到 `PlatformSubpanel surface="flat"`；操作面板标题走 `PlatformFieldLabel variant="section"`，页面只保留资源预览、排行榜数据、状态提示和动作回调，不再直接拼 `platform-subpanel rounded-[1.25rem] p-4` 或 `rounded-[1rem] border ... bg-white/70 p-3`。
|
||||
- 2026-06-09 追加：跳一跳结果页角色 / 图集 / 路径预览框和拼消消结果页场地底图 / 素材图集预览框使用 `PlatformSubpanel surface="flat" padding="none"`；白底媒体框只保留内部图片、占位和尺寸，不再重复拼 `rounded-[1rem] border ... bg-white/80`。
|
||||
- 2026-06-09 追加：`PlatformSubpanel` 支持 `radius="xl"`，用于承接方洞结果页等 `rounded-[1.5rem]` 的标准大面板；方洞结果页封面、主信息、形状选项和洞口选项面板已迁移到 `PlatformSubpanel radius="xl" padding="lg"`，页面只保留图片、字段、选项和动作逻辑。
|
||||
- 2026-06-09 追加：方洞结果页形状 / 洞口选项卡迁移到 `PlatformSubpanel surface="flat"`，贴图缩略图按钮迁移到 `PlatformSubpanel as="button" interactive surface="flat"`；选项卡只保留字段写回、目标洞口选择、删除和图片槽位打开逻辑，不再重复小卡边框、白底、圆角、缩略图 hover / disabled chrome。
|
||||
- 2026-06-09 追加：敲木鱼创作工作台的“功德有什么”词条面板迁移到 `PlatformSubpanel`，词条输入迁移到 `PlatformTextField`，删除词条圆形浮动入口迁移到 `PlatformIconButton variant="surfaceFloating"`；工作台只保留词条输入、新增和删除交互，不再直接拼 `platform-subpanel rounded-[1.25rem] p-4`、本地标题 class、白底输入框 chrome 或白底圆形图标按钮 chrome。
|
||||
- 2026-06-09 追加：视觉小说结果页作品、开场、运行配置和世界观标准编辑面板迁移到 `PlatformSubpanel radius="lg"`；页面只保留表单字段、资产预览和运行配置写回，不再直接拼 `platform-subpanel rounded-[1.35rem] p-4`。
|
||||
- 2026-06-09 追加：抓大鹅结果页作品信息、难度配置、难度统计、UI 素材预览和物品图集预览标准面板迁移到 `PlatformSubpanel radius="lg" padding="lg"`；页面只保留表单、滑杆、统计项和素材预览逻辑，不再直接拼 `platform-subpanel rounded-[1.35rem] p-4 sm:p-5`。
|
||||
- 2026-06-09 追加：`PlatformSubpanel` 支持 `surface="flat"`、`padding="sm"` 和 `radius="sm"`，用于承接素材 / 音频等小型白底卡片的圆角、边框、`bg-white/72`、标题行和右侧图标动作；视觉小说结果页素材选择 / 音频生成小面板已迁移，业务页不再重复手写 `rounded-[1rem] border ... bg-white/72 p-3`。
|
||||
- 2026-06-09 追加：抓大鹅结果页难度配置里的当前难度摘要小卡迁移到 `PlatformSubpanel surface="flat" radius="sm" padding="sm"`；结果页只保留当前难度标题、消除次数、物品种类和难度 badge，不再手写 `rounded-[1rem] border ... bg-white/62 px-3 py-3` 小卡 chrome。
|
||||
- 2026-06-09 追加：RPG 结果页开发资产诊断面板里的摘要卡、资产条目和空态迁移到 `PlatformSubpanel`；开发开关判定拆到 `rpgCreationAssetDebugPanelModel.ts`，组件文件只保留诊断面板渲染和图片加载状态。
|
||||
- 2026-06-09 追加：RPG 发布弹窗封面预览壳迁移到 `PlatformSubpanel padding="none"`；发布弹窗只保留封面 presentation、设置封面和发布动作语义，不再直接手写 `platform-subpanel rounded-[1.25rem] p-2`。
|
||||
- 2026-06-09 追加：creative-agent 关卡计划小卡和抓大鹅结果页物品 spritesheet 分组卡迁移到 `PlatformSubpanel surface="flat" radius="sm"`；普通信息 / 图集分组小卡不再直接拼 `rounded-[1rem] border ... bg-white/58 p-3` 或 `px-3 py-3`。
|
||||
- 2026-06-09 追加：抓大鹅批量物品素材生成状态卡迁移到 `PlatformSubpanel surface="flat" radius="sm"`，内部进度条迁移到 `PlatformProgressBar`；局部进度状态不再手写白底边框和 track / fill div。
|
||||
- 2026-06-09 追加：平台反馈页问题描述、上传凭证和联系方式三个普通白底区块迁移到 `PlatformSubpanel radius="md"`；平台表单页只表达字段、上传和提交语义，不再直接拼 `platform-subpanel rounded-[1.2rem] px-4 py-4`。
|
||||
- 2026-06-10 追加：`PlatformSubpanel` 支持 `surface="dark"`、`radius="xs"` 和 `padding="xs"`，用于暗色编辑 / 运行面板里的小型信息卡；RPG 冒险面板 / 覆盖层任务目标、区域、进度和描述卡，以及自定义世界实体目录角色维度小卡已迁移。后续同类暗色小信息卡只保留标题、图标和值，不再手写 `rounded-xl border border-white/10 bg-black/* px-* py-*`。
|
||||
- 2026-06-09 追加：`PlatformSubpanel` 支持 `as="button"` 与 `interactive`，用于承接普通白底整卡点击列表项的 hover、focus、disabled 和默认 `type="button"`；视觉小说 runtime 历史条目和存档列表已迁移，业务页不再重复手写 `rounded-[1rem] border ... bg-white/78 p-3 hover:bg-white disabled:cursor-not-allowed disabled:opacity-55`。
|
||||
- 2026-06-09 追加：视觉小说结果页角色 / 场景 / 阶段列表项和空态迁移到 `PlatformSubpanel`；列表项使用 `as="button" interactive` 保留整卡点击、hover / focus / disabled chrome 和默认 button type，空态使用静态 `PlatformSubpanel`，结果页不再直接手写 `platform-subpanel min-h-32` 列表卡片。
|
||||
- 2026-06-09 追加：账号设置入口卡、主题选择卡、当前主题状态、账号绑定卡、密码 / 安全 / 设备 / 操作记录区块，以及设备 / 操作记录内的白底列表行迁移到 `PlatformSubpanel`；账号弹窗只保留换绑、撤销会话、刷新和日志展示语义，不再直接拼 `platform-subpanel rounded-2xl` 或内层白底列表边框。
|
||||
- 2026-06-09 追加：RPG 世界详情页的世界信息统计卡、关键角色 / 关键场景预览卡和操作区标题迁移到 `PlatformSubpanel` 与 `PlatformFieldLabel variant="section"`；详情页只保留作品展示、启动、编辑、发布、下架和删除动作语义，不再直接拼小型 `platform-subpanel` 卡片或本地 section 标题 class。
|
||||
- 2026-06-10 追加：RPG 运行态任务覆盖层里的任务更新提示、地点 / 人物提示和任务日志条目迁移到 `PlatformSubpanel surface="dark"`；运行态只保留任务文案、任务选择和奖励条交互，暗色边框、底色、圆角和条目 hover 外壳不再在业务 JSX 中重复拼。验证命令：`npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx -t "quest offer accept button reuses the shared accepted-quest follow-up chain"`。
|
||||
- 2026-06-09 追加：大鱼吃小鱼结果页的关卡卡片、场地背景卡、发布校验卡、空草稿提示和素材工坊 PROMPT 信息块迁移到 `PlatformSubpanel`；结果页只保留大鱼玩法的青色主题按钮、预览背景、素材生成动作和发布校验语义，不再直接拼大圆角白底边框卡片。
|
||||
- 2026-06-09 追加：汪汪声浪结果页草稿编译小卡迁移到 `PlatformSubpanel surface="flat"`，跳一跳结果页排行榜行卡迁移到 `PlatformSubpanel surface="flat"`，排行榜无成绩空态迁移到 `PlatformEmptyState surface="subpanel"`；结果页只保留玩法文案、排行榜字段和错误 / 空态文案，不再手写白底小卡圆角、边框、底色和 padding。
|
||||
- 2026-06-09 追加：自定义世界实体目录世界页的档案规模统计迁移到 `PlatformStatGrid`，世界基调、角色维度和基本设定条目迁移到 `PlatformSubpanel`；目录只保留世界资料读取、编辑入口和标签展示语义，不再直接拼统计卡 grid 或 `platform-subpanel rounded-2xl` 设定块。
|
||||
- 2026-06-09 追加：自定义世界实体目录场景幕级缩略图迁移到 `PlatformSubpanel padding="none"`；目录只保留场景名、幕标题和图片来源语义，不再手写 `platform-subpanel h-12 w-[5.25rem]` 预览框 chrome。
|
||||
- 2026-06-09 追加：自定义世界实体目录 `CatalogCard` 的角色 / 场景媒体框迁移到 `PlatformSubpanel padding="none"`；目录卡片只保留图片、角色动画或占位内容，不再手写媒体框 `platform-subpanel rounded-[1rem]` / `rounded-[1.1rem]` chrome。
|
||||
- 2026-06-09 追加：`PlatformSubpanel` 支持 `surface="danger"` 承接整卡危险选中态，`PlatformPillBadge` 支持 `tone="muted"` 承接白底柔和选择 badge；自定义世界实体目录 `CatalogCard` 整卡壳迁移到 `PlatformSubpanel as="button"`，批量选择的“选择 / 已选”迁移到 `PlatformPillBadge`，目录只保留选择状态和点击回调，不再手写卡片 `role="button"` / 危险选中边框 / 选择 badge chrome。
|
||||
- 2026-06-09 追加：平台媒体预览框统一使用 `src/components/common/PlatformMediaFrame.tsx` 承载图片源、fallback 图、fallback 文案、固定比例、refreshKey、warm / editorDark / plain / soft / bright / none / bare surface 和 overlay；自定义世界实体目录场景图片框、RPG 实体编辑器 `ImagePreview` 和拼图结果页关卡列表正式图框已先迁移，业务页只保留素材地址、可访问名称和业务覆盖层。`surface="soft"` 用于由媒体框自身承接 `border border-[var(--platform-subpanel-border)] bg-white/68` 的白底柔和预览，`surface="bright"` 用于由媒体框自身承接 `border border-[var(--platform-subpanel-border)] bg-white/82` 的亮白素材槽，`surface="none"` 用于嵌在已有按钮 / 卡片交互壳里的纯图片与 fallback 内容；`PlatformSubpanel` 继续负责白底面板 / 轻量媒体壳 / 整卡点击列表项，不承接需要 fallback 或 overlay 的图片预览状态。
|
||||
- 2026-06-09 追加：`PlatformMediaFrame` 支持 `aspect="portrait"` 承接 9:16 竖版预览；拼消消结果页场地底图 / 素材图集预览已迁移到 `PlatformMediaFrame surface="none"`，外层仍用 `PlatformSubpanel surface="flat" padding="none"` 提供白底边框、圆角和 `bg-white/80` 媒体壳，页面不再手写 `ResolvedAssetImage` 与无图占位分支。
|
||||
- 2026-06-09 追加：平台媒体缩略格网格统一使用 `src/components/common/PlatformMediaTileGrid.tsx` 承载列数、间距、白底容器、tile 圆角、边框、图片、refreshKey、可选 tile `testId` 和 fallback 格；跳一跳结果页地块池 / 无图集 fallback 地块池、拼消消结果页卡片预览网格和抓大鹅物品 spritesheet 解析预览分组已先迁移。结果页只保留素材数组切片、素材地址、fallback 内容和玩法色值，不再重复手写 `grid-cols-*`、`rounded-[0.45rem] border border-white/80 bg-white/78` 或直接依赖底层 `ResolvedAssetImage`；网格内部 tile chrome 由 `tileSurface` 承接，内层 `PlatformMediaFrame` 统一使用 `surface="none"`，不再重复加公共 subpanel fill。
|
||||
- 2026-06-09 追加：`PlatformMediaFrame` 支持 `fallbackContent` 承接图标型无图占位；方洞结果页图片查看弹窗的 4:3 预览已迁移到 `PlatformMediaFrame aspect="standard" surface="plain"`，页面不再手写图片 / 图标占位分支。
|
||||
- 2026-06-09 追加：宝贝识物结果页素材卡图片框迁移到 `PlatformMediaFrame aspect="square" surface="none"`，占位资源 badge 作为 `previewOverlay` 传入；素材卡只保留外层 `PlatformSubpanel`、素材名、渐变槽局部样式和业务状态，不再手写 `ResolvedAssetImage` 绝对铺满与 overlay 分支。
|
||||
- 2026-06-09 追加：视觉小说结果页封面 4:3 预览和资产字段 16:9 图片预览迁移到 `PlatformMediaFrame`；封面使用 `surface="editorDark"` 和图标型 `fallbackContent`，资产字段使用 `aspect="landscape" surface="none"` 嵌入现有小型白底卡片，页面不再手写 `ResolvedAssetImage`、`aspect-[4/3]` / `aspect-[16/9]` 和无图占位分支。
|
||||
- 2026-06-09 追加：跳一跳结果页地块图集整图 fallback 预览迁移到 `PlatformMediaFrame aspect="square" surface="none"`；单个地块网格和路径平台预览保留专用组合布局，只有纯图片源 + 正方形比例的 atlas 分支进入公共媒体框，图集底色作为局部 `bg-white/78` 保留在媒体框 class。
|
||||
- 2026-06-09 追加：方洞结果页封面和背景两个点击预览按钮内部迁移到 `PlatformMediaFrame aspect="standard" / "landscape" surface="none"`；按钮继续负责打开图片槽位弹窗和承接渐变边框交互壳，公共媒体框只负责 4:3 / 16:9 比例、图片读取和图标型 fallback，占位和图片分支不再写在业务 JSX 中。
|
||||
- 2026-06-09 追加：方洞结果页形状 / 洞口选项里的 80px 贴图缩略图迁移到 `PlatformMediaFrame aspect="square" surface="none"`；外层 `PlatformSubpanel as="button"` 继续负责打开素材弹窗和亮白交互壳，业务页不再直接依赖底层 `ResolvedAssetImage`，内层媒体框也不再重复承接背景。
|
||||
- 2026-06-09 追加：`PlatformMediaFrame` 支持 `aspect="wide"` 承接 9:5 宽图预览；大鱼吃小鱼素材工坊候选预览迁移到 `PlatformMediaFrame aspect="wide" surface="none"`，工坊只保留 prompt、生成动作和 cyan 主题外观适配，虚线边框与浅青底作为局部 class 保留。
|
||||
- 2026-06-09 追加：拼图发布弹窗封面关卡预览迁移到 `PlatformMediaFrame aspect="square" surface="soft"`；发布弹窗只保留发布检查、泥点提示和发布动作，不再手写封面图片框 `aspect-square`、`ResolvedAssetImage`、白底柔和边框和空图分支。
|
||||
- 2026-06-09 追加：大鱼吃小鱼结果页场地背景竖版预览迁移到 `PlatformMediaFrame aspect="portrait" surface="none"`；结果页保留青色深海背景主题和生成背景动作，不再手写 9:16 图片框与 `ResolvedAssetImage` 分支。
|
||||
- 2026-06-09 追加：大鱼吃小鱼结果页关卡主图缩略图迁移到 `PlatformMediaFrame aspect="square" surface="none"`；关卡卡片只保留关卡文案、状态和工坊入口，不再直接依赖底层 `ResolvedAssetImage`。
|
||||
- 2026-06-10 追加：抓大鹅结果页物品素材列表缩略图和详情大图迁移到 `PlatformMediaFrame aspect="square" surface="bright"`，详情视角缩略图嵌在保留选中态的按钮壳内并使用 `surface="none"`；素材列表卡只保留打开详情、素材名和删除动作，详情预览只保留视角切换状态，不再手写正方形图片 / 图标 fallback / 亮白边框槽；需要测试 id / aria 时通过媒体框容器属性透传。
|
||||
- 2026-06-10 追加：抓大鹅结果页 UI 素材子 Tab 的游戏背景、UI spritesheet 和物品 spritesheet 主图预览迁移到 `PlatformMediaFrame surface="none"`；外层按钮 / 白底预览壳继续负责交互、边框、底色和内边距，媒体框只承接图片读取、fallback 和固定比例。
|
||||
- 2026-06-10 追加：`PlatformMediaFrame` 根节点固定带 `platform-media-frame` 类名，供业务测试断言公共媒体框接入；拼图图库详情页封面轮播的内层正方形图片 / 暂无封面 fallback / 轮播 overlay 迁移到 `PlatformMediaFrame aspect="square" surface="none"`，外层 `PlatformSubpanel radius="xl" padding="none"` 继续承接面板边框、圆角和裁切。
|
||||
- 2026-06-10 追加：认证图形验证码图片使用 `PlatformMediaFrame aspect="auto" surface="soft"`；验证码组件只保留图片 data URL、可访问名称和固定尺寸 class，不再手写 `img + platform-subpanel` 图片框。
|
||||
- 2026-06-09 追加：敲木鱼结果页主 9:16 背景 + 敲击物叠层预览迁移到 `PlatformMediaFrame aspect="portrait" surface="plain"`；页面保留背景图和敲击物的叠放顺序，不再手写固定比例外框、白底边框和无图占位。
|
||||
- 2026-06-09 追加：`PlatformMediaFrame` 支持 `fallbackShellClassName` 承接无图 fallback 区域的局部背景 / 渐变；creative-agent 模板确认预览迁移到 `PlatformMediaFrame aspect="landscape" surface="soft"`，弹窗只保留模板标题、泥点、调整和确认语义，不再手写 16:9 图片 / 图标占位容器，也不再在业务 JSX 中重复拼基础边框和 `bg-white/68`。
|
||||
- 2026-06-09 追加：creative-agent 模板目录卡迁移到 `PlatformSubpanel as="button" interactive surface="flat"`，卡内 16:9 预览迁移到 `PlatformMediaFrame aspect="landscape" surface="none"`；工作台只保留模板选择、标题、摘要、预览渐变局部样式和泥点范围，不再手写白底按钮卡、16:9 图片框或图标 fallback 容器。
|
||||
- 2026-06-09 追加：非交互中性 / 柔和 / hero / 暗色琥珀 / 成功 / 危险图标槽统一使用 `src/components/common/PlatformIconBadge.tsx` 承载图标、尺寸、圆角、neutral / soft / softBright / hero / heroMuted / darkAmber / success / danger 底色和可访问隐藏语义；视觉小说 runtime 面板标题、存档列表项，creative-agent 模板卡 / 模板确认 / 顶部 hero / 目标就绪 / 过程条目图标圆槽，创作类型弹层锁定卡小圆锁图标、大鱼吃小鱼发布失败弹窗图标槽、通用创作图片面板空主图上传占位图标槽，以及 GameCanvas 宝箱遭遇图标槽已先迁移，业务页不再重复拼 `grid h-* w-* place-items-center bg-[var(--platform-neutral-bg)] text-[var(--platform-neutral-text)]`、白底柔和小圆槽、目标完成图标槽、暗色琥珀图标槽或危险提示红色圆槽。
|
||||
- 2026-06-10 追加：宝贝识物工作台静态玩法预览卡迁移到 `PlatformSubpanel surface="soft"`，卡内礼物图标槽迁移到 `PlatformIconBadge tone="softBright"`；工作台只保留玩法渐变、装饰层和文案，不再手写白底柔和面板边框 / 圆角 / 内边距或图标槽 chrome。
|
||||
- 2026-06-09 追加：平台标签编辑统一使用 `src/components/common/PlatformTagEditor.tsx` 承载标签 chip、删除按钮、新增输入、Enter 提交、Escape 取消、空态、可选 AI 生成动作和错误提示；拼图结果页作品标签、敲木鱼结果页主题标签和抓大鹅结果页作品标签已先迁移。业务页只保留标签 parse / normalize 规则、最大数量和最终写回，不再重复维护标签编辑 JSX 与本地新增状态机。
|
||||
- 2026-06-10 追加：标签编辑 Module 内部的新增输入行由 `PlatformSubpanel surface="soft" padding="tight"` 承接外壳，输入框由 `PlatformTextField` 承接；公共标签编辑不再把子面板和输入框 chrome 混写在同一段本地 JSX class 中。
|
||||
- 2026-06-09 追加：方形上传入口和紧凑虚线新增入口统一使用 `src/components/common/PlatformUploadTile.tsx` 承载虚线方块、图标、主副文案、button / label 语义和禁用态；`size="compact" showLabel={false}` 用于工作台里的纯图标虚线新增入口，仍保留隐藏可访问名称。上传后的图片预览统一使用 `src/components/common/PlatformUploadPreviewCard.tsx` 承载缩略图壳、预览图片、可选标题行、可选预览点击、横向已选素材条和移除按钮。默认 `layout="square"` 用于方形缩略图，`layout="inline"` 用于“缩略图 + 文件名 / 素材名 + 移除”的已选参考图条，内部横向行复用 `PlatformSubpanel surface="soft" padding="row"`；反馈页上传凭证入口 / 预览、敲木鱼工作台新增功德词条入口、通用创作图片面板的提示词参考图缩略图、抓大鹅封面编辑参考图缩略图、通用输入 Composer 已选参考图条和 creation-agent 已选参考图条已先迁移，业务页只保留文件选择、预览数组、预览回调、删除回调、新增回调和校验逻辑。工具栏小图标上传仍使用 `PlatformIconButton asChild="label"`，带大面积缩略图选择的历史素材仍使用 `PlatformAssetPickerGrid`。
|
||||
- 2026-06-09 追加：拼图结果页关卡详情中的只读引用图横条也使用 `PlatformUploadPreviewCard layout="inline"`，由公共组件承载缩略图、`ResolvedAssetImage` 换签、素材名截断和横向白底条 chrome；只读场景不传 `onRemove`，避免结果页额外出现删除按钮。历史素材弹窗仍使用 `PlatformAssetPickerGrid`，结果页只展示选择后的引用关系。
|
||||
- 2026-06-09 追加：白底平台子面板内的无操作空态使用 `PlatformEmptyState surface="subpanel" size="inline"`，由 Module 承载圆角、边框、`bg-white/74`、居中、字号和 soft 文本色；视觉小说 runtime 历史、属性、存档读取 / 空态已先迁移，业务页不再重复拼白底空态 class。
|
||||
- 2026-06-10 追加：个人中心充值弹窗的“暂无可购买套餐”和每日任务弹窗的“暂无任务”使用 `PlatformEmptyState surface="subpanel" size="inline"`；业务组件只保留数据分支，不再手写 `platform-subpanel rounded-2xl px-4 py-8` 空态 chrome。
|
||||
- 2026-06-10 追加：`PlatformEmptyState` 根节点固定带 `platform-empty-state` 类名，并支持 `surface="editorDark"` 承接 RPG 大编辑器和运行态弹窗 / 面板里的暗色虚线纯展示空态；角色槽位、可选角色、关系、技能、物品、交易空列表、赠礼空列表、招募替换空列表、奖励物品空态、任务日志空态、运行态设置保存禁用提示和营地编组空队列只保留业务文案，不再重复拼 `rounded-2xl border border-dashed border-white/12 bg-black/20 px-4 py-4 text-sm text-zinc-500`、`rounded-xl border border-dashed border-white/10 bg-black/20 px-4 py-6 text-sm text-zinc-500` 或 `rounded-xl border border-dashed border-white/10 bg-black/20 px-3 py-4 text-center text-xs text-zinc-500`。
|
||||
- 2026-06-09 追加：自定义世界实体目录搜索框迁移到 `PlatformTextField density="compact"`，搜索无结果空态迁移到 `PlatformEmptyState surface="dashed"`；目录只保留搜索值、占位符和过滤语义，不再直接拼 `platform-subpanel rounded-2xl` 输入壳或虚线空态。
|
||||
- 2026-06-10 追加：creation-agent 聊天区“暂无消息”迁移到 `PlatformEmptyState surface="subpanel" size="compact"`，composer 文本域迁移到 `PlatformTextField variant="textarea" size="md" density="compact"`；工作台保留消息列表滚动、受控输入、禁用条件、Enter 提交和 Shift+Enter 换行语义，不再手写空态和 textarea chrome。
|
||||
- 2026-06-10 追加：大鱼吃小鱼结果页缺少可编辑草稿提示迁移到 `PlatformEmptyState surface="subpanel" size="compact"`；结果页只保留草稿分支和文案，不再为白底无操作提示手写 `PlatformSubpanel` 空面板。验证命令：`npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx src/components/common/PlatformEmptyState.test.tsx`。
|
||||
- 2026-06-09 追加：视觉小说 runtime 普通白底面板里的保存主按钮和历史重生成行内动作使用 `PlatformActionButton surface="platform"`；保存使用默认主动作，行内重生成使用 `tone="secondary" size="xs" shape="pill"`，业务页只保留图标、禁用条件和回调。
|
||||
- 影响范围：`src/components/common/UnifiedConfirmDialog.tsx`、`src/components/common/useCopyFeedback.ts`、`src/components/common/CopyFeedbackButton.tsx`、`src/components/common/CopyCodeButton.tsx`、`src/components/common/CopyFeedbackMessage.tsx`、`src/components/common/PlatformStatusMessage.tsx`、`src/components/common/PlatformEmptyState.tsx`、`src/components/common/PlatformActionButton.tsx`、`src/components/common/platformActionButtonModel.ts`、`src/components/common/PlatformIconButton.tsx`、`src/components/common/PlatformUploadTile.tsx`、`src/components/common/PlatformUploadPreviewCard.tsx`、`src/components/common/PlatformMediaFrame.tsx`、`src/components/common/PlatformModalCloseButton.tsx`、平台入口壳、公共错误 / 完成 / 分享弹窗、公开详情页、大鱼 runtime / result、账号个人资料区、自定义世界实体目录、RPG 结果页重新生成确认、RPG / 拼图 / 抓大鹅 / 跳一跳 / 敲木鱼 / 拼消消 / 宝贝识物 / 方洞 / 汪汪声浪 / 视觉小说结果页普通按钮和状态提示、历史图片选择弹窗 / RPG 发布检查弹窗 / creative-agent 侧边栏 / creation-agent 参考图 / 敲木鱼结果页 / 拼图结果页普通图标按钮、方洞结果页图片素材弹窗关闭按钮、视觉小说结果页资产 / 音频 / 编辑器弹窗和 runtime 普通面板关闭按钮、统一创作页壳层、拼图创作工作台、拼消消创作工作台、宝贝识物创作工作台、视觉小说创作工作台、汪汪声浪创作工作台、creation-agent 推荐回复、creative-agent 工作台、creative-agent 模板确认弹窗、自定义世界实体目录小动作和状态提示、创作中心错误重试、反馈页 header 返回、认证入口 / 邀请码弹窗关闭按钮、通用生成页重试 / 中断动作、RPG 详情页删除确认、RPG 角色素材工作室泥点确认、RPG 场景编辑器阻断提示、RPG 角色背景章节阻断提示、RPG 编辑器未保存关闭确认、RPG 场景背景 / 作品封面生成退出确认、公开作品深链失效恢复、账户充值 / 泥点账单 / 每日任务 / 兑换码 / 扫码 / 存档 / 玩过作品等个人中心弹窗、RPG 首页 / 公开广场 / 作品架和历史素材选择弹窗空态、个人中心充值 / 任务 / 兑换 / 邀请 / 支付结果弹窗主动作按钮、RPG 作品详情和生成结果恢复面板平台动作按钮、法律信息弹窗 footer、通用创作图片 / 音频输入面板动作按钮和上传 label、统一创作工作台返回 / 生成按钮和错误提示、短信登录 / 密码登录 / 绑定手机号认证表单动作按钮和状态提示、账号安全弹窗动作按钮和状态提示、验证码提示、邀请码弹窗提交按钮和错误提示、错误 / 完成 / 分享弹窗复制按钮外观、结果页 / 工作台后续简单弹窗迁移。
|
||||
- 验证方式：`npm run test -- src/components/common/UnifiedConfirmDialog.test.tsx src/components/common/useCopyFeedback.test.tsx src/components/common/CopyFeedbackButton.test.tsx src/components/common/CopyCodeButton.test.tsx src/components/common/CopyFeedbackMessage.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformActionButton.test.tsx src/components/common/platformActionButtonModel.test.ts src/components/common/PlatformIconButton.test.tsx src/components/common/PlatformUploadTile.test.tsx src/components/common/PlatformUploadPreviewCard.test.tsx src/components/common/PlatformModalCloseButton.test.tsx`，迁移页面时补跑对应页面交互测试；实体目录删除确认、角色背景章节阻断与场景编辑器提示补跑 `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx`；公开作品深链失效恢复补跑 `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "direct missing public work detail"`；RPG 结果页重新生成确认补跑 `npm run test -- src/components/CustomWorldResultView.test.tsx`；RPG 详情页删除 hook 补跑 `npm run test -- src/components/rpg-entry/useRpgEntryAgentDraftRestore.test.tsx`；角色素材工作室泥点确认补跑 `npm run test -- src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx`；个人中心弹窗关闭按钮迁移补跑 `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "wallet ledger|reward code|task center|recharge|save archive|played works"`；认证入口 / 邀请码弹窗关闭按钮迁移补跑 `npm run test -- src/components/auth/AuthGate.test.tsx src/components/common/PlatformModalCloseButton.test.tsx`；RPG 首页 / 公开广场 / 作品架空态迁移补跑 `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "mobile discover|desktop logged in home|profile played works|logged in draft bottom tab|ranking"`；历史素材选择弹窗空态迁移补跑 `npm run test -- src/components/unified-creation/shared/PuzzleHistoryAssetPickerDialog.test.tsx`；结果页普通动作和状态提示迁移补跑 `npm run test -- src/components/puzzle-result/PuzzleResultView.test.tsx`、`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`、`npm run test -- src/components/jump-hop-result/JumpHopResultView.test.tsx src/components/wooden-fish-result/WoodenFishResultView.test.tsx`、`npm run test -- src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/edutainment-result/BabyObjectMatchResultView.test.tsx`、`npm run test -- src/components/square-hole-result/SquareHoleResultView.test.tsx src/components/common/PlatformModalCloseButton.test.tsx`、`npm run test -- src/components/visual-novel-result/VisualNovelResultView.test.tsx`；玩法创作工作台普通动作和错误提示迁移补跑 `npm run test -- src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx src/components/edutainment-creation/BabyObjectMatchWorkspace.test.tsx src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx src/components/bark-battle-creation/BarkBattleResultView.test.tsx src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/creative-agent/CreativeAgentTemplateConfirmPanel.test.tsx`；creation-agent 推荐回复动作迁移补跑 `npm run test -- src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformActionButton.test.tsx src/components/common/platformActionButtonModel.test.ts`；创作中心重试和反馈页返回按钮迁移补跑 `npm run test -- src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/platform-entry/PlatformFeedbackView.test.tsx src/components/common/PlatformActionButton.test.tsx`；通用生成页动作迁移补跑 `npm run test -- src/components/CustomWorldGenerationView.test.tsx src/components/common/PlatformActionButton.test.tsx`；统一创作页壳层补跑 `npm run test -- src/components/unified-creation/UnifiedCreationPage.test.tsx`；拼图创作工作台返回按钮补跑 `npm run test -- src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx`；个人中心主动作按钮迁移补跑 `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recharge|wallet ledger|task center|reward code|invite|community"`；复制弹窗外观迁移补跑 `npm run test -- src/components/platform-entry/PlatformErrorDialog.test.tsx src/components/common/PublishShareModal.test.tsx`；阶段完成前复扫 `rg -n "window\\.confirm|window\\.alert" src/components src/services src/hooks -g '*.tsx' -g '*.ts'`。
|
||||
- 2026-06-09 验证补充：通用输入 Composer 图标按钮迁移补跑 `npm run test -- src/components/creative-agent/CreativeAgentInputComposer.test.tsx src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/common/PlatformIconButton.test.tsx`。
|
||||
- 2026-06-10 验证补充：creative-agent 首页抽屉空态和首页错误提示收口后，补跑 `npm run test -- src/components/creative-agent/CreativeAgentHome.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformStatusMessage.test.tsx`。
|
||||
- 2026-06-10 验证补充：creative-agent 过程面板空态收口到 `PlatformEmptyState surface="subpanel" size="compact"` 后，补跑 `npm run test -- src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/common/PlatformEmptyState.test.tsx`。
|
||||
- 2026-06-10 验证补充：creative-agent 工作台消息空态收口到 `PlatformEmptyState surface="subpanel" size="compact"` 后，补跑 `npm run test -- src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 验证补充：作品详情顶部和封面轮播图标按钮收口补跑 `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformIconButton.test.tsx`。
|
||||
- 2026-06-10 验证补充：作品详情底部启动 / 改造动作收口补跑 `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformActionButton.test.tsx`。
|
||||
- 2026-06-10 验证补充：作品详情点赞按钮收口补跑 `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformActionButton.test.tsx src/components/common/platformActionButtonModel.test.ts`。
|
||||
- 2026-06-10 验证补充：creative-agent 模板确认弹层“关卡数”行内标题收口到 `PlatformFieldLabel variant="inlineForm"` 后，补跑 `npm run test -- src/components/creative-agent/CreativeAgentTemplateConfirmPanel.test.tsx src/components/common/PlatformFieldLabel.test.tsx`。
|
||||
- 2026-06-10 验证补充：平台入口公开编号搜索结果弹层收口到 `UnifiedModal`、`PlatformStatusMessage` 和 `PlatformSubpanel` 后，补跑 `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "public code search"`。
|
||||
- 2026-06-10 验证补充：平台作品详情主题标签和作品号复制 chip 收口后，补跑 `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformPillBadge.test.tsx src/components/common/CopyCodeButton.test.tsx`。
|
||||
- 2026-06-10 验证补充：平台作品详情分享复制反馈按状态映射到 `PlatformStatusMessage surface="platform"` 后，补跑 `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformStatusMessage.test.tsx`。
|
||||
- 2026-06-10 验证补充：大鱼吃小鱼结果页缺草稿空态收口补跑 `npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx src/components/common/PlatformEmptyState.test.tsx`。
|
||||
- 2026-06-10 验证补充：大鱼吃小鱼结果页发布校验阻断项收口补跑 `npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx src/components/common/PlatformStatusMessage.test.tsx`。
|
||||
- 2026-06-09 验证补充：通用输入 Composer 面板、文本域和读图错误状态收口补跑 `npm run test -- src/components/creative-agent/CreativeAgentInputComposer.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 验证补充：creation-agent composer 错误条收口补跑 `npm run test -- src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformStatusMessage.test.tsx`。
|
||||
- 2026-06-09 验证补充：通用创作图片面板历史入口和抓大鹅封面编辑浮动图标按钮收口补跑 `npm run test -- src/components/common/PlatformIconButton.test.tsx src/components/common/CreativeImageInputPanel.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：AI 重绘胶囊开关收口补跑 `npm run test -- src/components/common/PlatformPillSwitch.test.tsx src/components/common/CreativeImageInputPanel.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：白底整行开关收口补跑 `npm run test -- src/components/common/PlatformToggleRow.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：RPG 大编辑器动作按钮收口补跑 `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx -t "保存修改|保存角色"`。
|
||||
- 2026-06-09 验证补充：runtime 白底 HUD 收口补跑 `npm run test -- src/components/wooden-fish-runtime/WoodenFishRuntimeShell.test.tsx src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
|
||||
- 2026-06-09 验证补充：历史素材选择卡片收口补跑 `npm run test -- src/components/common/PlatformAssetPickerCard.test.tsx src/components/unified-creation/shared/PuzzleHistoryAssetPickerDialog.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：RPG 大编辑器历史素材弹窗收口补跑 `npm run test -- src/components/common/PlatformAssetPickerCard.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx`。
|
||||
- 2026-06-09 验证补充：抓大鹅封面编辑可引用素材网格收口补跑 `npm run test -- src/components/common/PlatformAssetPickerCard.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：抓大鹅结果页白底输入框和文本域收口补跑 `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：方洞结果页主信息表单白底输入框和文本域收口补跑 `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：方洞结果页形状 / 洞口选项紧凑输入、文本域和下拉框收口补跑 `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：拼图 / 敲木鱼结果页作品信息输入、拼图关卡名称和智能修订输入收口补跑 `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/wooden-fish-result/WoodenFishResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：通用创作图片输入面板提示词文本域收口补跑 `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/common/CreativeImageInputPanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：创作工作台白底字段输入和焦点色 tone 收口补跑 `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx` 与 `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx src/components/edutainment-creation/BabyObjectMatchWorkspace.test.tsx`。
|
||||
- 2026-06-09 验证补充：白底分段 Tab / 二选一收口补跑 `npm run test -- src/components/common/PlatformSegmentedTabs.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx src/components/match3d-result/Match3DResultView.test.tsx src/components/creative-agent/CreativeAgentTemplateConfirmPanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：抓大鹅难度四选一收口补跑 `npm run test -- src/components/common/PlatformSegmentedTabs.test.tsx src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台统计小卡收口补跑 `npm run test -- src/components/common/PlatformStatGrid.test.tsx src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：自定义世界实体目录搜索框和空态收口补跑 `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformEmptyState.test.tsx`。
|
||||
- 2026-06-10 验证补充：RPG 大编辑器暗色纯展示空态迁移到 `PlatformEmptyState surface="editorDark"` 后，补跑 `npm run test -- src/components/common/PlatformEmptyState.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx -t "可扮演角色空态复用暗色平台空态"`。
|
||||
- 2026-06-10 验证补充：角色聊天错误提示收口到 `PlatformStatusMessage surface="editorDark"` 后，补跑 `npm run test -- src/components/CharacterChatModal.test.tsx src/components/common/PlatformStatusMessage.test.tsx`。
|
||||
- 2026-06-10 验证补充：营地编组战斗中提示、状态数值、分区 / 同行者卡、空队列和替换位按钮分别收口到 `PlatformStatusMessage surface="editorDark"`、`PlatformPillBadge darkNeutral`、`PlatformSubpanel surface="dark" / "darkSky"`、`PlatformEmptyState surface="editorDark"` 和 `PlatformDarkOptionCard` 后，补跑 `npm run test -- src/components/CompanionCampModal.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformDarkOptionCard.test.tsx`。
|
||||
- 2026-06-10 验证补充：自定义选择弹窗错误 / 生成中提示收口到 `PlatformStatusMessage surface="editorDark"` 和 `PlatformProgressBar` 后，补跑 `npm run test -- src/components/SelectionCustomizationModals.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/common/PlatformProgressBar.test.tsx`。
|
||||
- 2026-06-10 验证补充：地图场景切换目标场景面板、当前 / 前往摘要和方向标签收口到 `PlatformSubpanel surface="darkAmber" / "dark"` 与 `PlatformPillBadge dark*` 后，补跑 `npm run test -- src/components/MapModal.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx`。
|
||||
- 2026-06-10 验证补充：RPG 构筑标签效果详情收口到 `CharacterInfoShared.BuildContributionDetailPanel` 和 `PlatformSubpanel surface="dark"` 后，补跑 `npm run test -- src/components/CharacterInfoShared.test.tsx src/components/AdventureEntityModal.test.tsx -t "BuildContributionDetailPanel|技能详情静态标签"`。
|
||||
- 2026-06-10 验证补充：RPG 实体详情弹窗物品空态和技能详情暗色小卡收口后，补跑 `npm run test -- src/components/AdventureEntityModal.test.tsx -t "物品空态|技能详情静态标签"`。
|
||||
- 2026-06-09 验证补充：创作中心作品架空态和加载骨架卡收口补跑 `npm run test -- src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台胶囊状态标签和宝贝识物结果页白底卡片收口补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/edutainment-result/BabyObjectMatchResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台胶囊状态标签扩展到宝贝识物 / 拼图 / 汪汪声浪工作台和结果页 chip 后，补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx src/components/bark-battle-creation/BarkBattleResultView.test.tsx src/components/edutainment-creation/BabyObjectMatchWorkspace.test.tsx src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台胶囊状态标签扩展到视觉小说 / 抓大鹅工作台 BETA chip 后，补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台胶囊状态标签扩展到敲木鱼结果页飘字 chip 后，补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/wooden-fish-result/WoodenFishResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台胶囊状态标签扩展到 creative-agent 过程计数 / 条目 meta chip 后，补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/creative-agent/CreativeAgentWorkspace.test.tsx`。
|
||||
- 2026-06-10 验证补充：实心中性状态胶囊和整行状态开关收口补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/common/PlatformToggleRow.test.tsx`。
|
||||
- 2026-06-10 验证补充：媒体紧凑占位浮层收口补跑 `npm run test -- src/components/common/PlatformOverlayBadge.test.tsx src/components/edutainment-result/BabyObjectMatchResultView.test.tsx`。
|
||||
- 2026-06-10 验证补充：creative-agent 阶段时间线柔和步骤圆点收口补跑 `npm run test -- src/components/common/PlatformSlotBadge.test.tsx src/components/creative-agent/CreativeAgentWorkspace.test.tsx`。
|
||||
- 2026-06-10 验证补充：creative-agent 过程条目柔和图标圆槽收口补跑 `npm run test -- src/components/common/PlatformIconBadge.test.tsx src/components/creative-agent/CreativeAgentWorkspace.test.tsx`。
|
||||
- 2026-06-10 验证补充：creative-agent 模板 / hero / 目标就绪图标圆槽收口补跑 `npm run test -- src/components/common/PlatformIconBadge.test.tsx src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/creative-agent/CreativeAgentTemplateConfirmPanel.test.tsx`。
|
||||
- 2026-06-10 验证补充：创作类型弹层锁定卡小圆锁图标收口补跑 `npm run test -- src/components/common/PlatformIconBadge.test.tsx src/components/platform-entry/PlatformEntryCreationTypeModal.test.tsx`。
|
||||
- 2026-06-10 验证补充：大鱼吃小鱼发布失败弹窗危险图标槽收口补跑 `npm run test -- src/components/common/PlatformIconBadge.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx -t "shows publish failures in a dismissible modal"`。
|
||||
- 2026-06-10 追加：`PlatformIconBadge` 根节点固定带 `platform-icon-badge` 稳定类名；个人中心充值结果弹窗和支付确认遮罩里的 56px 圆形图标槽使用 `PlatformIconBadge size="xl"` 并保留局部 `bg-white/10` 与状态文字色覆盖，支付弹窗不再手写圆形图标容器。验证命令：`npm run test -- src/components/common/PlatformIconBadge.test.tsx`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "confirms virtual payment after returning without hash result|releases submitting state after cancelled wechat pay result"`。
|
||||
- 2026-06-10 验证补充：宝贝识物工作台静态玩法预览卡和图标槽收口补跑 `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformIconBadge.test.tsx src/components/edutainment-creation/BabyObjectMatchWorkspace.test.tsx`。
|
||||
- 2026-06-10 验证补充：通用创作图片面板空主图上传占位图标槽收口补跑 `npm run test -- src/components/common/PlatformIconBadge.test.tsx src/components/common/CreativeImageInputPanel.test.tsx`。
|
||||
- 2026-06-10 验证补充：GameCanvas 宝箱遭遇图标槽收口到 `PlatformIconBadge size="xxl" shape="xl" tone="darkAmber"` 后，补跑 `npm run test -- src/components/common/PlatformIconBadge.test.tsx src/components/game-canvas/GameCanvasEntityLayer.test.tsx`。
|
||||
- 2026-06-10 验证补充：通用创作图片面板按钮内泥点消耗胶囊收口补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/common/CreativeImageInputPanel.test.tsx`。
|
||||
- 2026-06-10 验证补充：抓大鹅创作工作台按钮内泥点消耗胶囊收口补跑 `npm run test -- src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx src/components/common/PlatformPillBadge.test.tsx`。
|
||||
- 2026-06-10 验证补充：标签编辑新增输入行 soft 子面板收口补跑 `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformTagEditor.test.tsx`。
|
||||
- 2026-06-10 验证补充：标签编辑新增输入框收口到 `PlatformTextField` 后，补跑 `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/common/PlatformTagEditor.test.tsx`。
|
||||
- 2026-06-10 验证补充：个人中心昵称弹窗输入框收口后，补跑 `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile nickname modal"` 与 `npm run test -- src/components/common/PlatformTextField.test.tsx`。
|
||||
- 2026-06-10 验证补充：认证图形验证码图片和答案输入分别收口到 `PlatformMediaFrame` 与 `PlatformTextField` 后，补跑 `npm run test -- src/components/auth/CaptchaChallengeField.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformMediaFrame.test.tsx`。
|
||||
- 2026-06-10 验证补充：认证登录、重置密码、绑定手机号、邀请码和账号安全表单字段收口到 `PlatformTextField` 与 `PlatformFieldLabel` 后，补跑 `npm run test -- src/components/auth/AuthGate.test.tsx src/components/auth/AccountModal.test.tsx src/components/auth/BindPhoneScreen.test.tsx src/components/auth/CaptchaChallengeField.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformFieldLabel.test.tsx`。
|
||||
- 2026-06-10 验证补充：通用创作图片输入面板主图 / 提示词字段标题收口到 `PlatformFieldLabel` 后，补跑 `npm run test -- src/components/common/CreativeImageInputPanel.test.tsx src/components/common/PlatformFieldLabel.test.tsx`。
|
||||
- 2026-06-10 验证补充：个人中心存档 / 玩过弹窗简单空态、分区标题和已玩作品按钮卡收口后，补跑 `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "profile played modal|profile page keeps save archives inside played stats panel"`。
|
||||
- 2026-06-10 验证补充：平台入口壳纯 Suspense fallback 收口到 `PlatformSubpanel` 后，补跑 `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/platform-entry/PlatformEntryFlowShellImpl.test.ts`。
|
||||
- 2026-06-10 验证补充：个人中心钱包账单空态和账单行收口后，补跑 `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "wallet ledger"` 与 `npm run test -- src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 验证补充：个人中心邀请弹窗内部卡片、标题和空态收口后，补跑 `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile community shortcut|profile redeem invite"` 与 `npm run test -- src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformFieldLabel.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 验证补充：个人中心任务中心任务条目收口后，补跑 `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile daily task"` 与 `npm run test -- src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 验证补充：个人中心充值弹窗 Native 支付二维码确认面板收口后，补跑 `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile recharge modal shows native qr code"` 与 `npm run test -- src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 验证补充：个人中心兑换码 / 邀请码输入和充值 / 任务空态收口后，补跑 `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformEmptyState.test.tsx -t "reward code|invite query|profile redeem invite|daily task"`。
|
||||
- 2026-06-10 验证补充：背包文书按钮收口到暗色 `PlatformSubpanel`、故事档案 QA 提示收口到 `PlatformStatusMessage surface="editorDark"` 后，补跑 `npm run test -- src/components/InventoryPanel.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformStatusMessage.test.tsx`。
|
||||
- 2026-06-10 验证补充：NPC 叙事提示和交易详情属性格收口后，补跑 `npm run test -- src/components/NpcModals.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformStatusMessage.test.tsx`。
|
||||
- 2026-06-10 验证补充：NPC 暗色可选项按钮卡收口到 `PlatformDarkOptionCard` 后，补跑 `npm run test -- src/components/NpcModals.test.tsx src/components/common/PlatformDarkOptionCard.test.tsx`。
|
||||
- 2026-06-10 验证补充：角色素材工作室动作预览格收口到 `PlatformDarkOptionCard` 后，补跑 `npm run test -- src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx src/components/common/PlatformDarkOptionCard.test.tsx`。
|
||||
- 2026-06-10 验证补充：上传预览横向已选素材条 soft row 子面板收口补跑 `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformUploadPreviewCard.test.tsx`。
|
||||
- 2026-06-10 验证补充：creation-agent 无 session / 加载提示块收口补跑 `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/creation-agent/CreationAgentWorkspace.test.tsx`。
|
||||
- 2026-06-10 验证补充：creation-agent 聊天空态和 composer 文本域收口后，补跑 `npm run test -- src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformTextField.test.tsx`。
|
||||
- 2026-06-10 验证补充：拼图首访 onboarding 提示词文本域、输入错误和登录保存错误收口后，补跑 `npm run test -- src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleOnboardingView.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/common/PlatformTextField.test.tsx`。
|
||||
- 2026-06-10 验证补充：拼图首访 onboarding 生成 / 登录 / 跳过按钮收口到 `PlatformActionButton` 后，补跑 `npm run test -- src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleOnboardingView.test.tsx src/components/common/PlatformActionButton.test.tsx src/components/common/platformActionButtonModel.test.ts`。
|
||||
- 2026-06-10 验证补充：拼图结果页空草稿提示块收口补跑 `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`。
|
||||
- 2026-06-10 验证补充：RPG 个人中心未登录提示子面板收口补跑 `npm run test -- src/components/common/PlatformSubpanel.test.tsx`，并对 `src/components/rpg-entry/RpgEntryHomeView.tsx` 执行 ESLint / typecheck；游客态当前不暴露“我的”Tab，不新增不可达业务断言。
|
||||
- 2026-06-10 验证补充：拼图图库详情页封面轮播壳收口到 `PlatformSubpanel radius="xl" padding="none"` 后，补跑 `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/puzzle-gallery/PuzzleGalleryDetailView.test.tsx`。
|
||||
- 2026-06-10 验证补充：抓大鹅物品详情五视角面板收口到 `PlatformSubpanel radius="xl" padding="sm"` 后，补跑 `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：拼图 / 方洞结果页自动保存 badge 收口补跑 `npm run test -- src/components/puzzle-result/PuzzleResultView.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx src/components/common/PlatformPillBadge.test.tsx`。
|
||||
- 2026-06-09 验证补充：抓大鹅结果页自动保存 / 当前难度 badge 收口补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：拼图结果页关卡生成中 badge 收口补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：大鱼吃小鱼结果页终局 / 发布校验成功 badge 收口补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx`。
|
||||
- 2026-06-10 验证补充：大鱼吃小鱼结果页关卡元信息标签收口补跑 `npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx src/components/common/PlatformPillBadge.test.tsx`。
|
||||
- 2026-06-09 验证补充：宝贝识物占位资源 overlay 和方洞选项删除图标按钮收口补跑 `npm run test -- src/components/edutainment-result/BabyObjectMatchResultView.test.tsx src/components/common/PlatformPillBadge.test.tsx` 与 `npm run test -- src/components/square-hole-result/SquareHoleResultView.test.tsx src/components/common/PlatformIconButton.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台普通进度条收口补跑 `npm run test -- src/components/common/PlatformProgressBar.test.tsx src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/CustomWorldResultView.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx src/components/CustomWorldGenerationView.test.tsx src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx`。
|
||||
- 2026-06-09 验证补充：汪汪声浪结果页草稿摘要 / 素材槽 / 预览卡收口到 `PlatformSubpanel` 后，补跑 `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/bark-battle-creation/BarkBattleResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：跳一跳结果页公开排行榜小卡收口到 `PlatformSubpanel surface="flat"` 后，补跑 `npm run test -- src/components/jump-hop-result/JumpHopResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：汪汪声浪草稿编译小卡、跳一跳排行榜行卡和排行榜空态收口后，补跑 `npm run test -- src/components/bark-battle-creation/BarkBattleResultView.test.tsx src/components/jump-hop-result/JumpHopResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformEmptyState.test.tsx`。
|
||||
- 2026-06-09 验证补充：跳一跳 / 拼消消结果页媒体预览框收口到 `PlatformSubpanel surface="flat" padding="none"` 后，补跑 `npm run test -- src/components/jump-hop-result/JumpHopResultView.test.tsx src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：方洞结果页标准大面板收口到 `PlatformSubpanel radius="xl"` 后，补跑 `npm run test -- src/components/square-hole-result/SquareHoleResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：方洞结果页形状 / 洞口选项卡和缩略图按钮收口后，补跑 `npm run test -- src/components/square-hole-result/SquareHoleResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-10 验证补充：RPG 大编辑器场景背景 / 作品封面生成和封面上传状态提示收口到 `PlatformStatusMessage surface="tinted"` 后，补跑 `npm run test -- src/components/common/PlatformStatusMessage.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx -t "场景图片保存后会同步更新编辑页和场景列表"`。
|
||||
- 2026-06-09 验证补充：creation-agent operation banner 状态外壳收口补跑 `npm run test -- src/components/common/PlatformStatusMessage.test.tsx src/components/creation-agent/CreationAgentWorkspace.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台只读信息块收口补跑 `npm run test -- src/components/common/PlatformInfoBlock.test.tsx src/components/platform-entry/PlatformErrorDialog.test.tsx`。
|
||||
- 2026-06-09 验证补充：汪汪声浪预览卡横向只读信息行收口补跑 `npm run test -- src/components/common/PlatformInfoBlock.test.tsx src/components/bark-battle-creation/BarkBattleResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台白底子面板收口补跑 `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/common/CreativeAudioInputPanel.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/wooden-fish-result/WoodenFishResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：拼消消创作工作台左侧表单面板收口补跑 `npm run test -- src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：抓大鹅创作工作台难度小面板收口补跑 `npm run test -- src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：视觉小说创作工作台画风选择小面板收口补跑 `npm run test -- src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：拼消消结果页白底面板收口补跑 `npm run test -- src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformStatGrid.test.tsx`。
|
||||
- 2026-06-09 验证补充：creative-agent 标准白底面板收口补跑 `npm run test -- src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/creative-agent/CreativeAgentTemplateConfirmPanel.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformStatGrid.test.tsx`。
|
||||
- 2026-06-09 验证补充：creative-agent 模板目录卡和 16:9 预览收口补跑 `npm run test -- src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformMediaFrame.test.tsx`。
|
||||
- 2026-06-10 验证补充：creative-agent 模板确认预览使用 `PlatformMediaFrame surface="soft"` 后，补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/creative-agent/CreativeAgentTemplateConfirmPanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：通用音频输入面板限制标签收口补跑 `npm run test -- src/components/common/CreativeAudioInputPanel.test.tsx src/components/common/PlatformPillBadge.test.tsx`。
|
||||
- 2026-06-09 验证补充：RPG 世界详情页白底信息卡与 section 标题收口补跑 `npm run test -- src/components/rpg-entry/RpgEntryWorldDetailView.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformFieldLabel.test.tsx`。
|
||||
- 2026-06-09 验证补充：大鱼吃小鱼结果页白底卡片收口补跑 `npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformFieldLabel.test.tsx`。
|
||||
- 2026-06-09 验证补充：大鱼吃小鱼结果页白底动作按钮收口补跑 `npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx src/components/common/PlatformActionButton.test.tsx`。
|
||||
- 2026-06-09 验证补充：RPG 结果页开发资产诊断面板收口补跑 `npm run test -- src/components/rpg-creation-result/RpgCreationAssetDebugPanel.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：自定义世界实体目录世界页统计和基本设定收口补跑 `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformStatGrid.test.tsx`。
|
||||
- 2026-06-09 验证补充：自定义世界实体目录场景幕级缩略图收口补跑 `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：自定义世界实体目录卡片媒体框收口补跑 `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformSubpanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：自定义世界实体目录卡片整卡壳和批量选择 badge 收口补跑 `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx`。
|
||||
- 2026-06-10 验证补充：RPG 实体编辑器基本设定 tag 和角色形象参考图 / 状态小卡收口补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/common/PlatformMediaFrame.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台媒体预览框收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：方洞图片查看弹窗媒体框收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：拼消消结果页卡片预览网格收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：宝贝识物结果页素材卡媒体框收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/edutainment-result/BabyObjectMatchResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：视觉小说结果页封面和资产字段媒体框收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：跳一跳结果页地块图集整图媒体框收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/jump-hop-result/JumpHopResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台媒体缩略格网格收口补跑 `npm run test -- src/components/common/PlatformMediaTileGrid.test.tsx src/components/jump-hop-result/JumpHopResultView.test.tsx src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：方洞结果页封面 / 背景点击预览媒体框收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：方洞结果页形状 / 洞口贴图缩略图媒体框收口到 `PlatformMediaFrame surface="none"` 后，补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx`。
|
||||
- 2026-06-10 验证补充：方洞封面 / 背景、拼消消场地底图 / 素材图集、宝贝识物素材卡、跳一跳图集整图和大鱼媒体槽统一收口到 `PlatformMediaFrame surface="none"` 后，补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/edutainment-result/BabyObjectMatchResultView.test.tsx src/components/jump-hop-result/JumpHopResultView.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx`。
|
||||
- 2026-06-10 验证补充：拼图发布封面收口到 `surface="soft"`，拼图关卡列表、视觉小说资产字段和 creative-agent 模板目录卡收口到 `surface="none"` 后，补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx`；业务页面不再直接使用 `PlatformMediaFrame surface="bare"`。
|
||||
- 2026-06-10 验证补充：`PlatformMediaTileGrid` 内部媒体框改用 `surface="none"` 并支持 item `testId`，抓大鹅物品 spritesheet 解析分组迁移后，补跑 `npm run test -- src/components/common/PlatformMediaTileGrid.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-10 验证补充：抓大鹅 UI 素材子 Tab 的背景、UI spritesheet 和物品 spritesheet 主图迁移到 `PlatformMediaFrame surface="none"` 后，补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/common/PlatformMediaTileGrid.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-10 验证补充：拼图图库详情页封面轮播内层媒体框收口到 `PlatformMediaFrame surface="none"` 后，补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/puzzle-gallery/PuzzleGalleryDetailView.test.tsx`。
|
||||
- 2026-06-10 验证补充：`PlatformMediaFrame` 增加 `aspect="auto"`、容器 `ref` 和 `imageProps` 后，RPG 封面上传裁剪操作区 / 裁剪结果、角色素材工作室形象预览和动作静态预览迁移到公共媒体框，补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx -t "作品封面上传会先进入 16:9 裁剪面板再提交到后端"` 与 `npm run test -- src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx`。
|
||||
- 2026-06-10 验证补充：RPG 编辑器场景幕背景预设、技能编辑 fallback 预览、技能列表缩略图和角色编辑顶部形象预览继续收口到 `PlatformMediaFrame` 后，补跑 `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx -t "可扮演角色技能动作状态复用暗色平台胶囊标签|场景编辑器会在场景内展示槽位化多幕配置并保存"`。
|
||||
- 2026-06-10 验证补充：RPG 大编辑器场景幕角色槽位当前角色 / 可选角色面板，以及幕背景预览 / 预设背景面板收口到本地 `EditorInfoPanel` + `PlatformSubpanel surface="dark"` 后，补跑 `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx -t "场景编辑器会在场景内展示槽位化多幕配置并保存"`。
|
||||
- 2026-06-09 验证补充：大鱼吃小鱼素材工坊宽图候选预览收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：拼图发布弹窗封面关卡预览收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：大鱼吃小鱼场地背景竖版预览收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：大鱼吃小鱼关卡主图缩略图收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx`。
|
||||
- 2026-06-10 验证补充：抓大鹅结果页物品素材列表缩略图和详情大图收口补跑 `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：敲木鱼结果页主预览面板和 9:16 叠层预览收口补跑 `npm run test -- src/components/wooden-fish-result/WoodenFishResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformMediaFrame.test.tsx`。
|
||||
- 2026-06-09 验证补充：平台标签编辑器收口补跑 `npm run test -- src/components/common/PlatformTagEditor.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/wooden-fish-result/WoodenFishResultView.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：反馈页上传方块和上传预览收口补跑 `npm run test -- src/components/common/PlatformUploadPreviewCard.test.tsx src/components/common/PlatformUploadTile.test.tsx src/components/platform-entry/PlatformFeedbackView.test.tsx`。
|
||||
- 2026-06-10 验证补充：反馈页查看记录次级动作收口补跑 `npm run test -- src/components/platform-entry/PlatformFeedbackView.test.tsx src/components/common/PlatformActionButton.test.tsx`。
|
||||
- 2026-06-10 验证补充：创作中心作品卡积分激励领取按钮收口补跑 `npm run test -- src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/common/PlatformActionButton.test.tsx src/index.test.ts`。
|
||||
- 2026-06-10 验证补充：UnifiedModal 头部关闭按钮收口到 `PlatformModalCloseButton platformIcon / pixel` 后，补跑 `npm run test -- src/components/common/UnifiedModal.test.tsx src/components/common/PlatformModalCloseButton.test.tsx src/components/common/UnifiedConfirmDialog.test.tsx`。
|
||||
- 2026-06-10 验证补充：上传预览卡右上移除按钮收口到 `PlatformIconButton darkMini` 后，补跑 `npm run test -- src/components/common/PlatformIconButton.test.tsx src/components/common/PlatformUploadPreviewCard.test.tsx`。
|
||||
- 2026-06-10 验证补充：RPG 大编辑器参考图和封面上传入口收口到 `PlatformUploadTile surface="editorDark"`、参考图预览条收口到 `PlatformUploadPreviewCard surface="editorDark"` 后，补跑 `npm run test -- src/components/common/PlatformUploadTile.test.tsx src/components/common/PlatformUploadPreviewCard.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx -t "场景图片保存后会同步更新编辑页和场景列表"`。
|
||||
- 2026-06-10 验证补充：角色素材工作室参考图入口收口到 `PlatformUploadTile surface="editorDark"` 后，补跑 `npm run test -- src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx`。
|
||||
- 2026-06-09 验证补充：敲木鱼工作台新增功德词条虚线入口收口补跑 `npm run test -- src/components/common/PlatformUploadTile.test.tsx src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx`。
|
||||
- 2026-06-09 验证补充：通用创作图片面板参考图缩略图收口补跑 `npm run test -- src/components/common/PlatformUploadPreviewCard.test.tsx src/components/common/CreativeImageInputPanel.test.tsx`。
|
||||
- 2026-06-09 验证补充：抓大鹅封面编辑参考图缩略图收口补跑 `npm run test -- src/components/common/PlatformUploadPreviewCard.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`。
|
||||
- 2026-06-09 验证补充：横向已选参考图条收口补跑 `npm run test -- src/components/common/PlatformUploadPreviewCard.test.tsx src/components/creative-agent/CreativeAgentInputComposer.test.tsx src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformIconButton.test.tsx`。
|
||||
- 2026-06-09 验证补充：拼图结果页关卡引用图横条收口补跑 `npm run test -- src/components/common/PlatformUploadPreviewCard.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`。
|
||||
- 2026-06-10 验证补充：汪汪声浪预览 VS chip 收口到 `PlatformPillBadge` 后，补跑 `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/bark-battle-creation/BarkBattleResultView.test.tsx`。
|
||||
- 2026-06-10 验证补充：拼图结果页智能修订条 / 关卡卡片收口到 `PlatformSubpanel` / `PlatformIconBadge` 后，补跑 `npm run test -- src/components/common/PlatformIconBadge.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformUiKit弹窗组件收口计划-2026-06-08.md`。
|
||||
|
||||
## 2026-06-07 推荐页运行态先封面预载再 ready 渐隐
|
||||
|
||||
- 背景：移动端推荐页上下切换公开作品时，如果运行态和封面资源没有明确准备边界，用户会看到未加载完成的 runtime、黑底闪动，或切卡后反向回弹。
|
||||
- 决策：推荐页拿到推荐作品列表后预加载每个作品的卡片封面、主封面和玩法兜底封面；嵌入 runtime 的启动遮罩必须复用带玩法标签和标题的作品卡面视觉，不能再切到一层单独的纯封面图。作品切换后遮罩接手当前卡面时必须瞬时显示，不允许从旧预览卡面再淡入到同一张卡面；runtime 统一通过 ready 门控等待 run / profile、lazy 组件和 runtime DOM 内图片资源准备完成，ready 返回 true 后再由外层露出游戏画面并只让卡面遮罩渐隐。遮罩层级必须隔离下层 runtime，防止高 z-index HUD、canvas 或子运行态穿透到封面上；ready 前保留无说明文案的加载条 / 动效，不展示“加载中”文案。推荐 rail 切换完成后归零不能走反向过渡动画。
|
||||
- 影响范围：`src/components/rpg-entry/RpgEntryHomeView.tsx`、推荐页 runtime 生命周期、平台玩法链路文档。
|
||||
- 验证方式：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`。
|
||||
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-07 登录态身份边界变更后刷新当前页
|
||||
|
||||
- 背景：推荐页运行态、作品架、个人数据和私有 query 都可能在页面内缓存当前身份；如果登录或退出只改 React 上下文，当前页可能继续拿旧身份的局部状态渲染。
|
||||
- 决策：H5 登录态从未登录变为已登录，或从已登录变为未登录后，前端必须刷新当前页面一次，让平台壳和运行态按新身份重新初始化。普通 access token refresh、账号资料更新、主题或音量设置变化不触发整页刷新。
|
||||
- 影响范围：`src/components/auth/AuthGate.tsx`、平台入口身份初始化、项目基线文档。
|
||||
- 验证方式：`npm run test -- src/components/auth/AuthGate.test.tsx`。
|
||||
- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。
|
||||
|
||||
## 2026-06-07 多端登录以 refresh session 为粒度互不顶号
|
||||
|
||||
- 背景：同一账号在多端登录后，若单设备退出或请求被打到尚未见过该 session 的 api-server 进程，旧设备会被误判为登录态失效。
|
||||
- 决策：普通登录只新增当前设备 refresh session，不撤销其它 active session；`POST /api/auth/logout` 只撤销当前 refresh session，不再提升账号级 `token_version`；`POST /api/auth/logout-all`、改密和重置密码继续吊销全端 session 并提升 `token_version`。api-server 鉴权和 refresh cookie 轮换在本进程工作集未命中 session 时，先从 SpacetimeDB 正式认证表按需刷新一次工作集再复查，支持多实例和滚动重启下的新会话被所有进程识别。
|
||||
- 影响范围：`module-auth` refresh session 语义、`api-server` Bearer 鉴权和 `/api/auth/refresh`、账号安全页多端会话。
|
||||
- 验证方式：`cargo test -p module-auth logout_current_session --manifest-path server-rs/Cargo.toml`、`cargo test -p module-auth refresh_from_snapshot_json_merges_session_created_by_another_process --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server logout_current_device_keeps_other_device_session_alive --manifest-path server-rs/Cargo.toml`。
|
||||
- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
## 2026-06-07 跳一跳排行榜展示名禁止泄露内部身份键
|
||||
|
||||
- 背景：跳一跳排行榜曾在结果页和运行态失败弹窗里直接展示 `playerId` / `user_id`，用户可见内容暴露了内部身份键。
|
||||
- 决策：`jump_hop_leaderboard_entry.player_id` 只作为 SpacetimeDB read model 的去重和 `viewerBest` 匹配字段，HTTP 契约新增并强制使用 `displayName` 作为排行榜展示字段。api-server 出口按账号 `displayName` 补齐展示名；匿名 runtime guest 固定展示“游客玩家”；账号失效或不可解析时展示“失效玩家”；前端排行榜 UI 禁止兜底展示 `playerId` / `user_id`。
|
||||
- 影响范围：`packages/shared/src/contracts/jumpHop.ts`、`server-rs/crates/shared-contracts/src/jump_hop.rs`、`server-rs/crates/api-server/src/jump_hop.rs`、跳一跳结果页和运行态排行榜组件、跳一跳 PRD 与后端契约文档。
|
||||
- 验证方式：`npm run test -- src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx -t "排行榜"`、`npm run test -- src/components/jump-hop-result/JumpHopResultView.test.tsx -t "排行榜"`、`cargo test -p api-server jump_hop_leaderboard_display_name_never_falls_back_to_player_id --manifest-path server-rs/Cargo.toml`。
|
||||
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
## 2026-06-07 generated 图片读取坚持 OSS 源站与签名缓存链路
|
||||
|
||||
- 背景：生成图片如果以完整 OSS 私有 bucket URL 进入前端，浏览器会裸连 OSS 并遇到 403 或绕过现有 `/api/assets/read-url` 签名缓存；同时旧对象缺少 `Cache-Control` 时只能走 `ETag` / `Last-Modified` 协商缓存，容易被误解为需要 api-server 本地磁盘缓存。
|
||||
- 决策：OSS 继续作为 generated 私有资产源站，api-server 只签发短期读 URL，不做本地磁盘静态资源兜底。前端收到同 bucket 的 `https://*.oss-*.aliyuncs.com/generated-*` 地址时，必须先归一为 legacy public path，再复用 `/api/assets/read-url` 和本地 signed URL 缓存。新上传 generated 私有对象默认写入 `Cache-Control: public, max-age=31536000, immutable`，缓存职责交给 OSS 对象头、浏览器 / WebView HTTP 缓存和后续 CDN。
|
||||
- 影响范围：`src/services/assetReadUrlService.ts`、`server-rs/crates/platform-oss`、`shared-contracts` direct upload form fields、`api-server` assets DTO 映射、后端契约文档和开发运维排障口径。
|
||||
- 验证方式：完整 OSS generated URL 应触发 `/api/assets/read-url?legacyPublicPath=...`，同一路径、同一 `refreshKey` 版本且未临近过期时复用本地 signed URL；`platform-oss` 的 `PostObject` policy / form fields 和 `PutObject` 请求头都应包含 immutable `Cache-Control`，且 `PutObject` V4 签名的 `AdditionalHeaders` 包含该普通请求头。
|
||||
- 验证方式：完整 OSS generated URL 应触发 `/api/assets/read-url?legacyPublicPath=...`，同一路径在签名有效期内复用本地 signed URL；`platform-oss` 的 `PostObject` policy / form fields 和 `PutObject` 请求头都应包含 immutable `Cache-Control`，且 `PutObject` V4 签名的 `AdditionalHeaders` 包含该普通请求头。
|
||||
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`server-rs/crates/platform-oss/README.md`。
|
||||
|
||||
## 2026-06-06 小程序微信绑定展示使用原生昵称组件
|
||||
@@ -520,10 +32,10 @@
|
||||
- 验证方式：`npm run test -- src/components/auth/AccountModal.test.tsx`、`cargo test -p platform-auth --manifest-path server-rs/Cargo.toml`、`cargo test -p module-auth --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml wechat_miniprogram`、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
## 2026-06-03 拼消消收敛为 4 关 6x6 与 4-sheet 素材策略
|
||||
## 2026-06-03 拼消消收敛为单关 6x6 与 4-sheet 素材策略
|
||||
|
||||
- 背景：最初 4 关 / 135 次消除 / 单张大 atlas 方案生图数量和空间一致性成本过高，真实 image2 结果容易被布局提示词诱导成带文字、边框或编号的说明图，不适合运行态 1x1 切片。
|
||||
- 决策：拼消消运行态收敛为 4 关 `6x6` 渐进规则：第 1 关目标 15、300 秒、仅 `1x2`；第 2 关目标 20、300 秒、解锁 `1x2/1x3`；第 3 关目标 30、420 秒、解锁 `1x2/1x3/2x2`；第 4 关目标 35、600 秒、解锁全部 `1x2/1x3/2x2/2x3`。目标消除数就是本关实际复合图案组总数，胜利条件永远是消除完本关全部卡牌；棋盘放不下的牌进入顶部准备区，牌不足棋盘格数时保留空格并露出背景图。素材生成仍使用 4 张 `1024x1536` 竖版 sheet，每张按 `4x6`、每格 `256x256` 切片，再由服务端合成 `10x10 / 2560x2560` 最终 atlas。形状配比固定为 `1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`，总计 35 个复合图案组和 95 个 1x1 卡牌切片。
|
||||
- 决策：拼消消运行态收敛为单关 `6x6 / 35 次消除 / 600 秒`，直接解锁 `1x2`、`1x3`、`2x2`、`2x3`；素材生成改为 4 张 `1024x1536` 竖版 sheet，每张按 `4x6`、每格 `256x256` 切片，再由服务端合成 `10x10 / 2560x2560` 最终 atlas。形状配比固定为 `1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`，总计 35 个复合图案组和 95 个 1x1 卡牌切片。
|
||||
- 影响范围：`module-puzzle-clear` 关卡与图案组规划、api-server 拼消消素材生成编排、前端草稿试玩本地 runtime、结果页 atlas 预览、拼消消 PRD / 技术方案 / 平台链路文档。
|
||||
- 验证方式：`cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle_clear --manifest-path server-rs/Cargo.toml -- --nocapture`、`npm run test -- src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`、`npm run test -- src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
|
||||
- 关联文档：`docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md`、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
@@ -532,17 +44,15 @@
|
||||
|
||||
- 背景：拼消消以拼图交换手感为基础，但核心规则从“拼完整单图过关”变为“拼成多个复合图案组后逐个消除”，同时需要顶部补牌、防死局、半锁定局部拼接组和正式统计，不能继续复用拼图运行态规则本体。
|
||||
- 决策：`puzzle-clear` 作为独立玩法域接入，公开作品码前缀固定为 `PC-`；创作链路采用表单 / 图片输入工作台 -> 独立生成页 -> 结果页 -> 试玩 -> 发布 -> 统一作品详情 -> 正式 runtime。领域规则落在 `module-puzzle-clear`，SpacetimeDB 新增 `puzzle_clear_*` 表 / procedure / view，并接入统一 `public_work_gallery_entry` / `public_work_detail_entry`；前端只表现后端 snapshot/action 结果，不把胜负、补牌或消除裁决做成前端事实源。
|
||||
- 补充约束：草稿编译和发布都必须拒绝缺失或 `placeholder` atlas / card assets，不允许后端 facade 或 SpacetimeDB 合成临时素材；正式 runtime 终态事件使用 `run-finished`、`level-failed`，并写入包含 `status`、`level`、`clears`、`clearDelta`、`elapsedMs` 的结果 JSON。
|
||||
- 补充约束：草稿编译和发布都必须拒绝缺失或 `placeholder` atlas / card assets，不允许后端 facade 或 SpacetimeDB 合成临时素材；当前单关正式 runtime 终态事件使用 `run-finished`、`level-failed`，并写入包含 `status`、`level`、`clears`、`clearDelta`、`elapsedMs` 的结果 JSON。
|
||||
- 补充约束：拼消消结果页草稿试玩使用前端本地 `runtimeMode=draft` snapshot，不调用 `/api/runtime/puzzle-clear/runs`，不写正式 run 统计；公开详情和推荐流正式运行继续走后端 `/api/runtime/puzzle-clear/*`，客户端需要区分创作详情 `/api/creation/puzzle-clear/works/{profileId}` 与公开运行态详情 `/api/runtime/puzzle-clear/works/{profileId}`。
|
||||
- 影响范围：`CONTEXT.md`、拼消消 PRD / 技术方案、平台玩法链路文档、`shared-contracts` / `packages/shared`、`api-server`、`spacetime-module`、`spacetime-client`、作品架 / 广场 / 统一作品详情 / runtime 前端分流。
|
||||
- 验证方式：PRD 和技术方案必须覆盖资产槽位、素材工作表风险、切片验证、恢复语义、API 命名空间和验证命令；实现侧至少运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`npm run check:server-rs-ddd`、`npm run typecheck`、`npm run check:encoding`、相关前端测试和 `cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml`。
|
||||
- 关联文档：`docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md`、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
## 2026-06-05 Server-Provision 全程在目标部署 agent 执行且不安装构建链
|
||||
|
||||
- 背景：`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；非 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`。
|
||||
@@ -579,153 +89,6 @@
|
||||
- 验证方式：关闭任一创作入口后，新建创作请求返回 `creation_entry_disabled`；公开作品列表 / 详情 / 启动 / 运行态动作不返回该错误；进入平台首页不弹“平台首页：creation_entry_disabled”；关闭态入口卡显示锁定状态且不显示 `10-20泥点数`。
|
||||
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Draft Generation Shelf 剩余草稿打开 intent 收口
|
||||
|
||||
- 背景：拼图 / 抓大鹅草稿打开 intent 已归入 `platformDraftGenerationShelfModel.ts`，但方洞挑战、大鱼吃小鱼和视觉小说仍在平台壳层内联判断已发布详情、缺 session、active generating、当前结果页和普通草稿恢复。
|
||||
- 决策：继续扩展 `src/components/platform-entry/platformDraftGenerationShelfModel.ts`，新增 `resolveSquareHoleDraftOpenIntent(...)`、`resolveBigFishDraftOpenIntent(...)` 与 `resolveVisualNovelDraftOpenIntent(...)`；平台壳只按 intent 执行 notice seen、详情打开、恢复 session、读取 work detail、清生成态和切 stage 副作用。
|
||||
- 追加决策：跳一跳与敲木鱼草稿打开也归入同一 Draft Generation Shelf Model，新增 `resolveJumpHopDraftOpenIntent(...)` 与 `resolveWoodenFishDraftOpenIntent(...)`；壳层只按 intent 执行已发布详情、失败生成页恢复、持久化 generating 恢复、读取 detail 和敲木鱼失败 fallback stage 副作用。
|
||||
- 影响范围：创作中心作品架打开方洞挑战 / 大鱼吃小鱼 / 视觉小说 / 跳一跳 / 敲木鱼草稿、创作 URL 恢复时强制打开草稿、生成中回到生成页和视觉小说结果页恢复。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`、针对 Draft Shelf Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】DraftGenerationShelfModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-04 Platform Public Code Search matcher / DTO 收口
|
||||
|
||||
- 背景：`resolvePlatformPublicCodeSearchPlan(...)` 已收口公开搜索顺序，但 `PlatformEntryFlowShellImpl.tsx` 仍内联 RPG by-code DTO 构造，以及拼图、大鱼吃小鱼、跳一跳、敲木鱼、宝贝识物、抓大鹅、方洞挑战、视觉小说和汪汪声浪的 `isSame*PublicWorkCode` 匹配、公开可见性过滤与详情卡映射。
|
||||
- 决策：扩展 `src/components/platform-entry/platformPublicCodeSearchModel.ts`，以 `mapRpgPublicCodeSearchDetailToGalleryCard(...)` 和各 `resolve*PublicCodeSearchMatch(...)` 收口 per-play 公开码匹配与 DTO 映射；壳层只保留 gallery 刷新、详情打开、Bark Battle runtime 特例、用户查询和错误归航副作用。`M3D-*` 旧抓大鹅前缀在 `isSameMatch3DPublicWorkCode(...)` 中继续匹配。
|
||||
- 影响范围：平台首页搜索框、初始 `publicWorkCode` 恢复、各玩法公开作品号命中、RPG 公开作品 by-code 详情映射、Bark Battle runtime 内搜索启动。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformPublicCodeSearchModel.test.ts src/services/publicWorkCode.test.ts`、针对搜索 Module / 壳层 / publicWorkCode 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Draft Generation Shelf 草稿打开 intent 收口
|
||||
|
||||
- 背景：`openPuzzleDraft` / `openMatch3DDraft` 在平台壳内重复判断已发布作品、缺 session、ready 未读、失败 notice、active / background 生成中、持久化 generating 和普通草稿恢复，导致壳层继续理解拼图稳定 ID、抓大鹅 notice key 与生成状态优先级。
|
||||
- 决策：扩展 `src/components/platform-entry/platformDraftGenerationShelfModel.ts`，以 `resolvePuzzleDraftOpenIntent(...)` 与 `resolveMatch3DDraftOpenIntent(...)` 返回纯打开计划和 notice keys；壳层只按 intent 执行网络读取、生成态 rebase、试玩启动、错误写入、路由 / stage 和 notice seen 副作用。
|
||||
- 影响范围：创作中心作品架打开拼图 / 抓大鹅草稿、公开码搜索强制打开抓大鹅草稿、生成完成后 ready 未读试玩、失败草稿恢复和后续 pending / persisted generating 判定。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`、针对 Draft Shelf Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】DraftGenerationShelfModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-04 Bark Battle Work Cache 草稿状态收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 仍内联维护 Bark Battle 草稿三图完整性、生成状态归一、作品架摘要恢复草稿配置，以及草稿 / 已发布作品进入 runtime 前的 `BarkBattlePublishedConfig` 字段映射，导致结果页试玩、作品架启动、草稿恢复和公开详情启动都要理解同一份资产字段清单。
|
||||
- 决策：扩展 `src/components/platform-entry/barkBattleWorkCache.ts`，以 `hasBarkBattleDraftRequiredImages`、`resolveBarkBattleDraftGenerationStatus`、`buildBarkBattleDraftConfigFromWorkSummary`、`buildBarkBattlePublishedConfigFromDraft`、`buildBarkBattlePublishedConfigFromWork`、`buildBarkBattlePublishSnapshot` 和 `mergeBarkBattlePublishedConfigAssets` 收口 Bark Battle 纯规则。平台壳只保留 API、缓存刷新、React state、URL 和 stage 副作用。
|
||||
- 影响范围：Bark Battle 草稿生成完成、结果页保存、作品架摘要恢复草稿、草稿试玩、作品架 / 公开详情启动正式 runtime，以及后续 Bark Battle 资产字段或 ruleset 默认值调整。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/barkBattleWorkCache.test.ts`、针对 Bark Battle Work Cache Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】BarkBattleWorkCache草稿状态收口计划-2026-06-04.md`。
|
||||
|
||||
## 2026-06-04 Platform Recommend Runtime Auth Model 收口
|
||||
|
||||
- 背景：平台推荐 runtime 的 embedded 启动需要在匿名 Runtime Guest Token、已登录 background auth 和非 embedded 默认鉴权之间分流，拼图还额外维护 `isolated` / `default` runtime auth mode；旧规则散在顶层 helper 与多个启动 callback。
|
||||
- 决策：新增 `src/components/platform-entry/platformRecommendRuntimeAuthModel.ts`，以 `resolvePlatformRecommendRuntimeAuthPlan(input)` 和 `shouldUsePlatformRecommendRuntimeGuestAuth(input)` 收口纯鉴权计划。壳层仍负责读取 `getStoredAccessToken()`、申请 `ensureRuntimeGuestToken()`、拼装 request options 和写入拼图 runtime auth mode。
|
||||
- 影响范围：推荐 Tab 内嵌 runtime 启动、拼图公开详情 isolated 入口、推荐运行态后续 action 的局部鉴权口径，以及后续新增可嵌入推荐 runtime 的玩法。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformRecommendRuntimeAuthModel.test.ts`、针对新 Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformRecommendRuntimeAuthModel收口计划-2026-06-04.md`。
|
||||
|
||||
## 2026-06-04 Platform Recommend Runtime Auto Start 收口
|
||||
|
||||
- 背景：推荐 runtime 自动启动 effect 同时判断桌面断点、stage、Tab、loading、推荐列表、active entry、ready 状态和启动中状态，导致壳层 effect 依赖过长且混合推荐流状态机知识。
|
||||
- 决策：扩展 `src/components/platform-entry/platformPublicGalleryFlow.ts`，新增 `resolvePlatformRecommendRuntimeAutoStartDecision(input)`，只返回 `noop`、`clear` 或 `start(entry)`。平台壳只执行清空 active runtime state 或调用 `selectRecommendRuntimeEntry(entry)`。
|
||||
- 影响范围：移动端首页推荐 runtime 自动启动、推荐列表为空时清空状态、active entry ready 判定，以及后续新增推荐 runtime 玩法的启动时机。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformPublicGalleryFlow.test.ts`、针对 Flow Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformRecommendRuntimeAutoStart收口计划-2026-06-04.md`。
|
||||
|
||||
## 2026-06-04 Platform Creation Launch Model 收口
|
||||
|
||||
- 背景：平台创作入口点击回调曾在 `PlatformEntryFlowShellImpl.tsx` 内联判断 `airp` 占位、隐藏的 `baby-object-match`、未知入口和各玩法工作台启动目标，壳层同时承接入口 ID 规则、启动前准备顺序和副作用。
|
||||
- 决策：新增 `src/components/platform-entry/platformCreationLaunchModel.ts`，以 `resolvePlatformCreationLaunchIntent({ type, isBabyObjectMatchVisible })` 收口创作入口启动意图。`airp` 返回 `noop` 且不触发 `prepareCreationLaunch()`；隐藏 `baby-object-match` 返回 blocked intent 且仍在 prepare 后显示 `EDUTAINMENT_HIDDEN_MESSAGE`；未知入口保持旧语义，先 prepare 后 no-op；已知入口返回稳定 launch target。壳层只执行 prepare、错误提示和 `runProtectedAction(...)`。
|
||||
- 影响范围：底部加号创作入口模板卡点击、入口可见性拦截、后续新增可启动模板的 launch target 接入。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformCreationLaunchModel.test.ts`、针对新 Module 与壳层执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformCreationLaunchModel收口计划-2026-06-04.md`。
|
||||
|
||||
## 2026-06-04 Platform Selection Stage Model 收口
|
||||
|
||||
- 背景：平台入口在受保护数据失效后会清空当前用户私有作品、草稿、运行态和生成状态，但哪些 `SelectionStage` 可保留、哪些必须回首页曾以内联长否定串散在 `PlatformEntryFlowShellImpl.tsx`。
|
||||
- 决策：新增 `src/components/platform-entry/platformSelectionStageModel.ts`，以 `resolveSelectionStageAfterProtectedDataLoss(stage)` 收口受保护数据失效后的 stage 去留判定。模型内部使用 `satisfies Record<SelectionStage, boolean>` 全量分类，新增 stage 时必须明确保留或回首页。壳层仍负责检测权限变化、清 state 和调用 `setSelectionStage`。
|
||||
- 追加决策：缺失草稿 / 作品 / run 时的阶段回退也归入 `platformSelectionStageModel.ts`，由 `resolveSelectionStageAfterMissingCreationState(params)` 统一判断 big-fish、match3d、square-hole、visual-novel 和 baby-object-match 的 result / runtime / gallery-detail 是否还能被当前状态支撑。壳层只汇总布尔事实并按输出 stage 跳转；big-fish、match3d、square-hole 的草稿事实固定来自 `Boolean(session?.draft)`，visual-novel 的 session draft 与 work draft 可独立支撑结果页，baby-object-match runtime 缺 draft 时直接回首页。
|
||||
- 影响范围：退出登录、鉴权上下文收回、平台入口公开页 / 工作台 / 结果页 / 生成页 / 运行态的阶段恢复规则，以及后续新增 `SelectionStage`。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformSelectionStageModel.test.ts`、针对新 Module 与壳层执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformSelectionStageModel收口计划-2026-06-04.md`。
|
||||
|
||||
## 2026-06-04 Creation Work Delete Flow 收口
|
||||
|
||||
- 背景：平台入口作品架删除入口在 RPG、拼图、抓大鹅、方洞挑战、大鱼吃小鱼、视觉小说和宝贝识物 handler 内重复计算确认标题、删除说明、草稿 notice key 与拼图派生稳定 ID，导致删除确认规则散在巨型壳层。
|
||||
- 决策：新增 `src/components/platform-entry/platformCreationWorkDeleteFlow.ts`，以 `resolvePlatformCreationWorkDeleteConfirmationModel(input)` 收口作品架删除确认纯模型；输出 `id/title/detail/noticeKeys`。`PlatformEntryFlowShellImpl.tsx` 仍作为副作用 Adapter，保留删除 API、刷新作品架 / 公开广场、错误状态、`markDraftNoticeSeen` 和页面跳转。
|
||||
- 影响范围：创作中心作品架删除确认弹窗、删除后生成 notice 清理、拼图稳定 result ID 清理、宝贝识物已发布删除说明，以及后续新增玩法作品架删除接入。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformCreationWorkDeleteFlow.test.ts`、`npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`、针对新 Module 与平台壳执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】CreationWorkDeleteFlow收口计划-2026-06-04.md`。
|
||||
|
||||
## 2026-06-03 平台入口公开作品详情 Strategy 收口
|
||||
|
||||
- 背景：平台壳层直接判断公开作品详情入口的玩法类型、是否需要补读完整详情，以及自有作品按钮显示“编辑”还是“改造”，导致统一作品详情的纯决策散落在巨型 Implementation 内。
|
||||
- 决策：新增 `src/components/platform-entry/platformPublicWorkDetailFlow.ts`，以 `getPlatformPublicWorkDetailKind`、`resolvePlatformPublicWorkDetailOpenStrategy`、`resolvePlatformPublicWorkActionMode`、`resolvePlatformPublicWorkDetailOpenDecision` 和 `resolveActivePlatformPublicWorkAuthorEntry` 收口公开作品详情 Strategy。`PlatformEntryFlowShellImpl.tsx` 只按 Strategy 调用现有详情读取 / 直接展示 Adapter，并保留作者请求竞态控制；启动、点赞、remix 和编辑副作用不搬入 Module。
|
||||
- 追加决策：公开详情 entry 映射与公开详情反推玩法 work 摘要也归入 `platformPublicWorkDetailFlow.ts`，包括 RPG、拼图、大鱼吃小鱼、方洞挑战、视觉小说、跳一跳、敲木鱼和汪汪声浪的通用映射。抓大鹅 `mapMatch3DWorkToPublicWorkDetail` 归入 `platformMatch3DRuntimeProfile.ts`，继续委托 `normalizeMatch3DWorkForRuntimeUi` 做素材归一和背景资产提升，避免把 Match3D 运行态规则复制到公开详情 Flow Module。
|
||||
- 追加决策：拼图公开详情封面解锁数由 `resolveVisiblePuzzleDetailCoverCount(entry, run)` 收口；非拼图、无当前 run 或 run 不匹配当前公开详情时只展示首图，匹配当前公开详情时按 `clearedLevelCount + 1` 解锁且至少为 1。`PlatformWorkDetailView` 只接收 `visibleCoverCount` 展示，不读取 run。
|
||||
- 追加决策：公开详情点赞能力矩阵由 `resolvePlatformPublicWorkLikeIntent(entry)` 收口；Module 只返回大鱼吃小鱼、拼图、旧 RPG gallery fallback 或不可用文案，壳层仍执行鉴权、API 调用、缓存同步、错误展示和 busy 状态。
|
||||
- 追加决策：公开详情改造能力矩阵由 `resolvePlatformPublicWorkRemixIntent(entry)` 收口；Module 只返回大鱼吃小鱼、拼图、旧 RPG gallery fallback 或不可用文案，壳层仍执行鉴权、remix API、session / 缓存写入、stage 切换、错误展示和 busy 状态。
|
||||
- 追加决策：公开详情启动分流由 `resolvePlatformPublicWorkStartIntent(entry, deps)` 收口；Module 只返回大鱼吃小鱼、拼图、跳一跳、敲木鱼、抓大鹅、方洞挑战、视觉小说、汪汪声浪、宝贝识物或旧 RPG gallery 记录游玩的 intent。壳层仍执行登录保护、运行态启动、RPG 游玩记录、详情更新、busy 状态和错误展示；抓大鹅 public detail -> work mapper 作为 Adapter 注入，继续由 Match3D Runtime Profile Module 维护素材归一与背景资产提升。
|
||||
- 追加决策：自有公开作品编辑分流由 `resolvePlatformPublicWorkEditIntent(entry, deps)` 收口；Module 只返回可编辑草稿目标、需解析宝贝识物本地草稿 intent、旧 RPG gallery 编辑 intent 或原阻断文案。壳层仍执行登录保护、草稿恢复、宝贝识物异步草稿解析、RPG 编辑导航和错误展示；抓大鹅 public detail -> work mapper 仍作为 Adapter 注入，不复制 Match3D 素材归一规则。
|
||||
- 影响范围：统一作品详情入口、公开详情打开策略、自有公开作品编辑 / 改造动作模式，以及后续新增玩法公开详情接入。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformPublicWorkDetailFlow.test.ts`、`npm run test -- src/components/platform-entry/platformMatch3DRuntimeProfile.test.ts`、公开详情壳层交互回归、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformPublicWorkDetailFlow收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 平台入口弹窗状态规则收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 曾同时持有平台级错误 / 完成弹窗的文案归一、来源格式、候选择一、dismiss key、后台生成 still-running 识别和任务完成文案，导致壳层 Interface 偏浅，测试面不稳定。
|
||||
- 决策：新增 `src/components/platform-entry/platformDialogStateModel.ts` 作为 Platform Dialog State Module，统一导出 `normalizePlatformDialogMessage`、`formatPlatformDialogSource`、`resolvePlatformErrorDialog`、dismiss key builder、`resolveActivePlatformDialog`、`isBackgroundGenerationStillRunningMessage` 和 `PLATFORM_TASK_COMPLETION_MESSAGE`。平台壳只汇总候选、持有 React state，并在关闭弹窗时作为 Adapter 清理对应副作用 setter。
|
||||
- 影响范围：平台入口错误弹窗、任务完成弹窗、后台生成仍在处理识别、草稿生成完成 / 失败通知。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformDialogStateModel.test.ts`、`npm run test -- src/components/platform-entry/PlatformErrorDialog.test.tsx`、相关壳层交互测试、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformDialogStateModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 前端 SSE 客户端传输层统一收口
|
||||
|
||||
- 背景：创作 Agent、创意互动 Agent、视觉小说运行态和微信充值订单状态等多个前端 client 曾各自手写 SSE 边界扫描、`TextDecoder` 解码、JSON 解析和流结束 flush，导致 CRLF / LF、UTF-8 尾部、多行 `data:` 和提前停止释放 reader 的处理容易漂移。
|
||||
- 决策：前端 SSE 传输层统一使用 `src/services/sseStream.ts`；`readSseStream` 负责事件边界、解码 flush、多行 data 和提前停止取消 reader，`readSseJsonStream` 负责 JSON object 事件解析与异常 JSON 静默跳过。业务 client 只保留领域事件归一化、结果聚合和中文错误文案，OpenAI 兼容文本流通过 `readSseStream` 处理 `[DONE]` 哨兵，后续不得复制 `findSseEventBoundary`、`parseSseEventBlock` 或手写 reader 循环。
|
||||
- 影响范围：`src/services/sseStream.ts`、`src/services/aiService.ts`、`src/services/llmClient.ts`、`src/services/creation-agent/creationAgentSse.ts`、`src/services/creative-agent/creativeAgentSse.ts`、`src/services/visual-novel-runtime/visualNovelRuntimeSse.ts`、`src/services/rpg-entry/rpgProfileClient.ts`、前端 SSE 相关测试与架构文档。
|
||||
- 验证方式：`npm run test -- src/services/sseStream.test.ts src/services/llmClient.test.ts src/services/creation-agent/creationAgentSse.test.ts src/services/creative-agent/creativeAgentSse.test.ts src/services/visual-novel-runtime/visualNovelRuntimeSse.test.ts src/services/rpg-entry/rpgProfileClient.test.ts src/services/ai.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 `npx eslint ... --max-warnings 0` 通过。
|
||||
- 关联文档：`docs/technical/【前端架构】SSE客户端传输层收口约定-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 平台入口公开作品流身份规则收口
|
||||
|
||||
- 背景：平台入口公开作品推荐流需要同时处理 RPG、拼图、抓大鹅、跳一跳、敲木鱼、视觉小说、Bark Battle、宝贝识物等卡片，公开作品身份、跨玩法去重、排序和推荐运行态 kind 判定曾放在 `PlatformEntryFlowShellImpl.tsx` 巨型实现里。
|
||||
- 决策：公开作品身份、排序规则、公开作品流聚合矩阵、推荐 runtime 启动意图和 ready 判定统一收口到 `src/components/platform-entry/platformPublicGalleryFlow.ts`；入口壳层只调用该 Module 的 `getPlatformPublicGalleryEntryKey`、`getPlatformRecommendRuntimeKind`、`buildPlatformPublicGalleryFeeds`、`resolvePlatformRecommendRuntimeStartIntent`、`isPlatformRecommendRuntimeReadyForEntry`、`isSamePlatformPublicGalleryEntry` 和 `mergePlatformPublicGalleryEntries`。`edutainment` key 必须带 `templateId`，RPG 卡片回退为 `rpg`。公开作品流聚合负责 featured / latest、玩法可见性 gate、汪汪声浪 works fallback 和首屏 `slice(0, 6)`；推荐 runtime 启动 intent 只返回启动目标、`embedded` / `returnStage` 参数、阻断文案和错误落点；ready 判定只接布尔值与拼图 profile id，避免把各玩法 run snapshot 类型拖入 Module。壳层仍执行 request key、运行态 API、错误 setter 与 UI 状态。
|
||||
- 影响范围：平台入口推荐流、最新公开作品流、公开作品详情、推荐 runtime 启动、跨玩法公开作品合并，以及后续新增玩法的入口接入。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformPublicGalleryFlow.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
|
||||
- 关联文档：`docs/technical/【前端架构】平台入口PublicGalleryFlowModule收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Work Shelf 打开动作交由 item Adapter
|
||||
|
||||
- 背景：`creationWorkShelf.ts` 已经为每个 `CreationWorkShelfItem` 生成 `actions.open`，但 `CustomWorldCreationHub.tsx` 点击卡片后仍按 `item.source.kind` 重复分发 RPG、拼图、抓大鹅、方洞、跳一跳、敲木鱼、视觉小说、Bark Battle 和宝贝识物的打开逻辑。
|
||||
- 决策：`CreationWorkShelfItem.actions.open` 作为作品架打开动作的正式 Interface；Hub 只保留 `onOpenShelfItem` 通知和 `item.actions.open()` 调用，不再读取玩法 kind 做打开分支。`buildCreationWorkShelfItemsFromSources` 与 `CreationWorkShelfSourceAdapter` 作为 source registry Interface，统一执行 flatten、运行态覆盖、持久化生成态兜底和更新时间排序；旧 `buildCreationWorkShelfItems` 保留兼容，但内部改为组装 source adapters。
|
||||
- 影响范围：创作中心作品架卡片点击、作品架动作 Adapter、source registry、后续新增玩法作品架接入。
|
||||
- 验证方式：`npm run test -- src/components/custom-world-home/creationWorkShelf.test.ts src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
|
||||
- 关联文档：`docs/technical/【前端架构】WorkShelfModule收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Runtime Client Family 请求骨架收口
|
||||
|
||||
- 背景：Match3D、SquareHole、Puzzle、Jump Hop 等 runtime client 重复手写 path segment 编码、JSON header / body、runtime guest token、auth options 和 retry options，新增玩法容易遗漏同一请求骨架。
|
||||
- 决策：新增 `src/services/runtimeRequest.ts`，以 `buildRuntimeApiPath` 统一 runtime path 编码，以 `requestRuntimeJson` 统一 JSON 请求、runtime guest auth 和 retry 合并。Match3D 与 SquareHole runtime client 已先迁移，保留原导出函数名、错误文案、返回契约和重试常量。
|
||||
- 追加决策：Big Fish 与 Bark Battle runtime client 也迁入 `runtimeRequest.ts`；玩法专属 payload 归一化（如 Bark Battle start / finish 自动补 `workId`、`runId`）仍留在各玩法 client，通用 Module 只承接请求骨架。
|
||||
- 追加决策：Puzzle 的 start / get / swap / drag / next-level / leaderboard / pause / props 与 Jump Hop 的 start / jump / restart 也迁入 `runtimeRequest.ts`；只要调用方传入 Runtime Guest Token，所有正式 runtime 请求都统一带局部 Authorization、`skipAuth` 与 `skipRefresh`。
|
||||
- 追加决策：Wooden Fish 的 start / checkpoint / finish 与 Visual Novel 的 gallery / run / history / regenerate JSON 请求也迁入 `runtimeRequest.ts`；Wooden Fish 的 `clientEventId` 生成仍留在木鱼 client，Visual Novel start 因 `timeoutMs`、SSE 因流式 `fetchWithApiAuth` 仍暂留原实现。
|
||||
- 影响范围：`src/services/runtimeRequest.ts`、Match3D / SquareHole / Big Fish / Bark Battle / Puzzle / Jump Hop / Wooden Fish / Visual Novel runtime client。
|
||||
- 验证方式：`npm run test -- src/services/runtimeRequest.test.ts src/services/recommendedRuntimeGuestLaunch.test.ts src/services/match3d-runtime/match3dRuntimeAdapter.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
|
||||
- 关联文档：`docs/technical/【前端架构】RuntimeClientFamily收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Public Gallery ViewModel 收口
|
||||
|
||||
- 背景：`RpgEntryHomeView.tsx` 巨型页面内混合了公开作品分类、跨来源去重、搜索归一化、作品号匹配、时间戳解析和排序规则，新增玩法时页面与 ViewModel 规则容易纠缠。
|
||||
- 决策：新增 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，把 `buildPublicGalleryCardKey`、`buildPublicCategoryGroups`、`getPlatformPublicEntries`、`getAllPlatformPublicEntries`、`getPlatformSearchableWorkIds`、`filterPlatformWorkSearchResults`、`isExactPublicWorkCodeSearch`、`filterTodayPublishedEntries`、公开卡片指标 getter、`buildPlatformRankingEntries`、`getPlatformRankingMetricValue`、`getPlatformCategoryKindFilter`、`matchesPlatformCategoryKindFilter`、`sortPlatformCategoryEntries`、`getPlatformCategoryPrimaryMetric`、`parsePlatformEntryTimestamp` 和 `getPlatformWorldTimestamp` 收口为公开作品 ViewModel Interface。公开作品 key 复用平台入口身份规则，补齐 jump-hop / wooden-fish 等玩法区分。
|
||||
- 影响范围：RPG 首页公开作品发现、分类、搜索、排行数据准备，以及后续新增玩法公开卡片接入。
|
||||
- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
|
||||
- 关联文档：`docs/technical/【前端架构】PublicGalleryViewModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Profile Task ViewModel 收口
|
||||
|
||||
- 背景：`RpgEntryHomeView.tsx` 同时持有每日任务卡片和任务中心弹窗的任务选择、进度 clamp、奖励兜底、状态标签和按钮文案，导致任务展示规则和 JSX 缠在一起。
|
||||
- 决策：新增 `src/components/rpg-entry/rpgEntryProfileTaskViewModel.ts`，把 `selectProfileTaskCenterTasks`、`selectProfileTaskCardTask`、`buildProfileTaskCardSummary`、`buildProfileTaskProgressLabel`、`getProfileTaskStatusLabel` 和 `getProfileTaskClaimButtonLabel` 收口为每日任务 ViewModel Interface。任务中心仍只展示一条 claimable / incomplete 优先任务，任务卡按可操作、claimed、非 disabled 的顺序兜底。
|
||||
- 影响范围：RPG 首页“每日任务”卡片、任务中心弹窗、后续任务状态和任务展示文案调整。
|
||||
- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryProfileTaskViewModel.test.ts`、`npm run typecheck`、`npm run check:encoding`、相关文件 ESLint 通过。
|
||||
- 关联文档：`docs/technical/【前端架构】ProfileTaskViewModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 最近创作只复用创作模板入口
|
||||
|
||||
- 背景：底部加号创作入口的“最近创作”最初由真实作品架摘要驱动，但页面曾按作品标题、摘要和生成状态渲染独立最近创作卡，和其它模板页签的卡片样式及点击语义不一致。
|
||||
@@ -853,7 +216,7 @@
|
||||
## 2026-05-25 抓大鹅运行态 HUD 收敛为拼图同款低遮挡样式
|
||||
|
||||
- 背景：抓大鹅游玩阶段 UI 需要继续对齐拼图运行态的观感，同时移除右上角设置入口、灰白半透底板和显眼锅壳，让棋盘区域更专注。
|
||||
- 决策：抓大鹅运行态只保留左上透明返回按钮，右上不再显示设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板、同造型和 `media/logo-runtime-hud.webp` 产品 logo 小图；底部备选栏和道具图标保持交互边界但不再显示灰白半透底；中央容器图层可以视觉隐藏，但棋盘命中边界和既有交互逻辑保留。
|
||||
- 决策：抓大鹅运行态只保留左上透明返回按钮，右上不再显示设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板、同造型和 `media/logo.png` 产品 logo；底部备选栏和道具图标保持交互边界但不再显示灰白半透底；中央容器图层可以视觉隐藏，但棋盘命中边界和既有交互逻辑保留。
|
||||
- 影响范围：`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.test.tsx`、`src/index.css`、抓大鹅玩法链路文档。
|
||||
- 验证方式：运行态页面不再渲染“打开抓大鹅设置”，顶部仍显示关卡名和倒计时，底部槽位和道具按钮 class 中不含旧白底视觉；相关测试通过后保持该口径。
|
||||
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
@@ -885,9 +248,9 @@
|
||||
## 2026-05-26 推荐页拼图下一关 pending 时保留当前运行态
|
||||
|
||||
- 背景：推荐页嵌入拼图在点击“下一关”时，`advancePuzzleNextLevel` 的服务端请求会短暂处于 pending。旧逻辑把推荐卡的 `isStartingRecommendEntry` 和拼图局部 busy 混在一起，导致外层直接切回“加载中...”，把当前 `PuzzleRuntimeShell` 一起卸载，视觉上像是切关闪回。
|
||||
- 决策：推荐页嵌入拼图切关 pending 期间必须保留当前运行态与棋盘，只让拼图壳内部 busy 表现承接同步；`isStartingRecommendEntry` 只表示推荐作品尚未真正启动出来，不再把已有嵌入拼图 run 的局部 busy 一并当成整卡加载态。若下一关落到相似作品，前端还必须把新作品写回推荐缓存并同步 `activeRecommendEntryKey`，避免运行态进入新作品但推荐卡元信息、分享 / 点赞 / 改造和后续“下一个”仍锚定旧作品。
|
||||
- 决策：推荐页嵌入拼图切关 pending 期间必须保留当前运行态与棋盘，只让拼图壳内部 busy 表现承接同步；`isStartingRecommendEntry` 只表示推荐作品尚未真正启动出来，不再把已有嵌入拼图 run 的局部 busy 一并当成整卡加载态。推荐页拼图“下一关”必须走推荐页统一相邻作品切换流程，前端不得传递 `preferSimilarWork`，也不得让拼图 runtime 自己把当前 run handoff 到其它作品。
|
||||
- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、推荐页拼图切关测试与平台链路文档。
|
||||
- 验证方式：点击推荐页拼图“下一关”后，在 `advancePuzzleNextLevel` 未返回前，页面仍应保留 `puzzle-board`，且不出现 `加载中...` 占位；返回相似作品后，当前推荐卡的 `作品信息` 应显示新作品标题。
|
||||
- 验证方式：点击推荐页拼图“下一关”后，页面先保留 `puzzle-board`，且不出现 `加载中...` 占位；随后应调用推荐页统一下一作品启动逻辑，而不是调用 `advancePuzzleNextLevel(...)`。
|
||||
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-05-24 创作入口页 banner 曾固定主题赛
|
||||
@@ -926,6 +289,7 @@
|
||||
|
||||
- 背景：创作页顶部、banner 奖池和玩法卡消耗口径曾经混在一起，容易把活动奖池误认成账号余额，也让横向空间被外部边框和过大的卡片高度挤占。
|
||||
- 决策：移动端创作 Tab 顶栏与 `陶泥儿` 品牌同一行只显示真实账户泥点数，数据直接取 `profileDashboard.walletBalance`；banner 内只展示赛事奖池，新增拼图主题创作赛和抓大鹅主题创作赛，两个主题奖池各 `1000` 泥点数；玩法卡封面右下角固定展示 `10-20泥点数`，列表外框取消，卡片高度和横向间距一起收紧。
|
||||
- 追加决策：创作页和草稿页顶栏右上泥点余额胶囊是补足泥点入口；当前环境开启充值入口时直接打开账户充值弹窗，否则打开运营兑换码弹窗，不再跳到账户面板或泥点账单。
|
||||
- 影响范围：`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、创作页相关测试和玩法链路文档。
|
||||
- 验证方式：移动端浏览器检查应看到创作顶栏余额、卡内分页点、内嵌横向 banner 和更紧凑的玩法卡；`CustomWorldCreationHub.test.tsx` 与 `RpgEntryHomeView.recharge.test.tsx` 的定向断言应保持通过。
|
||||
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
@@ -1144,7 +508,7 @@
|
||||
|
||||
## 2026-05-19 生产 provision 改为 Windows 下载包后由目标机本地安装
|
||||
|
||||
- 后续更新：该口径已被 `2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost` 取代；当前 `Genarrative-Server-Provision` 不再走 Windows 下载阶段，而是在 Linux build 节点直接准备 `provision-tools/`。
|
||||
- 后续更新：该口径先被 2026-06-01 Linux 优先方案取代，又在 2026-06-05 被 Server-Provision 专用口径覆盖；当前 `Genarrative-Server-Provision` 不走 Windows 下载阶段，也不在 Linux build 节点中转工具包，而是在目标 dev / release agent 内准备 `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 脚本被立即重写时触发 `拒绝访问`。
|
||||
@@ -1209,7 +573,7 @@
|
||||
- 验证方式：`cargo test -p module-custom-world publish_setting_text --manifest-path server-rs\Cargo.toml`；`cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml`；本地 api-server 重启后检查 `/healthz`。
|
||||
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`.hermes/shared-memory/pitfalls.md`。
|
||||
|
||||
## 2026-05-19 系列素材 n\*n 图集抽为 api-server 通用模块
|
||||
## 2026-05-19 系列素材 n*n 图集抽为 api-server 通用模块
|
||||
|
||||
- 背景：抓大鹅物品 sheet 已包含 prompt 组装、固定网格切图、绿幕 / 近白底透明化、切片 PNG 持久化和 prompt 追踪；继续留在 Match3D 私有模块会让跳一跳、后续地块 / 道具类玩法重复复制同一套算法和 OSS 元数据口径。
|
||||
- 决策：`server-rs/crates/api-server/src/generated_asset_sheets.rs` 作为通用系列素材图集模块，`n` 作为必选 `grid_size` 参数；物品名称 prompt 模板与特殊设定 prompt 作为可选输入；模块负责 sheet prompt、`n*n` 切片、透明化、PNG 输出、OSS private upload 请求构造，以及 sheet / item / special prompt 的 base64 元数据持久化。玩法只负责生图 provider、计费、slot 规划、失败回写和把通用切片结果映射回自身 DTO / 草稿 / runtime 字段。
|
||||
@@ -1343,7 +707,7 @@
|
||||
## 2026-05-13 refresh_session 会话组后端聚合与远端踢下线
|
||||
|
||||
- 背景：账号安全页中同设备同 IP 的多条 active `refresh_session` 会重复展示；退出登录没有稳定撤销当前 refresh session；前端“踢下线”只做本地状态变化，未真正让远端设备失效。
|
||||
- 决策：`GET /api/auth/sessions` 由后端按“同设备 + 同 IP”聚合 active refresh sessions，响应保留代表 `sessionId` 并新增 `sessionIds/sessionCount`；组内包含当前 refresh hash 或 Bearer `sid` 时整组视为当前设备组，前端不展示踢下线。新增 `POST /api/auth/sessions/{session_id}/revoke`，只允许撤销当前用户自己的非当前会话，不递增 `token_version`，但认证中间件会校验 access token `sid` 对应 active refresh session，使被踢设备立即失效。`/api/auth/logout` 在 refresh cookie 缺失时回退用 Bearer `sid` 撤销当前 session；自 2026-06-07 起单设备退出也不再递增 `token_version`，避免误伤其它设备，只有退出全部设备和改密类安全动作提升账号级版本。
|
||||
- 决策：`GET /api/auth/sessions` 由后端按“同设备 + 同 IP”聚合 active refresh sessions，响应保留代表 `sessionId` 并新增 `sessionIds/sessionCount`；组内包含当前 refresh hash 或 Bearer `sid` 时整组视为当前设备组，前端不展示踢下线。新增 `POST /api/auth/sessions/{session_id}/revoke`，只允许撤销当前用户自己的非当前会话，不递增 `token_version`，但认证中间件会校验 access token `sid` 对应 active refresh session，使被踢设备立即失效。`/api/auth/logout` 在 refresh cookie 缺失时回退用 Bearer `sid` 撤销当前 session，并继续递增 `token_version`。
|
||||
- 影响范围：`module-auth` refresh session service、`api-server` auth middleware/logout/sessions route、`shared-contracts`/TS auth contract、`AuthGate`、`AccountModal`、认证会话技术文档和路由/埋点索引。
|
||||
- 验证方式：执行 `cargo test -p module-auth --manifest-path server-rs/Cargo.toml refresh_session`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml auth_sessions -- --nocapture`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml revoke_auth_session -- --nocapture`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml logout_succeeds_without_refresh_cookie_when_bearer_token_is_valid -- --nocapture`、`npm run test -- AuthGate.test.tsx AccountModal.test.tsx authService.test.ts`、`npm run check:encoding`、`git diff --check`，并用 `npm run dev:api-server` 检查 `/healthz`。
|
||||
- 关联文档：`docs/technical/AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md`、`docs/technical/SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md`、`docs/technical/SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`。
|
||||
@@ -1802,6 +1166,7 @@
|
||||
|
||||
## 2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost
|
||||
|
||||
- 后续更新：该条仍适用于常规构建 / 发布流水线；`Genarrative-Server-Provision` 已在 2026-06-05 改为目标部署 agent 全程执行，并禁止公网 Git fallback 与 build 节点工具包中转。
|
||||
- 背景：生产流水线长期混用 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`、生产运维文档。
|
||||
@@ -1917,186 +1282,6 @@
|
||||
- 验证方式：工作台首屏不再出现标题 / 简介 / 标签输入；结果页修改后点试玩或发布会先写回当前作品信息。
|
||||
- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-03 Profile Dashboard Presentation 收口
|
||||
|
||||
- 背景：`RpgEntryHomeView.tsx` 同时承载个人数据卡、钱包 chip 与“玩过”弹窗，计数压缩、累计时长、单作品时长、玩法标签和作品号兜底散在页面 Implementation 内，修改展示口径时缺少稳定测试面。
|
||||
- 决策：新增 `src/components/rpg-entry/rpgEntryProfileDashboardPresentation.ts` 作为个人数据展示 Module，Interface 收口为 `buildProfileDashboardPresentation`、计数 / 时长格式化和“玩过”列表标签 / 作品号格式化函数；页面只消费结果并保留 UI 编排与点击处理。
|
||||
- 影响范围：RPG 首页“我的数据”卡片、移动端 / 桌面端钱包 chip、个人数据弹窗与“玩过”列表。
|
||||
- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryProfileDashboardPresentation.test.ts`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】ProfileDashboardPresentation收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Recommend Feed ViewModel 收口
|
||||
|
||||
- 背景：推荐 feed 与正式 runtime 的上一条 / 下一条选择分别在 `RpgEntryHomeView.tsx` 和 `PlatformEntryFlowShellImpl.tsx` 手写公开作品去重、隐藏内容过滤、active key 兜底和相邻回环，存在推荐预览与 runtime 口径漂移风险。
|
||||
- 决策：在 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts` 追加推荐 feed Module Interface：`dedupePlatformPublicGalleryEntries`、`buildPlatformRecommendFeedEntries`、`selectPlatformRecommendFeedWindow`、`selectAdjacentPlatformRecommendEntry`；首页与 FlowShell 均消费该 Interface。
|
||||
- 影响范围：移动端首页推荐 swipe、发现页推荐频道、桌面推荐格、推荐 runtime 队列与上一条 / 下一条跳转。
|
||||
- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend|edutainment"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "logged out home recommendation next starts the next puzzle work"`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】RecommendFeedViewModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Recommend Swipe Deck Model 收口
|
||||
|
||||
- 背景：移动端推荐首页 swipe deck 的拖拽阈值、offset clamp、commit 方向、rail class 和分享文案仍留在 `RpgEntryHomeView.tsx` 页面 Implementation 内，页面同时承载 DOM pointer 副作用和纯规则。
|
||||
- 决策：新增 `src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.ts` 作为 Recommend Swipe Deck Module，Interface 收口 `hasRecommendDragStarted`、`clampRecommendDragOffset`、`resolveRecommendDragCommitDirection`、`resolveRecommendCommitOffset`、`buildRecommendSwipeRailClassName`、`shouldAnimateRecommendSwipe` 与 `buildRecommendShareText`；页面仅保留 pointer capture、DOM 高度读取、动画 timer、clipboard 与 like/remix/open 副作用 Adapter。
|
||||
- 影响范围：移动端推荐首页 swipe 手势、上一条 / 下一条动画、推荐分享文案与未登录时的直接切换行为。
|
||||
- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend|edutainment"`、`npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts -t "recommend"`、针对新 Module 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】RecommendSwipeDeckModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Ranking ViewModel 收口
|
||||
|
||||
- 背景：排行 tab 的文案、metric label 与空态文案在 `RpgEntryHomeView.tsx`，排序和 metric value 在 `rpgEntryPublicGalleryViewModel.ts`，同一 `PlatformRankingTab` 的 Interface 分散且页面需要类型断言取 active config。
|
||||
- 决策：在 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts` 收口 `DEFAULT_PLATFORM_RANKING_TAB`、`PLATFORM_RANKING_TABS`、`getPlatformRankingTabConfig` 与 `getPlatformRankingMetric`；页面仅保留 active tab 状态和渲染。
|
||||
- 影响范围：发现页排行频道 tab 顺序、tab 文案、空态文案、排行项指标 label/value。
|
||||
- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "bottom category tab becomes ranking and switches ranking metrics|ranking"`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】RankingViewModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Category Option ViewModel 收口
|
||||
|
||||
- 背景：分类频道的筛选选项、排序选项、默认值、active label fallback 和排序循环仍留在 `RpgEntryHomeView.tsx` 页面 Implementation 内，而玩法过滤、排序和主指标已经在 `rpgEntryPublicGalleryViewModel.ts`，同一分类 Interface 被拆成两处。
|
||||
- 决策：在 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts` 收口 `DEFAULT_PLATFORM_CATEGORY_KIND_FILTER`、`DEFAULT_PLATFORM_CATEGORY_SORT_MODE`、`PLATFORM_CATEGORY_KIND_FILTERS`、`PLATFORM_CATEGORY_SORT_OPTIONS`、`getPlatformCategoryKindFilterOption`、`getPlatformCategorySortOption` 与 `getNextPlatformCategorySortMode`；页面仅保留当前筛选 / 排序状态和渲染。
|
||||
- 影响范围：发现页分类频道筛选弹窗、筛选按钮 label、排序按钮 label 与排序循环。
|
||||
- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "category"`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PublicGalleryViewModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Match3D Runtime Profile 收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 内仍直接承载抓大鹅公开详情转 work、session draft 转 profile、生成背景资产提升、runtime active profile 选择和 run / profile / public detail 素材优先级，平台壳需要理解抓大鹅生成素材内部结构。
|
||||
- 决策：新增 `src/components/platform-entry/platformMatch3DRuntimeProfile.ts` 作为抓大鹅 runtime profile Module，Interface 收口 `mapPublicWorkDetailToMatch3DWork`、`buildMatch3DProfileFromSession`、`normalizeMatch3DWorkForRuntimeUi`、`mapMatch3DWorksForRuntimeUi`、`promoteMatch3DGeneratedBackgroundAsset`、`hasMatch3DRuntimeAsset`、`hasMatch3DRuntimeBackgroundAsset`、`resolveActiveMatch3DRuntimeProfile` 与 runtime item/background/backgroundImage 解析函数；平台壳只保留启动 run、预加载、路由、错误和 state 编排。
|
||||
- 影响范围：抓大鹅作品架、公开详情试玩、推荐 runtime、正式 runtime 与草稿结果页试玩前素材规范化。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformMatch3DRuntimeProfile.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "match3d|抓大鹅"`、针对新 Module 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】Match3DRuntimeProfile收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Draft Generation Shelf Model 收口
|
||||
|
||||
- 背景：平台壳内散落创作生成 notice key、pending 作品架占位、作品详情更新回填、失败文案覆盖、拼图稳定 ID、持久化 generating/failed 判断与草稿 Tab 未读点，新增或调整玩法时需要在多处理解 `workId` / `profileId` / `sourceSessionId` / `draftId` 形状。
|
||||
- 决策：新增 `src/components/platform-entry/platformDraftGenerationShelfModel.ts` 作为 Draft Generation Shelf Module，Interface 收口 `collectDraftNoticeKeys`、`getGenerationNoticeShelfKeys`、`createPendingDraftShelfState`、各玩法 `buildPending*Works`、`buildCreationWorkShelfRuntimeState`、`collectVisibleDraftNoticeKeys`、`hasUnreadDraftGenerationUpdates`、`mergePuzzleWorkSummary`、`mergeBigFishWorkSummary`、拼图稳定 ID 与持久化状态判断；`PlatformEntryFlowShellImpl.tsx` 仅作为 React state、网络刷新、路由和弹窗副作用 Adapter。
|
||||
- 影响范围：创作中心草稿 Tab 未读点、作品架生成中遮罩、作品详情更新回填、失败草稿摘要、pending 草稿占位、拼图 / 抓大鹅生成恢复和各玩法生成完成通知。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`、`npm run test -- src/components/custom-world-home/creationWorkShelf.test.ts -t "generation state|failure notice|failed puzzle"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating puzzle draft|persisted generating match3d draft|completed baby object match draft"`、针对新 Module 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】DraftGenerationShelfModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Creation Hub Shelf Items Interface 收口
|
||||
|
||||
- 背景：`creationWorkShelf.ts` 已把各玩法作品映射为 `CreationWorkShelfItem.actions`，但 `CustomWorldCreationHub.tsx` 的生产 Interface 仍接收 raw items 与 open/delete/claim 回调列阵，新增玩法时 Hub props 继续膨胀。
|
||||
- 决策：`CustomWorldCreationHub.tsx` 生产 Interface 收敛为 `shelfItems: CreationWorkShelfItem[]` 与少量 UI 状态；`PlatformEntryFlowShellImpl.tsx` 在外层作为 Adapter 调用 `buildCreationWorkShelfItems` 注入完整 actions；Hub 测试改经 `CustomWorldCreationHub.testAdapter.tsx` 把旧 fixture 转成 shelf items，不让测试继续依赖旧浅 Interface。
|
||||
- 影响范围：创作 Tab / 草稿 Tab 作品架、RPG / 拼图 / 抓大鹅 / 方洞 / 跳一跳 / 敲木鱼 / 视觉小说 / Bark Battle / 宝贝识物作品打开、删除、生成态与拼图奖励领取。
|
||||
- 验证方式：`npm run test -- src/components/custom-world-home/creationWorkShelf.test.ts`、`npm run test -- src/components/custom-world-home/CustomWorldCreationHub.test.tsx`、`npm run test -- src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx`、相关 FlowShell creation hub 交互片段、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】WorkShelfModule收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Creation URL State Model 收口
|
||||
|
||||
- 背景：平台壳内散落各玩法创作恢复 URL 的 `sessionId` / `profileId` / `draftId` / `workId` 组装、空值归一化、拼图 runtime query key 与拼图稳定身份互推，导致刷新恢复规则缺少稳定测试面。
|
||||
- 决策：新增 `src/components/platform-entry/platformCreationUrlStateModel.ts` 作为 Creation URL State Module，Interface 收口各玩法 `build*CreationUrlState`、拼图 `buildPuzzle*RuntimeUrlState`、URL state 非空判断和 runtime state key；新增 `src/components/platform-entry/platformPuzzleIdentityModel.ts` 作为拼图稳定身份 Module，`platformDraftGenerationShelfModel.ts` 仅 re-export 旧入口以保持兼容。`PlatformEntryFlowShellImpl.tsx` 只保留路由、URL 写入和网络副作用 Adapter。
|
||||
- 追加决策：初始创作 URL 恢复的已处理、非创作路径、无私有 query、平台配置加载中、受保护数据暂不可读与可恢复判定也收口到 `resolveInitialCreationUrlRestoreDecision`；壳层只按 `skip`、`mark-handled`、`wait`、`restore` 执行 ref 标记或进入原恢复副作用。
|
||||
- 追加决策：创作直达恢复目标解析收口到 `resolveCreationUrlRestoreTarget(pathname, state)`；Module 统一识别 big-fish、match3d、square-hole、puzzle、visual-novel、bark-battle、baby-object-match、jump-hop、wooden-fish 的 path、私有 query 归一化、生成路径标记和 big-fish workId 到 sessionId 兜底。壳层仍执行作品列表读取、草稿恢复、错误处理、stage 切换和 URL 写回；`/creation/rpg` 继续保持无具体恢复目标，后续要接入需先补规则与测试。
|
||||
- 追加决策：创作 URL 恢复的作品 / 草稿身份匹配谓词、以及跳一跳 / 敲木鱼恢复后的阶段落点也归入 `platformCreationUrlStateModel.ts`。身份匹配只允许非空目标值命中，避免 query 缺失时用空值误开草稿；壳层只把已读取的列表项、session 或 work 交给 Module 判定，然后执行对应打开 / restore 副作用。
|
||||
- 影响范围：创作流程刷新恢复、拼图草稿 / 发布 runtime 深链、作品架打开试玩、跳一跳 / 敲木鱼 work-backed 恢复、Bark Battle / 宝贝识物本地草稿恢复。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformCreationUrlStateModel.test.ts src/components/platform-entry/platformPuzzleIdentityModel.test.ts`、`npm run test -- src/services/creationUrlState.test.ts`、`npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`、针对新 Module 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】CreationUrlStateModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-04 Platform Public Code Search Model 收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 的公开搜索回调内联判断内部用户 ID、陶泥号、RPG 作品号、各玩法公开作品号前缀和 fallback 顺序，壳层同时承担纯搜索计划与网络 / 打开副作用。
|
||||
- 决策：新增 `src/components/platform-entry/platformPublicCodeSearchModel.ts`，以 `resolvePlatformPublicCodeSearchPlan(keyword)` 返回 `normalizedKeyword` 与 `steps`。`user_` / `user-` 只查用户 ID；玩法前缀直达对应作品；`CW` / 纯数字先查 RPG 作品再查陶泥号；普通关键词和 `SY` 保持既有用户号、RPG 作品、汪汪声浪、用户号兜底顺序。壳层只按 step 执行既有查找、详情打开、Bark Battle runtime 特例和 missing work 归航。
|
||||
- 影响范围：发现页 / 推荐页公开搜索、作品详情深链初始搜索、陶泥号命中面板、各玩法公开作品号直达。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformPublicCodeSearchModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Platform Played Work Open Model 收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 的个人“玩过作品”点击回调内联判断 `worldType`、`worldKey` 前缀、玩法别名、目标 ID、RPG fallback 详情和大鱼吃小鱼 fallback work，壳层同时承担打开意图与异步副作用。
|
||||
- 决策：新增 `src/components/platform-entry/platformPlayedWorkOpenModel.ts`，以 `resolvePlatformPlayedWorkOpenIntent(work)` 返回 `noop`、各玩法公开详情打开意图、`open-big-fish` 或 `open-rpg`。Module 负责玩法别名、`worldKey` 前缀兜底、big-fish gallery miss `fallbackWork` 和 RPG `CustomWorldGalleryCard` payload；壳层继续负责关闭面板、刷新 gallery、命中真实作品、打开详情和错误提示。
|
||||
- 影响范围：个人“玩过作品”面板点击打开、拼图 / 抓大鹅 / 方洞 / 跳一跳 / 敲木鱼 / 大鱼吃小鱼 / RPG 公开详情入口。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformPlayedWorkOpenModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、相关 profile 面板交互片段、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformPlayedWorkOpenModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Platform Generation Progress Tick Model 收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 的生成页进度 tick effect 内联维护 stage 到小游戏生成状态的三元链，并额外手写视觉小说 `startedAtMs` / `phase` 特例，壳层同时承担纯判定与 interval 副作用。
|
||||
- 决策：新增 `src/components/platform-entry/platformGenerationProgressTickModel.ts`，以 `resolvePlatformGenerationProgressTickDecision(input)` 返回 `{ activeKind, shouldTick }`。Module 负责 stage 到 kind 映射、小游戏状态缺失 / 终态判定、视觉小说轻量生成判定；壳层继续负责 `Date.now()`、`window.setInterval`、progress now state 写入和 cleanup。
|
||||
- 影响范围：拼图、抓大鹅、大鱼吃小鱼、方洞挑战、跳一跳、敲木鱼、宝贝识物和视觉小说生成页进度 tick。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformGenerationProgressTickModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformGenerationProgressTickModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Platform Mini Game Session Mapping Model 收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 顶部仍保留拼图 runtime 恢复、方洞 session draft 转 profile、视觉小说 work detail 转 Agent session、跳一跳 pending session、敲木鱼 detail 恢复、敲木鱼生成中作品摘要和敲木鱼 pending session 等纯 DTO 映射，壳层需要理解 sessionId 优先级、拼图稳定 ID、方洞草稿 profile 默认值、视觉小说 work/session fallback、敲木鱼生成中摘要和 pending draft 默认值。
|
||||
- 决策：新增 `src/components/platform-entry/platformMiniGameSessionMappingModel.ts`，收口 `buildPuzzleRuntimeWorkFromSession`、`buildSquareHoleProfileFromSession`、`buildVisualNovelSessionFromWorkDetail`、`buildJumpHopPendingSession`、`buildWoodenFishSessionFromWorkDetail`、`buildWoodenFishGeneratingWorkSummary` 与 `buildWoodenFishPendingSession`。Module 复用 `normalizeCreationUrlValue` 与 `platformPuzzleIdentityModel`；壳层只保留网络读取、React state、URL 写入和 stage 切换副作用。
|
||||
- 影响范围：拼图 runtime URL 恢复、方洞挑战草稿 profile 构造、视觉小说草稿作品架恢复、跳一跳生成中作品架打开、敲木鱼生成中作品架摘要 / 作品架打开和敲木鱼草稿 detail 恢复。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformMiniGameSessionMappingModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformMiniGameSessionMappingModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Platform RPG Agent Result Preview Model 收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 内联维护 RPG Agent 结果页发布门禁展示修正和 result preview source label 映射，壳层需要理解 `CustomWorldProfile` 顶层字段、`creatorIntent`、`anchorContent`、章节蓝图和首幕 acts。
|
||||
- 决策：新增 `src/components/platform-entry/platformRpgAgentResultPreviewModel.ts`，收口 `buildPlatformRpgAgentResultPublishGateView` 与 `resolvePlatformRpgAgentResultPreviewSourceLabel`。Module 只做展示层纯判定；壳层继续负责 session/profile 编排、发布副作用和结果页 props 传递。
|
||||
- 影响范围：RPG Agent 结果页发布按钮门禁 blockers、publishReady 展示修正和预览来源 label。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformRpgAgentResultPreviewModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformRpgAgentResultPreviewModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Platform Mini Game Draft Generation State Model 收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 内联维护小游戏生成状态恢复、失败 / 完成收尾、展示 rebase、拼图后端进度合并和 ready / generating 判定，壳层同时承担 API / background task 副作用和 `MiniGameDraftGenerationState` 生命周期细节。
|
||||
- 决策：新增 `src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts`，收口恢复态、失败态、完成态、展示 rebase、拼图 progress phase 阈值和进度 metadata 合并。壳层继续负责 API、后台任务、React state 写入、作品架刷新、URL 和 stage 切换。
|
||||
- 追加决策：抓大鹅轮询作品素材时的旁路进度合并也归入该 Module，由 `mergeMatch3DGeneratedAssetsIntoGenerationState(state, assets)` 统一统计可用图片素材、至少 5 个总素材计数、`match3d-generate-views` phase 推进和首个素材错误传播；壳层只负责轮询 session / work detail 与写入 state。
|
||||
- 影响范围：拼图 / 抓大鹅 / 大鱼吃小鱼 / 方洞 / 跳一跳 / 敲木鱼 / 宝贝识物生成状态恢复、完成失败收尾、生成页返回展示和拼图轮询进度合并。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformMiniGameDraftGenerationStateModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformMiniGameDraftGenerationStateModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Platform Mini Game Draft Payload Model 收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 内联维护拼图 / 抓大鹅表单 payload、拼图作品更新 payload、拼图编译 action、跳一跳 / 敲木鱼生成 action、作品摘要回填 payload 和 pending 草稿 metadata，壳层需要理解描述字段优先级、formDraft 回退、结果页 draft 到作品更新字段的映射、跳一跳 / 敲木鱼 payload 与 draft 优先级、Match3D config / draft / anchorPack 优先级和数字解析。
|
||||
- 决策：新增 `src/components/platform-entry/platformMiniGameDraftPayloadModel.ts`，收口 `buildPuzzleFormPayloadFromWork`、`buildPuzzleFormPayloadFromSession`、`buildPuzzleFormPayloadFromAction`、`buildPuzzleCompileActionFromFormPayload`、`buildPuzzleWorkUpdatePayloadFromDraft`、`buildJumpHopDraftActionPayload`、`buildWoodenFishDraftActionPayload`、`buildPendingPuzzleDraftMetadata`、`isPuzzleFormOnlyDraft`、`isEmptyPuzzleFormOnlyDraft`、`buildMatch3DFormPayloadFromSession`、`buildMatch3DFormPayloadFromWork` 与 `buildPendingMatch3DDraftMetadata`；`parseOptionalFiniteNumber` 留在 Module 内部。
|
||||
- 影响范围：拼图 action 完成 / 执行前 / 失败恢复、拼图结果页试玩前作品更新、跳一跳 / 敲木鱼生成与重生成 action、拼图表单直生草稿、拼图 form-only 草稿恢复 / 分流 / 结果页渲染、拼图草稿架恢复、抓大鹅表单直生草稿与失败恢复。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformMiniGameDraftPayloadModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformMiniGameDraftPayloadModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Platform Puzzle Draft Recovery Model 收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 的拼图恢复链路只要 cover 或候选图存在就会把恢复 session 抬为 ready，可能让缺关卡画面、UI spritesheet 或关卡背景的半成品直接进入结果页完成态。
|
||||
- 决策：新增 `src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts`，收口 `normalizeRecoveredPuzzleDraftSession` 与 `hasRecoverableGeneratedPuzzleDraft`。恢复完成态必须同时具备首图、`levelSceneImage*`、`uiSpritesheetImage*` 与 `levelBackgroundImage*`；只有完整资产包成立时才把 draft 与首关 `generationStatus` 抬为 `ready`。
|
||||
- 影响范围：拼图生成完成后刷新恢复、拼图 background compile task 完成态写入和结果页自动打开。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformPuzzleDraftRecoveryModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating puzzle draft"`、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformPuzzleDraftRecoveryModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Platform Puzzle Runtime State Model 收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 在拼图排行榜提交回包后内联合并服务端 run 快照，壳层需要理解 `PuzzleRunSnapshot` 中哪些字段由前端即时裁决、哪些字段只由服务端补齐。
|
||||
- 决策：新增 `src/components/platform-entry/platformPuzzleRuntimeStateModel.ts`，以 `mergePuzzleServiceRuntimeState(currentRun, serviceRun)` 收口服务端 run 合并规则。Module 保留当前前端关卡状态、棋盘和计时，只合并服务端 run 身份、`clearedLevelCount` 上限、排行榜与下一关 handoff；任一 run 缺 `currentLevel` 时直接返回当前 run。
|
||||
- 影响范围：拼图排行榜提交、推荐 runtime isolated / default 运行态回包合并、下一关同作品 / 相似作品 handoff，以及后续 Puzzle runtime 快照字段调整。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformPuzzleRuntimeStateModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformPuzzleRuntimeStateModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Puzzle Publish Asset Gate 收紧
|
||||
|
||||
- 背景：后端拼图待发布门槛与前端历史恢复逻辑一样偏弱，只要求标题、描述、标签、关卡名和 cover，导致缺关卡画面、UI spritesheet 或关卡背景的半成品可能被标为 `publishReady` / `ready_to_publish`。
|
||||
- 决策：`module-puzzle::validate_publish_requirements` 新增三类资产 blocker，要求每关具备 `level_scene_image_*`、`ui_spritesheet_image_*` 与 `level_background_image_*`；`api-server::puzzle::tags::is_puzzle_session_snapshot_publish_ready` 同步使用完整资产包判定。
|
||||
- 影响范围：拼图 result preview blockers、publishReady、标签生成后 session stage、从 action payload 构造 fallback session 的 ready 判定。
|
||||
- 验证方式：`cargo test -p module-puzzle --manifest-path server-rs/Cargo.toml validate_publish_requirements`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml puzzle_image_generation_builds_fallback_session_from_levels_snapshot`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml puzzle_image_generation_fallback_session_ready_when_asset_pack_complete`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【后端架构】PuzzlePublishAssetGate收紧计划-2026-06-04.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-04 Platform Profile Wallet Delta Model 收口
|
||||
|
||||
- 背景：`PlatformEntryFlowShellImpl.tsx` 内联维护钱包余额归一、本地 delta 乐观更新和服务端 dashboard 刷新后的 delta 抵消，壳层需要理解余额非负、整数截断、借贷方向和服务端快照对账。
|
||||
- 决策：新增 `src/components/platform-entry/platformProfileWalletDeltaModel.ts`，收口 `resolveProfileWalletBalance`、`adjustProfileDashboardWalletBalance` 与 `reconcileProfileWalletLocalDeltaWithServerDashboard`。壳层只保留 API 请求、React ref、state 写入和刷新触发副作用。
|
||||
- 影响范围：创作入口泥点展示、生成前泥点校验、扣点 / 返还后的个人 dashboard 乐观更新、后台刷新 dashboard 时的本地 delta 对账。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/platformProfileWalletDeltaModel.test.ts`、针对新 Module 和 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformProfileWalletDeltaModel收口计划-2026-06-04.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-03 Public Work Presentation 收口
|
||||
|
||||
- 背景：作品卡、推荐 runtime meta、排行项、分类项、搜索结果和桌面 hero 共用玩法类型 label 与紧凑计数格式，但规则仍在 `RpgEntryHomeView.tsx` 页面 Implementation 内。
|
||||
- 决策：在 `src/components/rpg-entry/rpgEntryWorldPresentation.ts` 追加单作品展示 Interface：`describePlatformPublicWorkKind`、`formatPlatformCompactCount`、`resolvePlatformPublicWorkAuthorLookup` 与 `formatPlatformPublicAuthorAvatarLabel`；页面删除本地玩法类型、紧凑计数、公开作者 lookup 和头像首字实现。集合筛选、排序和指标选择继续留在 `rpgEntryPublicGalleryViewModel.ts`。
|
||||
- 影响范围：公开作品卡片 aria label、推荐点赞 / 改造文案、排行数值、分类主指标、搜索结果、桌面 hero 玩法 label、公开作者摘要缓存 key 与无头像首字兜底。
|
||||
- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryWorldPresentation.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend|ranking|category"`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】PublicWorkPresentation收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-06-03 Profile Funds ViewModel 收口
|
||||
|
||||
- 背景：个人资金展示规则散在 `RpgEntryHomeView.tsx`，且账单来源 label 表漏掉后端契约已有的 `puzzle_author_incentive_claim`，会把原始枚举值直接外显。
|
||||
- 决策：新增 `src/components/rpg-entry/rpgEntryProfileFundsViewModel.ts` 作为个人资金展示 Module，Interface 收口账单来源文案、金额正负号、余额兜底、充值价格、商品主值与会员摘要；页面保留弹窗布局、支付流程、微信渠道和订单轮询副作用。
|
||||
- 影响范围：泥点账单弹窗、充值商品卡片、账户充值弹窗会员摘要。
|
||||
- 验证方式：`npm run test -- src/components/rpg-entry/rpgEntryProfileFundsViewModel.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "wallet ledger|profile recharge modal shows native qr code"`、针对变更文件执行 ESLint、`npm run typecheck`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/technical/【前端架构】ProfileFundsViewModel收口计划-2026-06-03.md`。
|
||||
|
||||
## 2026-05-26 前端不外露图片模型名
|
||||
|
||||
- 背景：拼图与相关结果页、生成进度和错误提示里直接显示 `gpt-image-2`、`gemini-3.1-flash-image-preview`、`image-2` 等名称，会把内部模型路由暴露给普通用户。
|
||||
@@ -2113,33 +1298,6 @@
|
||||
- 验证方式：`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-06-11 前端组件收口补记
|
||||
|
||||
- 背景：个人中心 profile 弹层已抽成独立组件，但 `error / loading / empty / content` 仍在多个 modal 中重复分支，继续沿业务页各写一套会让后续 profile 面板收口越来越碎。
|
||||
- 决策：新增 `src/components/common/PlatformAsyncStatePanel.tsx` 作为互斥异步状态骨架，只承接 `errorState / loadingState / emptyState / children` 四类 slot 的优先级切换；`PlatformProfileWalletLedgerModal.tsx`、`PlatformProfileTaskCenterModal.tsx`、`PlatformProfileRechargeModal.tsx`、`PlatformProfilePlayedWorksModal.tsx` 与 `PlatformProfileReferralModal.tsx` 已接入。若错误或成功提示需要与内容并存，继续留在业务组件外层，不把 `PlatformAsyncStatePanel` 扩成全能状态机。
|
||||
- 决策：`src/components/common/PlatformSegmentedTabs.tsx` 支持 `layout="scroll"`，用于横向可滚动 tab rail；`CustomWorldCreationStartCard.tsx`、`CustomWorldWorkTabs.tsx` 以及 `RpgEntryHomeView.tsx` 的排行 / 分类筛选已接入。共享组件先负责 tab 语义、滚动容器和基础交互；当同一类皮肤在首页、作品架、分类筛选或个人中心中重复出现时，沉淀到 `src/components/common/PlatformSegmentedTabPresets.tsx` 的薄 preset，业务页不再重复复制长 `itemClassName`。
|
||||
- 决策：`src/components/PixelCloseButton.tsx` 保持为 RPG 语义薄封装，底层统一复用 `src/components/common/PlatformModalCloseButton.tsx` 的 `variant="pixel"`；共享 close button 现在负责 `absolute / inline` placement、默认 `title=label` 和可选 `stopPropagation` 点击拦截，业务 importer 不再各自维护像素风关闭按钮壳和冒泡控制。
|
||||
- 决策：`PlatformSegmentedTabs` 继续承接首页 / 结果页剩余的横向 rail 与二选一切换；`RpgEntryHomeView.tsx` 的 discover channel bar、移动端 / 桌面端分类 chip rail，`CustomWorldEntityCatalog.tsx` 的 `RESULT_TABS` sticky rail，以及 `PlatformProfileRechargeModal.tsx` 的“泥点充值 / 会员卡”切换条已迁移。像 `CustomWorldEntityCatalog` 这种“标题 + count”内容直接走 `ReactNode label`；首页 / 创作入口 / 作品架 / 个人中心里稳定复用的频道下划线、创作 pill rail、二列 option segment 皮肤走 `PlatformSegmentedTabPresets`。同类切换在测试里应优先按 `role="tablist" / "tab"` 查询，而不是把它们继续当普通 button。
|
||||
- 决策：简单泥点确认流的开关状态机统一收口到 `src/components/common/useMudPointConfirmController.ts`，只暴露 `open / requestOpen / close / confirm`，不持有点数、标题、描述或禁用态等业务字段；`PuzzleCreationWorkspace.tsx`、`Match3DCreationWorkspace.tsx` 与 `Match3DResultView.tsx` 的两个批量素材面板已接入。`PuzzleResultView.tsx` 和 `RpgCreationRoleAssetStudioModalImpl.tsx` 这类节奏不同或携带 pending payload 的场景继续保留本地状态机，避免把简单 hook 扩成泛型动作路由器。
|
||||
- 决策：标准平台 modal header 的关闭入口继续统一到 `PlatformModalCloseButton variant="platformIcon"`；结果页 / 工具页重复的白底 portal 弹窗壳层收口到 `src/components/common/PlatformToolModalShell.tsx`，由它统一承接平台主题 overlay、白底 remap panel、标准 header/body/footer spacing、关闭按钮和遮罩 / Escape 关闭策略。`PuzzleResultView.tsx` 的关卡详情 / 发布弹窗、`Match3DResultView.tsx` 的封面 / 发布工具弹窗，以及 `PuzzleHistoryAssetPickerDialog.tsx` 的历史素材弹窗已迁移；`UnifiedModal` 新增 `ariaLabel` 支持可见标题动态、可访问名称固定的场景。像素风 runtime、drawer collapse、玩法规则面板和运行态 overlay 不跟这条线混收，继续保留局部 close 语义。
|
||||
- 决策：平台入口的创作前置泥点阻断提示只在 `platform-entry` 局部抽成 `src/components/platform-entry/PlatformDraftGenerationPointNoticeDialog.tsx`，并使用 `DraftGenerationPointNotice` union（`insufficient-points` / `balance-load-failed`）承接业务真相；不要在 `common/` 再抽一个泛化 `BlockingNoticeDialog`，否则会把 `PlatformAcknowledgeStatusDialog` 的样式透传再包装一层而不缩小调用面。
|
||||
- 决策：`PlatformAsyncStatePanel` 从 profile modal 扩展到作品架类白底 panel；`CustomWorldCreationHub.tsx` 的作品架主体现在也统一走 `loadingState / emptyState / children` 三段 slot，但 error + 重试继续留在业务层外侧，不把共享组件扩成“banner + retry + content”全能状态机。后续白底作品架或列表 panel 若只是互斥的 `loading / empty / content`，优先直接复用这套骨架。
|
||||
- 决策：`CopyFeedbackButton.tsx` 的 `actionSurface` 分支继续收口到 `PlatformActionButton`，`pill` 分支继续保留 `PlatformPillBadge` 风格；复制反馈按钮不再直接调用 `getPlatformActionButtonClassName` 手拼平台按钮基础 chrome。后续同类“复制状态机 + 平台动作按钮”组合优先直接复用 `CopyFeedbackButton`，不要在业务页重新混写图标、文案、aria 和动作按钮 class。
|
||||
- 决策：白底 / 暗色面板里的轻量空态和普通 CTA 继续向共享组件收口。`PuzzleResultView.tsx` 的缺草稿提示、`RpgCreationAssetDebugPanel.tsx` 的空诊断提示、`VisualNovelEntityGrid` 的空实体列表、`AccountModal.tsx` 里账号安全分区的“无安全限制 / 无登录设备 / 无操作记录”以及 `LoginScreen.tsx` 的“当前登录入口暂不可用”都改为 `PlatformEmptyState`，`Match3DResultView.tsx` 的引用素材列表直接复用 `PlatformAssetPickerGrid` 自己的空态；`AdventureEntityModal.tsx` 的私聊按钮、`InventoryPanel.tsx` 的锻造 / 合成按钮、`RpgCreationRoleAssetStudioModalImpl.tsx`、`RpgCreationEntityEditorShared.tsx` 里的局部 `ActionButton` 包装层，以及 `RpgAdventurePanel.tsx` / `RpgAdventurePanelOverlays.tsx` 里标准 runtime CTA 都改为委托 `PlatformActionButton surface="editorDark"`。后续白底子面板里的只读空态优先使用 `PlatformEmptyState surface="subpanel"`；暗色编辑 / 运行面板里的普通动作优先使用 `PlatformActionButton surface="editorDark"`，若业务仍需 `stopPropagation`、tone 映射、运行态 icon 排版或局部字号，可保留薄包装层，但不要再直接写原生 `<button>` 基础 chrome。
|
||||
- 决策：白底 / 浅色结果页和工作台顶部的“左箭头 + 返回文案”轻量返回入口统一收口到 `src/components/common/PlatformBackActionButton.tsx`；共享组件固定承接 `PlatformActionButton tone="ghost" size="xs"` 上的返回按钮骨架，并只开放 `compact / regular` 两档尺寸，分别覆盖紧凑结果页 header 与标准白底结果页顶栏。当前已覆盖 `PuzzleResultView.tsx`、`SquareHoleResultView.tsx`、`Match3DResultView.tsx`、`VisualNovelResultView.tsx`、`PuzzleClearResultView.tsx`、`JumpHopResultView.tsx`、`WoodenFishResultView.tsx` 与 `BabyObjectMatchResultView.tsx`；暖色生成页继续走 `GenerationHeaderBackButton`，`BigFishResultView.tsx` 这类 dark hero / 强品牌返回入口继续走 `PlatformIconButton darkMini`，不把三条视觉语义线硬并成一个组件。
|
||||
- 决策：`CustomWorldNpcVisualEditor.tsx` 的本地 `ActionButton` 和 `SkillEffectPreview.tsx` 的“重新预览”按钮也继续并入这条暗色按钮收口线，统一委托 `PlatformActionButton surface="editorDark"`；局部包装层只保留 `stopPropagation`、图标排布、`tone` 映射和极少量视觉微调。后续暗色编辑器里的局部动作按钮若只是普通 CTA，不再新增原生 `<button>` 实现，优先沿用“薄包装 + 共享按钮本体”模式。
|
||||
- 决策：RPG 创作侧标准 dark header / footer 动作也继续纳入同一条按钮收口线。`RpgCreationRoleAssetStudioModalImpl.tsx` 的 header“关闭”、`RpgCreationEntityEditorShared.tsx` 的 footer“取消”以及 `RpgCreationRoleAssetStudioFooter.tsx` 的“保存到当前角色”都改为委托 `PlatformActionButton surface="editorDark"`；局部壳层只保留布局、宽度/字号贴合和少量 tone 语义，不再为标准 dark close / cancel / save CTA 单独维护原生 `<button>` 基础 chrome。
|
||||
- 决策：RPG runtime overlay 里的标准 dark CTA 和可点击 dark row 也继续纳入这条收口线。`RpgAdventurePanelOverlays.tsx` 的 goal panel“知道了”、任务详情里的“领取任务 / 返回交付”、任务完成提示里的“打开任务日志”都改为委托 `PlatformActionButton surface="editorDark"`；设置面板里的“运行统计”入口改为 `PlatformSubpanel as="button" surface="dark"`。像素风 choice button、HUD launcher、奖励物品格和输入 composer 保持 runtime 专属语义，不继续硬并到普通平台按钮。
|
||||
- 决策：`PlatformToolModalShell` 继续承接 RPG 结果页发布检查弹窗；`RpgCreationResultActionBar.tsx` 只保留发布检查、封面预览、封面设置和发布动作语义，不再直接维护 `createPortal`、平台主题 overlay、白底 remap panel、header close、body/footer spacing 和遮罩关闭逻辑。后续结果页 / 工具页里同形态的白底 portal 弹窗优先迁移到 `PlatformToolModalShell`；编辑器大壳、暗色 runtime overlay 和需要专属布局的面板继续保留局部 shell。
|
||||
- 决策：`PlatformToolModalShell` 继续承接方洞结果页图片槽弹窗；`SquareHoleResultView.tsx` 的封面 / 背景 / 形状 / 洞口图片查看与历史选择弹窗只保留当前图、上传、AI 生成和历史素材选择语义，不再直接维护 `createPortal`、主题 overlay、白底 remap panel、header close 和滚动 body。该弹窗使用 `ariaLabel` 保持“封面图查看 / 背景图查看”等固定可访问名称，历史生成区继续由 `PlatformAssetPickerGrid` 承接读取、错误和空态。
|
||||
- 决策：`PlatformToolModalShell` 继续承接视觉小说结果页素材选择弹窗；`VisualNovelAssetPickerDialog` 只保留本地上传、AI 图片生成、历史素材读取、错误提示和素材选择回调，不再直接维护 `createPortal`、平台主题 overlay、白底 remap panel、header close 和滚动 body。视觉小说音频生成弹窗需要保留生成中禁止关闭，实体编辑器弹窗需要保留编辑 footer，后续逐个迁移并补对应交互测试。
|
||||
- 决策：认证入口白底弹窗壳层收口到 `src/components/auth/PlatformAuthModalShell.tsx`；该壳层只承接平台主题 overlay、`platform-auth-card`、标准标题栏、关闭按钮、点击遮罩关闭和禁用 Escape 的认证弹窗策略，不持有短信 / 密码登录、重置密码、邀请码规范化、法律协议或错误状态。`LoginScreen.tsx` 与 `RegistrationInviteModal.tsx` 只保留各自表单状态和提交流程。
|
||||
- 决策：账号弹窗可以继续复用 `PlatformAuthModalShell` 的平台主题 overlay 与 auth card 壳层，但通过 `overlaySpacing`、`overlayStyle`、`showHeader` 和尺寸透传保留账号 direct mode 的唯一 dialog 语义与 safe-area 布局，不把账号安全详情、换绑手机号或修改密码子面板并进登录表单语义。
|
||||
- 决策：运行态弹窗先按玩法目录沉淀薄壳，只有跨玩法接口真正稳定后才上升到 `common/`。拼图运行态用 `src/components/puzzle-runtime/PuzzleRuntimeModalShell.tsx` 承接道具确认、设置、退出改造、失败和通关结算的 overlay / dialog / footer / button 骨架；抓大鹅和跳一跳结算分别保留在各自 runtime shell 内抽本地 settlement shell / summary / actions。`PlatformToolModalShell` 继续只服务平台白底工具弹窗，不强塞到像素风或游戏运行态 overlay；拖拽 ghost、飞行动画、原图查看和全屏 runtime 容器不按旧 modal 债务处理。
|
||||
- 决策：NPC dark modal footer 和暗色明细空态也继续纳入同一条收口线。`NpcModals.tsx` 里的交易 / 赠礼 / 招募弹窗 footer 按钮和物品详情“关闭”按钮都改为委托 `PlatformActionButton surface="editorDark"`，交易右侧“请选择一件物品”提示改为 `PlatformEmptyState surface="editorDark"`；`CharacterInfoShared.tsx` 的 `BuildContributionDetailPanel` 空明细也改为 `PlatformEmptyState surface="editorDark"`。数量 stepper、赠礼 / 招募 option card、标签强度按钮这类带独立业务语义的控件继续保留局部实现。
|
||||
- 决策：详情页头部动作组合统一收口到 `src/components/common/PlatformDetailTopbar.tsx` 与 `src/components/common/PlatformDetailShareActions.tsx`。`PlatformDetailTopbar` 只负责返回按钮、标题居中槽位和右侧动作槽位的布局，可在 `pill` / `icon` 返回入口之间切换；`PlatformDetailShareActions` 只负责“前置 badge 区块 + 作品号复制 + 分享复制”这组稳定动作，并允许按页面关闭复制或分享其中一项。`RpgEntryWorldDetailView.tsx` 已接入 overlay 版完整动作组，`PlatformWorkDetailView.tsx` 已接入 icon topbar 与 solid 版作品号复制动作，同时继续保留公开详情页自己的顶部 icon 分享入口和分享反馈提示。后续详情页若只是复用返回、标题、作品号复制或分享动作排列，优先组合这两个薄组件，不把作者、摘要、封面、轮播或业务 CTA 塞进共享配置对象。
|
||||
- 验证方式：`npm run test -- src/components/common/PlatformAsyncStatePanel.test.tsx src/components/platform-entry/PlatformProfileReferralModal.test.tsx src/components/platform-entry/PlatformProfileWalletLedgerModal.test.tsx src/components/platform-entry/PlatformProfilePlayedWorksModal.test.tsx src/components/platform-entry/PlatformProfileTaskCenterModal.test.tsx src/components/platform-entry/PlatformProfileRechargeModal.test.tsx src/components/common/PlatformSegmentedTabs.test.tsx src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx`、`npm run test -- src/components/common/PlatformModalCloseButton.test.tsx src/components/PixelCloseButton.test.tsx src/components/CharacterChatModal.test.tsx src/components/MapModal.test.tsx`、`npm run test -- src/components/common/useMudPointConfirmController.test.tsx src/components/match3d-result/Match3DResultView.test.tsx src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx src/components/platform-entry/PlatformProfileRechargeModal.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx src/components/rpg-creation-result/RpgCreationResultActionBar.test.tsx src/components/unified-creation/shared/PuzzleHistoryAssetPickerDialog.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`、`npm run test -- src/components/common/CopyFeedbackButton.test.tsx src/components/common/PlatformActionButton.test.tsx src/components/AdventureEntityModal.test.tsx src/components/InventoryPanel.test.tsx src/components/rpg-creation-result/RpgCreationAssetDebugPanel.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx src/components/auth/AccountModal.test.tsx src/components/rpg-runtime-panels/RpgAdventurePanel.test.tsx src/components/rpg-runtime-panels/RpgAdventurePanel.npcChat.test.tsx src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
|
||||
## 2026-05-26 敲木鱼发布后作品架与推荐流刷新口径
|
||||
|
||||
- 背景：敲木鱼已具备公开广场投影，但草稿 Tab 的作品架没有当前用户作品列表接口，导致已发布作品在发布后不能立即出现在“已发布”筛选和推荐流里。
|
||||
@@ -2156,23 +1314,6 @@
|
||||
- 验证方式：`cargo check -p module-auth --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p module-auth password --manifest-path server-rs/Cargo.toml -- --nocapture`、`npm run check:spacetime-schema`、`npm run check:encoding`、`cargo test -p api-server spacetime_unavailable_router_returns_service_unavailable_for_requests --manifest-path server-rs/Cargo.toml -- --nocapture`。
|
||||
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
## 2026-06-07 创作入口泥点消耗改由统一契约驱动
|
||||
|
||||
- 背景：创作入口玩法卡封面右下角长期固定显示 `10-20泥点数`，无法在后台按玩法调整，也容易和真实钱包余额或活动奖池混淆。
|
||||
- 决策：`creationTypes[].unifiedCreationSpec.mudPointCost` 作为入口卡泥点消耗数量字段，旧契约缺失时后端和前端都兜底为 `10`；入口卡由前端格式化为 `X泥点数` 展示，后端和后台不保存单位文案。该字段同时作为玩法新建草稿初始生成的扣费真相源，前端余额前置校验、拼图首图生成、抓大鹅完整草稿生成和汪汪声浪初始三图生成必须读取同一份后台入口配置；结果页单图重生成、发布、道具使用和其它独立资产操作继续使用各自业务成本。
|
||||
- 决策补充：后台创作入口开关页不再直接暴露统一创作契约 JSON textarea；页面按契约结构展示为卡片和字段列表，点击“修改契约”后通过弹窗表单编辑 `title`、`mudPointCost` 和 fields，再组装回统一契约 payload 保存。`workspaceStage`、`generationStage` 和 `resultStage` 属于内部阶段标识，后台不展示也不允许编辑；保存时沿用已有契约值，新增契约时按 `playId` 的固定阶段映射自动带出。
|
||||
- 影响范围：`shared-contracts` 的 `UnifiedCreationSpecResponse`、`/api/creation-entry/config` 响应、前端入口卡派生、后台入口开关页、玩法链路文档和创作入口回归测试。
|
||||
- 验证方式：后台修改 `mudPointCost` 后保存，`GET /api/creation-entry/config` 返回同名数字字段；底部加号创作入口卡显示前端格式化后的泥点消耗；创作表单泥点不足提示和后端实际钱包扣费都使用该数字；关闭态卡片仍只显示 `暂未开放`。
|
||||
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-11 拼图与拼消消运行态剩余阻断层继续局部收口
|
||||
|
||||
- 背景：账号弹窗、拼图 runtime、抓大鹅结算、跳一跳结算和拼图 onboarding 收口后，允许范围内仍剩拼图“正在准备下一关”阻断层与拼消消 runtime 的等待 / 结算层各自手写 overlay；它们结构相近，但又都带着玩法本地语义。
|
||||
- 决策：平台入口里的拼图“正在准备下一关”只在 `src/components/platform-entry/PlatformEntryFlowShellImpl/` 下新增 `PuzzleRuntimeBlockingOverlay.tsx` 做本地薄壳，继续复用 `UnifiedModal` 的遮罩、dialog 语义和关闭禁用策略，但不把这类运行态等待面板上推到 `common/`。拼消消 runtime 则在 `src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx` 内新增 `PuzzleClearRuntimeOverlayShell`、`PuzzleClearRuntimePendingOverlay` 与 `PuzzleClearRuntimeSettlementDialog`，统一 `!activeRun`、`level_cleared`、`finished`、`level_failed` 三类局部 overlay 的结构和动作出口。拖拽 ghost、swap flight、补牌 / 消除动画和全屏 runtime 容器继续视为玩法专属视觉层，不算旧 modal 债务。
|
||||
- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleRuntimeBlockingOverlay.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、相关测试与 PlatformUiKit 收口文档。
|
||||
- 验证方式：`npm run test -- src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleRuntimeBlockingOverlay.test.tsx src/components/platform-entry/PlatformEntryFlowShellImpl.test.ts src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
- 关联文档：`docs/technical/【前端架构】PlatformUiKit弹窗组件收口计划-2026-06-08.md`。
|
||||
|
||||
## 2026-05-31 拼消消底图 prompt 与 atlas 切片提示词收口
|
||||
|
||||
- 背景：拼消消生成资产检查时，用户需要区分主题词、场地底图主题词和复合图 atlas prompt 的职责；若小图案显式画出切分线或边框，运行态 1x1 切片会显得像错误素材。
|
||||
@@ -2184,15 +1325,7 @@
|
||||
## 2026-06-06 统一创作页表头按契约 title 原样显示
|
||||
|
||||
- 背景：统一创作页长期使用固定表头 `想做个什么玩法？`，导致跳一跳等玩法希望按自身语义展示标题时只能改前端或默认契约。
|
||||
- 决策：`creationTypes[].unifiedCreationSpec.title` 继续作为统一创作页表头传输字段，但读取和保存时都按契约内容原样显示和持久化，不再用入口 `title` 自动覆盖。默认 spec 可以给出玩法中文名；旧库中已经持久化为 `想做个什么玩法？` 的契约也保持原样，若需要改表头应在后台契约结构卡片中点击修改并编辑 `title` 字段。
|
||||
- 决策：`creationTypes[].unifiedCreationSpec.title` 继续作为统一创作页表头传输字段，但读取和保存时都按契约 JSON 原样显示和持久化，不再用入口 `title` 自动覆盖。默认 spec 可以给出玩法中文名；旧库中已经持久化为 `想做个什么玩法？` 的契约也保持原样，若需要改表头应直接修改后台契约 JSON 的 `title` 字段。
|
||||
- 影响范围：`shared-contracts` 默认 spec、`module-runtime` 入口配置响应、`spacetime-module` 后台保存校验、后台入口开关页摘要和前端 fallback spec。
|
||||
- 验证方式：`GET /api/creation-entry/config` 中各玩法 `unifiedCreationSpec.title` 等于已保存契约内容；后台只修改入口名称时不应隐式改写已保存的统一创作页表头。
|
||||
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 2026-06-11 资产计费边界改为 fail-closed 并补偿退款
|
||||
|
||||
- 背景：图片 / 资产生成入口曾在钱包或 SpacetimeDB 预扣费连通性异常时允许继续生成，且失败后同步退款如果遇到 SpacetimeDB 短暂不可用缺少本地补偿；拼图首图后台任务还使用 api-server 进程内 HashSet 互斥，多实例下不能防重复。
|
||||
- 决策：暂不实现 token 限流。所有资产生成预扣费改为 fail-closed，预扣费失败直接返回错误；支持 retry 的计费 ledger id 统一包含 HTTP `request_id`，前端静默刷新重试复用同一个 `x-request-id`。生成失败后的退款先同步调用 SpacetimeDB，失败则写入 `wallet-refund-outbox` 本地文件并由后台 worker 重放。拼图首图后台生成互斥改为 SpacetimeDB `puzzle_background_compile_task` 表，使用 `task_id + request_id` 作为 claim id，释放时校验 claim id，避免旧任务误删新租约。
|
||||
- 影响范围：`api-server` 资产计费包裹、钱包退款补偿、拼图首图后台生成、`spacetime-module` 拼图 task 表、`spacetime-client` bindings/facade、前端 API request id 复用和后端架构文档。
|
||||
- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:spacetime-runtime-access`、`node scripts/check-server-rs-ddd-boundaries.mjs`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml wallet_refund_outbox`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml asset_operation`、`npm run test -- src/services/apiClient.test.ts`、`npm run check:encoding`。
|
||||
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
@@ -52,8 +52,6 @@ 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 仍沿用原有端口探测与漂移逻辑。
|
||||
|
||||
本地 `npm run dev`、`npm run dev:spacetime` 和 `npm run dev:api-server` 会在 Rust 子进程环境中绕过项目默认 `sccache` wrapper，避免损坏的本机 cache daemon 阻断 `spacetime publish` 或 `api-server` 启动；显式设置的非 sccache 自定义 wrapper 会被保留。生产 / Jenkins 构建仍按流水线自身的 sccache 策略执行。
|
||||
|
||||
该命令会启动：
|
||||
|
||||
- SpacetimeDB standalone
|
||||
@@ -97,23 +95,12 @@ npm run dev:web
|
||||
npm run dev:admin-web
|
||||
```
|
||||
|
||||
本地 SSH 服务器管理面板：
|
||||
|
||||
```bash
|
||||
npm run server-manager:panel
|
||||
```
|
||||
|
||||
该命令启动 `server-rs/crates/server-manager-panel` 的 egui 桌面工具，从本机 `~/.ssh/config` 读取可用 `Host` alias，支持多服务器健康巡检、可折叠侧边栏和受控 systemd 服务启停。服务操作通过远端 `sudo -n systemctl start|stop|restart <unit>` 执行，目标服务器需要提前配置对应 unit 的免交互 sudo 权限。
|
||||
面板启动时会自动注入本机中文字体；如开发机中文仍显示为方块，可设置 `GENARRATIVE_SERVER_PANEL_CJK_FONT=/path/to/font.ttc|index` 指向本机 CJK 字体。
|
||||
|
||||
`npm run dev:api-server` 会保留终端实时输出，并把同一份输出持久化到 `logs/api-server/api-server-<timestamp>.log`。完整联调入口 `npm run dev` 启动的 Rust `api-server` 使用同一套日志规则。如需改写路径，可设置 `GENARRATIVE_API_SERVER_LOG_FILE`；如只改目录，可设置 `GENARRATIVE_API_SERVER_LOG_DIR`。
|
||||
|
||||
开发态 `npm run dev` / `npm run dev:api-server` 默认打开 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，密码入口可以直接注册未知手机号账号；生产默认仍关闭该开关。
|
||||
|
||||
生产 `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
|
||||
|
||||
@@ -15,36 +15,12 @@
|
||||
- 关联：相关文件、文档、提交或 Issue
|
||||
```
|
||||
|
||||
## 生产冷备份后 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` 后，入口卡和前置余额提示可能显示新数值，但用户真实钱包流水仍按代码常量扣除。
|
||||
- 原因：早期约定把 `creationTypes[].unifiedCreationSpec.mudPointCost` 只当展示字段，拼图、抓大鹅和汪汪声浪初始生成各自保留了 `2`、`10`、三次单图 `1` 的硬编码扣费路径。
|
||||
- 处理：新建草稿初始生成成本必须统一从 `GET /api/creation-entry/config` 的 `unifiedCreationSpec.mudPointCost` 解析；前端预校验、拼图首图生成、抓大鹅完整草稿生成和汪汪声浪初始三图生成同源。汪汪声浪结果页单图重新生成仍按单图资产操作成本，不套初始草稿总成本。
|
||||
- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "mud points"`、`npm run test -- src/services/bark-battle-creation/barkBattleCreationClient.test.ts`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml resolves_mud_point_cost initial_generation_slot_cost_splits_creation_entry_total_cost -- --nocapture`。
|
||||
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`server-rs/crates/api-server/src/creation_entry_config.rs`、`server-rs/crates/api-server/src/puzzle/handlers.rs`、`server-rs/crates/api-server/src/match3d/draft.rs`、`server-rs/crates/api-server/src/bark_battle.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
## generated 图片重复下载不要改成服务端本地磁盘缓存
|
||||
|
||||
- 现象：同一张 OSS generated 图片每次展示都重新从 OSS 拉取，或者完整 OSS 私有 URL 裸请求返回 403。
|
||||
- 原因：前端输入如果是 `https://*.oss-*.aliyuncs.com/generated-*`，会被当普通绝对 URL 直连，绕过 `/api/assets/read-url` 和 signed URL 本地缓存；旧 OSS 对象如果缺少 `Cache-Control`，浏览器只能依赖 `ETag` / `Last-Modified` 做 304 协商缓存，不会长期强缓存。
|
||||
- 处理：完整 OSS generated URL 先归一成 `/generated-*` legacy public path，再走 `/api/assets/read-url` 换签；`refreshKey` 是 signed URL 缓存版本号，同一路径、同一版本且未临近过期时必须复用，不要每次渲染都强制重新换签。新上传 generated 私有对象由 `platform-oss` 在 `PostObject` form fields / policy 和服务端 `PutObject` 请求头中写入 `Cache-Control: public, max-age=31536000, immutable`。不要把 api-server 变成图片静态代理，也不要把 OSS 内容 fallback 到服务器磁盘。
|
||||
- 验证：前端测试应看到完整 OSS generated URL 调用 `/api/assets/read-url?legacyPublicPath=...`，且相同 `refreshKey` 不重复换签；`cargo test -p platform-oss --manifest-path server-rs/Cargo.toml` 应覆盖 `Cache-Control` policy、form field、PutObject headers 和 V4 `AdditionalHeaders`；线上旧对象可用 `curl -I` 观察是否只有 `ETag` / `Last-Modified` 或已经补齐 `Cache-Control`。
|
||||
- 处理：完整 OSS generated URL 先归一成 `/generated-*` legacy public path，再走 `/api/assets/read-url` 换签；新上传 generated 私有对象由 `platform-oss` 在 `PostObject` form fields / policy 和服务端 `PutObject` 请求头中写入 `Cache-Control: public, max-age=31536000, immutable`。不要把 api-server 变成图片静态代理，也不要把 OSS 内容 fallback 到服务器磁盘。
|
||||
- 验证：前端测试应看到完整 OSS generated URL 调用 `/api/assets/read-url?legacyPublicPath=...`；`cargo test -p platform-oss --manifest-path server-rs/Cargo.toml` 应覆盖 `Cache-Control` policy、form field、PutObject headers 和 V4 `AdditionalHeaders`；线上旧对象可用 `curl -I` 观察是否只有 `ETag` / `Last-Modified` 或已经补齐 `Cache-Control`。
|
||||
- 关联：`src/services/assetReadUrlService.ts`、`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/platform-oss/README.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
## 小程序 H5 导航不能清掉宿主 query
|
||||
@@ -87,13 +63,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 图片生成 request_send 传输错误要按可重试网络抖动排查
|
||||
## VectorEngine 图片生成 SendRequest 超时要按传输失败排查
|
||||
|
||||
- 现象：`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` 或明确审核错误，按审核失败另行处理，不要归到网络抖动。
|
||||
- 现象：`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`，按上游网关或审核失败另行处理，不要归到传输超时。
|
||||
- 拼图关卡资产生成按 `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_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`。
|
||||
- 验证：`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`。
|
||||
|
||||
## “我的”页每日任务卡不要硬编码进度，也不要跨日保留旧状态
|
||||
@@ -144,14 +120,6 @@
|
||||
- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating puzzle draft"`，并确认恢复生成中草稿后 `getPuzzleAgentSession` 不会因为进度刷新继续连发。
|
||||
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/usePlatformCreationAgentFlowController.ts`、`src/components/platform-entry/usePlatformCreationAgentFlowController.test.tsx`。
|
||||
|
||||
## 小游戏恢复生成页不要只用请求 busy 判定是否生成中
|
||||
|
||||
- 现象：敲木鱼作品架里的生成中草稿点击进入生成页后，页面会显示“重新生成草稿”按钮，而不是继续显示素材生成中的等待态。
|
||||
- 原因：平台壳恢复 `generationStatus=generating` 草稿时会把 `isBusy` 置回 false，只保留 `MiniGameDraftGenerationState` 作为生成事实；生成页如果只把请求 busy 传给 `isGenerating`，共用生成页会误判为空闲态并展示重试按钮。
|
||||
- 处理：小游戏生成页的 `isGenerating` 必须由 `isBusy || isMiniGameDraftGenerating(generationState)` 推导；跳一跳、拼消消、敲木鱼等从作品架恢复的生成页都要使用同一口径。
|
||||
- 验证：`npm run test -- src/components/platform-entry/PlatformEntryFlowShellImpl.test.ts` 应覆盖 `busy=false` 但敲木鱼 generation state 仍在生成中时继续隐藏重试入口。
|
||||
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/unified-creation/UnifiedGenerationPage.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 拼图试玩恢复 query 必须先切到运行态路径再写
|
||||
|
||||
- 现象：拼图试玩或正式运行态打开后，刷新会停在“正在进入拼图关卡”，或地址栏只有 `runtimeProfileId`，缺少草稿 `runtimeSessionId`。
|
||||
@@ -184,22 +152,6 @@
|
||||
- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`，浏览器里确认局部拼合会闪、完整消除会放大淡出、补牌在淡出后段才开始掉落。
|
||||
- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/index.css`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`。
|
||||
|
||||
## 拼消消补牌下落叠层不能比动画提前卸载
|
||||
|
||||
- 现象：小牌补牌下落时看起来只是闪一下就切到目标格，下滑过程不连贯，途中还会闪出白色底。
|
||||
- 原因：补牌叠层的清理时间只按消除动画固定时长计算，没有覆盖每张卡自己的下落延迟、下落距离时长和收尾缓冲；同时下落叠层曾带 `bg-white` / `border-white` 外壳，动画起点透明度和提亮滤镜会把外壳闪成白块。
|
||||
- 处理：下落卡片按距离写入 `--puzzle-clear-drop-duration`，清理定时器取 `delay + duration + settle buffer` 的最大值；CSS 下落动画使用 `translate3d`、轻微过冲和回弹，叠层保持透明、无边框、无亮度提升，只渲染真实卡片图。
|
||||
- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx src/index.test.ts`；浏览器里完整消除后新补入小牌应有连续下滑和轻微落位感，过程中不应出现白色闪块。
|
||||
- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/index.css`、`src/index.test.ts`、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`。
|
||||
|
||||
## 拼消消替换飞行层要飞目标卡且不能带白底
|
||||
|
||||
- 现象：按下卡牌、拖动覆盖另一张卡并完成替换时，被替换的小卡在新位置先闪一下白底，然后才显示正确图像。
|
||||
- 原因：替换飞行层如果复用被拖动的源卡，并且容器本身带 `background: white` / 白色边框，就会和拖拽 ghost 同向叠在目标格附近；真正应该回到源空位的目标卡没有覆盖源位空槽，视觉上就会露出白壳或白底。
|
||||
- 处理：拖拽 ghost 只负责源卡落到目标格；`swapFlight` 必须使用被覆盖的 `target.card`，从目标格飞回源空位。飞行层容器保持透明、无边框，阴影只加在真实卡图上。
|
||||
- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx src/index.test.ts` 覆盖目标卡图片进入 `puzzle-clear-swap-flight`，并断言 `.puzzle-clear-swap-flight` 不再出现白底或白边。
|
||||
- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/index.css`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`src/index.test.ts`。
|
||||
|
||||
## 首页推荐分流参数不能条件性调用 hook
|
||||
|
||||
- 现象：桌面首页或移动首页在 HMR、断点切换或重新渲染后直接报 React hook 顺序错误，页面停在“正在加载内容”。
|
||||
@@ -216,14 +168,6 @@
|
||||
- 验证：`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "puzzle form checks mud points before creating a draft|match3d form checks mud points before creating a draft|bark battle form checks mud points before creating image assets"` 应断言弹窗出现、对应工作台仍在、玩法模板分类不再出现。
|
||||
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 内嵌泥点确认弹窗必须自带平台主题作用域
|
||||
|
||||
- 现象：拼图 / 抓大鹅统一创作页点击生成后，“确认消耗泥点”弹窗正文和按钮存在，但弹窗面板背景透明，只剩遮罩和文字。
|
||||
- 原因：`PlatformMudPointConfirmDialog` 作为二级确认常以 `portal={false}` 内嵌到工作台局部 DOM，局部节点不一定继承 `.platform-theme`；`platform-modal-shell` 依赖 `--platform-modal-fill` 等主题变量，变量缺失时面板底色解析为空。
|
||||
- 处理：共享泥点确认弹窗默认在 overlay 上带 `platform-theme platform-theme--<theme>`、`platform-modal-backdrop` 和实色遮罩，在 panel 上带 `platform-modal-shell platform-remap-surface`；单按钮状态弹窗也要有默认 light 主题，避免未来独立调用复现。
|
||||
- 验证：浏览器触发 `/creation/puzzle` 与 `/creation/match3d` 的泥点确认弹窗，检查 overlay 最近主题 class 存在、`--platform-modal-fill` 有值且面板为实底；聚焦测试覆盖默认 overlay / panel class。
|
||||
- 关联：`src/components/common/PlatformMudPointConfirmDialog.tsx`、`src/components/common/PlatformStatusDialog.tsx`、`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx`、`src/components/unified-creation/workspaces/Match3DCreationWorkspace.tsx`。
|
||||
|
||||
## 玩法入口分类字段缺失要前端兜底
|
||||
|
||||
- 现象：平台创作入口初始化时，`platformEntryCreationTypes.ts` 直接对 `creationTypes[].categoryId` / `categoryLabel` 调 `trim()`，一旦后端旧数据、局部 mock 或异常返回里缺字段，整个创作页会在 `derivePlatformCreationTypes(...)` 里直接炸掉。
|
||||
@@ -267,7 +211,7 @@
|
||||
- 现象：创作 Tab 两列玩法卡上图能看到，但标题、描述或预计消耗泥点在白底信息区里看不见，或只剩泥点小图标。
|
||||
- 原因：旧 `platform-creation-reference-card` 是给暗图蒙版卡用的全局样式，会把卡片及全部子元素强制成白色文字；参考图要求的是“上图 + 下方白底信息区”，继续复用旧类会让白底上的文字消失。
|
||||
- 处理：创作 Tab 首屏模板卡使用独立 `creation-template-card`、`creation-template-card__body`、`creation-template-card__title`、`creation-template-card__subtitle` 和 `creation-template-card__cost` 结构，不挂 `platform-creation-reference-card`；旧弹层如果仍是暗图蒙版卡，可以继续保留旧类。
|
||||
- 验证：浏览器创作 Tab 中每张开放态卡都应显示标题、描述和后台契约 `mudPointCost` 数量经前端格式化后的泥点消耗文案；旧契约缺字段时兜底显示 `10泥点数`；`npm test -- src/components/custom-world-home/CustomWorldCreationHub.test.tsx -t "creation start card renders reference-aligned banner and template metadata"` 应通过。
|
||||
- 验证：浏览器创作 Tab 中每张卡都应显示标题、描述和“预计消耗 10-20 泥点”；`npm test -- src/components/custom-world-home/CustomWorldCreationHub.test.tsx -t "creation start card renders reference-aligned banner and template metadata"` 应通过。
|
||||
- 关联：`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、`src/index.css`、`src/components/custom-world-home/CustomWorldCreationHub.test.tsx`。
|
||||
|
||||
## 创作首屏开放态卡片不要再显示左上状态标签
|
||||
@@ -497,14 +441,6 @@
|
||||
- 验证：未登录推荐页可以直接进入跳一跳运行态，且 `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 失败`。
|
||||
@@ -1096,8 +1032,8 @@
|
||||
## 拼图生成完成后图片只显示破图或 alt 文案
|
||||
|
||||
- 现象：拼图结果页生成完成后，“画面图”区域出现破图图标和作品名，图片无法正常预览；但打开历史拼图素材时同一张图可能可以正常预览。
|
||||
- 原因：拼图正式图保存为 `/generated-puzzle-assets/*` 兼容标识，旧 `/generated-*` 直读代理已删除；如果前端没有通过 `ResolvedAssetImage` / `/api/assets/read-url` 换签，或收到无前导斜杠的 `generated-puzzle-assets/*` object key 后未识别为 generated 私有资源，浏览器会直接请求裸路径并失败。生成完成后的结果图还会传入 `refreshKey`，它只能作为 signed URL 缓存版本号，不能给 OSS V4 签名 URL 追加 `_v`；OSS 会把 query 纳入签名，额外参数会让签名失效。
|
||||
- 处理：拼图结果页、发布预览、运行态和历史素材预览都走 `ResolvedAssetImage` 或 `useResolvedAssetReadUrl`；generated 私有资源识别必须同时覆盖 `/generated-*`、`generated-*` 和 `https://*.oss-*.aliyuncs.com/generated-*`；`refreshKey` 变化时重新换签，同一路径同一 `refreshKey` 且签名未临近过期时复用已返回的 OSS 签名 URL；禁止恢复 `/generated-puzzle-assets` 直读代理。
|
||||
- 原因：拼图正式图保存为 `/generated-puzzle-assets/*` 兼容标识，旧 `/generated-*` 直读代理已删除；如果前端没有通过 `ResolvedAssetImage` / `/api/assets/read-url` 换签，或收到无前导斜杠的 `generated-puzzle-assets/*` object key 后未识别为 generated 私有资源，浏览器会直接请求裸路径并失败。生成完成后的结果图还会传入 `refreshKey`，它只能用于重新请求 `/api/assets/read-url`，不能给 OSS V4 签名 URL 追加 `_v`；OSS 会把 query 纳入签名，额外参数会让签名失效，历史素材常因未传 `refreshKey` 而表现正常。
|
||||
- 处理：拼图结果页、发布预览、运行态和历史素材预览都走 `ResolvedAssetImage` 或 `useResolvedAssetReadUrl`；`isGeneratedLegacyPath(...)` 必须同时识别 `/generated-*` 和 `generated-*`；`refreshKey` 只绕过前端签名缓存并重新换签，不修改已返回的 OSS 签名 URL；禁止恢复 `/generated-puzzle-assets` 直读代理。
|
||||
- 验证：运行 `npm run test -- src\services\assetReadUrlService.test.ts src\hooks\useResolvedAssetReadUrl.test.tsx src\components\puzzle-result\PuzzleResultView.test.tsx`，再触发一次真实生成确认 Network 中先请求 `/api/assets/read-url`，图片 `src` 为未追加 `_v` 的签名 URL。
|
||||
- 关联：`src/services/assetReadUrlService.ts`、`src/components/ResolvedAssetImage.tsx`、`docs/technical/PUZZLE_IMAGE_ASSET_PROXY_FIX_2026-04-27.md`。
|
||||
|
||||
@@ -1159,8 +1095,6 @@
|
||||
- 现象：刷新网页后，用户明明有本地 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`。
|
||||
|
||||
@@ -1173,7 +1107,6 @@
|
||||
- 追加处理：generated 私有图片换签 `/api/assets/read-url` 也属于展示层后台请求；推荐页拼图运行态挂载后会立即解析封面图，若换签 401 触发全局鉴权事件，也会表现成“进入拼图作品后瞬间未登录”。资源换签失败只应让当前图片为空，不应清 token、广播 auth 事件或主动 refresh。
|
||||
- 追加处理：从推荐页点进公开拼图作品并启动完整运行态后，`startPuzzleRun`、通关自动 `submitPuzzleLeaderboard`、下一关 `advancePuzzleNextLevel` 和重开同样属于当前玩法局部同步；这些请求失败时只应留在拼图错误态，不应清 token 或广播 auth 事件。
|
||||
- 追加处理：通关后 `refreshSaveArchives()`、首屏 bootstrap 的个人看板/作品架/浏览历史读写也只是平台投影刷新，失败应显示局部错误，不能充当全局登录态判定。
|
||||
- 追加处理：未登录推荐页启动任一公开正式玩法时，`/api/runtime/*` 局内路由必须使用 `RuntimePrincipal`，前端通过 `PlatformEntryFlowShellImpl` 的统一 request options helper 给 start / checkpoint / finish / input / drop / click / restart / time-up / leaderboard / next-level 等动作透传 runtime guest token；公开 runtime detail 读取如跳一跳、敲木鱼必须显式 `skipAuth/skipRefresh`，匿名推荐流不能补读受保护创作详情，否则会在真正开局前打出 `/api/auth/refresh 401`。
|
||||
- 验证：`npm run test -- src/services/apiClient.test.ts src/services/assetReadUrlService.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation starts embedded puzzle"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "formal puzzle runtime uses frontend move merge logic and backend leaderboard"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "formal puzzle similar work keeps current run level progression"`。
|
||||
- 关联：`src/services/apiClient.ts`、`src/services/assetReadUrlService.ts`、`src/services/puzzle-runtime/puzzleRuntimeClient.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/RECOMMEND_RUNTIME_AUTH_FAILURE_ISOLATION_FIX_2026-05-09.md`。
|
||||
|
||||
@@ -1304,8 +1237,8 @@
|
||||
|
||||
- 现象：Cargo 报 `could not execute process sccache ... rustc.exe -vV (never executed)`、`sccache: error: Timed out waiting for server startup`，或 `sccache: caused by: Failed to send data to or receive data from server / Failed to read response header / failed to fill whole buffer`；真实 `rustc -Vv` 可以执行，但构建在调用包装器时失败。
|
||||
- 原因：环境、Jenkinsfile 或 `server-rs/.cargo/config.toml` 启用了 `sccache` wrapper，但当前 agent 没有可执行的 `sccache`、PATH 中 shim 损坏，或本地 sccache server/client 通道状态损坏。Windows 本机若配置了 `SCCACHE_OSS_*`，sccache daemon 冷启动会先经 OSS/本机代理完成缓存读写检查，再监听 `127.0.0.1:4226`；代理或 OSS 链路慢时，Cargo 的 `sccache rustc -vV` 可能先超时。
|
||||
- 处理：保留 `server-rs/.cargo/config.toml` 的 `rustc-wrapper = "sccache"`；本地 `npm run dev` / `npm run dev:spacetime` / `npm run dev:api-server` 由 `scripts/dev.mjs` 给 Rust 子进程注入直通 wrapper，自动绕过项目默认 sccache，避免损坏的 daemon 阻断 `spacetime publish` 或 `api-server` 启动；显式设置的非 sccache 自定义 wrapper 会被保留。Windows 本机优先在 `%APPDATA%\Mozilla\sccache\config\config` 写入 `server_startup_timeout_ms = 60000`，拉长 client 等待 daemon 完成 OSS 初始化的时间，然后删除 `server-rs/target/.rustc_info.json` 里缓存的失败探测结果并重跑原始 Cargo 命令。冷启动验证优先用 `sccache --stop-server`，不要在另一个 `cargo` / `rustc` 仍在编译时 `taskkill /F /IM sccache.exe /T`，否则 proc-macro crate 可能被打断并表现为 `serde_derive` / `spacetimedb-bindings-macro` 的 `sccache ... exit code: 1`。若只做临时排障，可在 Git Bash 中执行 `RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo build ...`，或在 PowerShell 用 `cargo check -p api-server --config "build.rustc-wrapper=''"` 一次性绕过 wrapper；生产流水线必须先实际执行 `sccache --version`，失败时移除 `RUSTC_WRAPPER` 并回退到直接 `rustc`。
|
||||
- 验证：`rustc -Vv` 能输出版本；本地 `npm run dev` 能完成 `spacetime publish`、`api-server` `/healthz`、主站 Vite 和后台 Vite 启动；冷启动后原始 `cargo check -p api-server` 和 `cargo check -p spacetime-module` 能通过；`sccache --show-stats` 显示 `Cache location oss, name: genarrative-sccache`，证明原始 Cargo/Jenkins 路径仍可使用 sccache/OSS 缓存；Jenkins 日志出现“未找到可用 sccache，改用 rustc 直接构建”后仍继续真实构建。
|
||||
- 处理：保留 `server-rs/.cargo/config.toml` 的 `rustc-wrapper = "sccache"`；Windows 本机优先在 `%APPDATA%\Mozilla\sccache\config\config` 写入 `server_startup_timeout_ms = 60000`，拉长 client 等待 daemon 完成 OSS 初始化的时间，然后删除 `server-rs/target/.rustc_info.json` 里缓存的失败探测结果并重跑原始 Cargo 命令。冷启动验证优先用 `sccache --stop-server`，不要在另一个 `cargo` / `rustc` 仍在编译时 `taskkill /F /IM sccache.exe /T`，否则 proc-macro crate 可能被打断并表现为 `serde_derive` / `spacetimedb-bindings-macro` 的 `sccache ... exit code: 1`。若只做临时排障，可在 Git Bash 中执行 `RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo build ...`，或在 PowerShell 用 `cargo check -p api-server --config "build.rustc-wrapper=''"` 一次性绕过 wrapper；生产流水线必须先实际执行 `sccache --version`，失败时移除 `RUSTC_WRAPPER` 并回退到直接 `rustc`。
|
||||
- 验证：`rustc -Vv` 能输出版本；冷启动后原始 `cargo check -p api-server` 和 `cargo check -p spacetime-module` 能通过；`sccache --show-stats` 显示 `Cache location oss, name: genarrative-sccache`，证明仍在使用 sccache/OSS 缓存；Jenkins 日志出现“未找到可用 sccache，改用 rustc 直接构建”后仍继续真实构建。
|
||||
- 关联：`scripts/dev.mjs`、`jenkins/Jenkinsfile.production-stdb-module-build`、`docs/technical/SPACETIMEDB_PUBLISH_SCCACHE_FALLBACK_2026-05-09.md`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
|
||||
|
||||
## 生产发布入口不要沿用旧 Jenkinsfile / 一体化脚本
|
||||
@@ -1329,8 +1262,8 @@
|
||||
- 后续更新：该条仍适用于常规构建 / 发布流水线；`Genarrative-Server-Provision` 已在 2026-06-05 改为服务器初始化专用口径，不允许公网 Git fallback，Job 的 `Pipeline script from SCM` 和 Jenkinsfile 内部 checkout 都必须使用本机路径或目标 agent 可访问的内网 Git 源。
|
||||
- 现象：生产发布、数据库导入导出、服务器配置、构建或 `Genarrative-Full-Build-And-Deploy` 流水线执行 `GitSCM checkout` 时，如果 Jenkins 生成的 fetch 是 `+refs/heads/*:refs/remotes/origin/*`，公网 Git 链路可能在收包阶段以 `git-remote-https died of signal 15`、`curl 56 GnuTLS recv error (-9)`、`early EOF`、`invalid index-pack output` 失败；发布类流水线还可能先遇到 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git` 不可达。
|
||||
- 原因：`127.0.0.1` 只代表当前执行阶段的 agent 自身；当 release agent 与 Git 服务不在同一台机器，或本机 Git/Web 服务临时不可用时，固定写死 localhost 会阻断 Jenkinsfile 内部源码/脚本 checkout。即使只使用域名 Git，如果 `GitSCM` 没有显式 refspec 并开启 `CloneOption honorRefspec=true`，Jenkins Git 插件也会拉取所有分支。
|
||||
- 处理：Jenkins Job 的 `Pipeline script from SCM` 由 Windows controller 执行，SCM URL 使用公网域名 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行于 `linux && genarrative-build` 的 `Genarrative-Full-Build-And-Deploy` 源码解析阶段、`Genarrative-Web-Build` checkout 阶段，以及部署/发布类 Linux agent 的 Jenkinsfile 首次 `checkout([$class: 'GitSCM', ...])` 层先尝试 `GIT_REMOTE_URL=http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后直接尝试 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不再配置内网 IP fallback；这些首次 checkout 都必须使用目标分支 refspec、`CloneOption shallow=true depth=1 noTags=true honorRefspec=true`。后续统一走 `scripts/jenkins-checkout-source.sh`，该脚本也按主地址、域名备用地址顺序重新 fetch 并把 `origin` 切到实际可用地址；`COMMIT_HASH` 为空时继续 `--depth=1 --no-tags`，指定 commit 时也先保持 `depth=1` 校验，浅历史无法证明归属时才按 `GENARRATIVE_JENKINS_CHECKOUT_DEEPEN_STEPS` 逐步加深，最后才展开完整历史。发布流水线不得为了缩短 checkout 时间清空上游构建传入的 `COMMIT_HASH`。
|
||||
- 验证：扫描本地 Jenkins live job `config.xml`，确认 SCM `<url>` 都是 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；扫描所有生产 Jenkinsfile 的首次 `GitSCM checkout`，确认 `userRemoteConfigs` 带 `+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}`，`CloneOption` 带 `honorRefspec: true`；扫描发布流水线确认传给 `scripts/jenkins-checkout-source.sh` 的 `COMMIT_HASH` 未被硬编码为空；运行 `bash -n scripts/jenkins-checkout-source.sh`。
|
||||
- 处理：Jenkins Job 的 `Pipeline script from SCM` 由 Windows controller 执行，SCM URL 使用公网域名 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行于 `linux && genarrative-build` 的 `Genarrative-Full-Build-And-Deploy` 源码解析阶段、`Genarrative-Web-Build` checkout 阶段，以及部署/发布类 Linux agent 的 Jenkinsfile 首次 `checkout([$class: 'GitSCM', ...])` 层先尝试 `GIT_REMOTE_URL=http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后直接尝试 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不再配置内网 IP fallback；这些首次 checkout 都必须使用目标分支 refspec、`CloneOption shallow=true depth=1 noTags=true honorRefspec=true`。后续统一走 `scripts/jenkins-checkout-source.sh`，该脚本也按主地址、域名备用地址顺序重新 fetch 并把 `origin` 切到实际可用地址；`COMMIT_HASH` 为空时继续 `--depth=1 --no-tags`，只有指定 commit 时才允许加深历史做分支归属校验。
|
||||
- 验证：扫描本地 Jenkins live job `config.xml`，确认 SCM `<url>` 都是 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；扫描所有生产 Jenkinsfile 的首次 `GitSCM checkout`，确认 `userRemoteConfigs` 带 `+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}`，`CloneOption` 带 `honorRefspec: true`；运行 `bash -n scripts/jenkins-checkout-source.sh`。
|
||||
- 关联：`jenkins/Jenkinsfile.production-full-build-and-deploy`、`jenkins/Jenkinsfile.production-web-build`、`jenkins/Jenkinsfile.production-api-build`、`jenkins/Jenkinsfile.production-stdb-module-build`、`jenkins/Jenkinsfile.production-web-deploy`、`jenkins/Jenkinsfile.production-api-deploy`、`jenkins/Jenkinsfile.production-stdb-module-publish`、`jenkins/Jenkinsfile.production-server-provision`、`jenkins/Jenkinsfile.production-database-export`、`jenkins/Jenkinsfile.production-database-import`、`scripts/jenkins-checkout-source.sh`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
|
||||
|
||||
## Jenkins 可选参数在 set -u 下不能裸读
|
||||
@@ -1357,14 +1290,6 @@
|
||||
- 验证：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 处理。
|
||||
@@ -1392,10 +1317,10 @@
|
||||
## 拼图会过早进入待发布态，结果页可能空图但仍显示可发布
|
||||
|
||||
- 现象：拼图创作有时刚结束就跳到“待发布”结果页，但结果页里的正式图还是空的，发布检查随后又会拦住，用户会感觉“已经完成了却又不能发布”。
|
||||
- 原因：拼图的待发布判定太弱，`build_result_preview` / `validate_publish_requirements` 和 `is_puzzle_session_snapshot_publish_ready` 只检查了作品名、简介、标签、关卡名和 cover 图，没有要求 `level_scene_image_src`、`ui_spritesheet_image_src`、`level_background_image_src` 等完整资产都齐；历史前端恢复链路里的 `hasRecoverableGeneratedPuzzleDraft` / `normalizeRecoveredPuzzleDraftSession` 也只要有 cover 或候选图就会把草稿当成已完成。
|
||||
- 处理：前端恢复链路已收口到 `platformPuzzleDraftRecoveryModel.ts`，只有首图、关卡画面、UI spritesheet 与关卡背景资产包完整时才把恢复草稿抬为完成态；后端 `build_result_preview` / `validate_publish_requirements` / `is_puzzle_session_snapshot_publish_ready` 也已收紧到同一完整资产包门槛。
|
||||
- 验证：当某个拼图草稿只补齐首图、但关卡背景或 UI spritesheet 仍缺失时，前端恢复链路不应把它误判为已完成，后端也不应进入 `ready_to_publish` 或返回 `publishReady=true`。
|
||||
- 关联：`server-rs/crates/module-puzzle/src/application.rs`、`server-rs/crates/api-server/src/puzzle/tags.rs`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts`、`src/components/puzzle-result/PuzzleResultView.tsx`。
|
||||
- 原因：拼图的待发布判定太弱，`build_result_preview` / `validate_publish_requirements` 和 `is_puzzle_session_snapshot_publish_ready` 只检查了作品名、简介、标签、关卡名和 cover 图，没有要求 `level_scene_image_src`、`ui_spritesheet_image_src`、`level_background_image_src` 等完整资产都齐；前端恢复链路里的 `hasRecoverableGeneratedPuzzleDraft` / `normalizeRecoveredPuzzleDraftSession` 也只要有 cover 或候选图就会把草稿当成已完成。
|
||||
- 处理：待修复时要把“待发布”门槛收紧到整套拼图资产包完整，再让恢复逻辑只在完整草稿下抬高为完成态，避免半成品直接进入结果页。
|
||||
- 验证：当某个拼图草稿只补齐首图、但关卡背景或 UI spritesheet 仍缺失时，不应再进入 `ready_to_publish`；结果页也不应把这类草稿误判为已完成。
|
||||
- 关联：`server-rs/crates/module-puzzle/src/application.rs`、`server-rs/crates/api-server/src/puzzle/tags.rs`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`。
|
||||
|
||||
## WebGL 画布在高 DPR 移动端放大溢出
|
||||
|
||||
@@ -1799,18 +1724,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`。
|
||||
|
||||
## 跳一跳地块图集固定走 18 个 UV 大单元
|
||||
## 跳一跳地块图集固定走 5x5 地块池
|
||||
|
||||
- 现象：跳一跳初始草稿生成时报 `系列素材图集的物品行数不能超过 n。`，或者生成完成后只有 atlas 预览路径，地块切片没有真正落盘。
|
||||
- 原因：旧模板先后尝试过通用系列素材 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。
|
||||
- 原因：旧模板先后尝试过通用系列素材 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`，运行态无限路径从地块池随机取材。
|
||||
- 关联：`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"`。
|
||||
- 原因：18 个立方体主题物体 UV 展开图集 prompt 会把这些词放进“主题物体图集”语境，容易被上游理解为要求生成具体宝可梦角色或标志道具，触发安全拦截；这不是普通平台造型词、抠图或超时问题。
|
||||
- 原因：25 个落点图集 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`。
|
||||
@@ -1818,9 +1743,9 @@
|
||||
## 跳一跳地块切片不要按 tileType 复用资产槽位
|
||||
|
||||
- 现象：跳一跳生成完成后，运行态看起来仍像在显示默认几何地块，或者地块图片在加载时频闪；结果页地块池也可能只看到少量重复素材。
|
||||
- 原因：`tileType` 只是路径平台的玩法类型标签，18 个 atlas 大单元里会重复出现 `normal / target / bonus / accent` 等类型。若后端持久化时用 `tileType` 生成 slot/path，同类型切片会写入同一个 `/generated-jump-hop-assets/<profile>/<slot>/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 资产会解析六张面贴图。
|
||||
- 原因：`tileType` 只是路径平台的玩法类型标签，25 个 atlas 切片里会重复出现 `normal / target / bonus / accent` 等类型。若后端持久化时用 `tileType` 生成 slot/path，同类型切片会写入同一个 `/generated-jump-hop-assets/<profile>/<slot>/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` 刷新键。
|
||||
- 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/components/jump-hop-result/JumpHopResultView.tsx`。
|
||||
|
||||
## 跳一跳落点辅助标识不要再用舞台高度常量拍脑袋投影
|
||||
@@ -1831,12 +1756,12 @@
|
||||
- 验证：拖拽半程时辅助点应落在当前地块和目标地块之间，完整拖拽时应逼近目标地块中心；运行态截图里辅助点必须始终压在地块与角色之上。
|
||||
- 关联：`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`。
|
||||
|
||||
## 跳一跳长按蓄力不能再消费拖拽方向
|
||||
## 跳一跳落点辅助和后端裁决必须统一坐标换算
|
||||
|
||||
- 现象：跳一跳改成长按蓄力后，如果前端或后端仍消费 `dragVectorX/dragVectorY`，玩家手指轻微移动就会改变跳跃方向，和“始终朝下一块中心跳”的体验不一致。
|
||||
- 原因：历史弹弓拖拽版本把屏幕拖拽方向作为正式裁决输入，契约字段仍为兼容旧客户端保留，容易被误认为仍是当前玩法规则。
|
||||
- 处理：前端运行态只用长按时长提交 `dragDistance` 兼容字段，不再发送方向字段；落点预测按当前地块中心到下一块地块中心的方向投影。后端 `module-jump-hop` 即使收到旧客户端 `dragVectorX/dragVectorY` 也必须忽略，只按当前地块到下一块地块中心的单位向量裁决。
|
||||
- 验证：前端回归测试覆盖手指移动不改变提交方向、预测落点忽略旧方向字段；后端领域测试覆盖旧客户端传错误方向时仍按下一块中心命中。
|
||||
- 现象：落点辅助标识已经压在目标地块图片上，松手后后端仍判定失败，玩家看到的是“明明瞄准了却没落上去”。
|
||||
- 原因：前端辅助标识使用屏幕像素坐标绘制，而后端裁决使用世界坐标。屏幕 y 轴向下为正、世界 y 轴向上为正；同时屏幕 x/y 每个世界单位对应的像素比例不同。若前端直接把屏幕像素拖拽向量发给后端，辅助点和后端落点方向会不一致。
|
||||
- 处理：前端运行态保留原始屏幕拖拽向量用于画弹弓和辅助点，但提交后端前必须按当前地块到目标地块的屏幕跨度 / 世界跨度把 x、y 分别换算成世界尺度一致的向量；后端继续只负责反向弹射和落点裁决。
|
||||
- 验证：前端回归测试要同时覆盖辅助点完整拖拽到目标地块，以及提交给后端的向量已完成世界尺度换算；后端领域测试覆盖屏幕向后下拉时应向世界 y 正方向跳出并命中。
|
||||
- 关联：`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`server-rs/crates/module-jump-hop/src/application.rs`。
|
||||
|
||||
## 跳一跳创作入口旧文案先查 SpacetimeDB 配置
|
||||
@@ -1964,7 +1889,7 @@
|
||||
|
||||
- 现象：`http://127.0.0.1:3001/` 打不开，但 `3000 / 3101 / 8082` 仍有进程；`npm run dev` 直接退出，没有把新栈拉起来。
|
||||
- 原因：旧 worktree 的 `api-server`、`spacetime-standalone` 和 Vite 还活着，或者当前 worktree 的本机 SpacetimeDB CLI 默认版本低于仓库锁定版本，`scripts/dev.mjs` 会先校验版本再启动并直接报错退出。
|
||||
- 处理：先停掉占用端口的旧进程，再执行 `spacetime version list` 和 `spacetime version use 2.4.1`，确认本机 CLI/standalone 与仓库一致后重新启动 `npm run dev -- --no-interactive --web-port 3001 --api-port 8083 --spacetime-port 3103 --admin-web-port 3104`。
|
||||
- 处理：先停掉占用端口的旧进程，再执行 `spacetime version list` 和 `spacetime version use 2.3.0`，确认本机 CLI/standalone 与仓库一致后重新启动 `npm run dev -- --no-interactive --web-port 3001 --api-port 8083 --spacetime-port 3103 --admin-web-port 3104`。
|
||||
- 验证：`http://127.0.0.1:3001/`、`http://127.0.0.1:8083/healthz`、`http://127.0.0.1:3103/v1/ping` 都返回 200，且进程命令行指向当前 worktree 路径而不是别的仓库。
|
||||
- 关联：`scripts/dev.mjs`、`.hermes/shared-memory/pitfalls.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
@@ -2024,22 +1949,6 @@
|
||||
- 验证：浏览器拖拽时能看到跟手 ghost、源位空槽、落点飞入和整组拼接层；`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx` 应覆盖这些行为。
|
||||
- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`src/index.css`。
|
||||
|
||||
## 拼消消整组拖拽越界要前端回弹，不要发无效 swap
|
||||
|
||||
- 现象：正式拼消消 runtime 玩到已有局部拼接组后，把整组拖到棋盘边缘外侧，前端弹出“puzzle-clear 坐标无效”，后端日志里对应 `/api/runtime/puzzle-clear/runs/{runId}/swap`。
|
||||
- 原因：后端 `move_locked_group` 会按整组平移后的每个格子做边界校验；前端早期只校验松手目标格存在，没有校验整组的其它格子是否会越界，因此会把后端必然拒绝的动作发出去。
|
||||
- 处理：拖动带 `lockedGroupId` 的拼接组时，前端先用当前 board snapshot 计算 `rowDelta/colDelta`，确认组内所有格子平移后仍在棋盘内；越界时只播放回弹，不调用 `onSwapCards`。后端继续保留最终规则裁决；`puzzle-clear 坐标无效`、缺卡、非 playing、超时这类玩法动作校验错误应映射为 400，避免误判为网关问题。
|
||||
- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx` 覆盖“已拼接局部拖到会越界的位置时只回弹不提交后端动作”；`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 通过。
|
||||
- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`server-rs/crates/module-puzzle-clear/src/application.rs`、`server-rs/crates/api-server/src/puzzle_clear.rs`。
|
||||
|
||||
## 拼消消多行局部拼合要按连通块整体锁定和拖起
|
||||
|
||||
- 现象：`2x2` 或 `2x3` 图案拼成 L 形、转角或多行局部后，玩家拖起已拼合组时会看到有一张卡没有被拿起，仍留在格子层里，并被格子白底或锁定组覆盖层压住。
|
||||
- 原因：半锁定局部拼接组如果只按 `partY/partX` 排序后的线性相邻关系判断，会漏掉 2D 形状里的分叉 / 转角连通块；前端如果只隐藏起点和线性邻格，也会让未写入同一 `lockedGroupId` 的卡继续按普通格子层渲染。
|
||||
- 处理：本地草稿 runtime 和 Rust `module-puzzle-clear` 都要按同组卡牌“素材坐标相邻且棋盘格相邻”的连通块识别半锁定组，`1x3`、`2x2`、`2x3` 的局部拼合必须整体写入同一个 `lockedGroupId`。前端拖起锁定组时，活动组覆盖层不再渲染；组内所有源格标记为 `drag-group-source`，格子层不渲染卡图，只保留透明空槽，卡图只出现在 `document.body` portal 里的 drag ghost。
|
||||
- 验证：`npm run test -- src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx src/services/puzzle-clear/puzzleClearLocalRuntime.test.ts`、`cargo test -p module-puzzle-clear --manifest-path server-rs/Cargo.toml`。
|
||||
- 关联：`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx`、`src/services/puzzle-clear/puzzleClearLocalRuntime.ts`、`server-rs/crates/module-puzzle-clear/src/application.rs`、`src/index.css`。
|
||||
|
||||
## 拼消消空格位必须允许落位，不能当成不可交互死格
|
||||
|
||||
- 现象：运行到某一关后，棋盘里出现空格位，用户能看见空洞但拖不进去，也点不动。
|
||||
@@ -2130,32 +2039,24 @@
|
||||
|
||||
- 现象：跳一跳松手后如果后端很快返回下一帧 run，地块窗口会立刻前移，角色翻腾动画看起来像没播放；若同时刷新图片资产，还可能被误认为地块频闪。
|
||||
- 原因：后端 run 是规则真相，前端 runtime 又需要低延迟表现。如果 DOM 平台层直接用最新 `run.currentPlatformIndex` 渲染，后端回包会抢在动画前完成视觉切换。
|
||||
- 处理：前端保留独立 `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 且下一跳不会被旧地块保留态阻塞。
|
||||
- 处理：前端保留独立 `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`。
|
||||
- 关联：`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 原型地块。Three.js 平台层接入后，如果隐藏预加载只让浏览器缓存 `<img>`，但没有把未来 `platformId` 的纹理 URL 写入 `platformTextureUrlsByRenderKey`，相机推进时新预览地块会短暂缺 Three 贴图；若旧 blob 贴图在空 URL 回调时先被 revoke，再继续保留在 state 中，也会留下一个看似 ready、实际已失效的贴图地址。
|
||||
- 处理：exiting 地块继续使用稳定 `platformId` key，让旧图片组件在推进期复用；有真实 `resolvedUrl` 且未错误时直接保留真实 `<img>`，只在无 URL 或加载失败时显示 fallback；当前 3 块之外的后续地块通过隐藏预加载图片提前解析签名 URL 和浏览器缓存，并同步按未来 `platformId` 发布 Three 纹理 URL。Three 平台层在当前 render items 全部有贴图 URL 后继续承接包含 exiting 地块在内的 3D 渲染；退出地块只随相机推进自然离屏，不播放独立飞走动画，避免退出期露出被放大的平面贴图或重复飞多次；贴图 URL 替换必须等新 URL 到达后再释放旧 parent-owned blob，空 URL 回调不得清空或 revoke 仍在活跃 / 预加载 key 上的旧贴图。
|
||||
- 原因：旧地块进入 exiting 状态时如果 React key 从 `platformId` 变成 `platformId-exiting`，图片组件会重新挂载并丢失已加载状态；同时 `JumpHopTileImage` 曾在真实图片 URL 已存在但 `onLoad` 尚未触发时显示 fallback 原型地块。
|
||||
- 处理：exiting 地块继续使用稳定 `platformId` key，让旧图片组件在推进期复用；有真实 `resolvedUrl` 且未错误时直接保留真实 `<img>`，只在无 URL 或加载失败时显示 fallback；当前 3 块之外的后续地块通过隐藏预加载图片提前解析签名 URL 和浏览器缓存。
|
||||
- 验证：`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 坐标
|
||||
## 跳一跳地块抠图不要用绿幕或近白底识别
|
||||
|
||||
- 现象：视觉上下一块地块在角色右侧，但蓄力引导和角色飞行动画朝左侧；后端回包后地块窗口又闪现摆回正确位置，像是先按反方向飞、再由快照刷新纠正。
|
||||
- 原因：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。
|
||||
- 现象：跳一跳生成草地、花、雪地、白石或云朵地块时，透明化会把绿色 / 白色主体局部扣掉，运行态看到平台缺口、变薄或主体消失。
|
||||
- 原因：通用图集默认按绿幕和近白底做透明化，适合 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 与绿 / 白地块切片。
|
||||
- 关联：`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 源码
|
||||
@@ -2174,22 +2075,6 @@
|
||||
- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "puzzle draft generation auto starts trial and runtime back opens draft result"`。
|
||||
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 推荐页 ready 不能只等主图或首次 DOM 图片
|
||||
|
||||
- 现象：移动端推荐页卡面遮罩在作品主图加载后就渐隐，但游戏内 UI 图集、背景、道具图或换签中的 generated 图片还没有准备好，用户会看到运行态半成品或资源闪入。
|
||||
- 原因：推荐页 ready probe 如果只扫描首次挂载时已有的 `<img>`，就会漏掉 React effect、`/api/assets/read-url` 换签、spritesheet 解析或后续 state 更新才新增的资源。
|
||||
- 处理：推荐页 runtime 遮罩必须持续观察运行态 DOM 内新增图片、内联 `background-image` 和 `data-runtime-resource-pending` 隐藏标记；各玩法对换签中、解析中的资源源头要暴露 pending 标记，失败后释放标记并交给玩法兜底，避免遮罩永久卡住。
|
||||
- 验证：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "mobile recommend cover waits for async runtime resources beyond the main image|mobile recommend cover waits until runtime images are ready"`。
|
||||
- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/common/RuntimeResourcePendingMarker.tsx`、`src/components/ResolvedAssetImage.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 拼图文字直创的 compile 回包不等于生成完成
|
||||
|
||||
- 现象：只输入文字点击生成拼图时，页面刚进入生成页就弹出“生成任务已完成，可以继续查看草稿。”，随后又提示“请先选择一张正式拼图图片。”，结果页关卡里也没有图。
|
||||
- 原因：统一创作表单路径把 `compile_puzzle_draft` 的同步回包无条件当成 ready；但后端在 AI 重绘路径会先返回 `stage=image_refining`、`progressPercent=88` 的会话，只表示首关草稿已编译且后台首图 / UI 资产任务已启动，还没有正式封面或候选图。
|
||||
- 处理：前端必须继续用 `isPuzzleCompileActionReady(...)` 判断回包 session；没有 `draft.coverImageSrc`、首关 `coverImageSrc` 或候选图时保持生成中，不弹完成、不把作品架 pending 标 ready、不自动试玩。生成页轮询合并 session 进度时，未进入编译态或进度无变化就返回原 state，避免轮询制造重复 render。
|
||||
- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "puzzle text-only form stays generating|puzzle draft generation auto starts trial|running puzzle draft opens generation progress"`。
|
||||
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## CreativeImageInputPanel 主图点击默认预览
|
||||
|
||||
- 现象：复用 `CreativeImageInputPanel` 的结果页 / 编辑页已有主图时，用户点击图片却触发上传，无法直接查看大图；不同玩法若各自手写上传按钮会让主图、历史图、AI 重绘和参考图行为再次分叉。
|
||||
@@ -2200,41 +2085,8 @@
|
||||
|
||||
## 统一创作页短表单软键盘打开不要露出黑底
|
||||
|
||||
- 现象：小程序 / H5 移动端点击拼图或敲木鱼创作输入框后，输入框和键盘之间出现一大片黑色区域；H5 还会明显弹一下。跳一跳因为按钮区用 `mt-auto` 撑开页面，看起来没有同样问题。
|
||||
- 原因：旧移动键盘处理会用 `--platform-keyboard-focus-offset` 把 `.platform-viewport-shell` 整体上移；但 H5 浏览器和小程序 `web-view` 已会自行处理输入框可见性，二次整体上移会造成页面弹跳并露出 `body` 或原生 `page` 的黑色宿主底色。统一创作短表单若内容区按短内容收缩，也会放大这个黑底暴露。
|
||||
- 处理：`UnifiedCreationPage` 根容器必须保留 `bg-[image:var(--platform-body-fill)]` 和 `overscroll-contain`，内容区必须用 `flex-1 min-h-0` 占满统一页剩余高度；移动端键盘打开时只记录 `data-mobile-keyboard-open`、隐藏底部 dock、设置键盘 inset 和浅色 `--platform-keyboard-exposed-fill`，不要再对 `.platform-viewport-shell` 做全局 `transform`；小程序 `pages/web-view` 的 `page` 和 web-view class 也要用浅色背景。不要只给某个玩法工作台单独加高度补丁。
|
||||
- 验证：`npm run test -- src/components/unified-creation/UnifiedCreationPage.test.tsx src/components/unified-creation/UnifiedCreationWorkspace.test.tsx src/mobileViewportKeyboardFocus.test.ts src/index.test.ts miniprogram/pages/web-view/index.style.test.js`；移动端点击拼图、敲木鱼、跳一跳输入框时，页面不应整体弹起，键盘上方应持续显示平台浅色背景。
|
||||
- 关联：`src/components/unified-creation/UnifiedCreationPage.tsx`、`src/mobileViewportKeyboardFocus.ts`、`src/index.css`、`miniprogram/pages/web-view/index.wxml`、`miniprogram/pages/web-view/index.wxss`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 小程序订阅消息授权不要依赖 web-view bindmessage
|
||||
|
||||
- 现象：拼图点击生成后，H5 以为已经请求了生成结果订阅授权，但小程序没有弹出 `wx.requestSubscribeMessage` 授权框。
|
||||
- 原因：`web-view bindmessage` / `wx.miniProgram.postMessage` 不适合承接“当前用户点击后立刻请求授权”的时序，消息可能等到 web-view 后退、分享或销毁时才派发，导致授权请求没有发生在 `compile_puzzle_draft` 前。
|
||||
- 处理：不要在原生页 `onLoad` 自动触发 `wx.requestSubscribeMessage`，真机会闪页返回且不弹授权框。H5 在 `compile_puzzle_draft` 前应先进入生成进度态并立即发起生成 action，再通过微信 JS SDK `miniProgram.navigateTo` 非阻塞跳转到小程序原生订阅页尝试请求授权；用户接受、拒绝或返回都不能阻塞生成。原生页不要改写上一页 `webViewUrl`，否则 web-view 可能重新加载首页并丢失进度页状态。后端发送订阅消息仍只允许在拼图资产成功或失败终态后执行。
|
||||
- 验证：`npm run test -- src/services/wechatMiniProgramSubscribe.test.ts miniprogram/pages/subscribe-message/index.test.js`。
|
||||
- 关联：`src/services/wechatMiniProgramSubscribe.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`miniprogram/pages/subscribe-message/index.shared.js`、`miniprogram/pages/web-view/index.js`。
|
||||
|
||||
## 微信订阅消息 time 字段不能用内部时间戳
|
||||
|
||||
- 现象：dev 服务器拼图资产生成终态后已经调用订阅消息发送，但日志出现 `微信订阅消息发送失败：argument invalid! data.time4.value invalid`，用户收不到生成结果通知。
|
||||
- 原因：微信模板 `time` 字段不接受内部微秒时间戳、秒级时间戳或带 `Z` / 时区后缀的字符串；发送 `1713686401.234567Z` 或类似 `2026-06-08 08:09:18Z` 会被微信拒绝。
|
||||
- 处理：`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=<id>` 后应能恢复到后端真实状态；同一 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`。
|
||||
|
||||
## SpacetimeDB 连接池租约必须有 Drop 兜底，acquire 不允许无界自旋
|
||||
|
||||
- 现象：release 上 api-server 周期性出现全量 `spacetime_stage="pool_acquire" elapsed_ms=45000` 业务超时，`/readyz` 503（`reason=spacetime_unhealthy, stage=pool_acquire`），`/healthz` 仍 200，只有重启能恢复，过若干小时复发。
|
||||
- 原因：旧 `PooledConnectionLease` 只能显式 `release_connection` 归还；HTTP 请求方在等待 StDB 回包期间断开时 handler future 被取消，permit 自动归还但槽位 `in_use` 永不复位。后续 acquire 在拿到 permit 后进入无界 `loop + yield_now` 扫描空闲槽位，泄漏积累到 pool_size 后整池挂死。
|
||||
- 处理：租约持有 `Arc<SpacetimeConnectionPool>` 并实现 `Drop` 统一复位槽位/归还连接；槽位改 `AtomicBool` CAS 抢占，删除自旋循环（持有 permit 必然命中空闲槽位）。任何新的"显式归还"资源在 async 取消语义下都要先想 Drop 兜底。
|
||||
- 验证：`cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`（`dropped_lease_releases_slot_and_permit`、`acquire_times_out_at_pool_acquire_when_pool_is_busy`）。
|
||||
- 关联：`server-rs/crates/spacetime-client/src/lib.rs`、`docs/【后端架构】SpacetimeDB连接池租约Drop兜底与取消安全-2026-06-11.md`。
|
||||
- 现象：小程序 / 移动端点击拼图或敲木鱼创作输入框后，输入框和键盘之间出现一大片黑色区域；跳一跳因为按钮区用 `mt-auto` 撑开页面，看起来没有同样问题。
|
||||
- 原因：移动键盘处理会用 `--platform-keyboard-focus-offset` 把 `.platform-viewport-shell` 整体上移；`UnifiedCreationPage` 内容区如果用 `min-h-max` 按短内容收缩，且统一页自身没有平台背景，键盘压缩或位移动画期间会露出 `body` 的黑色宿主底色。
|
||||
- 处理：`UnifiedCreationPage` 根容器必须保留 `bg-[image:var(--platform-body-fill)]` 和 `overscroll-contain`，内容区必须用 `flex-1 min-h-0` 占满统一页剩余高度；不要只给某个玩法工作台单独加高度补丁。
|
||||
- 验证：`npm run test -- src/components/unified-creation/UnifiedCreationPage.test.tsx src/components/unified-creation/UnifiedCreationWorkspace.test.tsx`；移动端点击拼图、敲木鱼、跳一跳输入框时，键盘上方应持续显示平台浅色背景。
|
||||
- 关联：`src/components/unified-creation/UnifiedCreationPage.tsx`、`src/mobileViewportKeyboardFocus.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
@@ -34,7 +34,7 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A
|
||||
server-rs + Axum + SpacetimeDB
|
||||
```
|
||||
|
||||
当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.4.1` 对齐。
|
||||
当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.3.0` 对齐。
|
||||
|
||||
职责边界：
|
||||
|
||||
|
||||
@@ -20,7 +20,6 @@ import type {
|
||||
AdminUpsertProfileRechargeProductRequest,
|
||||
AdminUpsertProfileRedeemCodeRequest,
|
||||
AdminUpsertProfileTaskConfigRequest,
|
||||
AdminUpsertPublicWorkInteractionConfigRequest,
|
||||
AdminWorkVisibilityListResponse,
|
||||
ApiErrorEnvelope,
|
||||
ApiMeta,
|
||||
@@ -130,16 +129,16 @@ export async function request<T>(
|
||||
export function loginAdmin(username: string, password: string) {
|
||||
return request<AdminLoginResponse>('/admin/api/login', {
|
||||
method: 'POST',
|
||||
body: { username, password },
|
||||
body: {username, password},
|
||||
});
|
||||
}
|
||||
|
||||
export function getAdminMe(token: string) {
|
||||
return request<AdminMeResponse>('/admin/api/me', { token });
|
||||
return request<AdminMeResponse>('/admin/api/me', {token});
|
||||
}
|
||||
|
||||
export function getAdminOverview(token: string) {
|
||||
return request<AdminOverviewResponse>('/admin/api/overview', { token });
|
||||
return request<AdminOverviewResponse>('/admin/api/overview', {token});
|
||||
}
|
||||
|
||||
export function getAdminDatabaseTables(token: string) {
|
||||
@@ -155,7 +154,7 @@ export function getAdminDatabaseTableRows(
|
||||
) {
|
||||
return request<AdminDatabaseTableRowsResponse>(
|
||||
`/admin/api/database/tables/${encodeURIComponent(tableName)}/rows${buildDatabaseTableRowsQuery(query)}`,
|
||||
{ token },
|
||||
{token},
|
||||
);
|
||||
}
|
||||
|
||||
@@ -173,14 +172,15 @@ export function listAdminTrackingEvents(
|
||||
) {
|
||||
return request<AdminTrackingEventListResponse>(
|
||||
`/admin/api/tracking/events${buildQueryString(query)}`,
|
||||
{ token },
|
||||
{token},
|
||||
);
|
||||
}
|
||||
|
||||
|
||||
export function getAdminCreationEntryConfig(token: string) {
|
||||
return request<AdminCreationEntryConfigResponse>(
|
||||
'/admin/api/creation-entry/config',
|
||||
{ token },
|
||||
{token},
|
||||
);
|
||||
}
|
||||
|
||||
@@ -213,25 +213,10 @@ export function upsertAdminCreationEntryBanners(
|
||||
);
|
||||
}
|
||||
|
||||
/** 保存公开作品详情页点赞 / 改造能力配置。 */
|
||||
export function upsertAdminPublicWorkInteractions(
|
||||
token: string,
|
||||
payload: AdminUpsertPublicWorkInteractionConfigRequest,
|
||||
) {
|
||||
return request<AdminCreationEntryConfigResponse>(
|
||||
'/admin/api/creation-entry/config/interactions',
|
||||
{
|
||||
method: 'POST',
|
||||
token,
|
||||
body: payload,
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
export function listAdminWorkVisibility(token: string) {
|
||||
return request<AdminWorkVisibilityListResponse>(
|
||||
'/admin/api/works/visibility',
|
||||
{ token },
|
||||
{token},
|
||||
);
|
||||
}
|
||||
|
||||
@@ -252,7 +237,7 @@ export function updateAdminWorkVisibility(
|
||||
export function listProfileRedeemCodes(token: string) {
|
||||
return request<ProfileRedeemCodeAdminListResponse>(
|
||||
'/admin/api/profile/redeem-codes',
|
||||
{ token },
|
||||
{token},
|
||||
);
|
||||
}
|
||||
|
||||
@@ -273,7 +258,7 @@ export function upsertProfileRedeemCode(
|
||||
export function listProfileInviteCodes(token: string) {
|
||||
return request<ProfileInviteCodeAdminListResponse>(
|
||||
'/admin/api/profile/invite-codes',
|
||||
{ token },
|
||||
{token},
|
||||
);
|
||||
}
|
||||
|
||||
@@ -308,7 +293,7 @@ export function disableProfileRedeemCode(
|
||||
export function listProfileTaskConfigs(token: string) {
|
||||
return request<ProfileTaskConfigAdminListResponse>(
|
||||
'/admin/api/profile/tasks',
|
||||
{ token },
|
||||
{token},
|
||||
);
|
||||
}
|
||||
|
||||
@@ -340,7 +325,7 @@ export function disableProfileTaskConfig(
|
||||
export function listProfileRechargeProducts(token: string) {
|
||||
return request<ProfileRechargeProductConfigAdminListResponse>(
|
||||
'/admin/api/profile/recharge-products',
|
||||
{ token },
|
||||
{token},
|
||||
);
|
||||
}
|
||||
|
||||
@@ -429,13 +414,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 =
|
||||
|
||||
@@ -107,7 +107,12 @@ 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;
|
||||
@@ -138,11 +143,11 @@ export interface AdminTrackingEventListQuery {
|
||||
limit?: number;
|
||||
}
|
||||
|
||||
|
||||
/** 后台创作入口配置响应，同时包含模板入口和独立公告配置。 */
|
||||
export interface AdminCreationEntryConfigResponse {
|
||||
entries: AdminCreationEntryTypeConfigPayload[];
|
||||
eventBanners: AdminCreationEntryEventBannerPayload[];
|
||||
publicWorkInteractions: PublicWorkInteractionConfigPayload[];
|
||||
}
|
||||
|
||||
/** 后台创作入口公告位配置项；旧结构化 banner 字段仅保留兼容。 */
|
||||
@@ -196,25 +201,10 @@ 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;
|
||||
title: string;
|
||||
mudPointCost: number;
|
||||
workspaceStage: string;
|
||||
generationStage: string;
|
||||
resultStage: string;
|
||||
|
||||
@@ -1,26 +1,19 @@
|
||||
/* @vitest-environment jsdom */
|
||||
|
||||
import {
|
||||
fireEvent,
|
||||
render,
|
||||
screen,
|
||||
waitFor,
|
||||
within,
|
||||
} from '@testing-library/react';
|
||||
import {fireEvent, render, screen, waitFor} 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) =>
|
||||
@@ -30,13 +23,11 @@ vi.mock('../api/adminApiClient', () => ({
|
||||
isAdminApiError: vi.fn(() => false),
|
||||
upsertAdminCreationEntryBanners: vi.fn(),
|
||||
upsertAdminCreationEntryConfig: vi.fn(),
|
||||
upsertAdminPublicWorkInteractions: vi.fn(),
|
||||
}));
|
||||
|
||||
const puzzleSpec: UnifiedCreationSpecPayload = {
|
||||
playId: 'puzzle',
|
||||
title: '拼图',
|
||||
mudPointCost: 10,
|
||||
workspaceStage: 'puzzle-agent-workspace',
|
||||
generationStage: 'puzzle-generating',
|
||||
resultStage: 'puzzle-result',
|
||||
@@ -63,15 +54,6 @@ const configResponse: AdminCreationEntryConfigResponse = {
|
||||
htmlCode: '<section>后台公告</section>',
|
||||
},
|
||||
],
|
||||
publicWorkInteractions: [
|
||||
{
|
||||
sourceType: 'puzzle',
|
||||
likeEnabled: true,
|
||||
remixEnabled: true,
|
||||
likeDisabledMessage: '拼图点赞暂不可用。',
|
||||
remixDisabledMessage: '拼图作品改造暂不可用。',
|
||||
},
|
||||
],
|
||||
entries: [
|
||||
{
|
||||
id: 'puzzle',
|
||||
@@ -96,58 +78,31 @@ 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(
|
||||
<AdminCreationEntrySwitchPage
|
||||
token="admin-token"
|
||||
onUnauthorized={vi.fn()}
|
||||
/>,
|
||||
const {container} = render(
|
||||
<AdminCreationEntrySwitchPage token="admin-token" onUnauthorized={vi.fn()} />,
|
||||
);
|
||||
|
||||
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('拼图');
|
||||
expect(container.querySelector('.admin-panel .admin-panel')).toBeNull();
|
||||
expect(container.querySelector('.admin-muted')).toBeNull();
|
||||
expect(screen.queryByLabelText('契约 JSON')).toBeNull();
|
||||
expect(screen.queryByText('puzzle-generating')).toBeNull();
|
||||
|
||||
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' },
|
||||
});
|
||||
await user.click(within(dialog).getByRole('button', { name: '应用修改' }));
|
||||
|
||||
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(
|
||||
'admin-token',
|
||||
expect.objectContaining({
|
||||
id: 'puzzle',
|
||||
unifiedCreationSpec: {
|
||||
...puzzleSpec,
|
||||
mudPointCost: 12,
|
||||
},
|
||||
unifiedCreationSpec: puzzleSpec,
|
||||
}),
|
||||
);
|
||||
});
|
||||
@@ -155,18 +110,6 @@ test('创作入口后台展示并保存统一创作契约', async () => {
|
||||
|
||||
test('创作入口后台拒绝 playId 不一致的统一创作契约', async () => {
|
||||
const user = userEvent.setup();
|
||||
vi.mocked(getAdminCreationEntryConfig).mockResolvedValueOnce({
|
||||
...configResponse,
|
||||
entries: [
|
||||
{
|
||||
...configResponse.entries[0]!,
|
||||
unifiedCreationSpec: {
|
||||
...puzzleSpec,
|
||||
playId: 'match3d',
|
||||
},
|
||||
},
|
||||
],
|
||||
});
|
||||
render(
|
||||
<AdminCreationEntrySwitchPage
|
||||
token="admin-token"
|
||||
@@ -174,12 +117,18 @@ test('创作入口后台拒绝 playId 不一致的统一创作契约', async ()
|
||||
/>,
|
||||
);
|
||||
|
||||
await screen.findByText('pictureDescription');
|
||||
await user.click(screen.getByRole('button', { name: '保存入库' }));
|
||||
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(await screen.findByText('统一创作契约 playId 必须与入口 ID 一致')).toBeTruthy();
|
||||
expect(upsertAdminCreationEntryConfig).not.toHaveBeenCalled();
|
||||
});
|
||||
|
||||
@@ -193,25 +142,23 @@ 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: '<section>新的入口公告</section>' },
|
||||
target: {value: '<section>新的入口公告</section>'},
|
||||
});
|
||||
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: '<section>轮播第二条</section>' },
|
||||
target: {value: '<section>轮播第二条</section>'},
|
||||
});
|
||||
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();
|
||||
@@ -235,42 +182,6 @@ test('创作入口后台用表单保存公告配置', async () => {
|
||||
);
|
||||
});
|
||||
|
||||
test('创作入口后台用表单保存作品互动配置', async () => {
|
||||
const user = userEvent.setup();
|
||||
render(
|
||||
<AdminCreationEntrySwitchPage
|
||||
token="admin-token"
|
||||
onUnauthorized={vi.fn()}
|
||||
/>,
|
||||
);
|
||||
|
||||
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,
|
||||
@@ -316,12 +227,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();
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -791,67 +791,6 @@ button:disabled {
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
|
||||
.admin-contract-card {
|
||||
display: grid;
|
||||
gap: 12px;
|
||||
border: 1px solid #eaded2;
|
||||
border-radius: 8px;
|
||||
background: #fffdf9;
|
||||
padding: 12px;
|
||||
}
|
||||
|
||||
.admin-contract-field-list,
|
||||
.admin-contract-field-editor-list {
|
||||
display: grid;
|
||||
gap: 10px;
|
||||
}
|
||||
|
||||
.admin-contract-field-list {
|
||||
grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
|
||||
}
|
||||
|
||||
.admin-contract-field-card,
|
||||
.admin-contract-field-editor {
|
||||
display: grid;
|
||||
gap: 6px;
|
||||
border: 1px solid #eaded2;
|
||||
border-radius: 8px;
|
||||
background: #fff8f1;
|
||||
padding: 10px;
|
||||
}
|
||||
|
||||
.admin-contract-field-card strong,
|
||||
.admin-contract-field-card span {
|
||||
min-width: 0;
|
||||
overflow-wrap: anywhere;
|
||||
}
|
||||
|
||||
.admin-contract-field-card strong {
|
||||
color: #3d1f10;
|
||||
font-size: 13px;
|
||||
}
|
||||
|
||||
.admin-contract-field-card span {
|
||||
color: #8f7868;
|
||||
font-size: 12px;
|
||||
font-weight: 650;
|
||||
}
|
||||
|
||||
.admin-contract-dialog {
|
||||
width: min(100%, 860px);
|
||||
}
|
||||
|
||||
.admin-contract-field-editor-grid {
|
||||
display: grid;
|
||||
grid-template-columns: minmax(0, 1.1fr) minmax(120px, 0.6fr) minmax(0, 1fr) auto;
|
||||
gap: 10px;
|
||||
align-items: end;
|
||||
}
|
||||
|
||||
.admin-contract-required-toggle {
|
||||
min-height: 42px;
|
||||
}
|
||||
|
||||
.admin-status {
|
||||
display: inline-flex;
|
||||
max-width: 460px;
|
||||
@@ -1009,8 +948,7 @@ button:disabled {
|
||||
.admin-two-column-wide,
|
||||
.admin-form-row,
|
||||
.admin-filter-grid,
|
||||
.admin-table-query-grid,
|
||||
.admin-contract-field-editor-grid {
|
||||
.admin-table-query-grid {
|
||||
grid-template-columns: 1fr;
|
||||
}
|
||||
|
||||
|
||||
@@ -55,7 +55,7 @@ Linux Docker Engine 若要从宿主机 CLI 连到容器内服务，直接用 `ht
|
||||
|
||||
## 构建工具链
|
||||
|
||||
`api-server` 容器镜像只构建 Linux release API 二进制，不构建 `spacetime-module`。当前 `api-server -> spacetime-client -> spacetimedb-sdk 2.4.1` 依赖链要求 Rust 1.93，因此 `deploy/container/api-server.Dockerfile` 的 Rust builder 固定为 `rust:1.93-bookworm`。如果本机 Docker Hub 拉取失败，可以先在本机准备同名本地 builder 镜像，但不要把临时 bootstrap 容器或私有 registry 凭据写入仓库。
|
||||
`api-server` 容器镜像只构建 Linux release API 二进制，不构建 `spacetime-module`。当前 `api-server -> spacetime-client -> spacetimedb-sdk 2.3.0` 依赖链要求 Rust 1.93，因此 `deploy/container/api-server.Dockerfile` 的 Rust builder 固定为 `rust:1.93-bookworm`。如果本机 Docker Hub 拉取失败，可以先在本机准备同名本地 builder 镜像，但不要把临时 bootstrap 容器或私有 registry 凭据写入仓库。
|
||||
|
||||
## 启动与验证
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@ name: genarrative-container-loadtest
|
||||
|
||||
services:
|
||||
spacetimedb:
|
||||
image: clockworklabs/spacetime:v2.4.1
|
||||
image: clockworklabs/spacetime:v2.3.0
|
||||
user: root
|
||||
command:
|
||||
[
|
||||
|
||||
@@ -9,9 +9,10 @@ User=root
|
||||
Group=root
|
||||
WorkingDirectory=/opt/genarrative/current
|
||||
EnvironmentFile=/etc/genarrative/api-server.env
|
||||
ExecStart=/usr/bin/node /opt/genarrative/current/scripts/database-backup-to-oss.mjs --env-file /etc/genarrative/api-server.env --stop-service spacetimedb.service --restart-service-after genarrative-api.service
|
||||
ExecStart=/usr/bin/node /opt/genarrative/current/scripts/database-backup-to-oss.mjs --env-file /etc/genarrative/api-server.env --stop-service spacetimedb.service
|
||||
|
||||
# 备份需要停止 / 启动 spacetimedb.service，并读取 /stdb、写入 /var/lib/genarrative/database-backups。
|
||||
PrivateTmp=true
|
||||
ProtectSystem=full
|
||||
ReadWritePaths=/stdb /var/lib/genarrative
|
||||
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
[Unit]
|
||||
Description=Genarrative Production Health Patrol
|
||||
After=network-online.target genarrative-api.service spacetimedb.service nginx.service
|
||||
Wants=network-online.target
|
||||
ConditionPathExists=/opt/genarrative/current/scripts/ops/production-health-patrol.mjs
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
User=root
|
||||
Group=root
|
||||
WorkingDirectory=/opt/genarrative/current
|
||||
EnvironmentFile=-/etc/genarrative/health-patrol.env
|
||||
ExecStart=/usr/bin/node /opt/genarrative/current/scripts/ops/production-health-patrol.mjs --status-file /var/lib/genarrative/health-patrol/status.json
|
||||
TimeoutStartSec=30
|
||||
|
||||
# 巡检只读 systemd、HTTP 和 journal；只允许写入自己的最近一次状态文件。
|
||||
NoNewPrivileges=true
|
||||
PrivateTmp=true
|
||||
ProtectSystem=full
|
||||
ReadWritePaths=/var/lib/genarrative/health-patrol
|
||||
@@ -1,13 +0,0 @@
|
||||
[Unit]
|
||||
Description=Run Genarrative Production Health Patrol
|
||||
|
||||
[Timer]
|
||||
OnBootSec=2min
|
||||
OnCalendar=*-*-* *:0/5:00
|
||||
Persistent=true
|
||||
RandomizedDelaySec=30
|
||||
AccuracySec=30s
|
||||
Unit=genarrative-health-patrol.service
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
@@ -21,8 +21,6 @@
|
||||
|
||||
微信小程序虚拟支付接入、`wechat_mp_virtual` 渠道、`wx.requestVirtualPayment` 承接页和后端签名配置见 [【技术方案】微信虚拟支付接入-2026-05-26.md](./%E3%80%90%E6%8A%80%E6%9C%AF%E6%96%B9%E6%A1%88%E3%80%91%E5%BE%AE%E4%BF%A1%E8%99%9A%E6%8B%9F%E6%94%AF%E4%BB%98%E6%8E%A5%E5%85%A5-2026-05-26.md)。
|
||||
|
||||
本地通过 SSH alias 管理多台服务器、查看硬件 / systemd / HTTP 健康状态并执行受控服务启停的 egui 桌面工具见 [【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md](./technical/【开发运维】本地SSH服务器管理面板技术方案-2026-06-11.md)。
|
||||
|
||||
生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。
|
||||
|
||||
SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)。
|
||||
@@ -39,76 +37,6 @@ SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段
|
||||
|
||||
AI 文字游戏模板接入以 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md) 为最新口径：只吸收 MOKU / 幕间类 AI 文游的剧本游乐场、自由行动、AI GM、记忆和模拟器强反馈经验，禁止迁入外部社区、支付、榜单、私有存档或回放。
|
||||
|
||||
前端 Server-Sent Events 客户端传输层收口到 `src/services/sseStream.ts`，事件边界、UTF-8 flush、JSON 解析跳过和提前取消约定见 [【前端架构】SSE客户端传输层收口约定-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91SSE%E5%AE%A2%E6%88%B7%E7%AB%AF%E4%BC%A0%E8%BE%93%E5%B1%82%E6%94%B6%E5%8F%A3%E7%BA%A6%E5%AE%9A-2026-06-03.md)。
|
||||
|
||||
平台入口公开作品身份、跨玩法去重、公开作品流聚合、推荐运行态 kind 判定、推荐 runtime 启动意图、ready 判定和最新排序收口到 `src/components/platform-entry/platformPublicGalleryFlow.ts`，规则见 [【前端架构】平台入口PublicGalleryFlowModule收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91%E5%B9%B3%E5%8F%B0%E5%85%A5%E5%8F%A3PublicGalleryFlowModule%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
统一作品详情页的玩法 kind、详情打开策略、自有作品动作模式、编辑 / 点赞 / 改造 / 启动意图和公开详情映射收口到 `src/components/platform-entry/platformPublicWorkDetailFlow.ts`；抓大鹅公开详情映射与启动 / 编辑 Adapter 的素材归一仍归 `platformMatch3DRuntimeProfile.ts`，规则见 [【前端架构】PlatformPublicWorkDetailFlow收口计划-2026-06-03.md](./technical/【前端架构】PlatformPublicWorkDetailFlow收口计划-2026-06-03.md)。
|
||||
|
||||
创作中心作品架打开动作由 `CreationWorkShelfItem.actions.open` 统一承载，生产 Hub 只接收 `CreationWorkShelfItem[]` 与 UI 状态，不再接收各玩法 raw items 和回调列阵，规则见 [【前端架构】WorkShelfModule收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91WorkShelfModule%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
作品架删除确认的标题、删除说明、草稿 notice key 和拼图派生稳定 ID 收口到 `src/components/platform-entry/platformCreationWorkDeleteFlow.ts`，平台壳只保留删除 API、刷新、错误和页面跳转副作用，规则见 [【前端架构】CreationWorkDeleteFlow收口计划-2026-06-04.md](./technical/【前端架构】CreationWorkDeleteFlow收口计划-2026-06-04.md)。
|
||||
|
||||
创作入口点击的占位、隐藏模板拦截、未知入口 no-op 与工作台启动目标收口到 `src/components/platform-entry/platformCreationLaunchModel.ts`，壳层只执行启动前准备、错误提示和受保护动作，规则见 [【前端架构】PlatformCreationLaunchModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformCreationLaunchModel收口计划-2026-06-04.md)。
|
||||
|
||||
平台入口公开码搜索的用户 ID、陶泥号、RPG 作品号、各玩法作品号前缀、per-play 公开码匹配、详情卡 DTO 映射和失败回退顺序收口到 `src/components/platform-entry/platformPublicCodeSearchModel.ts`，壳层只按计划执行网络读取、详情打开和错误归航副作用，规则见 [【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPublicCodeSearchModel收口计划-2026-06-04.md)。
|
||||
|
||||
个人“玩过作品”面板的玩法别名、`worldKey` 前缀兜底、RPG 公开详情 payload 和大鱼吃小鱼 gallery miss fallback 收口到 `src/components/platform-entry/platformPlayedWorkOpenModel.ts`，壳层只执行面板关闭、gallery 读取、详情打开和错误提示副作用，规则见 [【前端架构】PlatformPlayedWorkOpenModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPlayedWorkOpenModel收口计划-2026-06-04.md)。
|
||||
|
||||
平台入口生成页进度 tick 的 stage 到生成状态映射、终态判定和视觉小说轻量生成特例收口到 `src/components/platform-entry/platformGenerationProgressTickModel.ts`，壳层只保留 `Date.now()`、`setInterval` 和 cleanup 副作用，规则见 [【前端架构】PlatformGenerationProgressTickModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformGenerationProgressTickModel收口计划-2026-06-04.md)。
|
||||
|
||||
平台壳的拼图 runtime 恢复 work、方洞 session draft 转 profile、视觉小说 work detail 转 Agent session、跳一跳 pending session、敲木鱼 detail 恢复 session、敲木鱼生成中作品摘要和敲木鱼 pending session DTO 映射收口到 `src/components/platform-entry/platformMiniGameSessionMappingModel.ts`，壳层只保留网络、状态、URL 与 stage 副作用，规则见 [【前端架构】PlatformMiniGameSessionMappingModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformMiniGameSessionMappingModel收口计划-2026-06-04.md)。
|
||||
|
||||
平台小游戏生成状态的恢复、失败 / 完成收尾、展示 rebase、拼图后端进度合并、抓大鹅生成资产旁路进度合并和 ready / generating 判定收口到 `src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts`，壳层只保留 API、后台任务、React state、URL 与 stage 副作用，规则见 [【前端架构】PlatformMiniGameDraftGenerationStateModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformMiniGameDraftGenerationStateModel收口计划-2026-06-04.md)。
|
||||
|
||||
平台小游戏草稿恢复和提交所需的拼图 / 抓大鹅表单 payload、拼图作品更新 payload、拼图编译 action、跳一跳 / 敲木鱼生成 action、pending metadata 与拼图 form-only 草稿判定收口到 `src/components/platform-entry/platformMiniGameDraftPayloadModel.ts`，壳层只保留 API、Action 执行、background task 与状态副作用，规则见 [【前端架构】PlatformMiniGameDraftPayloadModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformMiniGameDraftPayloadModel收口计划-2026-06-04.md)。
|
||||
|
||||
平台拼图生成完成后刷新恢复的草稿归一化与可恢复完成态判定收口到 `src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts`，恢复链路只有在首图、关卡画面、UI spritesheet 与关卡背景资产包完整时才抬为 ready，规则见 [【前端架构】PlatformPuzzleDraftRecoveryModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPuzzleDraftRecoveryModel收口计划-2026-06-04.md)。
|
||||
|
||||
拼图排行榜提交回包后的服务端 run 快照合并收口到 `src/components/platform-entry/platformPuzzleRuntimeStateModel.ts`，只合并排行榜、run 身份、通关数上限和下一关 handoff，保留前端即时裁决的关卡状态与棋盘，规则见 [【前端架构】PlatformPuzzleRuntimeStateModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformPuzzleRuntimeStateModel收口计划-2026-06-04.md)。
|
||||
|
||||
后端拼图发布 / 待发布门槛收紧到首图、关卡画面、UI spritesheet 与关卡背景资产包完整，`module-puzzle` 的 preview blockers 与 `api-server` 的 session stage 判定保持同一规则，方案见 [【后端架构】PuzzlePublishAssetGate收紧计划-2026-06-04.md](./technical/【后端架构】PuzzlePublishAssetGate收紧计划-2026-06-04.md)。
|
||||
|
||||
平台入口个人钱包本地 delta、dashboard 乐观更新与服务端快照对账规则收口到 `src/components/platform-entry/platformProfileWalletDeltaModel.ts`，平台壳只保留 API、ref 与 state 副作用，规则见 [【前端架构】PlatformProfileWalletDeltaModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformProfileWalletDeltaModel收口计划-2026-06-04.md)。
|
||||
|
||||
Bark Battle 草稿三图完整性、生成状态归一、作品架摘要恢复草稿配置、发布快照 / 发布回包资产兜底和草稿 / 已发布作品进入 runtime 前的 `BarkBattlePublishedConfig` 映射收口到 `src/components/platform-entry/barkBattleWorkCache.ts`，规则见 [【前端架构】BarkBattleWorkCache草稿状态收口计划-2026-06-04.md](./technical/【前端架构】BarkBattleWorkCache草稿状态收口计划-2026-06-04.md)。
|
||||
|
||||
平台首页推荐 runtime 的匿名 Runtime Guest Token、已登录 background auth、非 embedded no-op 和拼图 isolated/default auth mode 计划收口到 `src/components/platform-entry/platformRecommendRuntimeAuthModel.ts`，规则见 [【前端架构】PlatformRecommendRuntimeAuthModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformRecommendRuntimeAuthModel收口计划-2026-06-04.md)。
|
||||
|
||||
平台首页推荐 runtime 自动启动的桌面 / Tab / stage / loading gate、active entry 查找、ready 判定和 clear/start/noop 决策收口到 `src/components/platform-entry/platformPublicGalleryFlow.ts`，规则见 [【前端架构】PlatformRecommendRuntimeAutoStart收口计划-2026-06-04.md](./technical/【前端架构】PlatformRecommendRuntimeAutoStart收口计划-2026-06-04.md)。
|
||||
|
||||
RPG Agent 结果页发布门禁展示和预览来源 label 收口到 `src/components/platform-entry/platformRpgAgentResultPreviewModel.ts`，壳层只保留 session/profile 编排和结果页 props 传递，规则见 [【前端架构】PlatformRpgAgentResultPreviewModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformRpgAgentResultPreviewModel收口计划-2026-06-04.md)。
|
||||
|
||||
平台入口创作生成通知、pending 作品架占位、作品详情更新回填、失败覆盖、跨玩法草稿打开优先级、拼图稳定 ID 和草稿 Tab 未读点收口到 `src/components/platform-entry/platformDraftGenerationShelfModel.ts`，规则见 [【前端架构】DraftGenerationShelfModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91DraftGenerationShelfModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
平台入口创作恢复 URL 私有 query、初始恢复判定、创作直达恢复目标解析、恢复目标身份匹配、跳一跳 / 敲木鱼恢复阶段落点、拼图 runtime query 与拼图稳定身份互推收口到 `src/components/platform-entry/platformCreationUrlStateModel.ts` 和 `src/components/platform-entry/platformPuzzleIdentityModel.ts`，规则见 [【前端架构】CreationUrlStateModel收口计划-2026-06-03.md](./technical/【前端架构】CreationUrlStateModel收口计划-2026-06-03.md)。
|
||||
|
||||
平台入口错误 / 完成弹窗的文案归一、来源格式、候选择一、dismiss key 与任务完成文案收口到 `src/components/platform-entry/platformDialogStateModel.ts`，规则见 [【前端架构】PlatformDialogStateModel收口计划-2026-06-03.md](./technical/【前端架构】PlatformDialogStateModel收口计划-2026-06-03.md)。
|
||||
|
||||
平台 UI Kit 的提示 / 确认弹窗收口到 `src/components/common/UnifiedConfirmDialog.tsx`，复制反馈收口到 `src/components/common/useCopyFeedback.ts`、`src/components/common/CopyFeedbackButton.tsx`、`src/components/common/CopyCodeButton.tsx` 与 `src/components/common/CopyFeedbackMessage.tsx`，基础状态提示收口到 `src/components/common/PlatformStatusMessage.tsx`，运行态短错误 / 成功 / 反馈 toast 收口到 `src/components/common/PlatformRuntimeStatusToast.tsx`，平台空态 / 轻量加载态收口到 `src/components/common/PlatformEmptyState.tsx`，平台动作按钮收口到 `src/components/common/PlatformActionButton.tsx`，平台白底子面板 / 小型列表卡片收口到 `src/components/common/PlatformSubpanel.tsx`，平台输入框 / 文本域收口到 `src/components/common/PlatformTextField.tsx`，平台字段标题收口到 `src/components/common/PlatformFieldLabel.tsx`，平台媒体预览框收口到 `src/components/common/PlatformMediaFrame.tsx`，平台胶囊状态标签收口到 `src/components/common/PlatformPillBadge.tsx`，平台 / 个人中心弹窗关闭按钮收口到 `src/components/common/PlatformModalCloseButton.tsx`，底层继续复用 `UnifiedModal`；普通提示、确认 / 取消、危险确认、复制状态机、短代码复制 chip、复制按钮表现、白底 / 个人中心 / 认证入口 token 状态条、运行态状态 toast、无操作空态、主动作按钮、白底子面板、白底交互列表卡片、普通输入字段、字段标题、图片源 / fallback / 固定比例媒体预览、单个状态 / 标签 chip 和圆形关闭按钮优先使用公共 Module，规则见 [【前端架构】PlatformUiKit弹窗组件收口计划-2026-06-08.md](./technical/【前端架构】PlatformUiKit弹窗组件收口计划-2026-06-08.md)。
|
||||
|
||||
平台入口受保护数据失效后的 stage 去留判定，以及缺失草稿 / 作品 / run 时的阶段回退，收口到 `src/components/platform-entry/platformSelectionStageModel.ts`，壳层只执行缓存清空、布尔事实汇总和必要跳转，规则见 [【前端架构】PlatformSelectionStageModel收口计划-2026-06-04.md](./technical/【前端架构】PlatformSelectionStageModel收口计划-2026-06-04.md)。
|
||||
|
||||
小游戏 runtime client 的路径编码、JSON 请求、runtime guest auth 与 retry 选项收口到 `src/services/runtimeRequest.ts`，Match3D、SquareHole、Big Fish、Bark Battle、Puzzle 公开 / 推荐运行态请求、Jump Hop / Wooden Fish 正式 run 请求和 Visual Novel 局部 JSON runtime 请求已先迁移，规则见 [【前端架构】RuntimeClientFamily收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91RuntimeClientFamily%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
抓大鹅 runtime profile 的公开详情转 work、session draft 转 profile、生成背景资产提升和 run/profile/public detail 素材优先级收口到 `src/components/platform-entry/platformMatch3DRuntimeProfile.ts`，规则见 [【前端架构】Match3DRuntimeProfile收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91Match3DRuntimeProfile%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
公开作品分类选项、搜索、跨来源去重、今日筛选、排行排序和时间戳解析收口到 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，规则见 [【前端架构】PublicGalleryViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91PublicGalleryViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
公开作品的玩法类型 label、公开作者 lookup 与游玩 / 改造 / 点赞等紧凑计数格式收口到 `src/components/rpg-entry/rpgEntryWorldPresentation.ts`，规则见 [【前端架构】PublicWorkPresentation收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91PublicWorkPresentation%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
推荐 feed 的公开作品去重、普通内容过滤、active 窗口与上一条 / 下一条回环选择也收口到 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，规则见 [【前端架构】RecommendFeedViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91RecommendFeedViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
移动端推荐首页 swipe deck 的拖拽阈值、offset clamp、commit 方向、rail class 和分享文案收口到 `src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.ts`，规则见 [【前端架构】RecommendSwipeDeckModel收口计划-2026-06-03.md](./technical/【前端架构】RecommendSwipeDeckModel收口计划-2026-06-03.md)。
|
||||
|
||||
排行频道的默认 tab、tab 文案、空态文案、排序字段与指标 label/value 收口到 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，规则见 [【前端架构】RankingViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91RankingViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
每日任务卡片与任务中心弹窗的任务选择、进度、状态标签和按钮文案收口到 `src/components/rpg-entry/rpgEntryProfileTaskViewModel.ts`，规则见 [【前端架构】ProfileTaskViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91ProfileTaskViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
个人数据卡、钱包 chip 与“玩过”弹窗的计数、时长、作品类型和作品号展示收口到 `src/components/rpg-entry/rpgEntryProfileDashboardPresentation.ts`，规则见 [【前端架构】ProfileDashboardPresentation收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91ProfileDashboardPresentation%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
个人资金展示的账单来源、金额正负号、余额兜底、充值价格、商品主值和会员摘要收口到 `src/components/rpg-entry/rpgEntryProfileFundsViewModel.ts`，规则见 [【前端架构】ProfileFundsViewModel收口计划-2026-06-03.md](./technical/%E3%80%90%E5%89%8D%E7%AB%AF%E6%9E%B6%E6%9E%84%E3%80%91ProfileFundsViewModel%E6%94%B6%E5%8F%A3%E8%AE%A1%E5%88%92-2026-06-03.md)。
|
||||
|
||||
## 推荐阅读顺序
|
||||
|
||||
1. 先看 [经验沉淀](./experience/README.md)，快速建立这个项目的开发共识。
|
||||
|
||||
@@ -17,8 +17,8 @@
|
||||
- 工作台模式：表单 / 图片输入创作工作台。
|
||||
- 创作链路：入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态。
|
||||
- 单图资产槽位：
|
||||
- `board-background` / `ui-background` / `背景图` / `boardBackgroundPrompt` 优先、空值时回退 `themePrompt`，并支持用户上传图片或填写画面描述生图 / 写回 `draft.boardBackgroundAsset`、`draft.boardBackgroundPrompt`、`work.boardBackgroundAsset` 与 `work.boardBackgroundPrompt` / 允许历史图 / 允许 AI 重绘。
|
||||
- 背景图实际作用是玩家逐步消除清空中央棋盘后慢慢看到的主题目标图；AI 生成尺寸必须与中央棋盘一致，使用 1:1 正方形画面。prompt 必须强绑定主题、画面精致、强表现力并一眼体现主题，带来探索、揭开全貌和追求目标完成的感受；不得继续要求“画面干净”或“适合作为卡牌棋盘底图”。
|
||||
- `board-background` / `ui-background` / `中央场地底图` / `boardBackgroundPrompt` 优先、空值时回退 `themePrompt`，并支持用户上传图 / 写回 `draft.boardBackgroundAsset`、`draft.boardBackgroundPrompt`、`work.boardBackgroundAsset` 与 `work.boardBackgroundPrompt` / 允许历史图 / 允许 AI 重绘。
|
||||
- 中央场地底图的字段名沿用平台表面口径，实际作用是玩家逐步消除清空中央棋盘后慢慢看到的主题目标图；AI 生成尺寸必须与中央棋盘一致，使用 1:1 正方形画面。prompt 必须强绑定主题、画面精致、强表现力并一眼体现主题，带来探索、揭开全貌和追求目标完成的感受；不得继续要求“画面干净”或“适合作为卡牌棋盘底图”。
|
||||
- 系列素材槽位：
|
||||
- `batchId=puzzle-clear-pattern-atlas-v1`。
|
||||
- `sheetSpec`：4 张素材工作表，每张 `1024x1536` 竖版，后台按 `4 列 x 6 行` 裁切，每个 1x1 单元为 `256x256`；服务端再把切片合成一张 `10x10 / 2560x2560` 最终 atlas。复合图案组总数为 `35`，形状配比 `1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`，总计 `95` 个 1x1 卡牌切片。
|
||||
@@ -36,12 +36,12 @@
|
||||
|
||||
| 字段 | 契约字段 | 默认值 | 校验 | 落库 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 卡牌素材主题 | `themePrompt` | 空 | 必填，1-80 字 | 生成 prompt 与草稿；工作台内部派生草稿占位标题，不向用户展示作品标题输入 |
|
||||
| 画面描述 | `boardBackgroundPrompt` | 空 | 0-80 字；为空时背景图生成回退 `themePrompt` | session draft / work profile / 主题目标图生成 prompt |
|
||||
| 背景图 | `boardBackgroundAsset` | 空 | 上传图片或 AI 生成至少一种 | 单图资产槽位 |
|
||||
| AI 生成背景图 | `generateBoardBackground` | `true` | boolean | 生成编排参数 |
|
||||
|
||||
作品标题 `workTitle` 与简介 `workDescription` 不属于工作台游戏内容配置；发布前检查环节必须让用户填写 / 修改标题与简介，保存为 `update-work-meta` 后再发布。工作台阶段只展示玩法标题、卡牌素材主题和背景图配置；背景图可以上传图片，也可以填写画面描述后使用 AI 生成，不再在同一界面混排发布元信息。
|
||||
| 作品标题 | `workTitle` | 空 | 必填，1-30 字 | session draft / work profile |
|
||||
| 简介 | `workDescription` | 空 | 0-120 字 | session draft / work profile |
|
||||
| 主题词 | `themePrompt` | 空 | 必填，1-80 字 | 生成 prompt 与草稿 |
|
||||
| 场地底图主题词 | `boardBackgroundPrompt` | 空 | 0-80 字；为空时底图生成回退 `themePrompt` | session draft / work profile / 主题目标图生成 prompt |
|
||||
| 中央场地底图 | `boardBackgroundAsset` | 空 | 上传或 AI 生成至少一种 | 单图资产槽位 |
|
||||
| AI 生成底图 | `generateBoardBackground` | `true` | boolean | 生成编排参数 |
|
||||
|
||||
规则参数不开放创作者编辑：棋盘尺寸、倒计时、消除次数、形状解锁、防死局发牌和半锁定规则固定。
|
||||
|
||||
@@ -49,24 +49,20 @@
|
||||
|
||||
| 关卡 | 棋盘 | 目标消除 | 倒计时 | 解锁形状 |
|
||||
| --- | --- | --- | --- | --- |
|
||||
| 1 | 6x6 | 15 | 5 分钟 | 1x2 |
|
||||
| 2 | 6x6 | 20 | 5 分钟 | 1x2、1x3 |
|
||||
| 3 | 6x6 | 30 | 7 分钟 | 1x2、1x3、2x2 |
|
||||
| 4 | 6x6 | 35 | 10 分钟 | 1x2、1x3、2x2、2x3 |
|
||||
| 1 | 6x6 | 35 | 10 分钟 | 1x2、1x3、2x2、2x3 |
|
||||
|
||||
- 开局只放入本关目标消除数对应的全部卡牌；棋盘放不下的牌进入顶部准备区，牌不足棋盘格数时空格保留。
|
||||
- 每个有卡牌的小格子从背面翻向正面。
|
||||
- 开局每个小格子从背面翻向正面。
|
||||
- 可消除图由横向或纵向复合图案组组成，最小消除单位为两张图拼接。
|
||||
- 完成一个复合图案组后，该组所有 1x1 卡牌碎片消除。
|
||||
- 消除后空位按列由顶部卡牌准备区下落补齐；若顶部没有新牌，则空格留在场上并露出背景图。
|
||||
- 消除后空位按列由顶部卡牌准备区下落补齐。
|
||||
- 每次补牌至少保证掉落卡中有一张可以与场上剩余某张卡拼接，防止死局。
|
||||
- 非 2 格消除时，若场上已有局部完成的半锁定拼接组，补牌不得破坏它。
|
||||
- 半锁定拼接组可整体拖动；玩家用外部单格撞入组内某格时，只交换该格，组其余部分保留，组状态退回半完成。
|
||||
- 超时只判当前关失败，可重试当前关；胜利条件永远是消除完本关全部卡牌，达到目标消除数且棋盘与顶部准备区都没有剩余卡牌后进入下一关，完成第 4 关全部卡牌后整局完成。
|
||||
- 超时只判当前关失败，可重试当前关；完成 35 次目标并清空当前棋盘后整局完成。
|
||||
|
||||
## 结果页
|
||||
|
||||
结果页展示：素材 atlas、背景图、发布状态、试玩入口和失败重试。点击发布时弹出发布前检查面板，收集作品标题和简介并保存作品信息后再发布。结果页不写功能说明类文案，不开放规则编辑器，不新增排行榜配置。
|
||||
结果页展示：素材 atlas、中央场地底图、发布状态、试玩入口和失败重试。结果页不写功能说明类文案，不开放规则编辑器，不新增排行榜配置。
|
||||
|
||||
## 统计
|
||||
|
||||
|
||||
@@ -2,15 +2,15 @@
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`jump-hop` 重定义为竖屏俯视角平台跳跃游戏。创作者只输入主题，系统生成一张该主题的 `1024x1536` 立方体主题物体 UV 展开图集，按 `3列*6行` 容纳 18 个方块，每个方块内部再用自适应 blob+gradient 算法提取 top/front/right/back/left/bottom 六张面贴图；运行态使用 Three.js 复用标准 `1x1x1` 等比极小倒角立方体几何体，把六面贴图贴到立方体地板上组成无限平台流，同时使用陶泥儿 logo 透明 PNG 作为玩家角色。
|
||||
`jump-hop` 重定义为竖屏俯视角平台跳跃游戏。创作者只输入主题，系统生成一张该主题的 `5x5` 地块资源图集，切成 25 个 2D 地块素材；运行态使用抠除白底后的陶泥儿 logo 透明 PNG 作为玩家角色，并和这些 2D 地块资产组成无限平台流。
|
||||
|
||||
首版目标：
|
||||
|
||||
1. 创作输入只保留主题，标题、简介、标签和提示词由系统派生；
|
||||
2. image2 只生成一张 `1024x1536` 地板 UV 展开图集，后端切成 18 组、共 108 张面贴图 PNG；
|
||||
2. image2 只生成一张 `5x5` 地块图集，后端均匀切成 25 张 PNG；
|
||||
3. 角色不再单独生图，v1 使用 `public/branding/jump-hop-taonier-character.png` 陶泥儿 logo 透明 PNG；
|
||||
4. 运行态每屏只展示 3 个地块：当前地块、目标地块、下一预览地块；
|
||||
5. 操作方式为长按屏幕蓄力并按拖拽方向起跳，松手后角色按前端提交的后端方向向量弹出；
|
||||
5. 操作方式为按住屏幕向后拖动蓄力，松手后角色向拖拽反方向弹出；
|
||||
6. 只要落点未命中下一个地块，本局立即失败并冻结计时；
|
||||
7. 成绩记录成功跳跃次数和游戏时长；
|
||||
8. 排行榜按作品维度展示玩家 ID、成功跳跃次数和游戏时长，排序为成功跳跃次数降序、游戏时长升序、更新时间升序。
|
||||
@@ -21,10 +21,10 @@
|
||||
- 展示名：`跳一跳`
|
||||
- 工程域：`jump-hop`
|
||||
- 创作入口卡：`subtitle = 主题驱动平台跳跃`，`imageSrc = /creation-type-references/jump-hop.webp`
|
||||
- 运行态：`Three.js 标准 1x1x1 等比极小倒角立方体地板 + DOM 角色 + DOM HUD`
|
||||
- 运行态：`DOM 平台 / DOM 角色 + Three.js 透明扩展层 + DOM HUD`
|
||||
- 画面比例：移动端竖屏优先，桌面端居中承载 `9:16`
|
||||
- 素材策略：18 个立方体主题物体 UV 展开包装 + Three.js 复用标准 1x1x1 等比立方体几何 + 陶泥儿 logo 透明角色
|
||||
- 渲染分层：Three.js 平台层复用一份标准 `1x1x1` 等比极小倒角立方体几何体，`tileAssets[]` 切片只作为主题身份方块包装贴图；单块立方体必须正轴向摆放，不做 Y 轴偏航或 Z 轴歪斜旋转，也不得用不同 x/y/z scale 压成扁盒子；运行态视角采用约 `1.3x` 近距相机和 45° 下压视角，当前脚下地块基准位于屏幕中线略下方，后续两块向上展开且保持紧凑的纵向 / 横向间距；Three.js 平台层与 DOM 角色层必须保持屏幕 X 轴同向，禁止通过反向相机 `up` 或镜像容器把平台左右翻转；DOM 地块图片层只用于换签、预加载、WebGL 不可用和测试 fallback，Three.js 平台层 ready 后必须隐藏 DOM 地块图片和 DOM 阴影，退出地块只随相机推进自然离屏，不播放独立飞走动画，超过屏幕后再销毁，避免旧地块退出期露出被放大的平面 DOM 贴图；角色必须由 DOM 透明 PNG 层渲染并保持在 Three.js 平台层之上
|
||||
- 素材策略：2D 地块图集 + 陶泥儿 logo 透明角色
|
||||
- 渲染分层：生成地块切片必须由 DOM 平台层直接渲染为图片；角色必须由 DOM 透明 PNG 层渲染并保持最高层级，Three.js 透明画布只作为后续扩展层，不能把地块图片或角色回退为 WebGL 占位材质
|
||||
|
||||
本玩法不是横版平台跳跃，也不是关卡制闯关。平台从屏幕下方向上无限延展，目标地块在当前地块上方不同 x 轴位置随机出现。
|
||||
|
||||
@@ -35,12 +35,12 @@
|
||||
- 单图资产槽位：无独立角色图槽位；v1 固定使用陶泥儿 logo 透明 PNG 角色
|
||||
- 系列素材槽位：
|
||||
- `batchId = jump-hop-tile-atlas`
|
||||
- `sheetSpec = 1024x1536 / 3列*6行大单元 / 每格内自适应blob+gradient提取六面 / PNG / 纯洋红 #FF00FF 安全缝与外圈背景 / 后端切图为面贴图 PNG`
|
||||
- `slotSpecs = tile-01 ... tile-18`，每个 tile 再包含 `top/front/right/back/left/bottom` 六个面 slot，所有 slot 必须对应唯一 OSS path / `assetObjectId`
|
||||
- 切图规则：先通过 density 种子点精修自适应检测 3 列 6 行大单元边界（`SeedRefinement`）；每个大单元内部先用 BFS 连通域提取主 blob、清除非主 blob 噪点，再对行 density 和列 height profile 做 gradient 分析检测边界（y₀/y₁/y₂/y₃、x₀/x₁/x₂/x₃），按此边界划分为 3×3 block 并保留 5 个有效 block，将含 Right+Back 的 block 从中点拆分为两块，对每个 block 取最大不透明矩形后缩放为 `256x256` 不透明 PNG
|
||||
- 透明化规则：生成时要求纯洋红 key 安全缝和 UV 空位；后端先对图集做洋红去背（BFS 漫水 + 镂空洞检测），再对每个大单元内提取主 blob 后进行自适应面切分；切分后在 block 内取最大不透明矩形，消除透明边缘
|
||||
- `sheetSpec = 5x5 / 1:1 / PNG / 纯绿色绿幕背景 / 后端切图透明化`
|
||||
- `slotSpecs = tile-01 ... tile-25`，每个 slot 必须对应唯一 OSS path / `assetObjectId`
|
||||
- 切图规则：按原图宽高均分为 5 行 5 列，从上到下、从左到右切出 25 张 PNG；每格透明化后只保留最大的 alpha 连通主体，再裁边并补透明安全边，避免相邻格越界碎片或方形杂边进入 tile
|
||||
- 透明化规则：生成时要求绿幕背景，后端上传 OSS 前抠成透明 PNG，并清理与主体分离的小型残片
|
||||
- 失败回写：生成失败时 session 保持 failed，可从生成页重试
|
||||
- 局部重生成：结果页允许重生成地板贴图图集，仍只调用一次 image2；前端展示生成图时以 `assetObjectId` 作为刷新键，避免同一路径重写后的旧签名或旧缓存
|
||||
- 局部重生成：结果页允许重生成地块图集，仍只调用一次 image2；前端展示生成图时以 `assetObjectId` 作为刷新键，避免同一路径重写后的旧签名或旧缓存
|
||||
- API 命名空间：`/api/creation/jump-hop/*`、`/api/runtime/jump-hop/*`
|
||||
- 业务真相：后端裁决落点、失败、成功跳跃次数、冻结时长和排行榜
|
||||
- 创作工具模式例外：无
|
||||
@@ -55,35 +55,33 @@
|
||||
1. 作品标题：主题为空白修剪后的短标题，默认前缀不外露；
|
||||
2. 作品简介：基于主题生成一句短简介；
|
||||
3. 标签：`跳一跳`、`休闲` 和主题关键词；
|
||||
4. 地板贴图提示词：围绕主题生成 18 个风格一致的立方体主题物体 UV 展开包装，每个包装由 top/front/right/back/left/bottom 六面组成，供 Three.js 标准 1x1x1 等比极小倒角立方体地板复用；实际 image2 prompt 使用“立方体主题物体 UV 展开包装图集 / cube object UV unwrap atlas”措辞，要求六面共同表达同一个完整方块化主题物体，例如水果主题要生成可一眼辨认的方块苹果、方块香蕉、方块橙子、方块西瓜等，而不是单纯生成平铺材质、抽象纹理、平台、跳台、地块成品、单张图重复六面或游戏界面资源；
|
||||
4. 地块提示词：围绕主题生成 25 个风格一致的俯视角清爽游戏化 2D 平台素材，每一块都是符合主题的单独可跳跃平台；实际 image2 prompt 使用“独立可落脚平台素材 / 平台裸素材 / 完整平台”措辞，不再把正向主体描述成图标集或游戏界面资源；
|
||||
5. 初始平台流参数：固定 v1 标准参数，不让创作者手工调规则。
|
||||
|
||||
## 5. 地板贴图图集
|
||||
## 5. 地块图集
|
||||
|
||||
image2 只生成一张 `1024x1536` 竖版图片，画面为 `3列*6行` 均匀分布的立方体主题物体 UV 展开包装；实际提示词必须先约束“画面只包含 18 个用于跳一跳地板的立方体主题物体 UV 展开包装图”，并明确这是供 Three.js 标准 1x1x1 等比极小倒角立方体使用的 cube object UV unwrap atlas。每个大单元格代表一个完整方块化主题物体，并在固定 `4列*3行` UV 网中提供六张面贴图（AI prompt 侧不变）；后端通过自适应 blob+gradient 算法检测面的实际位置并切图，不再依赖固定像素坐标均分。不是单纯材质贴片、单张图重复六面、地块成品图、跳板、物体剪影、游戏界面、棋盘、背包、装备栏或图标集页面。
|
||||
image2 只生成一张 `1:1` 图片，画面为 `5x5` 均匀分布平台裸素材；实际提示词必须先约束“画面只包含 25 个独立跳一跳可落脚平台素材”，并明确不是游戏界面、棋盘、背包、装备栏或图标集页面。
|
||||
|
||||
图集要求：
|
||||
|
||||
1. 每个大单元内部固定使用 `4列*3行` UV 网，只有六个位置有贴图：第 1 行第 2 列是 `top`；第 2 行第 1-4 列依次是 `left / front / right / back`；第 3 行第 2 列是 `bottom`；其它位置保持纯洋红 `#FF00FF`。以上为 AI 生图的 layout 要求（prompt 侧不变）。后端切图改为自适应 blob+gradient 算法检测面的实际像素区域，不再依赖固定像素坐标均分。
|
||||
2. 每个面都是 full-bleed 不透明正方形贴图，四角、边缘和中心都要有可识别内容；六个面共同组成同一个完整方块化主题物体，不能把同一张纹理重复六次，也不能六面各画互不相关的小图标；
|
||||
3. 贴图不生成已经渲染好的透视 3D 块体成品，不包含摄像机角度、已烘焙侧壁、已烘焙厚度、自身投影、接触阴影或烘焙高光；真实倒角、侧壁、透视和阴影由运行态 Three.js 生成；
|
||||
4. 18 个方块来自同一主题、同一哑光手绘包装体系，但应表达不同方块化主题物体或明显不同的包装识别特征；水果主题要混排方块苹果、方块香蕉、方块橙子、方块西瓜、方块草莓、方块葡萄、方块奇异果、方块菠萝、方块柠檬、方块桃子、方块梨、方块蓝莓、方块芒果、方块椰子、方块火龙果、方块樱桃、方块哈密瓜、方块石榴，不要 18 个方块都只是同一种果皮、果肉或叶脉纹理；
|
||||
5. 大单元之间、UV 空位、六面之间和画布外圈为纯洋红 `#FF00FF`，方便后端安全切图；
|
||||
6. 不包含角色、文字、水印、UI、游戏面板、棋盘、背包、装备栏、按钮、标题、外层边框、可见网格线、场景背景、落地投影、接触阴影、方形阴影、方形底板、白底、灰底或黑底；
|
||||
7. 贴图不能跨格、贴边串色或进入相邻格；每个面贴图应尽量铺满自己的 UV 面，纯洋红只作为安全缝、UV 空位和外圈 key 色。
|
||||
1. 每格只放一个完整地块资源；
|
||||
2. 资源为纯 2D 平面素材，但要表现为符合主题且有设计感的俯视角清爽游戏化立体感平台，有顶面、主体内部明暗和清晰轮廓；主题元素必须直接成为平台主体，例如“水果”应生成苹果切片、橙子切片、西瓜块、草莓、菠萝、香蕉等水果造型平台；
|
||||
3. 25 个地块来自同一主题、同一光向和同一材质体系；
|
||||
4. 背景为纯绿色绿幕，方便后端透明化；
|
||||
5. 不包含角色、文字、水印、UI、游戏面板、棋盘、背包、装备栏、按钮、标题、外层边框、网格线、场景背景、落地投影、接触阴影、方形阴影、方形底板、白底、灰底或黑底；
|
||||
6. 地块不能跨格、贴边或进入相邻格，主体必须居中并保留至少 18% 纯绿色安全留白；每个平台之间只能是纯绿色空白，不画容器框或棋盘格。
|
||||
|
||||
大单元切片顺序固定为：
|
||||
切片顺序固定为：
|
||||
|
||||
```text
|
||||
tile-01 tile-02 tile-03
|
||||
tile-04 tile-05 tile-06
|
||||
tile-07 tile-08 tile-09
|
||||
tile-10 tile-11 tile-12
|
||||
tile-13 tile-14 tile-15
|
||||
tile-16 tile-17 tile-18
|
||||
tile-01 tile-02 tile-03 tile-04 tile-05
|
||||
tile-06 tile-07 tile-08 tile-09 tile-10
|
||||
tile-11 tile-12 tile-13 tile-14 tile-15
|
||||
tile-16 tile-17 tile-18 tile-19 tile-20
|
||||
tile-21 tile-22 tile-23 tile-24 tile-25
|
||||
```
|
||||
|
||||
每个 `tile-XX` 再切出 `top/front/right/back/left/bottom` 六个面贴图并写入 `tileAssets[].faceAssets`。历史兼容字段 `imageSrc/imageObjectKey/assetObjectId` 保存 top 面，旧作品没有 `faceAssets` 时运行态仍可把单张旧贴图应用到立方体所有面。运行态随机使用这 18 个地块作为后续平台外观。起点地块可复用第一个切片，其余平台从完整池中随机选择。
|
||||
运行态随机使用这 25 个地块作为后续平台外观。起点地块可复用第一个切片，其余平台从完整池中随机选择。
|
||||
|
||||
## 6. 运行态规则
|
||||
|
||||
@@ -99,24 +97,23 @@ tile-16 tile-17 tile-18
|
||||
|
||||
### 6.2 操作
|
||||
|
||||
1. 用户按住当前地块或画面开始蓄力；
|
||||
2. 长按时长形成蓄力值，达到 `maxChargeMs` 后封顶；
|
||||
3. 松手后角色按本次输入方向弹出；
|
||||
4. 蓄力值决定跳跃距离，拖拽方向决定跳跃方向；
|
||||
5. 前端必须同时提交 `dragDistance` 与换算到后端世界坐标的 `dragVectorX/dragVectorY`，后端以这两个方向字段裁决真实落点；旧客户端缺失方向或方向非法时，后端才 fallback 到当前地块中心指向下一块地块中心。
|
||||
1. 用户按住当前地块或画面；
|
||||
2. 向后拖动形成蓄力向量；
|
||||
3. 松手后角色沿拖拽反方向弹出；
|
||||
4. 拖拽距离决定力度，拖拽方向决定落点方向；
|
||||
5. 力度和方向都由前端提交给后端裁决。
|
||||
|
||||
手感参数固定由后端 `module-jump-hop` 提供：`chargeToDistanceRatio = 0.004`。该值表示蓄力时长到世界跳跃距离的换算系数；旧作品运行时若仍携带其它系数，开局归一化为 `0.004`。契约中的 `dragDistance` 语义是前端提交的蓄力值；`dragVectorX/dragVectorY` 是正式方向输入契约，不能在前端提交或后端裁决中丢弃。
|
||||
手感参数固定由后端 `module-jump-hop` 提供：`chargeToDistanceRatio = 0.008`。该值表示同等世界跳跃距离只需要旧版 `0.004` 配置的一半屏幕拖动距离；旧作品运行时若仍携带 `0.004`，开局归一化为 `0.008`。
|
||||
|
||||
松手后前端必须立即生成 `visualJump`，用当前角色位置作为起点、前端预测真实落点作为终点，播放约 `560ms` 的角色飞行动画；视觉预测必须使用当前显示窗口的 current/next 地块作为方向来源，即使后端最新 run 已提前返回，也不能拿新 run 目标配旧窗口角色导致下一跳反向；角色从当前地块沿下一块地块中心方向弹向预测真实落点，蓄力阶段角色只做垂直压缩，不沿目标方向拉长。成功落地后必须保留 `lastJump.landedX/landedY` 对应的真实落点偏移，不得强制吸附回目标地块中心；落地后可以轻量回弹，但不能把角色位置拉离真实落点。动画期间 DOM 地块窗口保持在本次起跳前的 3 块布局，动画路径不得等待后端新 run。若后端新 run 晚于飞行动画返回，角色必须停在预测真实落点等待；新 run 到达后应先使用后端真实落点对齐显示态，再进入约 `1440ms` 的相机推进过渡，避免角色先飞过很远再瞬间拉回地块。推进过渡中，地块 DOM 层和 DOM 角色层必须放在同一个相机层里统一位移，不允许 p1/p2 单独改 `top/left` 做过渡；旧当前地块只随相机推进保留在屏幕后方，不单独执行飞走动画，玩家继续向前跳时再被新的相机推进自然带出屏幕并销毁，新预览地块从上方自然露出，避免角色和地块不同步或闪现。相机推进必须同时携带 X/Y 偏移，从旧真实落点位置斜向滑到新当前地块聚焦位置，不允许先横向瞬切居中后再只做纵向滑动。地块可以保留当前 / 目标 / 预览的深度尺寸差异，但该差异必须通过固定基准宽高上的 CSS `transform: scale(...)` 表达，并在相机推进期间用同一 `1440ms` 缓动过渡；不得通过直接改宽高造成瞬切变大。当前地块高亮不得额外通过 CSS `scale` 放大。该动画只属于表现层，命中、失败、成功跳跃次数和冻结时长仍以后端裁决为准。
|
||||
松手后前端必须立即生成 `visualJump`，用当前角色位置作为起点、前端预测落点作为终点，播放约 `560ms` 的角色飞行动画；角色从当前地块弹向预测落点，蓄力阶段角色应沿拖拽方向明显拉长，落地后再向反方向回弹两次。动画期间 DOM 地块窗口保持在本次起跳前的 3 块布局，动画路径不得等待后端新 run。若后端新 run 晚于飞行动画返回，角色必须停在预测落点等待，直到新 run 到达后再把显示态切到后端返回的最新 run，并进入约 `1440ms` 的相机推进过渡。推进过渡中，地块 DOM 层和 DOM 角色层必须放在同一个相机层里统一位移，不允许 p1/p2 单独改 `top/left` 做过渡；旧当前地块随相机推进自然离开视野，新预览地块从上方自然露出，避免角色和地块不同步或闪现。相机推进必须同时携带 X/Y 偏移，从旧目标地块位置斜向滑到新当前地块聚焦位置，不允许先横向瞬切居中后再只做纵向滑动。地块可以保留当前 / 目标 / 预览的深度尺寸差异，但该差异必须通过固定基准宽高上的 CSS `transform: scale(...)` 表达，并在相机推进期间用同一 `1440ms` 缓动过渡；不得通过直接改宽高造成瞬切变大。当前地块高亮不得额外通过 CSS `scale` 放大。该动画只属于表现层，命中、失败、成功跳跃次数和冻结时长仍以后端裁决为准。
|
||||
|
||||
### 6.3 判定
|
||||
|
||||
1. 目标永远是当前地块后的下一个地块；
|
||||
2. 真实落点沿前端提交的 `dragVectorX/dragVectorY` 归一化方向计算；仅当方向缺失、非有限数或长度过小时，才沿当前地块中心到下一块地块中心方向兼容计算；
|
||||
3. 落点进入下一个地块可见顶面 footprint，则成功；footprint 使用当前路径里该地块 `width/height` 的收缩矩形模拟 45° 视角下的可见顶面，当前命中区约为宽度 72% 和高度 52%；
|
||||
4. 落点未进入下一个地块可见顶面 footprint，则失败；旧 `landingRadius/perfectRadius` 字段仅保留兼容读写，不再作为当前 v1 成功判定；
|
||||
5. 失败后状态改为 `failed`，计时冻结；
|
||||
6. v1 没有通关状态、combo、perfect 或生命数。
|
||||
2. 落点进入下一个地块落地半径，则成功；
|
||||
3. 落点未进入下一个地块落地半径，则失败；
|
||||
4. 失败后状态改为 `failed`，计时冻结；
|
||||
5. v1 没有通关状态、combo、perfect 或生命数。
|
||||
|
||||
### 6.4 计分与时间
|
||||
|
||||
@@ -138,13 +135,11 @@ successfulJumpCount desc -> durationMs asc -> updatedAt asc
|
||||
展示字段：
|
||||
|
||||
1. rank；
|
||||
2. displayName；
|
||||
2. playerId；
|
||||
3. successfulJumpCount；
|
||||
4. durationMs；
|
||||
5. updatedAt。
|
||||
|
||||
排行榜 UI 禁止展示 `user_id` / `playerId` 这类内部身份键。后端可以继续用 `playerId` 做作品维度最佳成绩去重和 `viewerBest` 匹配，但 HTTP 响应必须补齐 `displayName`；已登录用户读取账号 `displayName`，匿名游客展示为“游客玩家”，账号失效或无法解析时展示为“失效玩家”。
|
||||
|
||||
草稿试玩可以展示本地结果，但正式排行榜只消费后端 run 记录。匿名 runtime guest 也按 guest subject 作为 playerId 参与当次作品维度排行。
|
||||
|
||||
## 8. 结果页
|
||||
@@ -152,7 +147,7 @@ successfulJumpCount desc -> durationMs asc -> updatedAt asc
|
||||
结果页展示：
|
||||
|
||||
1. 陶泥儿 logo 透明角色预览；
|
||||
2. 18 个地块资源池预览；
|
||||
2. 25 个地块资源池预览；
|
||||
3. 首屏 3 块平台预览；
|
||||
4. 试玩；
|
||||
5. 发布；
|
||||
@@ -186,14 +181,14 @@ successfulJumpCount desc -> durationMs asc -> updatedAt asc
|
||||
## 10. 验收
|
||||
|
||||
1. 创作页只显示主题输入；
|
||||
2. 生成链路只调用一次地板贴图图集 image2，不再调用角色生图；
|
||||
3. 地板贴图图集为 `1024x1536 / 3列*6行`，后端通过自适应 blob+gradient 算法切出 18 组、共 108 张面贴图 PNG；
|
||||
2. 生成链路只调用一次地块图集 image2，不再调用角色生图；
|
||||
3. 地块图集为 `5x5`，后端切出 25 个地块 PNG；
|
||||
4. 结果页不依赖旧角色图片槽；
|
||||
5. 运行态为竖屏俯视角，首屏保持 3 个地块可见；
|
||||
6. 长按蓄力值影响落点距离，`dragVectorX/dragVectorY` 影响正式落点方向；
|
||||
6. 拖拽方向和力度会影响落点；
|
||||
7. 未落到下一个地块立即失败；
|
||||
8. 成功跳跃次数累加，失败后计时冻结；
|
||||
9. 排行榜按成功跳跃次数优先排序；
|
||||
10. 作品可保存、发布、分享并从公开入口启动。
|
||||
11. 运行态 Three.js 地板必须优先把 `tileAssets[].faceAssets` 六面贴图按 right/left/top/bottom/front/back 材质顺序贴到标准 `1x1x1` 等比立方体上；旧作品没有 `faceAssets` 时才使用 `tileAssets[].imageSrc` 单贴图 fallback。六面贴图通过换签或 blob 异步解析时，Three.js 平台 mesh 的刷新签名必须包含 top/front/right/back/left/bottom 六个 texture URL，任一面 URL 变化都要触发材质重建，不能只监听旧单图 `imageSrc`。立方体正轴向摆放，不做 Y 轴偏航或 Z 轴歪斜旋转，不得把 x/y/z 缩放成扁盒子；相机保持近距 45° 下压视角，当前脚下地块基准位于屏幕中线略下方，可见三块地板之间的屏幕间距必须偏紧凑；长按蓄力、计时刷新和角色位置更新不得销毁重建透明画布、平台贴图预加载层或 DOM 角色层。
|
||||
12. 同等世界距离的蓄力换算必须使用 `0.004` 系数，松手后必须先看到角色飞行动画，再看到地块窗口前移；成功落地显示必须保留真实落点偏移。
|
||||
11. 运行态地块必须显示 `tileAssets[]` 中的生成切片图片；拖拽蓄力、计时刷新和角色位置更新不得销毁重建透明画布、平台图片层或 DOM 角色层。
|
||||
12. 同等跳跃距离的拖动距离必须比旧 `0.004` 系数缩短一半，松手后必须先看到角色飞行动画，再看到地块窗口前移。
|
||||
|
||||
@@ -1,46 +0,0 @@
|
||||
# 【前端架构】Bark Battle Work Cache 草稿状态收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍内联维护 Bark Battle 草稿三图完整性、生成状态归一、作品架摘要恢复草稿配置，以及草稿 / 已发布作品进入 runtime 前的 `BarkBattlePublishedConfig` 映射。壳层因此需要同时理解三图资产字段、`partial_failed` 与 `pending_assets` 的差异、`publishedAt` 兜底、作品摘要字段和草稿试玩配置默认值。
|
||||
|
||||
这些规则属于 Bark Battle 作品摘要与草稿缓存的纯模型。若留在平台壳层，后续发布、作品架刷新、公开详情启动或草稿试玩都容易重复一份字段清单。
|
||||
|
||||
## 决策
|
||||
|
||||
扩展 `src/components/platform-entry/barkBattleWorkCache.ts`，作为 Bark Battle Work Cache **Module** 继续承接作品摘要缓存和草稿 runtime 配置规则。新增公开 **Interface**：
|
||||
|
||||
- `hasBarkBattleDraftRequiredImages(draft)`：判断草稿是否已具备玩家形象、对手形象和竞技背景三图。
|
||||
- `resolveBarkBattleDraftGenerationStatus(draft, partialFailed)`：三图齐备返回 `ready`，否则按是否部分失败返回 `partial_failed` 或 `pending_assets`。
|
||||
- `buildBarkBattleDraftConfigFromWorkSummary(work)`：把作品架摘要恢复成可编辑 / 可试玩的 `BarkBattleDraftConfig`。
|
||||
- `buildBarkBattlePublishedConfigFromDraft(draft)`：把草稿结果页试玩所需配置映射为 `BarkBattlePublishedConfig`。
|
||||
- `buildBarkBattlePublishedConfigFromWork(work)`：把作品架 / 公开详情启动正式 runtime 所需配置映射为 `BarkBattlePublishedConfig`。
|
||||
- `buildBarkBattlePublishSnapshot(draft)`：拼装发布接口所需的最终草稿快照。
|
||||
- `mergeBarkBattlePublishedConfigAssets(published, draft)`：发布回包缺少三图字段时沿用结果页草稿图。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 继续作为 **Adapter**：它只负责 API 请求、React state、URL、运行态 stage 切换和错误提示，不再持有 Bark Battle 三图完整性与 runtime config 字段清单。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 草稿三图必须同时具备 `playerCharacterImageSrc`、`opponentCharacterImageSrc` 和 `uiBackgroundImageSrc` 的非空值，才视为 `ready`。
|
||||
- 未齐三图且 `partialFailed=true` 时返回 `partial_failed`，否则返回 `pending_assets`。
|
||||
- 作品摘要恢复草稿时，`draftId` 缺失回退 `workId`，`description` 来自 summary，三图 null 归一为 `undefined`，`configVersion=1` 且 `rulesetVersion='bark-battle-ruleset-v1'`。
|
||||
- 草稿试玩配置的 `workId` 优先使用草稿稳定 `workId`，缺失时回退 `draftId`。
|
||||
- 草稿试玩配置的 `configVersion` 与 `rulesetVersion` 使用草稿值，缺失时回退 `1` 与 `bark-battle-ruleset-v1`。
|
||||
- 已发布作品配置的 `publishedAt` 缺失时回退 `updatedAt`，保持旧 runtime 启动语义。
|
||||
- 发布快照只携带草稿已有的三图字段，不凭空补空字符串。
|
||||
- 发布接口回包缺少三图字段时，结果页草稿图继续作为 runtime 和作品摘要的兜底。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层传入草稿或作品摘要，即可得到生成状态、草稿配置或 runtime 配置；字段归一、默认值和三图完整性藏入 Module Implementation。
|
||||
- **Leverage**：作品架草稿恢复、结果页试玩、作品架启动、公开详情启动和缓存刷新可复用同一组 Bark Battle 规则。
|
||||
- **Locality**：Bark Battle 资产完整性与配置映射集中到纯测试面，后续变更三图字段或规则集默认值时无需搜索巨型平台壳。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/barkBattleWorkCache.test.ts`
|
||||
- `npx eslint --max-warnings 0 src/components/platform-entry/barkBattleWorkCache.ts src/components/platform-entry/barkBattleWorkCache.test.ts`
|
||||
- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,41 +0,0 @@
|
||||
# CreationUrlStateModel 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 曾直接承载多玩法创作恢复 URL 的拼装规则：`sessionId`、`profileId`、`draftId`、`workId` 的优先级、拼图草稿 runtime query、以及空值归一化散在壳层 Implementation 内。平台壳因此需要理解各玩法快照结构，新增玩法或修复刷新恢复时缺少稳定测试面。
|
||||
|
||||
## 决策
|
||||
|
||||
- 新增 `src/components/platform-entry/platformCreationUrlStateModel.ts` 作为 Creation URL State Module。
|
||||
- 该 Module 的 Interface 收口为各玩法 `build*CreationUrlState`、拼图 `buildPuzzle*RuntimeUrlState`、`normalizeCreationUrlValue`、`hasCreationUrlStateValue`、`hasPuzzleRuntimeUrlStateValue`、`buildPuzzleRuntimeUrlStateKey`、初始创作 URL 恢复判定 `resolveInitialCreationUrlRestoreDecision`、创作直达恢复目标解析 `resolveCreationUrlRestoreTarget`、恢复目标身份匹配谓词，以及跳一跳 / 敲木鱼恢复后的阶段落点判定。
|
||||
- 新增 `src/components/platform-entry/platformPuzzleIdentityModel.ts` 作为拼图稳定身份 Module，统一 `puzzle-session-*`、`puzzle-profile-*`、`puzzle-work-*` 的互推规则。
|
||||
- `PlatformEntryFlowShellImpl.tsx` 保留 React state、路由、登录门禁、网络请求和 URL 写入副作用 Adapter；不再在壳层内定义各玩法 URL 状态构造函数，也不直接内联初始恢复的已处理 / 等待 / 可恢复判定。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 创作恢复私有 query 只使用 `sessionId`、`profileId`、`draftId`、`workId`；不得新增说明性 query 字段。
|
||||
- 空字符串、全空白字符串统一视为 `null`，避免刷新恢复时写入无效私有参数。
|
||||
- work-backed 玩法优先使用后端 work summary 的公开 `workId` / `profileId`；仅缺失时才回退 session draft。
|
||||
- 拼图 runtime query 独立使用 `mode`、`runtimeSessionId`、`runtimeProfileId`、`runtimeLevelId`、`publicWorkCode`，不与创作恢复 query 混写。
|
||||
- 拼图 draft runtime 若没有 `sourceSessionId`，只允许从 `puzzle-profile-*` 反推出 `puzzle-session-*`。
|
||||
- 初始创作 URL 恢复只在未处理、当前路径属于创作恢复路径、私有 query 有值、平台配置加载完成且受保护数据可读时执行；非创作路径或无私有 query 时标记已处理，加载中或暂不可读时等待。
|
||||
- 创作直达恢复目标由 `resolveCreationUrlRestoreTarget(pathname, state)` 统一识别；它只返回玩法 kind、归一化后的四个私有 query、生成路径标记和大鱼吃小鱼 session 兜底，不执行网络请求、草稿打开、stage 切换或 URL 写回。
|
||||
- 作品 / 草稿身份匹配只允许非空目标值命中，避免 query 缺失时用 `null` / 空值误匹配到无效草稿。匹配谓词仍只判断身份，不触发列表读取或打开动作。
|
||||
- 跳一跳和敲木鱼的恢复阶段落点由 `resolveJumpHopCreationUrlRestoreStage` 与 `resolveWoodenFishCreationUrlRestoreStage` 决定；生成路径优先进入生成页，否则按是否恢复到 draft / work 落到结果页或工作台。
|
||||
- `/creation/rpg` 当前仍不归入具体恢复目标；若后续要恢复 RPG 直达，需要先补明确恢复规则和测试，不得让壳层重新内联路径判定。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：调用方只传玩法快照或作品摘要，即可得到规范化 URL state；各玩法字段优先级藏在 Module Implementation 内。
|
||||
- **Leverage**：新增或调整玩法恢复规则、恢复目标或恢复等待条件时，优先补 Module Interface 测试，再接壳层 Adapter。
|
||||
- **Locality**：恢复 query、拼图 runtime query 和拼图稳定身份规则集中在两个小 Module，避免散落在页面壳、作品架和 runtime 打开逻辑中。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformCreationUrlStateModel.test.ts src/components/platform-entry/platformPuzzleIdentityModel.test.ts`
|
||||
- `npm run test -- src/services/creationUrlState.test.ts`
|
||||
- `npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformCreationUrlStateModel.ts src/components/platform-entry/platformCreationUrlStateModel.test.ts src/components/platform-entry/platformPuzzleIdentityModel.ts src/components/platform-entry/platformPuzzleIdentityModel.test.ts --max-warnings 0`
|
||||
- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx src/components/platform-entry/platformDraftGenerationShelfModel.ts --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,33 +0,0 @@
|
||||
# 【前端架构】Creation Work Delete Flow 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
平台入口作品架的删除入口覆盖 RPG、拼图、抓大鹅、方洞挑战、大鱼吃小鱼、视觉小说和宝贝识物。此前 `PlatformEntryFlowShellImpl.tsx` 在每个删除 handler 内重复计算确认框标题、删除说明、草稿 notice key 和拼图派生稳定 ID。壳层既要理解每种玩法的作品身份，又要承接异步删除、刷新列表、错误状态和页面跳转，导致删除确认规则缺少稳定测试面。
|
||||
|
||||
该 **Interface** 过浅：页面只想展示“删除哪个作品、会从哪里移除、删除成功后清哪些生成 notice”，却必须知道 `workId` / `profileId` / `sourceSessionId` / `draftId`、`status` / `publicationStatus` / `publishStatus` 和宝贝识物特殊公开去向。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformCreationWorkDeleteFlow.ts` 作为 Creation Work Delete Flow **Module**。其唯一公开 **Interface** 是 `resolvePlatformCreationWorkDeleteConfirmationModel(input)`，输入为带 `kind` 的 union，输出：
|
||||
|
||||
- `id`：确认框和删除 busy 使用的稳定作品 ID。
|
||||
- `title`：确认框标题，含拼图、视觉小说和宝贝识物标题兜底。
|
||||
- `detail`：草稿 / 已发布删除说明，宝贝识物已发布使用“寓教于乐板块”文案。
|
||||
- `noticeKeys`：删除成功后应标记已读的草稿生成 notice keys，拼图包含 `buildPuzzleResultWorkId` / `buildPuzzleResultProfileId` 派生 key。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为副作用 **Adapter**：负责鉴权保护、确认框 state、调用各玩法删除 API、清错误、刷新作品架 / 公开广场、`markDraftNoticeSeen` 和必要的页面跳转。`run` 不进入纯 **Module**，避免把网络副作用和 React state 写入藏入模型层。
|
||||
|
||||
## 约定
|
||||
|
||||
- 新玩法接入作品架删除时，先补齐后端删除链路、作品架 action 和本 **Module** 的确认模型，再开放删除按钮。
|
||||
- Jump Hop、Wooden Fish 和 Bark Battle 当前仅有作品架 action 预留，平台壳不传删除 handler；不得因本 Module 存在而默认开放删除。
|
||||
- 删除确认文案不得散回平台壳；若公开去向不是公开广场，应在本 **Module** 明确分支。
|
||||
- 草稿 notice key 的身份扩展必须复用 `collectDraftNoticeKeys`，保持 trim、去空和去重语义一致。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformCreationWorkDeleteFlow.test.ts`
|
||||
- `npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformCreationWorkDeleteFlow.ts src/components/platform-entry/platformCreationWorkDeleteFlow.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,40 +0,0 @@
|
||||
# 【前端架构】Draft Generation Shelf Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 同时承载创作生成状态、草稿 Tab 未读点、pending 作品架占位、失败文案覆盖、作品详情更新回填和跨玩法 notice key。拼图、抓大鹅、方洞、跳一跳、敲木鱼、视觉小说、汪汪声浪、大鱼吃小鱼和宝贝识物各有不同的 `workId` / `profileId` / `sourceSessionId` / `draftId`，这些规则散在平台壳 **Implementation** 内，导致调用方必须理解每种玩法的草稿身份形状。
|
||||
|
||||
该 **Interface** 过浅：页面看似只关心“生成中 / 已完成未读 / 失败”，却要知道多 ID 去重、pending 草稿去重、失败摘要、拼图空标题兜底和持久化 generating 覆盖规则。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformDraftGenerationShelfModel.ts` 作为 Draft Generation Shelf **Module**。其 **Interface** 收口为：
|
||||
|
||||
- `collectDraftNoticeKeys(kind, ids)` / `getGenerationNoticeShelfKeys(item)`：统一把玩法草稿身份映射为 notice key。
|
||||
- `createPendingDraftShelfState(...)` 与 `buildPending*Works(...)`：统一把本地 pending 生成状态映射成作品架占位，并避免与后端已有草稿重复。
|
||||
- `buildCreationWorkShelfRuntimeState({ item, notices, pendingShelfItems })`：统一输出 `CreationWorkShelfRuntimeState`，处理失败覆盖、拼图空标题 `拼图草稿` 兜底、summary 占位覆盖、生成中遮罩和 ready 未读点。
|
||||
- `collectVisibleDraftNoticeKeys(...)` / `hasUnreadDraftGenerationUpdates(...)`：统一草稿 Tab 顶部未读点规则。
|
||||
- `mergePuzzleWorkSummary(current, updated)` 与 `mergeBigFishWorkSummary(current, updated)`：统一作品详情更新后回填作品架和当前详情的身份匹配规则。
|
||||
- `resolvePuzzleDraftOpenIntent(...)`、`resolveMatch3DDraftOpenIntent(...)`、`resolveSquareHoleDraftOpenIntent(...)`、`resolveBigFishDraftOpenIntent(...)`、`resolveVisualNovelDraftOpenIntent(...)`、`resolveJumpHopDraftOpenIntent(...)` 与 `resolveWoodenFishDraftOpenIntent(...)`：统一拼图、抓大鹅、方洞挑战、大鱼吃小鱼、视觉小说、跳一跳和敲木鱼草稿打开时的已发布详情、缺 session、ready 未读试玩、失败 / active / background 生成页、当前结果页、持久化 generating 恢复、失败 fallback stage 和普通草稿恢复优先级。
|
||||
- `buildPuzzleResultWorkId(...)` / `buildPuzzleResultProfileId(...)`、`isPersistedDraftGenerating(...)` / `isPersistedDraftFailed(...)`：把拼图稳定 ID 与持久化状态判断收在同一 **Seam**。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为 React state 与副作用 **Adapter**：负责写入 `draftGenerationNotices` / `pendingDraftShelfItems`、读取生成 session、启动 ready 草稿试玩、刷新后端列表、打开结果页和弹窗；它不再内联 pending shelf row shape、notice key 汇总、作品架 runtime state 和上述玩法草稿打开优先级。
|
||||
|
||||
## 约定
|
||||
|
||||
- 新玩法若需进入草稿生成通知，必须在此 **Module** 补 notice key、pending 占位和 visible key 映射，避免在平台壳里新增散落 switch。
|
||||
- pending 作品只用于本地生成任务尚未被后端作品架返回时的临时展示；一旦后端已有同一 `sourceSessionId` / `profileId` / `workId`，pending 占位必须让位。
|
||||
- 拼图作品详情更新只以 `profileId` 匹配回填；大鱼吃小鱼作品详情更新只以 `sourceSessionId` 匹配回填。
|
||||
- 失败 notice 优先级高于持久化 generating，且可通过 pending metadata 提供更具体 summary；否则回退玩法默认失败摘要。
|
||||
- 已有封面的拼图草稿即使局部关卡仍在后台生成，也不得被整卡遮罩为不可打开的生成中状态。
|
||||
- 草稿打开 intent 只返回纯计划、notice keys 与必要稳定 ID，不创建失败生成态、不请求详情、不写 stage；这些仍由壳层 Adapter 执行。
|
||||
- 本 **Module** 不做网络请求、路由切换、弹窗副作用或 React state 写入，只保留纯 **Implementation**，以提高 **Depth**、**Leverage** 与 **Locality**。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformDraftGenerationShelfModel.test.ts`
|
||||
- `npm run test -- src/components/custom-world-home/creationWorkShelf.test.ts -t "generation state|failure notice|failed puzzle"`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating puzzle draft|persisted generating match3d draft|completed baby object match draft"`
|
||||
- 针对新 **Module** 与测试执行 ESLint；`PlatformEntryFlowShellImpl.tsx` 保留既有 hook dependency warnings，不在本切片扩大处理。
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,34 +0,0 @@
|
||||
# 【前端架构】Match3D Runtime Profile 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 同时编排抓大鹅创作、作品详情、推荐 runtime 和正式 runtime。运行态启动前的 profile 规范化、公开详情转 work、生成背景资产提升、run / profile / public detail 优先级和 runtime 素材选择原本都在平台壳 **Implementation** 内，导致平台壳必须理解抓大鹅生成素材的内部结构。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformMatch3DRuntimeProfile.ts`，作为抓大鹅 runtime profile **Module**。该 **Module** 的 **Interface** 收口为：
|
||||
|
||||
- `mapPublicWorkDetailToMatch3DWork(entry)`：把公开作品详情映射为可启动 runtime 的 Match3D work，并补齐生成背景资产。
|
||||
- `buildMatch3DProfileFromSession(session)`：从创作 session draft 生成 runtime profile。
|
||||
- `normalizeMatch3DWorkForRuntimeUi(profile)` / `mapMatch3DWorksForRuntimeUi(profiles)`：统一作品列表进入 UI / runtime 前的素材规范化。
|
||||
- `promoteMatch3DGeneratedBackgroundAsset(profile)`：从 `generatedBackgroundAsset` 或 `generatedItemAssets[].backgroundAsset` 提升背景图、对象 key 与 prompt。
|
||||
- `hasMatch3DRuntimeAsset(profile.generatedItemAssets)` / `hasMatch3DRuntimeBackgroundAsset(profile)`：统一判断 runtime 是否具备物品与背景素材。
|
||||
- `resolveActiveMatch3DRuntimeProfile(run, runtimeProfile, profile)`：按 run 的 `profileId` 选择当前 profile，避免切屏时误用旧草稿。
|
||||
- `resolveMatch3DRuntimeGeneratedItemAssets(...)`、`resolveMatch3DRuntimeGeneratedBackgroundAsset(...)`、`resolveMatch3DRuntimeBackgroundImageSrc(...)`：统一 run / profile / public detail 的素材优先级。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 只保留启动 run、预加载、路由、错误和 state 编排；抓大鹅素材规则集中到该 **Module**，提升 **Locality** 与测试 **Leverage**。
|
||||
|
||||
## 约定
|
||||
|
||||
- 公开详情补 runtime 素材时，只有 `profileId` 与 run 匹配才优先使用公开详情；错配时不得污染当前 run。
|
||||
- 当前启动时拿到的 `runtimeProfile` 优先于旧草稿 profile；若 run 指向旧草稿 profile，才使用草稿 profile。
|
||||
- 背景资产提升不得覆盖已有显式 `backgroundImageSrc` / `backgroundImageObjectKey` / `generatedBackgroundAsset`，只补缺。
|
||||
- 本 **Module** 只放纯 profile / asset 规则，不引入启动 run、预加载、URL、状态机或 UI 副作用。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformMatch3DRuntimeProfile.test.ts`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "match3d|抓大鹅"`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
- 针对新 Module 与测试执行 ESLint；`PlatformEntryFlowShellImpl.tsx` 保留既有 hook dependency warnings，不在本切片扩大处理。
|
||||
@@ -1,29 +0,0 @@
|
||||
# 【前端架构】Platform Creation Launch Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 的创作入口点击回调曾直接以内联 `if` 链判断 `airp` 占位、隐藏的 `baby-object-match`、RPG 与各小游戏工作台启动目标。壳层因此同时理解入口 ID、是否需要执行启动前准备、隐藏模板错误文案和具体工作台分流。
|
||||
|
||||
这类规则属于创作入口启动意图。壳层应只执行准备、错误提示和受保护动作，不应持有入口 ID 到工作台目标的长链判定。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformCreationLaunchModel.ts` 作为 Platform Creation Launch **Module**。其公开 **Interface** 为：
|
||||
|
||||
- `resolvePlatformCreationLaunchIntent({ type, isBabyObjectMatchVisible })`：输入后端入口配置下发的模板 ID 与幼教入口可见性，输出 `noop`、`blocked` 或 `launch` 意图。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为副作用 **Adapter**：根据 intent 决定是否调用 `prepareCreationLaunch()`，对 blocked intent 写入 `sessionController.setCreationTypeError(...)`，对 launch intent 进入 `runProtectedAction(...)` 并调用具体工作台打开函数。
|
||||
|
||||
## 约定
|
||||
|
||||
- `airp` 是占位入口，必须在 `prepareCreationLaunch()` 之前返回 `noop`，避免触发新游戏初始化、返回目标复位或错误清理。
|
||||
- 隐藏的 `baby-object-match` 必须在 `prepareCreationLaunch()` 之后返回 blocked intent，错误文案仍使用 `EDUTAINMENT_HIDDEN_MESSAGE`。
|
||||
- 未知入口 ID 保持旧语义：先允许壳层执行启动前准备，再作为 `noop` 结束，避免改变未来后端配置异常时的准备流程。
|
||||
- 新增可启动模板时，先在本 **Module** 的 launch target union、目标集合和测试中列明，再在壳层 Adapter 中补具体启动函数。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformCreationLaunchModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformCreationLaunchModel.ts src/components/platform-entry/platformCreationLaunchModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,46 +0,0 @@
|
||||
# PlatformDialogStateModel 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 曾直接承载平台级错误 / 完成弹窗的纯状态规则：错误文案 trim、来源 label 与 id 拼接、后台生成仍在处理的识别、错误候选优先级、dismiss key 与生成完成文案都散在壳层 Implementation 内。壳层因此既要管理 React state 与副作用清理，又要记住弹窗判定细则；新增玩法错误或调整弹窗展示时缺少稳定测试面。
|
||||
|
||||
## 决策
|
||||
|
||||
- 新增 `src/components/platform-entry/platformDialogStateModel.ts` 作为 Platform Dialog State Module。
|
||||
- Module Interface 收口：
|
||||
- `normalizePlatformDialogMessage`
|
||||
- `formatPlatformDialogSource`
|
||||
- `isBackgroundGenerationStillRunningMessage`
|
||||
- `resolvePlatformErrorDialog`
|
||||
- `buildPlatformErrorDialogDismissKey`
|
||||
- `buildPlatformTaskCompletionDialogDismissKey`
|
||||
- `resolveActivePlatformDialog`
|
||||
- `PLATFORM_TASK_COMPLETION_MESSAGE`
|
||||
- `PlatformErrorDialogState`、`PlatformTaskFailureDialogState` 与 `PlatformTaskCompletionDialogState`
|
||||
- `PlatformEntryFlowShellImpl.tsx` 继续作为 Adapter：汇总各玩法候选、持有 React state、关闭弹窗时清理对应 setter。副作用清理不下沉到 Module，避免把大量壳层 setter 变成浅 Interface。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 错误与完成弹窗文案先 trim；空字符串或全空白字符串统一视为 `null`。
|
||||
- 来源格式固定为 `label + 空格 + trimmed id`；缺 id 时只返回 label。
|
||||
- 平台错误候选按数组顺序取第一个有效文案；候选本身只描述 `key/source/message`。
|
||||
- 错误 dismiss key 固定为 `key:source:message`；完成 dismiss key 固定为 `key:source:message:completedAtMs`，缺完成时间时补 `0`。
|
||||
- `resolveActivePlatformDialog` 只根据当前弹窗 dismiss key 与已记录 dismiss key 决定是否隐藏，不修改底层错误或完成状态。
|
||||
- 任务完成弹窗文案统一使用 `PLATFORM_TASK_COMPLETION_MESSAGE`，不得在壳层重复写同一中文 literal。
|
||||
- `closePlatformErrorDialog` 保持在壳层 Adapter；它负责按错误来源清理 `creationEntryConfigError`、玩法 error、作品详情 error 等副作用状态，不属于纯状态 Module。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层传入候选和 dismiss 记录，即可得到当前平台弹窗状态；文案归一、来源格式和 dismiss 规则藏在 Module Implementation 内。
|
||||
- **Leverage**：新增玩法错误来源时只需补候选；调整弹窗纯规则时优先改 Module 与单测。
|
||||
- **Locality**：平台错误弹窗、任务完成弹窗和后台生成 still-running 识别集中在一个小 Module，避免继续散落在大型平台壳 Implementation 内。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformDialogStateModel.test.ts`
|
||||
- `npm run test -- src/components/platform-entry/PlatformErrorDialog.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "background match3d draft failure notifies and reopens failed retry page|completed match3d draft notice first opens trial then reopens result|puzzle compile timeout shows failure dialog when reread session is still generating"`
|
||||
- `npx eslint src/components/platform-entry/platformDialogStateModel.ts src/components/platform-entry/platformDialogStateModel.test.ts --max-warnings 0`
|
||||
- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,37 +0,0 @@
|
||||
# 【前端架构】Platform Generation Progress Tick Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 的生成页进度 tick effect 曾以内联三元链按 `selectionStage` 选择拼图、抓大鹅、大鱼吃小鱼、方洞挑战、跳一跳、敲木鱼和宝贝识物的生成状态，并额外手写视觉小说的 `startedAtMs` / `phase` 判定。壳层因此既要维护 `setInterval` 副作用，又要记住每个生成页 stage 对应哪份进度状态。
|
||||
|
||||
生成进度是否需要 tick 是纯判定；`Date.now()`、`window.setInterval` 和进度时间 state 写入仍属于 React 壳层副作用。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformGenerationProgressTickModel.ts` 作为 Platform Generation Progress Tick **Module**。其公开 **Interface** 为：
|
||||
|
||||
- `resolvePlatformGenerationProgressTickDecision(input)`：输入当前 `selectionStage`、各小游戏 `MiniGameDraftGenerationState` 和视觉小说轻量生成状态，输出 `{ activeKind, shouldTick }`。
|
||||
- `PlatformGenerationProgressTickKind`：枚举可 tick 的生成类型，包含已有小游戏生成 kind 与 `visual-novel`。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它把当前 state 组装给 Module，若 `shouldTick=false` 则不启动 interval；若为真，仍按旧逻辑立即写一次 `Date.now()`，再每 `500ms` 更新并在 effect cleanup 中清理 timer。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 小游戏生成 stage 只读取匹配 kind 的 `MiniGameDraftGenerationState`；stage 与 state 不匹配时不 tick。
|
||||
- 小游戏状态缺失、`phase='ready'` 或 `phase='failed'` 时不 tick；其它 phase 按进行中处理。
|
||||
- `visual-novel-generating` 不强行转成 `MiniGameDraftGenerationState`，只在 `startedAtMs != null` 且 phase 非 `ready` / `failed` 时 tick。
|
||||
- 非生成 stage 即使传入可运行 state 也不 tick。
|
||||
- 本 Module 不计算进度、不重建 view state、不处理拼图 / 抓大鹅 background task 覆盖；这些仍按既有生成页和作品架模型处理。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层只消费 `shouldTick`，stage 到 state 的映射和终态判定藏入 Module Implementation。
|
||||
- **Leverage**：新增生成页玩法时，先扩展 stage-to-kind 映射和单测，再让壳层 Adapter 传入对应 state。
|
||||
- **Locality**：生成进度 tick 规则集中到一个纯测试面，interval 副作用继续局部留在 React effect，避免把 timer 控制做成浅 Interface。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformGenerationProgressTickModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformGenerationProgressTickModel.ts src/components/platform-entry/platformGenerationProgressTickModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,47 +0,0 @@
|
||||
# 【前端架构】Platform Mini Game Draft Generation State Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 曾内联维护小游戏生成状态的恢复、失败/完成收尾、展示 rebase、拼图后端进度合并、抓大鹅生成资产旁路进度合并和生成中 / ready 判定。壳层因此既要处理 API 回包、React state、后台任务、URL 和 stage，又要记住 `MiniGameDraftGenerationState` 的生命周期细节。
|
||||
|
||||
这些状态变换不读取 DOM，不请求网络，也不写 React state；它们属于平台层小游戏草稿生成状态 **Module**。壳层只应决定何时调用、把返回值写入对应 state。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts` 作为 Platform Mini Game Draft Generation State **Module**。其公开 **Interface** 为：
|
||||
|
||||
- `createMiniGameDraftGenerationStateForRestoredDraft(kind, metadata?, startedAtMs?)`：为恢复的草稿重建生成态，并保留后端开始时间作为进度事实源。
|
||||
- `createFailedMiniGameDraftGenerationStateForRestoredDraft(kind, updatedAt, error, metadata?)`：恢复失败草稿时按后端 `updatedAt` 建立失败态。
|
||||
- `rebaseMiniGameDraftGenerationStateForDisplay(state)` 与 `rebaseMiniGameDraftBackgroundCompileTaskForDisplay(task)`：清理展示用 `finishedAtMs`，避免返回生成页后沿用结束态计时。
|
||||
- `createPuzzleDraftGenerationStateFromPayload(payload, session?)`、`resolvePuzzlePhaseFromSessionProgress(state, session)`、`mergePuzzleSessionProgressIntoGenerationState(state, session)`：集中处理拼图生成的 aiRedraw、后端进度百分比和 phase 推进。
|
||||
- `mergeMatch3DGeneratedAssetsIntoGenerationState(state, assets)`：抓大鹅轮询到作品素材后，按可用图片数量推进生成页资产计数，并把首个素材错误传播到生成态。
|
||||
- `resolveFinishedMiniGameDraftGenerationState(state, phase, options?)`：统一完成 / 失败收尾的 `finishedAtMs`、错误与资产计数合并。
|
||||
- `isMiniGameDraftReady(state)` 与 `isMiniGameDraftGenerating(state)`：统一生成态轻量判定。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它继续负责 API、background task、React state 写入、作品架刷新、URL 与 stage 切换。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 恢复草稿状态必须允许调用方传入 `startedAtMs`；未传时使用当前时间，与旧逻辑一致。
|
||||
- 恢复失败状态必须通过 `resolveMiniGameDraftGenerationStartedAtMs(updatedAt)` 解析后端时间，并保留传入 metadata。
|
||||
- `resolveFinishedMiniGameDraftGenerationState` 只覆盖显式传入的 `error`、`completedAssetCount`、`totalAssetCount`；未传时沿用原 state。
|
||||
- 拼图 session 只有在 `draft` 存在且不是 `formDraft` 时才视为后端编译生成中 session，才写入 `puzzleProgressPercent` 并推进 phase。
|
||||
- 拼图进度阈值保持旧值：`>=96` 到 `puzzle-select-image`，`>=94` 到 `puzzle-ui-assets`，`>=88` 时按 `puzzleAiRedraw=false` 进入 `puzzle-level-scene`，否则进入 `puzzle-cover-image`。
|
||||
- phase 变化时 `puzzleActiveStepStartedAtMs` 使用 session `updatedAt` 解析值；phase 不变时保留旧值。
|
||||
- 抓大鹅资产旁路进度不得覆盖 `ready` 或 `failed` 终态；非终态下只统计有 `imageViews[].imageObjectKey` / `imageViews[].imageSrc`、顶层 `imageObjectKey` 或顶层 `imageSrc` 的素材。
|
||||
- 抓大鹅资产旁路进度的 `totalAssetCount` 至少为 `5`，保留当前五物品首批生成节奏；已有素材数量超过 `5` 时按真实素材数量展示。
|
||||
- 抓大鹅已有可用素材时 phase 推进到 `match3d-generate-views`；无可用素材时保留原 phase；首个素材错误写入 `error`，无素材错误时保留原错误。
|
||||
- 展示 rebase 只清理 `finishedAtMs`，不得修改 phase、error、资产计数或 metadata。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层以状态变换函数表达意图；生成态字段、拼图阈值、抓大鹅素材计数、时间解析与计数合并藏入 Module Implementation。
|
||||
- **Leverage**：后续新增小游戏生成恢复、调整拼图后端进度阈值或改变抓大鹅素材批次展示时，先改 Module 与单测，再让壳层 Adapter 保持调用点不变。
|
||||
- **Locality**：小游戏生成状态规则集中到一个纯测试面，避免在大型壳层的 API callback、background task 和恢复流程中重复推理 `MiniGameDraftGenerationState`。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformMiniGameDraftGenerationStateModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformMiniGameDraftGenerationStateModel.ts src/components/platform-entry/platformMiniGameDraftGenerationStateModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,52 +0,0 @@
|
||||
# 【前端架构】Platform Mini Game Draft Payload Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 曾内联维护拼图和抓大鹅草稿恢复所需的表单 payload、拼图编译 action payload、拼图作品更新 payload、跳一跳 / 敲木鱼生成 action payload、作品摘要回填 payload 和 pending 草稿 metadata。壳层因此需要理解拼图描述字段优先级、formDraft 回退、结果页 draft 到作品更新字段的映射、Match3D config / draft / anchorPack 优先级、跳一跳 / 敲木鱼 payload 与 session draft 优先级，以及 pending 作品架标题摘要如何从 payload 派生。后续还残留拼图 form-only 草稿判定，影响 action 分流、草稿恢复阶段和结果页渲染。
|
||||
|
||||
这些逻辑都是 DTO 变换；不读取 React state，不请求网络，也不写 URL。壳层只应决定何时恢复、何时提交 action、何时写入生成状态。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformMiniGameDraftPayloadModel.ts` 作为 Platform Mini Game Draft Payload **Module**。其公开 **Interface** 为：
|
||||
|
||||
- `buildPuzzleFormPayloadFromWork(item)`：从拼图作品摘要恢复创作表单 payload。
|
||||
- `buildPuzzleFormPayloadFromSession(session)`：从拼图 session 恢复创作表单 payload。
|
||||
- `buildPuzzleFormPayloadFromAction(payload)`：从拼图 action 还原表单 payload，仅接受 `compile_puzzle_draft` 与 `save_puzzle_form_draft`。
|
||||
- `buildPuzzleCompileActionFromFormPayload(payload)`：从表单 payload 构造拼图编译 action。
|
||||
- `buildPuzzleWorkUpdatePayloadFromDraft(draft)`：从拼图结果 draft 构造 `updatePuzzleWork(...)` 所需 payload。
|
||||
- `buildJumpHopDraftActionPayload(actionType, { payload, draft })`：从跳一跳表单 payload / session draft 构造生成或重生成 action。
|
||||
- `buildWoodenFishDraftActionPayload(actionType, { payload, draft })`：从敲木鱼表单 payload / session draft 构造生成或重生成 action。
|
||||
- `buildPendingPuzzleDraftMetadata(payload)`：从拼图 payload 派生 pending 作品架 metadata。
|
||||
- `isPuzzleFormOnlyDraft(session)` 与 `isEmptyPuzzleFormOnlyDraft(session)`：判断拼图 session 是否仍只是表单草稿，以及表单草稿是否没有任何可提交内容。
|
||||
- `buildMatch3DFormPayloadFromSession(session)` 与 `buildMatch3DFormPayloadFromWork(item)`：从抓大鹅 session / work 恢复表单 payload。
|
||||
- `buildPendingMatch3DDraftMetadata(payload)`：从抓大鹅 payload 派生 pending metadata。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它继续负责 API、Action 执行、background task、生成状态、错误提示、作品架和阶段切换。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 拼图 work payload 的 `pictureDescription` 优先级固定为 `workDescription > summary > first level pictureDescription > levelName > workTitle > ''`。
|
||||
- 拼图 session payload 的 `pictureDescription` 优先级固定为 `formDraft.pictureDescription > first level pictureDescription > anchorPack.visualSubject.value > seedText > ''`。
|
||||
- 拼图编译 action 的 `promptText` 来自 `pictureDescription || seedText`；`workDescription` 缺省回退到图片描述；`candidateCount` 固定为 `1`。
|
||||
- 拼图 action 还原只接受 `compile_puzzle_draft` 与 `save_puzzle_form_draft`；其它 action 返回 `null`。
|
||||
- 拼图作品更新 payload 必须直接映射 `workTitle`、`workDescription`、`levelName`、`summary`、`themeTags`、`coverImageSrc`、`coverAssetId`，`levels` 缺失时回退空数组。
|
||||
- 跳一跳和敲木鱼生成 action payload 的字段优先级固定为表单 payload 优先，其次 session draft；重生成 action 只传 session draft 字段。
|
||||
- 拼图 form-only 草稿只在 `session.stage === 'collecting_anchors'` 且存在 `draft.formDraft` 时成立。
|
||||
- 空 form-only 草稿必须同时缺少 `seedText`、`formDraft.workTitle`、`formDraft.workDescription` 与 `formDraft.pictureDescription`。
|
||||
- 抓大鹅 session payload 优先读取 `config`，其次 `draft`，最后 `anchorPack`；`anchorPack.clearCount` 与 `anchorPack.difficulty` 只接受有限数字字符串或数字。
|
||||
- 抓大鹅 work payload 的 `themeText` 优先 `themeText`，缺失回退 `gameName`。
|
||||
- pending metadata 只收非空 trim 后标题和摘要；抓大鹅 metadata 用 `themeText || seedText` 同时作为 title 和 summary。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层以一组表意函数取得 payload / metadata；字段优先级、结果页 draft 更新字段、跳一跳 / 敲木鱼 action 字段、默认空资产和数字解析藏入 Module Implementation。
|
||||
- **Leverage**：后续调整拼图或抓大鹅草稿恢复表单、拼图作品更新字段、跳一跳 / 敲木鱼生成 action 字段时，先改 Module 与单测，再保持壳层 API / state 副作用不变。
|
||||
- **Locality**：表单恢复、作品更新与 action payload 规则集中到一个纯测试面，避免在大型平台壳的生成、重试和恢复流程里重复散落 DTO 拼装。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformMiniGameDraftPayloadModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformMiniGameDraftPayloadModel.ts src/components/platform-entry/platformMiniGameDraftPayloadModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,47 +0,0 @@
|
||||
# 【前端架构】Platform Mini Game Session Mapping Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 顶部曾保留拼图 runtime 恢复、方洞挑战 session draft 转 profile、视觉小说 work detail 转 Agent session、跳一跳 pending session、敲木鱼 work detail 恢复、敲木鱼生成中作品摘要和敲木鱼 pending session 多段纯 DTO 映射。它们没有 React state、网络请求、路由、弹窗或计时副作用，却住在大型平台壳内；新增或修正生成中草稿恢复时，需要在壳层里理解 sessionId 优先级、拼图稳定 ID、方洞 profile 默认值、视觉小说 work/session fallback、pending draft 默认值和木鱼 fallback 规则。
|
||||
|
||||
这些规则属于平台壳 session / work 恢复映射，应成为可测试的 **Module**。壳层只负责调用网络、写 React state、写 URL 和切换 stage。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformMiniGameSessionMappingModel.ts` 作为 Platform Mini Game Session Mapping **Module**。其公开 **Interface** 为：
|
||||
|
||||
- `buildPuzzleRuntimeWorkFromSession(session, owner)`：从拼图 Agent session 构造可进入 runtime 的 draft `PuzzleWorkSummary`，缺草稿、缺 profile 或缺封面时返回 `null`。
|
||||
- `buildSquareHoleProfileFromSession(session)`：从方洞挑战 Agent session draft 构造草稿 `SquareHoleWorkProfile`，缺 session、缺 draft 或缺 profileId 时返回 `null`。
|
||||
- `buildVisualNovelSessionFromWorkDetail(work)`：从视觉小说 work detail 恢复 `VisualNovelAgentSessionSnapshot`，供草稿作品架回到结果页继续编辑。
|
||||
- `buildJumpHopPendingSession(item)`：从跳一跳作品架 summary 构造生成中 pending session。
|
||||
- `buildWoodenFishSessionFromWorkDetail(work, fallbackItem?)`：从敲木鱼 work detail 恢复 session，并按 summary / fallback / profileId 决定 sessionId。
|
||||
- `buildWoodenFishGeneratingWorkSummary(session, payload?)`：从敲木鱼生成 session 和可选表单 payload 构造作品架生成中摘要。
|
||||
- `buildWoodenFishPendingSession(item)`：从敲木鱼作品架 summary 构造生成中 pending session。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：调用这些映射后继续负责 `set*Session`、`set*Work`、`set*Run`、`createMiniGameDraftGenerationState(...)`、`writeCreationUrlState(...)`、`enterCreateTab()` 和 `setSelectionStage(...)`。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 拼图 runtime work 必须保留 `draft.coverImageSrc` 非空门槛，避免启动缺封面的草稿运行态。
|
||||
- 拼图 profileId 优先 `publishedProfileId`，否则用 `buildPuzzleResultProfileId(sessionId)`；workId 使用 `buildPuzzleResultWorkId(sessionId)`，缺失时回退 profileId。
|
||||
- 拼图 owner 缺省为 `current-user` / `玩家`；`publishReady` 来自 `session.resultPreview?.publishReady`。
|
||||
- 方洞 profile 的 `workId` 与 `profileId` 都来自 draft `profileId`；owner 固定为 `current-user`，`sourceSessionId` 来自 sessionId。
|
||||
- 方洞 profile 的 `updatedAt` 优先 session `updatedAt`，缺失时使用当前时间；`publicationStatus='draft'`、`playCount=0`、`publishedAt=null`，`publishReady` 来自 draft。
|
||||
- 视觉小说恢复 session 的 `sessionId` 优先归一化后的 `sourceSessionId`，为空时回退 `workId`；`status='ready'`，`messages=[]`，`pendingAction=null`，`sourceMode` 来自 draft，`updatedAt` 来自 summary。
|
||||
- 跳一跳 pending sessionId 优先 `sourceSessionId`，缺失时用 `profileId`；素材、路径和 prompt 维持空值兜底。
|
||||
- 敲木鱼 detail sessionId 优先级固定为 `work.summary.sourceSessionId > fallbackItem.sourceSessionId > profileId`。
|
||||
- 敲木鱼生成中摘要的 `workId/profileId/sourceSessionId` 都来自 sessionId；标题、描述和标签优先表单 payload，其次 session draft，最后回退 `敲木鱼` / 空描述 / `['敲木鱼']`。
|
||||
- 敲木鱼 pending session 保持 `floatingWords=['功德 +1']`、素材 / 音效 / 背景为空的旧默认。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层以少量函数取得恢复用 DTO；ID 优先级、方洞 profile 默认值、视觉小说 session fallback、敲木鱼生成中摘要和 pending draft 字段藏入 Module Implementation。
|
||||
- **Leverage**：后续新增生成中作品恢复或修改 sessionId 规则时，先改 Module 与单测，再保持壳层 Adapter 副作用不变。
|
||||
- **Locality**：拼图、方洞、视觉小说、跳一跳和敲木鱼的恢复 / 生成中映射集中在一个纯测试面，避免在大型壳层顶部继续堆积 DTO 构造。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformMiniGameSessionMappingModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformMiniGameSessionMappingModel.ts src/components/platform-entry/platformMiniGameSessionMappingModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,39 +0,0 @@
|
||||
# 【前端架构】Platform Played Work Open Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 的个人“玩过作品”点击回调曾在壳层内直接判断 `worldType`、`worldKey` 前缀、玩法别名、目标 ID 兜底、RPG 公开详情 payload 和大鱼吃小鱼 gallery miss fallback。壳层因此同时承载纯打开意图与异步副作用，后续新增玩法或修正玩过作品身份时缺少稳定测试面。
|
||||
|
||||
个人“玩过作品”的点击规则属于打开意图。壳层应只关闭面板、读取 gallery、打开详情和写错误；玩法别名、目标 ID、fallback payload 应收口到纯 **Module**。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformPlayedWorkOpenModel.ts` 作为 Platform Played Work Open **Module**。其公开 **Interface** 为：
|
||||
|
||||
- `resolvePlatformPlayedWorkOpenIntent(work)`：输入 `ProfilePlayedWorkSummary`，输出 `noop`、各玩法公开详情打开意图、`open-big-fish` 或 `open-rpg`。
|
||||
- `PlatformPlayedWorkOpenIntent`：描述壳层可执行的打开动作；大鱼吃小鱼意图包含 `sessionId` 和 gallery miss 时使用的 `fallbackWork`，RPG 意图包含 `CustomWorldGalleryCard` 详情 payload。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它保留 `setIsProfilePlayStatsOpen(false)`、各玩法 `open*PublicWorkDetail`、`refreshBigFishGallery()`、大鱼 gallery 命中优先逻辑、`mapBigFishWorkToPublicWorkDetail(...)` 与错误 setter。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- `worldType` 只做小写归一，不 trim；`worldKey` 前缀匹配保持大小写敏感，延续旧行为。
|
||||
- `profileId` 使用 nullish 优先级：只在 `profileId` 为 `null` / `undefined` 时从 `worldKey` 前缀兜底；空字符串仍视为缺目标并返回 `noop`。
|
||||
- `puzzle` 打开时固定携带 `{ tab: 'profile' }`。
|
||||
- `match3d` / `match_3d`、`square-hole` / `square_hole`、`jump-hop` / `jump_hop`、`wooden-fish` / `wooden_fish`、`big-fish` / `big_fish` 均保持既有别名。
|
||||
- `big-fish` 缺 gallery 命中时使用 Module 生成的 `fallbackWork`，默认 `ownerUserId` 为空串、`authorDisplayName` 为 `worldSubtitle || '玩家'`、关卡和素材 ready 计数为 `0` / `false`。
|
||||
- 未识别的 `worldType` 仍按 RPG 公开详情打开；缺 `ownerUserId` 或缺 profile 目标时返回 `noop`。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：调用方只消费一个打开 intent；玩法别名、目标 ID 兜底和 fallback payload 藏入 Module Implementation。
|
||||
- **Leverage**：新增“玩过作品”玩法时，先在 intent union、resolver 与单测中定义，再让壳层 Adapter 绑定对应打开副作用。
|
||||
- **Locality**：RPG fallback payload 与大鱼 fallback work 不再散落在大型壳层里，维护者可在纯测试中锁定字段契约。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformPlayedWorkOpenModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformPlayedWorkOpenModel.ts src/components/platform-entry/platformPlayedWorkOpenModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "authenticated users can open save archives from the profile played panel"`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,32 +0,0 @@
|
||||
# 【前端架构】Platform Profile Wallet Delta Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍内联维护个人钱包余额的本地 delta 规则：余额归一化、本地扣点 / 返还后的 dashboard 乐观更新，以及刷新服务端 dashboard 时如何抵消已经被服务端反映的本地 delta。
|
||||
|
||||
这些规则是纯展示状态计算，但留在平台壳层会让壳层同时理解钱包余额边界、整数截断、负数保护和服务端快照对账。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `platformProfileWalletDeltaModel.ts`，收口钱包余额本地 delta 的纯规则：
|
||||
|
||||
- `resolveProfileWalletBalance(...)` 负责把 dashboard 余额归一为非负整数。
|
||||
- `adjustProfileDashboardWalletBalance(...)` 负责把本地 delta 应用到 dashboard，并刷新 `updatedAt`。
|
||||
- `reconcileProfileWalletLocalDeltaWithServerDashboard(...)` 负责在拿到新服务端 dashboard 后扣除已被服务端反映的本地借贷变化。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 继续保留 API 请求、React ref、state 写入和刷新触发副作用。
|
||||
|
||||
## 接口约束
|
||||
|
||||
- 非数字、无穷值或空 dashboard 的余额按 `0` 处理。
|
||||
- 本地 delta 必须先 `Math.trunc`，余额不得低于 `0`。
|
||||
- 当服务端最新余额已经反映本地扣点时，剩余负 delta 应减少；已经全部反映时归零。
|
||||
- 当服务端最新余额已经反映本地返还 / 奖励时，剩余正 delta 应减少；已经全部反映时归零。
|
||||
- 服务端余额变化方向与本地 delta 相反时，不得错误抵消。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformProfileWalletDeltaModel.test.ts`
|
||||
- 针对新 Module 与 `PlatformEntryFlowShellImpl.tsx` 执行 ESLint。
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,40 +0,0 @@
|
||||
# 【前端架构】Platform Public Code Search Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 的公开搜索回调曾直接在壳层内判断 `user_` / `user-`、`PZ`、`BF`、`JH`、`WF`、`BO`、`M3`、`SH`、`VN`、`BB`、`CW`、纯数字和普通关键词的优先级。壳层因此既要持有搜索输入到查找顺序的纯规则，又要执行各玩法公开详情读取、用户读取、运行态启动和错误归航副作用。
|
||||
|
||||
公开搜索的“先查什么、失败后回退什么”是稳定的分流规则，应有独立测试面；壳层只应作为副作用 Adapter，按计划执行网络读取与打开动作。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformPublicCodeSearchModel.ts` 作为 Platform Public Code Search **Module**。其公开 **Interface** 为：
|
||||
|
||||
- `resolvePlatformPublicCodeSearchPlan(keyword)`：输入用户搜索词，输出 `{ normalizedKeyword, steps }`；空输入返回 `null`。
|
||||
- `PlatformPublicCodeSearchStep`：枚举壳层可执行的查找步骤，包括 `user-id`、`public-user-code`、`rpg-work`、各玩法公开作品步骤与 `bark-battle-work`。
|
||||
- `mapRpgPublicCodeSearchDetailToGalleryCard(entry)`：把 RPG by-code 详情响应映射为公开作品卡，收口 `playCount` / `remixCount` / `likeCount` 的 `0` 兜底。
|
||||
- `resolve*PublicCodeSearchMatch(entries, keyword)`：统一各玩法公开作品列表的公开码匹配、公开可见性过滤和详情卡 DTO 映射；拼图、大鱼吃小鱼、跳一跳、敲木鱼、宝贝识物、抓大鹅、方洞挑战、视觉小说和汪汪声浪都走此接口。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它保留 `getPublicAuthUserByCode`、各玩法 gallery 刷新 / 详情打开、Bark Battle runtime 特例和 missing work 归航副作用，只按 `steps` 顺序执行，前一步失败才尝试下一步；壳层不再重复维护 per-play `isSame*PublicWorkCode` 匹配和 DTO 映射。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 空白搜索词返回 `null`，壳层不得进入搜索 loading。
|
||||
- `user_` / `user-` 开头的内部用户 ID 只执行 `user-id`，不回退作品号。
|
||||
- `PZ`、`BF`、`JH`、`WF`、`BO`、`M3`、`SH`、`VN`、`BB` 前缀只进入对应玩法公开作品查找；`M3D-*` 继续归入并匹配 `M3` / 抓大鹅。
|
||||
- `CW` 与 `1-8` 位纯数字先查 RPG 公开作品，再回退陶泥号。
|
||||
- 普通关键词与 `SY` 陶泥号保持既有顺序：先查陶泥号，再查 RPG 公开作品，再查汪汪声浪作品，最后再以陶泥号兜底。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层只消费短小的 `steps` 与 match result Interface，搜索前缀、优先级、回退顺序、per-play 匹配和 DTO 映射藏入 Module Implementation。
|
||||
- **Leverage**：新增公开作品前缀时，先扩展 Module 的 step union、前缀表、matcher 和单测，再在壳层 Adapter 绑定对应网络读取与打开动作。
|
||||
- **Locality**：搜索计划与作品命中规则集中在一个纯 Module；UI、网络、详情打开与 runtime 启动副作用继续留在壳层，避免把副作用 setter 变成浅 Interface。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformPublicCodeSearchModel.test.ts`
|
||||
- `npm run test -- src/services/publicWorkCode.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformPublicCodeSearchModel.ts src/components/platform-entry/platformPublicCodeSearchModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,68 +0,0 @@
|
||||
# PlatformPublicWorkDetailFlow 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 已把公开作品身份、去重和推荐 runtime kind 收口到 `platformPublicGalleryFlow.ts`，但统一作品详情入口仍在壳层 Implementation 内直接判断 RPG、拼图、跳一跳、敲木鱼、视觉小说和其它玩法。壳层既要知道哪些公开详情可直接使用当前 entry，又要知道哪些玩法必须先补读完整详情，还要按当前用户判断详情按钮是“编辑”还是“改造”。这些是纯决策规则，继续留在巨型壳层会削弱 Locality。
|
||||
|
||||
## 决策
|
||||
|
||||
- 新增 `src/components/platform-entry/platformPublicWorkDetailFlow.ts` 作为 Platform Public Work Detail Flow Module。
|
||||
- Module Interface 收口：
|
||||
- `getPlatformPublicWorkDetailKind(entry)`
|
||||
- `resolvePlatformPublicWorkDetailOpenStrategy(entry)`
|
||||
- `resolvePlatformPublicWorkActionMode(entry, viewerUserId)`
|
||||
- `resolvePlatformPublicWorkEditIntent(entry, deps)`
|
||||
- `resolvePlatformPublicWorkLikeIntent(entry)`
|
||||
- `resolvePlatformPublicWorkRemixIntent(entry)`
|
||||
- `resolvePlatformPublicWorkStartIntent(entry, deps)`
|
||||
- `resolvePlatformPublicWorkDetailOpenDecision(entry, deps)`
|
||||
- `resolveActivePlatformPublicWorkAuthorEntry(args)`
|
||||
- `map*WorkToPublicWorkDetail(...)`
|
||||
- `mapPublicWorkDetailToPuzzleWork(entry)`
|
||||
- `mapPublicWorkDetailToBigFishWork(entry)`
|
||||
- `mapPublicWorkDetailToSquareHoleWork(entry)`
|
||||
- `mapBarkBattlePublicDetailToWorkSummary(entry)`
|
||||
- `resolveVisiblePuzzleDetailCoverCount(entry, run)`
|
||||
- `PlatformEntryFlowShellImpl.tsx` 继续作为 Adapter：根据 open strategy 调用 `openPublicWorkDetail`、`openPuzzlePublicWorkDetail`、`openJumpHopPublicWorkDetail`、`openWoodenFishPublicWorkDetail`、`openVisualNovelPublicWorkDetail` 或 `openRpgPublicWorkDetail`。
|
||||
- 公开详情 entry 映射与公开详情反推玩法 work 摘要也收口到 Module。壳层只在运行态启动、编辑、改造、推荐缓存和详情展示时调用映射 Interface，不再在壳层顶部持有每个玩法的 DTO 拼装 Implementation。
|
||||
- `mapMatch3DWorkToPublicWorkDetail` 归入 `platformMatch3DRuntimeProfile.ts`，继续委托 `normalizeMatch3DWorkForRuntimeUi` 处理素材归一和背景资产提升；`platformPublicWorkDetailFlow.ts` 不复制 Match3D 运行态素材规则。
|
||||
- 公开详情启动、编辑、点赞和改造只抽“意图” Interface，不把整个 callback 搬进 Module。壳层继续作为 Adapter 执行鉴权、API 调用、运行态启动、草稿恢复、busy 状态、缓存同步、stage 切换和错误 setter，避免形成伪 Seam。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- `getPlatformPublicWorkDetailKind` 只根据 `PlatformPublicGalleryCard` 的玩法判定 helper 归一 kind；没有 `sourceType` 的公开 RPG 作品回退为 `rpg`。
|
||||
- `resolvePlatformPublicWorkDetailOpenStrategy` 只表达“如何打开详情”，不执行网络请求或 state setter。
|
||||
- 拼图、跳一跳、敲木鱼、视觉小说需要按 `profileId` 补读完整详情；返回对应 `load-*` strategy。
|
||||
- 大鱼吃小鱼、抓大鹅、方洞挑战、汪汪声浪、宝贝识物和其它可直接展示的公开 entry 返回 `use-entry` strategy。
|
||||
- RPG 返回 `load-rpg-detail` strategy，由壳层 Adapter 继续调用 RPG 详情读取流程。
|
||||
- `resolvePlatformPublicWorkActionMode` 只比较 `entry.ownerUserId` 与当前 viewer user id；当前用户拥有该公开作品时返回 `edit`，否则返回 `remix`。
|
||||
- `resolvePlatformPublicWorkEditIntent` 只表达自有公开作品编辑意图：大鱼吃小鱼、拼图、抓大鹅、方洞挑战、视觉小说和汪汪声浪在能定位原草稿时返回对应 draft open 目标；跳一跳、敲木鱼和缺草稿作品返回原阻断文案；宝贝识物只返回需解析本地草稿的 intent；旧 RPG gallery fallback 只在完整 RPG 详情已补读且 profile 匹配时返回编辑 intent。壳层仍执行草稿恢复、宝贝识物异步草稿解析、RPG 编辑导航和错误展示。
|
||||
- `resolvePlatformPublicWorkEditIntent` 的 `deps` 只接编辑决策所需的当前拼图详情、当前 RPG 详情、视觉小说作品缓存、汪汪声浪作品缓存，以及抓大鹅 public detail -> work 的 Adapter。抓大鹅 Adapter 必须来自 Match3D Runtime Profile Module，以保留 `generatedItemAssets` 归一化与背景资产提升的 Locality。
|
||||
- `resolvePlatformPublicWorkLikeIntent` 只表达公开作品点赞意图：大鱼吃小鱼、拼图和旧 RPG gallery fallback 返回可执行 intent；宝贝识物、汪汪声浪、方洞挑战和视觉小说返回不可用文案。壳层只按 intent 调用 API、写缓存和展示错误，不再持有这组能力矩阵。
|
||||
- `resolvePlatformPublicWorkRemixIntent` 只表达公开作品改造意图：大鱼吃小鱼和拼图返回可执行 intent 与成功后目标 stage，旧 RPG gallery fallback 返回可执行 intent，其它玩法返回原未开放文案。壳层只按 intent 调用 remix API、写 session / 缓存、切 stage 和展示错误。
|
||||
- `resolvePlatformPublicWorkStartIntent` 只表达公开作品“开始游玩”意图：大鱼吃小鱼、拼图、跳一跳、敲木鱼、抓大鹅、方洞挑战、视觉小说、汪汪声浪和宝贝识物返回对应启动目标；旧 RPG gallery fallback 只在完整 RPG 详情已补读且 profile 匹配时返回记录游玩 intent，否则返回原阻断文案。壳层仍执行登录保护、运行态启动、RPG 游玩记录、详情更新、busy 状态和错误展示。
|
||||
- `resolvePlatformPublicWorkStartIntent` 的 `deps` 只接启动决策所需的当前拼图详情、当前 RPG 详情、汪汪声浪作品缓存，以及抓大鹅 public detail -> work 的 Adapter。抓大鹅 Adapter 必须来自 Match3D Runtime Profile Module，以保留 `generatedItemAssets` 归一化与背景资产提升的 Locality。
|
||||
- `resolvePlatformPublicWorkDetailOpenDecision` 只表达直接展示公开详情的打开 / 阻断结果、错误文案、目标 stage 与可写入历史的路径；真正执行 setter、push history 的副作用仍由壳层 Adapter 执行。
|
||||
- `resolveActivePlatformPublicWorkAuthorEntry` 只在 `work-detail` 阶段选择统一公开详情 entry，在 RPG `detail` 阶段只选择非 draft 的 RPG 详情 entry；作者请求、竞态 request key 和缓存仍留壳层。
|
||||
- `map*WorkToPublicWorkDetail` 只把各玩法已存在的 work / gallery summary 映射为统一详情 entry；公开码、封面、统计与标题字段继续复用 `rpgEntryWorldPresentation.ts` 的平台公开卡片映射。
|
||||
- `mapPublicWorkDetailToPuzzleWork`、`mapPublicWorkDetailToBigFishWork`、`mapPublicWorkDetailToSquareHoleWork` 和 `mapBarkBattlePublicDetailToWorkSummary` 只用于公开详情 CTA、推荐缓存或运行态启动前的兼容 work 摘要拼装；缺省值必须留在 Module 测试中固定，壳层不得重复推导。
|
||||
- `resolveVisiblePuzzleDetailCoverCount` 只表达拼图公开详情封面解锁规则：非拼图、无当前 run 或 run 不属于当前公开详情时只展示首图；当前 run 属于该公开详情时按 `clearedLevelCount + 1` 解锁，但至少为 1。`PlatformWorkDetailView` 只接收 `visibleCoverCount` 展示，不读取 run。
|
||||
- Match3D 的公开详情与 work 摘要互转仍属于 Match3D Runtime Profile Module，因为它依赖 `generatedItemAssets` 归一化与背景资产提升。公开详情 Flow 只接统一详情策略，不复制该运行态规则。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层传入公开作品 entry、玩法 work summary、当前用户 id、当前拼图 run 或少量启动 / 编辑 deps，即可得到详情打开策略、动作模式、编辑 / 点赞 / 改造 / 启动意图、统一详情映射和封面可见数；玩法判定、能力矩阵与 DTO 默认值藏在 Module Implementation 内。
|
||||
- **Leverage**：新增玩法公开详情时先补 Strategy / Mapping 单测，再接壳层 Adapter，不必在多个 JSX / callback 位置重复 sourceType 判断或 DTO 回填。
|
||||
- **Locality**：公开作品详情入口的纯策略与通用映射集中到一个小 Module；Match3D 素材归一仍在 Match3D Module；启动运行态、点赞、改造、编辑等副作用仍留在壳层，避免伪 Seam。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformPublicWorkDetailFlow.test.ts`
|
||||
- `npm run test -- src/components/platform-entry/platformMatch3DRuntimeProfile.test.ts`
|
||||
- `npm run test -- src/components/platform-entry/platformPublicGalleryFlow.test.ts`
|
||||
- `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "public detail|owned public puzzle detail|direct missing public work detail"`
|
||||
- `npx eslint src/components/platform-entry/platformPublicWorkDetailFlow.ts src/components/platform-entry/platformPublicWorkDetailFlow.test.ts --max-warnings 0`
|
||||
- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,44 +0,0 @@
|
||||
# 【前端架构】Platform Puzzle Draft Recovery Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 曾内联维护拼图生成完成后刷新恢复的两个纯函数：`normalizeRecoveredPuzzleDraftSession` 与 `hasRecoverableGeneratedPuzzleDraft`。旧逻辑只要草稿有 `coverImageSrc`、首关 cover 或候选图，就会把恢复会话的 draft 和首关 `generationStatus` 抬成 `ready`，再进入结果页。
|
||||
|
||||
`.hermes/shared-memory/pitfalls.md` 已记录：拼图待发布判定偏弱时，只有首图但缺关卡画面、UI spritesheet 或关卡背景的半成品会被误当完成，用户进入结果页后仍可能空图或无法发布。
|
||||
|
||||
本切片先修前端恢复链路：只有完整首关资产包存在时，恢复流程才视为可完成。后端 `build_result_preview` / `validate_publish_requirements` / `is_puzzle_session_snapshot_publish_ready` 的发布门槛收紧另作后续切片，不混入本次前端模型收口。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts` 作为 Platform Puzzle Draft Recovery **Module**。其公开 **Interface** 为：
|
||||
|
||||
- `normalizeRecoveredPuzzleDraftSession(session)`：从恢复会话里补齐首图 cover、assetId 和 selectedCandidateId；只有完整资产包满足时，才把 draft 与首关 `generationStatus` 改为 `ready`。
|
||||
- `hasRecoverableGeneratedPuzzleDraft(session)`：判断恢复会话是否拥有完整首关资产包。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它继续负责拉取 session、写 background task、写 React state、打开结果页和切换 stage。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 无 draft 时保持原 session，并判定不可恢复完成态。
|
||||
- 首图可来自 `draft.coverImageSrc`、首关 `coverImageSrc` 或选中 / 首个候选图。
|
||||
- 完整首关资产包必须同时具备：
|
||||
- 首图 cover；
|
||||
- `levelSceneImageSrc` 或 `levelSceneImageObjectKey`；
|
||||
- `uiSpritesheetImageSrc` 或 `uiSpritesheetImageObjectKey`；
|
||||
- `levelBackgroundImageSrc` 或 `levelBackgroundImageObjectKey`。
|
||||
- cover / assetId / selectedCandidateId 可按旧优先级从 draft、首关、候选图回填；但若完整资产包不满足，不得把 `generationStatus` 抬为 `ready`。
|
||||
- 只修复前端恢复判定，不改变拼图发布接口、后端 session stage 或后端 preview compiler。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层以两个函数表达“恢复会话归一化”和“是否可作为生成完成态恢复”；完整资产门槛和候选图 fallback 藏入 Module Implementation。
|
||||
- **Leverage**：后续后端补齐发布门槛时，可用同一资产语言对齐前端恢复模型，避免壳层再散落条件判断。
|
||||
- **Locality**：拼图恢复判定集中到纯测试面，避免在异步恢复 callback 中把半成品 ready 规则继续隐身。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformPuzzleDraftRecoveryModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformPuzzleDraftRecoveryModel.ts src/components/platform-entry/platformPuzzleDraftRecoveryModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating puzzle draft"`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,36 +0,0 @@
|
||||
# 【前端架构】Platform Puzzle Runtime State Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 曾内联 `mergePuzzleServiceRuntimeState(...)`，在拼图排行榜提交回包后，把服务端 run 快照合并回当前前端 run。此逻辑没有 React state、网络、URL 或弹窗副作用，却需要理解 `PuzzleRunSnapshot` 的局部真相分工：拼块布局、当前关卡状态和计时结果由前端即时裁决；服务端回包只补排行榜、run 身份、通关数上限和下一关 handoff。
|
||||
|
||||
若该合并规则继续留在平台壳，后续调整排行榜来源、相似作品下一关或本地 / 服务端 run 混合策略时，维护者必须翻大型壳层并同时避开大量副作用代码。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformPuzzleRuntimeStateModel.ts` 作为 Platform Puzzle Runtime State **Module**。公开 **Interface**：
|
||||
|
||||
- `mergePuzzleServiceRuntimeState(currentRun, serviceRun)`：当双方都有 `currentLevel` 时，保留当前前端关卡状态与棋盘，只合并服务端 run 身份、`clearedLevelCount` 上限、排行榜与下一关 handoff；任一方缺 `currentLevel` 时返回当前 run。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 继续作为 **Adapter**：它负责提交排行榜、读取回包、写 React state、刷新 archive 和错误提示，不再持有拼图 run 快照合并字段清单。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 缺少 `currentRun.currentLevel` 或 `serviceRun.currentLevel` 时不得合并，直接返回当前 run。
|
||||
- `clearedLevelCount` 取当前 run 与服务端 run 的最大值，避免服务端较旧回包降低本地通关数。
|
||||
- 排行榜优先取 `serviceRun.currentLevel.leaderboardEntries`；为空时取 `serviceRun.leaderboardEntries`；两者皆空时保留当前关卡榜单。
|
||||
- `currentLevel` 的棋盘、状态、计时和关卡字段来自当前 run，不被服务端回包覆盖。
|
||||
- `runId`、`entryProfileId`、`recommendedNextProfileId`、`nextLevelMode`、`nextLevelProfileId`、`nextLevelId`、`recommendedNextWorks` 来自服务端 run。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层传入当前 run 与服务端 run，即取得合并后的稳定快照；排行榜来源、下一关 handoff 和前端局部真相保留规则藏入 Module Implementation。
|
||||
- **Leverage**：排行榜提交、后续相似作品推荐或服务端 run 字段变化时，先改纯 Module 与单测，壳层提交副作用不变。
|
||||
- **Locality**：拼图 runtime 快照合并规则集中到一个纯测试面，避免在平台壳中继续散落 `PuzzleRunSnapshot` 字段判断。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformPuzzleRuntimeStateModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformPuzzleRuntimeStateModel.ts src/components/platform-entry/platformPuzzleRuntimeStateModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,36 +0,0 @@
|
||||
# 【前端架构】Platform Recommend Runtime Auth Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
平台首页推荐流会以 embedded runtime 方式启动跳一跳、抓大鹅、方洞挑战、拼图、敲木鱼、视觉小说、大鱼吃小鱼和汪汪声浪等玩法。旧规则散在 `PlatformEntryFlowShellImpl.tsx` 顶层 helper 与多个启动 callback：匿名访客应申请 Runtime Guest Token，已登录或已有 access token 时应走 background auth，非 embedded 正常启动则不改普通鉴权。拼图还额外维护 `isolated` / `default` runtime auth mode，容易与通用推荐流口径漂移。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformRecommendRuntimeAuthModel.ts`，以纯 **Module** 收口推荐 runtime 鉴权计划：
|
||||
|
||||
- `resolvePlatformRecommendRuntimeAuthPlan(input)`：返回 `requestKind` 为 `none`、`background` 或 `runtime-guest`，并给出拼图 runtime 应落到 `default` 还是 `isolated`。
|
||||
- `shouldUsePlatformRecommendRuntimeGuestAuth(input)`：只判断当前用户状态和是否允许 guest auth，不读取本地 token。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 继续作为 **Adapter**：它读取 `getStoredAccessToken()`、调用 `ensureRuntimeGuestToken()`、拼装具体 request options，并在启动拼图时写入 `setPuzzleRuntimeAuthMode(...)`。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 非 embedded 且未显式允许 runtime guest auth 时，计划为 `none`。
|
||||
- embedded 推荐 runtime 若无登录用户且无本地 access token，计划为 `runtime-guest`。
|
||||
- embedded 推荐 runtime 若已有登录用户或本地 access token，计划为 `background`。
|
||||
- 拼图公开详情要求 `authMode='isolated'` 时，匿名状态应返回 `runtime-guest` 且 `puzzleRuntimeAuthMode='isolated'`。
|
||||
- 拼图公开详情要求 `authMode='isolated'` 但已登录或已有 access token 时，应回到 `default`，避免把账号态伪装成匿名 isolated guest。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层传入 embedded、是否允许 guest、用户 ID 与本地 token 布尔值，即得 request 计划和拼图 runtime auth mode。
|
||||
- **Leverage**：所有推荐 runtime 启动复用同一鉴权矩阵；新增玩法只需消费计划，不再重写匿名 / 已登录分支。
|
||||
- **Locality**：guest token 选择规则集中在纯测试面，具体 token 获取和 request options 仍留在壳层副作用 Adapter。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformRecommendRuntimeAuthModel.test.ts`
|
||||
- `npx eslint --max-warnings 0 src/components/platform-entry/platformRecommendRuntimeAuthModel.ts src/components/platform-entry/platformRecommendRuntimeAuthModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,40 +0,0 @@
|
||||
# 【前端架构】Platform Recommend Runtime Auto Start 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
平台推荐页的 embedded runtime 会在移动端首页自动选择当前推荐作品并启动对应玩法。旧 `useEffect` 同时判断桌面断点、当前 stage、当前 Tab、平台 loading、推荐列表是否为空、active entry 是否仍存在、对应 runtime 是否 ready、是否已有启动请求，以及下一条 entry 应选谁。
|
||||
|
||||
这组判断是纯推荐流自动启动决策，但留在 `PlatformEntryFlowShellImpl.tsx` 会让 effect 依赖很长，也让后续新增玩法时容易把 ready 判定和启动时机混在副作用里。
|
||||
|
||||
## 决策
|
||||
|
||||
扩展 `src/components/platform-entry/platformPublicGalleryFlow.ts`，新增 `resolvePlatformRecommendRuntimeAutoStartDecision(input)`：
|
||||
|
||||
- `noop`：当前不需要改变推荐 runtime。
|
||||
- `clear`：推荐列表为空，壳层应清空 active entry、runtime kind 和错误。
|
||||
- `start`：壳层应调用既有 `selectRecommendRuntimeEntry(entry)` 启动指定作品。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 继续作为 **Adapter**：它负责收集 React state、清空 state、调用 `selectRecommendRuntimeEntry(...)` 和执行各玩法 runtime 副作用。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 桌面端、非 `platform` stage、非 `home` Tab 或平台仍在 loading 时返回 `noop`。
|
||||
- 推荐列表为空时返回 `clear`。
|
||||
- active entry 存在且对应 runtime 已 ready 时返回 `noop`。
|
||||
- 当前已有启动请求时返回 `noop`。
|
||||
- active entry 存在但未 ready 时返回 `start(activeEntry)`。
|
||||
- active key 缺失或已不在列表中时返回 `start(firstEntry)`。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层只消费三态决策；列表查找、ready 判定和自动启动门禁藏入 Flow Module Implementation。
|
||||
- **Leverage**：后续推荐流新增玩法或改 ready 判定，只需补 `platformPublicGalleryFlow.ts` 的模型测试。
|
||||
- **Locality**：effect 只保留副作用动作，不再承载推荐流状态机知识。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformPublicGalleryFlow.test.ts`
|
||||
- `npx eslint --max-warnings 0 src/components/platform-entry/platformPublicGalleryFlow.ts src/components/platform-entry/platformPublicGalleryFlow.test.ts`
|
||||
- `npx eslint src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,38 +0,0 @@
|
||||
# 【前端架构】Platform RPG Agent Result Preview Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 曾内联维护 RPG Agent 结果页的发布门禁展示规则：从 `CustomWorldProfile` 顶层字段、`creatorIntent`、`anchorContent`、章节蓝图和场景章节中反证服务端返回的 legacy blocker 是否已经被当前结果页 profile 补齐，并同时在壳层内把 result preview source 映射成展示标签。
|
||||
|
||||
这些逻辑不读取 React state，不请求网络，不写 URL，也不操作弹窗；它们属于 RPG Agent 结果预览展示的纯判定。壳层继续负责 session、profile、发布动作和结果页 props 编排。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformRpgAgentResultPreviewModel.ts` 作为 Platform RPG Agent Result Preview **Module**。其公开 **Interface** 为：
|
||||
|
||||
- `buildPlatformRpgAgentResultPublishGateView(profile, fallbackBlockers, fallbackPublishReady)`：无 profile 时沿用服务端 fallback；有 profile 时过滤已经被当前 profile 结构字段满足的发布 blocker，并按剩余 blocker 重算展示态 `publishReady`。
|
||||
- `resolvePlatformRpgAgentResultPreviewSourceLabel(source)`：把 `published_profile`、`session_preview` 和未知 future source 映射成结果页预览来源标签。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为 **Adapter**：它只把 `agentResultPreview` 与 `generatedCustomWorldProfile` 交给 Module，并将返回的 blocker / label 传入结果页组件。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- 无 profile 时不得自行修正 blocker，必须保留 fallback blocker message 与 fallback `publishReady`。
|
||||
- 有 profile 时只过滤已知结构 blocker：`publish_missing_world_hook`、`publish_missing_player_premise`、`publish_missing_core_conflict`、`publish_missing_main_chapter`、`publish_missing_first_act`。
|
||||
- 世界钩子兼容读取 `worldHook`、`creatorIntent.worldHook`、`anchorContent.worldPromise`、`anchorContent.worldPromise.hook` 和 `settingText`。
|
||||
- 玩家前提兼容读取 `playerPremise`、`creatorIntent.playerPremise`、`anchorContent.playerEntryPoint.openingIdentity`、`openingProblem`、`entryMotivation`。
|
||||
- 主章节兼容读取 `chapters`、`sceneChapterBlueprints`、`sceneChapters`；首幕读取 `sceneChapterBlueprints` / `sceneChapters` 下的 `acts`。
|
||||
- 未知 blocker code 不得被前端过滤；未知 source 保留“服务端预览”兜底，不做穷尽删除。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：壳层以两个函数取得发布门禁展示和 source label；profile 兼容字段路径、legacy blocker code 与兜底规则藏入 Module Implementation。
|
||||
- **Leverage**：后续后端调整 RPG result preview blocker 或新增 source 时，先改 Module 与单测，再让壳层 Adapter 保持结果页 props 编排不变。
|
||||
- **Locality**：RPG Agent 结果预览展示规则集中到一个纯测试面，避免在大型平台壳中继续混杂 profile 结构探测。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformRpgAgentResultPreviewModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformRpgAgentResultPreviewModel.ts src/components/platform-entry/platformRpgAgentResultPreviewModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,32 +0,0 @@
|
||||
# 【前端架构】Platform Selection Stage Model 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 在受保护数据失效后会清空当前用户的私有作品、运行态、草稿 notice 和生成状态。清理完成后，壳层还要判断当前 `SelectionStage` 是否还能继续展示：公开首页、公开详情、工作台入口等阶段可保留；结果页、生成页、运行态、个人反馈等依赖私有数据或运行态快照的阶段必须回到首页。
|
||||
|
||||
此外，平台壳还曾在多个 `useEffect` 中分别判断 big-fish、match3d、square-hole、visual-novel、baby-object-match 缺少草稿、作品或 run 时应回工作台、结果页还是首页。这类“当前 stage 已不能被现有状态支撑”的规则同样属于 stage 纯判定，不应散在壳层。
|
||||
|
||||
此前这些规则以内联长否定串或多段相似 effect 维护在壳层 **Implementation** 内。新增玩法 stage 或调整登录态行为时，维护者必须在巨型壳层中查找白名单和状态缺失回退，缺少独立测试面。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformSelectionStageModel.ts` 作为 Platform Selection Stage **Module**。其公开 **Interface** 为：
|
||||
|
||||
- `resolveSelectionStageAfterProtectedDataLoss(stage)`：输入当前 `SelectionStage`，输出受保护数据失效后应停留的 stage；可保留则原样返回，否则返回 `platform`。
|
||||
- `resolveSelectionStageAfterMissingCreationState(params)`：输入当前 `SelectionStage` 与各玩法“是否有 session / draft / run / work / formPayload”等可渲染事实，输出状态缺失后应停留的 stage；仍可展示则原样返回。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍作为副作用 **Adapter**：负责检测受保护数据从可读变为不可读、清空各玩法缓存、重置生成和错误状态，或把当前 React state 汇总为布尔事实，并只在模型输出与当前 stage 不一致时调用 `setSelectionStage(nextStage)`。
|
||||
|
||||
## 约定
|
||||
|
||||
- 新增 `SelectionStage` 时，必须判断它在退出登录或鉴权上下文收回后是否仍可展示，并在本 **Module** 的全量 `Record<SelectionStage, boolean>` 与测试中列明。
|
||||
- 公开列表、公开详情和创作工作台入口可保留；依赖当前用户私有数据、生成 session、运行态 run 或个人资料的 stage 默认回 `platform`。
|
||||
- 缺失状态回退只读取壳层传入的布尔事实，不直接读取玩法 session / work / run 对象。big-fish、match3d、square-hole 的草稿事实必须来自 `Boolean(session?.draft)`；visual-novel 的 session draft 与 work draft 可独立支撑结果页；baby-object-match runtime 缺 draft 时不看 formPayload，直接回 `platform`。
|
||||
- 此 **Module** 不清理 state、不调用路由、不触发登录弹窗，只表达纯 stage 决策。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformSelectionStageModel.test.ts`
|
||||
- `npx eslint src/components/platform-entry/platformSelectionStageModel.ts src/components/platform-entry/platformSelectionStageModel.test.ts src/components/platform-entry/PlatformEntryFlowShellImpl.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,531 +0,0 @@
|
||||
# PlatformUiKit 弹窗与状态组件收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
前端已经有 `UnifiedModal` 统一遮罩、无障碍属性、Escape 关闭和移动端底部贴边布局，但业务页面仍反复手写提示弹窗、确认弹窗和 footer 按钮。平台入口的泥点提示、作品删除确认、发布失败提示等都在页面实现内拼接同类 `UnifiedModal` 属性和按钮样式，导致后续调整主题、按钮状态或移动端布局时需要改多个页面。
|
||||
|
||||
## 收口目标
|
||||
|
||||
- `src/components/common/UnifiedModal.tsx` 继续作为底层模态窗口 Module，负责遮罩、panel、header、body、footer 与关闭路径。
|
||||
- 新增 `src/components/common/UnifiedConfirmDialog.tsx` 作为提示 / 确认弹窗 Module，统一承载标题、说明、正文、主按钮、副按钮、危险动作、处理中禁用和主题样式。
|
||||
- 新增 `src/components/common/useCopyFeedback.ts` 作为复制反馈 Module，统一承载剪贴板写入、`idle / copied / failed` 状态、定时复位和卸载清理。
|
||||
- 新增 `src/components/common/CopyFeedbackButton.tsx` 作为复制反馈按钮 Module，统一承载默认复制 / 成功图标、反馈文案、`aria-label` / `title`、纯图标按钮模式和胶囊 action 外观入口。
|
||||
- 新增 `src/components/common/CopyCodeButton.tsx` 作为代码复制按钮 Module，统一承载作品号 / 用户号等短代码 chip 的三态文案、默认可访问名称、标题和胶囊 action 外观透传。
|
||||
- 新增 `src/components/common/CopyFeedbackMessage.tsx` 作为复制反馈提示 Module，统一承载成功 / 失败 toast 或行内状态提示。
|
||||
- 新增 `src/components/common/PlatformStatusMessage.tsx` 作为平台状态提示 Module，统一承载错误、成功、信息和警告提示条的基础边框、底色、文字颜色和默认间距。
|
||||
- 新增 `src/components/common/PlatformEmptyState.tsx` 作为平台空态 / 轻量加载态 Module，统一承载作品架、公开广场和素材选择弹窗的空面板外观。
|
||||
- 新增 `src/components/common/PlatformAssetPickerCard.tsx` 作为平台历史素材选择 Module，统一承载历史图片 / 历史素材的缩略图卡片、读取态、错误态、空态和响应式网格外观。
|
||||
- 新增 `src/components/common/PlatformActionButton.tsx` 作为平台动作按钮 Module，统一承载平台按钮、个人中心主动作按钮和暗色编辑 / 运行面板普通动作按钮的样式族、尺寸、圆角、宽度和禁用态 class。
|
||||
- 新增 `src/components/common/PlatformIconButton.tsx` 作为平台图标动作按钮 Module，统一承载普通 icon button / 图标上传 label / 白底短标签浮动图标按钮的可访问名称、默认 `type="button"`、title 和基础外观。
|
||||
- 新增 `src/components/common/PlatformIconBadge.tsx` 作为平台非交互图标徽章 Module，统一承载弹窗标题、列表项和小卡片里的中性图标槽。
|
||||
- 新增 `src/components/common/PlatformUploadTile.tsx` 作为平台虚线入口 Module，统一承载图片 / 附件上传方块和紧凑虚线动作入口的图标、主副文案、button / label 语义和禁用态。
|
||||
- 新增 `src/components/common/PlatformUploadPreviewCard.tsx` 作为平台上传预览 Module，统一承载上传后的缩略图壳、预览图片、右上角移除按钮和禁用态。
|
||||
- 新增 `src/components/common/PlatformPillSwitch.tsx` 作为平台胶囊开关 Module，统一承载图片面板中类似 AI 重绘的 label + switch 语义、轨道、圆点、禁用态和白底浮层 chrome。
|
||||
- 新增 `src/components/common/PlatformToggleRow.tsx` 作为平台整行开关 Module，统一承载设置面板和结果页配置里的白底 label + checkbox / 状态行。
|
||||
- 新增 `src/components/common/PlatformTextField.tsx` 作为平台输入字段 Module，统一承载白底 / 暗色 input、textarea 和下拉框共用 chrome，认证表单也只保留受控值、原生属性和业务校验。
|
||||
- 新增 `src/components/common/PlatformFieldLabel.tsx` 作为平台字段标签 Module，统一承载结果页、编辑弹窗和创作工作台中的普通字段名、分区标题、表单字段标题、胶囊字段标题和强调胶囊字段标题。
|
||||
- 新增 `src/components/common/PlatformSegmentedTabs.tsx` 作为平台分段选择 Module，统一承载白底结果页 Tab、编辑弹窗二选一和轻量配置 Tab 的容器、按钮、选中态、禁用态、列数、尺寸和截断标签。
|
||||
- 新增 `src/components/common/PlatformStatGrid.tsx` 作为平台统计小卡 Module，统一承载结果页里的数值 / 标签摘要、轻量状态 chip、响应式列数、密度、surface 和 label/value 顺序。
|
||||
- 新增 `src/components/common/PlatformPillBadge.tsx` 作为平台胶囊状态标签 Module，统一承载结果页、作品卡和配置摘要里的单个状态 / 标签 chip。
|
||||
- 新增 `src/components/common/PlatformProgressBar.tsx` 作为平台进度条 Module，统一承载 `progressbar` 语义、`platform-progress-track` 壳、填充宽度、最小可见宽度、未知进度语义、条内覆盖层和局部主题色。
|
||||
- 新增 `src/components/common/PlatformInfoBlock.tsx` 作为平台只读信息块 Module，统一承载弹窗和详情页中的短标签、白底内容壳、单行 / 多行正文排版。
|
||||
- 新增 `src/components/common/PlatformReportDialog.tsx` 作为平台可复制报告弹窗 Module，统一承载来源 / 状态 / 错误这类字段块展示、报告拼装、复制反馈按钮和标准 footer。
|
||||
- 新增 `src/components/common/PlatformSubpanel.tsx` 作为平台白底子面板 Module，统一承载结果页、创作工作台和普通白底面板内的小型列表卡片里的 `platform-subpanel` / flat 外壳、标题行、右侧动作区、圆角、响应式内边距和交互态。
|
||||
- 新增 `src/components/common/PlatformMediaFrame.tsx` 作为平台媒体预览框 Module，统一承载图片源、fallback 图、fallback 文案、固定比例、surface 和可选 overlay。
|
||||
- 新增 `src/components/common/PlatformMediaTileGrid.tsx` 作为平台媒体缩略格网格 Module，统一承载结果页里同尺寸素材 tile 的列数、间距、白底容器、圆角、边框、图片和 fallback 格。
|
||||
- 新增 `src/components/common/PlatformTagEditor.tsx` 作为平台标签编辑 Module，统一承载结果页里的标签 chip、删除、新增输入、Enter / Escape 键盘行为、空态、可选 AI 生成动作和错误提示。
|
||||
- 新增 `src/components/common/PlatformModalCloseButton.tsx` 作为平台弹窗关闭按钮 Module，统一承载个人中心弹窗和平台浮层关闭按钮的尺寸、圆形视觉、默认图标和可访问名称。
|
||||
- 新增 `src/components/common/squareImageCropModel.ts` 作为正方形图片裁剪数学 Module，统一承载居中初始裁剪、尺寸边界和坐标 clamp，头像裁剪和拼图参考图裁剪不再从弹窗组件文件导入 helper。
|
||||
- 平台页面遇到“知道了”“确认 / 取消”“危险确认”这三类弹窗时，优先使用 `UnifiedConfirmDialog`，不再在业务 JSX 中手写 `UnifiedModal` footer。
|
||||
- 带复制反馈的弹窗和详情页优先组合使用 `useCopyFeedback`、`CopyFeedbackButton` 与 `CopyFeedbackMessage`，不再重复写 `useState + setTimeout + clearTimeout` 的复制状态机，也不在业务 JSX 中手写 copied / failed 文案分支。
|
||||
- 白底平台弹窗、详情页、结果页、个人页、认证入口、统一创作工作台和通用创作输入区中的普通错误 / 成功 / 信息 / 警告 / 中性提示条优先使用 `PlatformStatusMessage`，不再在业务 JSX 中重复拼 `border-rose-* / bg-rose-* / text-rose-*`、`border-emerald-* / bg-emerald-* / text-emerald-*`、`platform-banner--danger / success / info / warning / neutral` 或个人页 token 色值 class。
|
||||
- 平台公开列表、作品架、分类列表、素材选择弹窗、RPG 暗色编辑器和 RPG 运行态弹窗 / 面板中的“正在读取 / 暂无内容 / 当前筛选下没有内容 / 还没有配置”等无操作空态优先使用 `PlatformEmptyState`，业务页只传展示内容和必要的 `surface` / `size`，不再重复写 `platform-surface--soft`、虚线空态面板或暗色编辑器 dashed 空态 class。
|
||||
- 平台弹窗、个人中心弹窗、认证入口、公共确认弹窗 footer、统一创作工作台、创作面板和 RPG 暗色弹窗 / 运行面板中的普通主动作 / 次动作按钮优先使用 `PlatformActionButton`，业务页只传 `surface`、`tone`、`size`、`shape`、`fullWidth` 和动作回调，不再重复拼 `platform-button` / `platform-primary-button`、暗色按钮边框 / 底色、圆角、px/py、字号和禁用态 class。
|
||||
- 普通图标动作按钮、图标上传 label 和白底短标签浮动图标按钮优先使用 `PlatformIconButton`，业务页只传 `label`、`icon`、可选 `children`、可选 `title`、`asChild="label"` 和局部尺寸 class，不再重复手写 `platform-icon-button`、浮动白底按钮、`type="button"` 与 aria。平台浮层、个人中心弹窗和资料面板中只承担“关闭当前弹窗”的圆形图标按钮优先使用 `PlatformModalCloseButton`，业务页只传 `label`、`onClick` 和必要的 `variant` / `icon`，不再重复手写 `platform-modal-close`、绝对定位白底关闭按钮或关闭按钮 aria。
|
||||
- 弹窗标题、列表项和小卡片里的非交互中性图标槽优先使用 `PlatformIconBadge`，业务页只传 icon、尺寸和形状，不再重复拼 `grid h-* w-* place-items-center bg-[var(--platform-neutral-bg)] text-[var(--platform-neutral-text)]`。
|
||||
- 平台表单和结果页中的方形上传入口、紧凑虚线新增入口优先使用 `PlatformUploadTile`，业务页只传 `label`、`hint`、可选 `icon`、`size`、`showLabel`、`disabled`、`asChild="label"` 或点击回调，不再重复手写虚线边框、图标、提示文案和 hover / 禁用态 class。上传后的方形图片预览优先使用 `PlatformUploadPreviewCard`，业务页只保留文件读取、预览数组和删除回调，不再重复手写缩略图壳、`object-cover` 图片和右上角移除按钮。
|
||||
- 特殊内容弹窗仍可直接使用 `UnifiedModal`，但只有在正文需要复杂网格、媒体预览、渠道按钮或运行态专属布局时才保留自定义 footer。
|
||||
- `UnifiedModal` 补充：平台入口公开编号搜索结果弹层使用 `size="sm"`、`closeLabel="关闭搜索结果"` 和 `closeOnBackdrop={false}`；壳层只保留搜索状态机、命中 / 未命中分支和关闭时清空结果状态，不再手写 overlay、header 和平台 close button 布局。
|
||||
|
||||
## 当前接口
|
||||
|
||||
- `open`：是否展示弹窗。
|
||||
- `title` / `description` / `children`：标题、说明和正文。
|
||||
- `onClose`：关闭弹窗，取消按钮、遮罩和关闭图标共用。
|
||||
- `confirmLabel` / `onConfirm` / `confirmTone` / `confirmDisabled` / `confirmClassName`：主操作按钮；`confirmClassName` 只用于整行按钮、局部主题等外观适配，不让业务页重新手写 footer。
|
||||
- `cancelLabel` / `showCancel` / `cancelDisabled`：副操作按钮。
|
||||
- `busy` / `busyConfirmLabel`：执行中禁用关闭路径，并替换主按钮文案。
|
||||
- `portal`：默认挂到 `document.body`；已有弹窗栈内的二级确认使用 `portal={false}`，避免脱离当前局部遮罩和层级。
|
||||
- `variant`：默认 `platform`；RPG 编辑器内需要像素风确认时使用 `pixel`，不再为简单确认另写专用壳层和按钮。
|
||||
- `overlayClassName` / `panelClassName` / `zIndexClassName`：保留主题和层级 Adapter，不把主题选择写死在组件内。
|
||||
- `useCopyFeedback().copyText(value)`：调用统一剪贴板写入并更新反馈状态。
|
||||
- `useCopyFeedback().copyState`：调用方按 `idle / copied / failed` 渲染文案或图标。
|
||||
- `useCopyFeedback().resetCopyState()`：业务上下文切换时主动清空旧反馈。
|
||||
- `CopyFeedbackButton`：接收 `state`、`idleLabel`、`copiedLabel`、`failedLabel`、三态图标、`showIcon`、`showLabel`、`labelClassName`、`accessibleLabel`、`actionSurface`、`actionTone`、`actionSize`、`actionFullWidth`、`actionAppearance="pill"`、`actionPillTone` 和 `actionPillSize`；文本按钮、chip 按钮和运行态纯图标分享按钮都应走同一 Module。需要平台主按钮外观时通过 `actionSurface="platform"` 或 `actionSurface="profile"` 复用 `PlatformActionButton` 样式，不在业务 JSX 中传整串 `platform-button` class；需要可点击胶囊复制 / 分享 chip 时用 `actionAppearance="pill"` 复用 `PlatformPillBadge` chrome，不在业务 JSX 中传 `platform-pill`。
|
||||
- `CopyCodeButton`：接收 `state`、`code`、`codeLabel`、`copiedSuffix`、`failedSuffix`、`codeClassName`、`suffixClassName`、`actionAppearance="pill"`、`actionPillTone`、`actionPillSize` 和复制按钮透传属性；作品号、用户号等短代码 chip 优先用它，不在业务 JSX 中重复写 `{code} + 已复制 / 复制失败` fragments，也不直接传 `platform-pill` class。
|
||||
- `CopyCodeButton` 补充：作品详情页作品号复制按钮使用 `actionAppearance="pill" actionPillTone="neutralSolid" actionPillSize="sm"`；详情页只保留顶部外边距和复制回调，不再把代码 chip 基础 chrome 写在 `platform-work-detail__code`。
|
||||
- `CopyFeedbackMessage`：接收 `state`、`copiedLabel` 和 `failedLabel`；toast 或行内状态只展示成功 / 失败时使用，不在业务页手写三态分支。若场景需要按成功 / 失败切换状态条色值，可在业务壳层继续使用 `useCopyFeedback` 状态机，并组合 `PlatformStatusMessage` 渲染对应 tone。
|
||||
- `PlatformStatusMessage`：接收 `tone="error" | "success" | "info" | "warning" | "neutral"`、`surface="light" | "tinted" | "platform" | "profile" | "editorDark"`、`size="xs" | "sm" | "md"`、`remapSurface`、`children` 和 `className`；根节点固定带 `platform-status-message` 稳定类名，业务测试可断言公共状态条接入。局部可覆盖圆角、外边距和网格布局，但状态色值、基础内边距和字号由 Module 统一控制。结果页、发布检查、素材生成面板和 creation-agent composer 错误条等需要复用旧 `platform-banner--danger / success / info / warning / neutral` token 外观时使用 `surface="platform"`；需要在局部 platform token 作用域内重映射 CSS 变量的提示条传 `remapSurface`，不在业务 JSX 手写 `platform-remap-surface platform-banner`。个人中心弹窗、认证入口、验证码提示、统一创作工作台和通用创作输入区需要 profile token 外观时使用 `surface="profile"`，RPG 暗色编辑 / 运行面板内的普通状态提示使用 `surface="editorDark"`；背包故事档案 QA、NPC 叙事提示、角色聊天错误提示、营地编组战斗中提示、自定义选择弹窗错误 / 生成中提示等暗色状态条已迁移。旧 `platform-profile-error` / `platform-profile-success`、暗色手写 `border-*-300/15 bg-*-500/10 text-*-50/90` 和 `platform-banner--danger / success / info / warning / neutral` 不再作为业务 JSX 接口。
|
||||
- `PlatformStatusMessage` 补充：大鱼吃小鱼结果页发布校验阻断项使用 `tone="warning" surface="platform" size="xs"`；结果页只保留阻断项裁剪和文案，不再手写 amber 文本列表。
|
||||
- `PlatformStatusMessage` 补充：个人中心邀请弹窗里的邀请奖励说明使用 `tone="warning" surface="profile" size="md"`；弹窗只保留奖励文案和两行排版，不再手写 amber 提示块。
|
||||
- `PlatformStatusMessage` 补充：拼图首访 onboarding 的输入错误和登录保存错误使用 `surface="editorDark"`；onboarding 只保留错误文案和条件渲染，不再手写暗色红色错误条。
|
||||
- `PlatformStatusMessage` 补充：平台作品详情页分享复制反馈使用 `surface="platform"` 并按 `shareState` 映射 `success / error`；详情页只保留复制状态机和文案，不再为失败态复用成功 toast chrome。
|
||||
- `PlatformStatusMessage` 补充：creative-agent 首页错误提示使用 `tone="error" surface="platform" size="md"`；首页只保留宽度对齐布局 class 和错误文案，不再手写 danger panel chrome。
|
||||
- `PlatformStatusMessage` 补充：平台入口公开编号搜索未命中结果使用 `tone="neutral" surface="platform" size="md"`；壳层只保留搜索错误文案，不再手写普通文本提示块。
|
||||
- `PlatformRuntimeStatusToast`：接收 `tone="error" | "success" | "info" | "warning" | "neutral"`、`surface="light" | "dark" | "solid"`、`size="xs" | "sm" | "md"`、`shape="pill" | "rounded"`、`children` 和 `className`；根节点固定带 `platform-runtime-status-toast` 稳定类名，默认按 `tone` 写入 `role="alert/status"` 与 `aria-live`。它只承接运行态 HUD 中短错误、成功和反馈 chip 的圆角、字号、阴影、色值和可访问语义，具体浮层位置、玩法资产按钮、计分牌、蓄力提示、强品牌 primary 按钮仍由玩法 runtime 控制。跳一跳、拼图、敲木鱼、方洞和宝贝爱画运行态的短错误 / 成功 / 投放反馈已先迁移；后续同类短 toast 不再手写 `rounded-full bg-white/* text-*`、暗色 `border-rose/emerald bg-*/text-*` 或单玩法 `*-runtime-error-chip`。
|
||||
- `PlatformDarkOptionCard`：接收 `selected`、`tone="emerald" | "sky" | "rose" | "amber"`、`radius="sm" | "md" | "lg"`、`padding="sm" | "md" | "lg"`、`children`、`className` 和原生 button props；根节点固定带 `platform-dark-option-card` 稳定类名，统一承接 RPG 暗色弹窗 / 面板中的 selected / idle / hover / disabled 可选项卡按钮外观。NPC 交易模式、交易物品行、赠礼候选、招募替换候选、角色素材工作室动作预览格、营地编组替换位按钮和角色聊天建议按钮已先迁移；业务页只保留选中判断、点击回调和内容布局，不再重复手写 `rounded-* border px-3 py-*`、`border-*-400/* bg-*-500/10` 或 `border-white/* bg-black/20 hover:border-white/15`。
|
||||
- `PlatformEmptyState`：接收 `surface="soft" | "dashed" | "subpanel" | "editorDark"`、`size="compact" | "panel" | "inline"`、`tone="base" | "soft"`、`children` 和 `className`；根节点固定带 `platform-empty-state` 稳定类名，业务测试可断言公共空态接入。`soft + compact` 用于公开广场、排行和作品架内的轻量空态，`soft + panel` 用于创作中心作品架整块空态，`dashed + panel` 用于素材选择、历史资源等弹窗的大面积空态或读取态，`subpanel + inline` 用于视觉小说 runtime、个人中心充值 / 任务等白底子面板内的无操作空态，`editorDark + compact/inline` 用于 RPG 大编辑器、实体详情弹窗、营地编组、角色聊天和运行态设置弹窗等暗色面板里的纯展示空态 / 禁用提示。组件只承接外观，不内置业务文案。
|
||||
- `PlatformEmptyState` 补充：个人中心存档弹窗和玩过弹窗里的简单“暂无存档 / 暂无玩过”也使用 `surface="subpanel" size="inline"`；玩过弹窗可通过 `tone="base"` 和局部 `text-left` 保留原有白底列表语境，不在业务 JSX 重复写 `rounded-xl bg-zinc-50 px-4 py-* text-sm`。
|
||||
- `PlatformEmptyState` 补充：个人中心钱包账单弹窗里的“暂无账单记录”使用 `surface="subpanel" size="inline"`；业务组件只保留外边距和纵向留白，不再手写白底空态边框、字号和居中文案。
|
||||
- `PlatformEmptyState` 补充：个人中心邀请弹窗里的“已填写邀请码 / 暂无成功邀请”使用 `surface="subpanel"`；业务组件保留面板分支和邀请状态机，不再为无操作提示手写白底空态。
|
||||
- `PlatformEmptyState` 补充：creation-agent 聊天区里的“暂无消息”使用 `surface="subpanel" size="compact"`；工作台保留消息列表滚动容器和文案，不再手写居中空态字号、颜色和高度 class。
|
||||
- `PlatformEmptyState` 补充：大鱼吃小鱼结果页缺少可编辑草稿时使用 `surface="subpanel" size="compact"`；结果页只保留草稿分支和文案，不再为白底无操作提示手写 `PlatformSubpanel` 空面板。
|
||||
- `PlatformEmptyState` 补充：creative-agent 首页抽屉“暂无创作记录”使用 `surface="subpanel" size="inline"`；抽屉只保留分组和历史条目分支，不再手写白底 bordered empty chrome。
|
||||
- `PlatformEmptyState` 补充：creative-agent 工作台消息区“发一句想法，或加一张参考图。”使用 `surface="subpanel" size="compact"`；工作台只保留消息分支和文案，不再为白底空消息面板手写 `PlatformSubpanel` 外壳。
|
||||
- `PlatformEmptyState` 补充：creative-agent 过程面板空态“等待新的创作输入”使用 `surface="subpanel" size="compact"`；过程面板只保留空态分支和文案，非空时继续复用 `PlatformSubpanel` + `PlatformPillBadge` 承接过程列表。
|
||||
- `PlatformTextField`：接收 `variant="input" | "textarea"`、`surface="platform" | "editorDark"`、`size="xs" | "sm" | "md" | "lg"`、`density="default" | "compact" | "roomy"`、`tone="warm" | "rose" | "emerald" | "sky"`、`className` 和原生 input / textarea props；统一承接平台白底与 RPG 暗色弹窗里的圆角输入框、文本域、禁用态、密度、字号 / 行高和焦点色，暗色 surface 根节点固定带 `platform-text-field--editor-dark` 稳定类名。`PlatformSelectField` 复用同一套输入 chrome 承接下拉框。业务页继续持有 `value`、`onChange`、`aria-label`、`rows`、`placeholder`、`option` 等语义，不再重复拼 `rounded-[1rem] border border-[var(--platform-subpanel-border)] bg-white/86 px-3 py-3`、`rounded-[0.85rem] bg-white/90 px-3 py-2`、`bg-white/90 px-4 py-3`、暗色 `border-white/10 bg-black/30 px-4 py-3` 或 `focus:border-* focus:ring-*`。抓大鹅结果页作品信息、封面描述、素材名称和批量物品名称，方洞结果页主信息表单和形状 / 洞口选项字段，拼图 / 敲木鱼结果页作品信息字段，视觉小说结果页的音乐生成、作品信息、开场、运行配置、角色、场景、阶段和世界观普通文本 / 下拉字段，以及视觉小说 / 抓大鹅 / 汪汪声浪 / 宝贝识物 / 拼消消 / 跳一跳创作工作台普通输入字段已先迁移；自定义选择弹窗角色名字 / 背景补充 / 生成模式 / 世界描述和角色聊天草稿等暗色字段使用 `surface="editorDark"`。通用创作图片输入面板的提示词文本域也使用该 Module，只通过局部 class 保留高度和底部浮动上传按钮避让。认证图形验证码答案、短信 / 密码登录、重置密码、绑定手机号、邀请码和账号安全表单字段，以及个人中心兑换码 / 邀请码输入使用 `surface="platform"`，业务层只保留认证 / 兑换流程、受控值、原生属性和校验提示。
|
||||
- `PlatformTextField` 补充：个人中心昵称弹窗输入框使用 `surface="editorDark" size="lg" density="roomy"`，业务组件保留外层原生 `label` / sr-only “新昵称”、`autoFocus`、`maxLength`、Enter 提交和保存状态；局部 class 只保留暗色弹窗里的 `bg-white/10`、文字色和焦点边框，不再手写 input chrome。
|
||||
- `PlatformTextField` 补充：`PlatformTagEditor` 内部新增标签输入框使用 `density="compact" size="xs"` 复用同一输入 chrome；标签编辑器只保留新增输入状态、解析、Enter / Escape 行为和按钮组合，不再手写输入框边框、白底、字号、焦点色或禁用态。
|
||||
- `PlatformTextField` 补充：creation-agent composer 文本域使用 `variant="textarea" size="md" density="compact"`；工作台只保留受控值、禁用条件、Enter / Shift+Enter 行为和局部布局 class，不再手写 textarea chrome。
|
||||
- `PlatformTextField` 补充：拼图首访 onboarding 提示词文本域使用 `variant="textarea" surface="editorDark" density="roomy" size="lg"`；onboarding 保留受控输入、生成 / 已生成禁用和沉浸式壳层，不再手写 textarea 基础 chrome。
|
||||
- `PlatformTextField` 补充：平台反馈页问题描述和联系电话字段使用 `surface="platform"`；反馈页保留外层原生 `label`、受控值、长度限制和透明嵌入式局部 class，不再手写 textarea / input 基础语义和重复 chrome。
|
||||
- `PlatformFieldLabel`：接收 `variant="field" | "section" | "form" | "inlineForm" | "pill" | "accentPill"`、`children` 和 `className`；`field` 用于视觉小说等结果页的普通字段名，`section` 用于平台白底面板内小标题，`form` 用于创作工作台、通用创作输入面板和认证表单普通字段标题，`inlineForm` 用于模板确认弹层这类行内字段标题，`pill` / `accentPill` 用于汪汪声浪等工作台里的胶囊字段标题。业务页只传字段文案和必要的局部 class，不再重复写 `text-xs font-bold text-[var(--platform-text-soft)]`、`text-xs font-bold tracking-[0.18em] text-[var(--platform-text-soft)]`、`mb-2 block text-sm font-black`、`text-sm font-bold text-[var(--platform-text-base)]`、普通胶囊或 rose 强调胶囊 class。视觉小说结果页、抓大鹅结果页作品 / 封面 / 素材字段标题、方洞结果页主信息 / 形状 / 洞口 / 历史图片字段标题、拼图结果页关卡详情 / 发布弹窗字段标题、拼消消创作工作台作品标题 / 简介 / 主题词、跳一跳创作工作台主题、大鱼素材弹窗 prompt、RPG 发布弹窗发布检查 / 封面设置、汪汪声浪轻配置编辑器、宝贝识物工作台、通用创作图片输入面板主图 / 提示词标题，以及认证表单中的手机号 / 验证码 / 密码 / 邀请码标题已先迁移。认证和提示词字段继续保留外层原生 `label` 关联，不把可访问命名交给装饰性标题组件。
|
||||
- `PlatformFieldLabel` 补充：个人中心玩过弹窗内的“可继续 / 玩过”分区标题使用 `variant="section"`；业务组件只传分区文案和 `mb-2 block` 局部布局，不再手写 `text-xs font-black text-zinc-500`。
|
||||
- `PlatformFieldLabel` 补充：个人中心邀请弹窗里的“邀请码 / 成功邀请”小标题使用 `variant="section"`；业务组件只保留必要的居中或深色文本局部 class，不再手写同类小标题字体。
|
||||
- `PlatformFieldLabel` 补充：平台反馈页问题描述和联系电话标题使用 `variant="form"`，并保留外层原生 `label htmlFor` 负责可访问名称；反馈页不再手写字段标题字体和颜色。
|
||||
- `PlatformFieldLabel` 补充：creative-agent 模板确认弹层里的“关卡数”行内标题使用 `variant="inlineForm"`，并继续保留外层原生 `label` 与 `PlatformTextField aria-label="计划关卡数"` 的可访问命名；弹层不再手写紧凑行内字段标题字体。
|
||||
- `PlatformSegmentedTabs`：接收 `items`、`activeId`、`onChange`、`columns="one" | "two" | "three" | "four" | "threeToSix"`、`gap="sm" | "md"`、`radius="md" | "lg" | "xl"`、`size="sm" | "md" | "compact" | "choice" | "tab"`、`surface="default" | "soft" | "transparent"`、`tone="neutral" | "warm" | "rose" | "underline"`、`frame="panel" | "bare"`、`semantics="segment" | "tabs"`、`ariaLabel`、`truncateLabels`、`disabled`、`className` 和 `itemClassName`；普通分段统一写入 `aria-pressed`，Tab 语义统一写入 `role="tablist"` / `role="tab"` / `aria-selected`，并承载禁用阻断、白底选中态、空闲 hover、焦点 ring、响应式列数、裸分段外壳、下划线选中态和 label 截断。拼图结果页、抓大鹅结果页、抓大鹅素材配置、抓大鹅创作 / 结果页难度选择、视觉小说结果页、creative-agent 模板确认弹窗和认证入口短信 / 密码登录切换已先迁移。后续白底结果页 Tab、弹窗分段选择、四选一配置项或认证 / 设置类下划线 Tab 只传选项、当前值和变更回调，不再重复 `grid + border + bg-white/62 + button aria-pressed` 或本地 `role="tab"` 下划线按钮。
|
||||
- `PlatformStatGrid`：接收 `items`、`columns="two" | "three" | "four" | "twoToFour"`、`density="compact" | "default"`、`order="valueFirst" | "labelFirst"`、`surface="soft" | "plain"`、`textAlign="left" | "center"`、`className` 和 `itemClassName`；统一承载平台结果页里的统计小卡、状态 chip、白底摘要卡、label/value 排版和响应式列数。拼消消结果页素材摘要、方洞结果页封面状态 chip、抓大鹅结果页难度摘要、creative-agent 模板确认摘要和自定义世界实体目录世界页档案规模已先迁移，业务页只传统计项数组和少量布局参数，不再重复写 `grid + rounded + bg-white/* + text-xl/text-xs`。
|
||||
- `PlatformPillBadge`：接收 `tone="muted" | "neutral" | "neutralSolid" | "lightOverlay" | "success" | "warning" | "danger" | "cool" | "profile" | "profileAccent" | "darkSoft" | "darkNeutral" | "darkSky" | "darkEmerald" | "darkAmber" | "darkRose"`、`size="xxs" | "xs" | "sm"`、可选 `icon`、`children`、`className` 和原生 span props；统一承接单个状态 / 标签 chip 的圆角、边框、底色、字号和图标间距，并通过 `platformPillBadgeModel.ts` 的 `getPlatformPillBadgeClassName` 给复制类交互按钮复用同一视觉 chrome。`xxs` 用于实体目录卡片等密集元信息 chip，`muted` 用于平台白底柔和选择态和地图节点当前状态，`lightOverlay` 用于主动作按钮内部的泥点消耗等浅色叠层小胶囊，`danger` 用于删除 / 选中危险态，`profile` / `profileAccent` 用于个人中心玫瑰色信息 / 分类 chip，`dark*` 用于 RPG 暗色弹窗和角色详情里的纯展示 chip。宝贝识物结果页发布状态、主题标签与占位资源 overlay，宝贝识物 / 拼图 / 抓大鹅 / 视觉小说工作台 BETA chip、汪汪声浪轻配置 chip、汪汪声浪结果页草稿 chip、汪汪声浪预览 VS chip、敲木鱼结果页飘字 chip、creative-agent 顶部阶段 / 过程计数 / 条目 meta chip、通用音频输入面板限制标签、自定义世界实体目录批量选择 / 生成中 / 开局 CG / 可扮演角色元信息 badge、RPG 首页公开作品卡 / 搜索结果 / 充值商品 / 移动端创建入口 / 桌面发现区 chip、RPG 世界详情静态元信息 chip、RPG 角色身份 / 等级 / 技能出手方式 / 技能详情与状态标签 / 背景故事解锁状态 / 好感等级 / 角色资产工作室动作状态 / 角色编辑技能动作状态 / 角色资源应用状态 / 场景角色选择状态 / 地标当前连接状态 / 地图节点方向标签 / 地图场景切换方向标签 / 营地编组状态数值 / 作品封面来源状态 / 开局物品标签、NPC 交易数量 / 赠礼好感和背包工坊材料需求等暗色展示 chip、抓大鹅批量新增 / 批量重生成物品名称预览 chip、抓大鹅 / RPG / 拼图 / 方洞结果页自动保存状态、抓大鹅结果页当前难度 badge、拼图结果页关卡生成中 overlay / 列表 badge、大鱼吃小鱼结果页终局 / 关卡元信息 / 发布校验成功 badge、拼图图库详情页题材标签、自定义世界作品卡二级 badge、生成失败 chip，以及个人中心泥点账单余额、玩过总时长和玩过作品类型 chip 已先迁移。后续作品卡状态、结果页标签、个人中心轻量信息、按钮内消耗标签和轻量配置 chip 优先使用该 Module；多项数值 / 标签摘要仍使用 `PlatformStatGrid`，可交互标签编辑仍使用 `PlatformTagEditor`，可点击复制 / 分享 chip 使用 `CopyCodeButton` / `CopyFeedbackButton actionAppearance="pill"`。
|
||||
- `PlatformPillBadge` 补充：大鱼吃小鱼结果页 hero 顶部的玩法摘要 chip 使用 `tone="lightOverlay"` 并保留局部 `bg-white/10` 覆盖；hero 只保留 `coreFun / ecologyTheme / levelCount` 文案，不再手写三段 `rounded-full bg-white/10 px-3 py-1` 静态标签。
|
||||
- `PlatformPillBadge` 补充：RPG 实体编辑器基本设定里的拆分标签也使用 `tone="darkSoft"`；这类标签只表达解析后的静态词条，不把可编辑标签输入、删除按钮或点击选择态塞进静态 badge。
|
||||
- `PlatformPillBadge` 补充：`tone="neutralSolid"` 承接无强调、无业务状态色的实心中性胶囊；`PlatformToggleRow mode="status"` 的开启 / 关闭状态已改用该 tone。后续只读开关状态或类似轻量状态值优先复用它，不在业务 JSX 中重复拼 `rounded-full bg-[var(--platform-neutral-bg)] px-3 py-1 text-xs font-black`。
|
||||
- `PlatformPillBadge` 补充：平台作品详情页的主题标签使用 `tone="neutralSolid" size="sm"`；详情页只保留标签数组映射，不再手写 `platform-work-detail__chip` 的边框、底色、圆角、字号和内边距。
|
||||
- `PlatformProgressBar`：接收 `value`、可选 `minVisibleValue`、`size="xs" | "sm" | "md" | "lg"`、`ariaLabel`、`labelledBy`、`indeterminate`、`className`、`fillClassName`、`fillStyle`、`trackStyle` 和 `children`；内部 clamp 到 0-100，并统一写入 `role="progressbar"`、`aria-valuemin/max/now`、`platform-progress-track`、填充宽度和最小可见宽度。`children` 仅用于条内倒计时、加载图标等覆盖层；没有准确百分比的脉冲占位条使用 `indeterminate`，避免暴露假的 `aria-valuenow`。creation-agent 主进度 / operation banner、RPG 结果页生成提示、RPG 实体目录生成中提示、开场 CG 生成占位、拼图关卡画面生成进度、生成页当前步骤线性进度、抓大鹅批量物品素材生成进度和自定义世界生成选择弹窗进度提示已先迁移；后续普通平台进度条只传业务进度值、标签关联、局部主题色和必要覆盖内容，不再重复手写 aria、track/fill div 和 `Math.max(...)` 宽度计算。
|
||||
- `PlatformSubpanel`：接收 `as="section" | "div" | "article" | "aside" | "button"`、`title`、`titleVariant="section" | "strong"`、`actions`、`interactive`、`padding="tight" | "row" | "xs" | "sm" | "md" | "lg" | "none"`、`radius="xs" | "sm" | "md" | "lg" | "xl"`、`surface="platform" | "flat" | "soft" | "dark" | "darkSky" | "darkEmerald" | "darkAmber" | "darkRose" | "danger"`、`className`、`headerClassName`、`titleClassName`、`actionsClassName`、`bodyClassName` 和 `children`；静态 element 透传 `aria-*`、`data-*` 等原生属性，`as="button"` 时透传普通 button 属性并默认 `type="button"`。Module 统一承接平台结果页 / 工作台 / 个人中心子面板外壳、`PlatformFieldLabel variant="section"` 标题、强标题、右侧动作区、内容容器和普通白底列表卡片的 hover / focus / disabled 交互态。`surface="platform"` 复用 `platform-subpanel` token；`surface="soft" + padding="tight"` 用于标签编辑新增输入行等白底柔和紧凑行，`surface="soft" + padding="row"` 用于上传预览横向已选素材条等白底柔和横向行；`surface="danger"` 用于整卡危险选中态；`radius="xl" + padding="lg"` 用于方洞等更大圆角的标准结果页面板；`surface="platform" + radius="xl" + padding="none"` 用于只需要公共边框 / 背景 / 大圆角且内部自带固定比例内容的静态封面壳，`surface="platform" + radius="xl" + padding="sm"` 可用局部 `sm:p-5` 保留物品详情类响应式内容面板；`surface="flat" + radius="sm" + padding="sm"` 用于素材 / 音频 / 排行榜 / 选项编辑 / 局部进度状态等小型白底卡片，`surface="flat" + radius="sm" + padding="none"` 仅用于只包已有图片、图集、角色或路径预览且不需要 fallback / overlay 的白底壳；需要图片源、fallback、固定比例或 overlay 时优先使用 `PlatformMediaFrame`。需要整卡点击或缩略图点击时组合 `as="button" interactive`。拼图结果页作品名称 / 描述 / 标签编辑 / 智能修订条 / 关卡卡片、拼图图库详情页封面轮播壳 / 题材标签 / 关卡摘要、敲木鱼结果页主预览面板 / 作品标题 / 简介 / 主题标签 / 飘字 / 音效、敲木鱼工作台功德词条面板、跳一跳结果页预览 / 操作面板 / 排行榜 / 轻量媒体壳、拼消消创作工作台左侧表单面板、拼消消结果页预览 / 统计 / 操作面板 / 轻量媒体壳、方洞结果页封面 / 主信息 / 形状 / 洞口标准面板、方洞形状 / 洞口选项卡与缩略图按钮、RPG 结果页开发资产诊断摘要 / 条目 / 空态、RPG 个人中心未登录提示、通用音频输入面板、视觉小说创作工作台画风选择面板、视觉小说结果页素材 / 音频小面板、视觉小说结果页作品 / 开场 / 运行配置 / 世界观标准编辑面板、视觉小说 runtime 历史条目 / 存档列表、抓大鹅创作工作台难度小面板、抓大鹅结果页作品 / 难度 / 统计 / UI素材预览标准面板 / 当前难度摘要小卡 / 物品详情五视角面板 / 物品图集分组卡 / 批量素材生成进度卡、汪汪声浪结果页草稿摘要 / 素材槽 / 预览卡、平台反馈页问题描述 / 上传凭证 / 联系方式区块、自定义世界实体目录世界基调 / 角色维度 / 基本设定条目 / 场景幕级缩略图 / 目录卡片媒体壳 / 目录卡片整卡壳、创作中心作品架加载骨架卡，以及 creative-agent 工作台目录 / 目标就绪 / 空消息 / 过程 / 关卡计划 / 关卡计划小卡 / 模板确认理由面板已先迁移；`PlatformTagEditor` 内部新增输入行使用 `surface="soft" padding="tight"`，`PlatformUploadPreviewCard layout="inline"` 内部横向已选素材条使用 `surface="soft" padding="row"`。后续同类白底面板、白底轻量媒体壳或白底交互列表卡片只传标题、动作、内容、可访问属性和点击回调，不再重复写 `platform-subpanel rounded-[1.25rem] p-4`、`rounded-[1.35rem] p-4 sm:p-5`、`platform-subpanel rounded-[1.5rem] p-4 sm:p-5`、`rounded-[1.5rem] border border-[var(--platform-subpanel-border)] bg-[var(--platform-subpanel-fill)]`、`rounded-[1rem] border ... bg-white/72 p-3`、`rounded-[1rem] border ... bg-white/68 p-2`、`rounded-[1rem] border ... bg-white/68 px-3 py-2`、`rounded-[1.1rem] border ... bg-white/58 p-3`、`rounded-[1rem] border ... bg-white/80`、`hover:bg-white disabled:cursor-not-allowed disabled:opacity-55`、标题行 flex 和 `text-xs font-bold tracking-[0.18em]`。
|
||||
- `PlatformSubpanel` 补充：个人中心玩过弹窗里的已玩作品按钮卡使用 `as="button" surface="flat" radius="sm" padding="md" interactive`，业务组件只保留作品标题 / 副标题 / 类型胶囊 / 作品号 / 最近游玩 / 时长内容和粉色 hover 边框，不再手写白底按钮卡 chrome。
|
||||
- `PlatformSubpanel` 补充：平台入口壳纯 Suspense fallback、作品详情读取 / 错误提示和 Agent 工作区恢复提示使用 `radius="sm" padding="none"` 承接原 `platform-subpanel` 外壳，业务层只保留居中布局、提示文案和局部内边距；生成结果恢复面板使用 `radius="xl" padding="none"` 保留恢复动作与固定内容间距。玩法 runtime overlay 仍保留专用层级语义，后续单独评估。
|
||||
- `PlatformSubpanel` 补充：平台入口公开编号搜索命中用户卡使用 `surface="flat" radius="sm" padding="md"` 和 `titleVariant="strong"`；壳层只保留用户摘要字段和关闭分支，不再手写白底 bordered 搜索结果卡。
|
||||
- `PlatformSubpanel` 补充：RPG runtime 主阶段路由里的平台首页、角色选择和冒险面板懒加载提示使用 `radius="sm" padding="none"` 承接原 `platform-subpanel` 外壳；路由器只保留 Suspense 分流和提示文案，运行态 HUD / overlay 继续保留专用层级语义。
|
||||
- `PlatformSubpanel` 补充：个人中心钱包账单行使用 `as="div" surface="flat" radius="xs" padding="none"`，业务组件只保留来源、时间、收入 / 支出色值、余额右对齐和局部 `px-3 py-3 shadow-sm`；后续同类白底数据行优先从该组合扩展。
|
||||
- `PlatformSubpanel` 补充：个人中心邀请弹窗里的社区二维码卡、邀请码展示卡、成功邀请容器和邀请用户行使用 `surface="flat" | "soft"` 的白底子面板；复制按钮、奖励说明卡和弹窗状态机不并入本轮。
|
||||
- `PlatformSubpanel` 补充：个人中心任务中心里的任务条目使用 `radius="sm" padding="md"` 承接原 `platform-subpanel` 外壳；业务组件只保留任务标题、进度、奖励、状态和领取按钮逻辑。
|
||||
- `PlatformSubpanel` 补充：个人中心充值弹窗里的微信 Native 支付二维码确认面板使用 `radius="sm" padding="md"`；业务组件保留二维码生成、扫码提示和确认支付按钮，不再手写 `platform-subpanel` 外壳。
|
||||
- `PlatformSubpanel` 补充：个人中心充值弹窗里的商品整卡按钮使用 `as="button" interactive radius="sm" padding="none"`；业务组件只保留商品标题、金额、角标、购买状态和下单回调，不再手写 `platform-subpanel` 按钮壳、hover、focus 或 disabled chrome。
|
||||
- `PlatformSubpanel` 补充：发布分享弹窗里的渠道 tile 按钮使用 `as="button" surface="flat" radius="sm" padding="tight" interactive`；弹窗只保留渠道枚举、品牌图标和复制分享文本回调，不再手写白底 tile 的圆角、边框、底色、hover 或 focus chrome。
|
||||
- `PlatformSubpanel` 补充：平台入口创作类型弹层里的玩法卡片使用 `as="button" surface="platform" radius="xl" padding="none"`；卡片只保留玩法图片、锁定态、标题、副标题和选择分流，外层按钮语义、标准圆角和已开放卡 hover / focus chrome 由公共子面板承接。
|
||||
- `PlatformSubpanel` 补充：creation-agent 工作台聊天区外壳使用 `radius="xl" padding="none"`；工作台只保留消息列表、引用图预览、错误提示和输入区语义，不再手写聊天面板外层圆角、边框和底色。
|
||||
- `PlatformSubpanel` 补充：当前 Interface 额外支持 `padding="xs"`、`radius="xs"` 和 `surface="dark"`，用于 RPG 暗色编辑器 / 运行态里的非交互小信息卡。任务目标、区域、进度、描述、角色维度、角色形象状态、自定义选择弹窗当前角色、地图场景切换当前 / 前往摘要、营地编组分区、同行者卡、营地气氛小卡、角色聊天状态和聊天总结这类只展示信息的小卡走该组合；暗色 HUD、动作按钮、可点击卡片和强玩法品牌面板仍保留业务布局。
|
||||
- `PlatformSubpanel` 补充：当前 Interface 额外支持 `surface="darkSky" | "darkEmerald" | "darkAmber" | "darkRose"`，用于 RPG 暗色编辑器 / 运行态中带业务色强调的结构化信息面板；实体详情私聊提示、队友收束、玩家等级进度、角色面板等级 / 收束状态、任务奖励好感度 / 货币 / 经验数值卡、RPG 大编辑器上传封面中提示、地图场景切换目标场景面板，以及 `CharacterInfoShared.MultiplierContributionList` 状态标签外壳已迁移，后续同类 sky / emerald / amber / rose 暗色信息壳不再手写 `border-*-400/18 bg-*-500/8`。
|
||||
- `PlatformSubpanel` 补充：RPG 大编辑器里的标题型暗色信息块通过本地 `EditorInfoPanel` 适配到 `surface="dark" radius="md" padding="md"`；场景幕角色槽位的当前角色 / 可选角色面板、幕背景预览面板和预设背景面板已迁移。业务 JSX 只保留标题、内容和局部 grid，不再重复拼 `rounded-2xl border border-white/8 bg-black/20 px-4 py-4`。
|
||||
- `PlatformSubpanel` 补充：RPG 队伍面板和实体详情弹窗中的构筑标签效果详情统一由 `CharacterInfoShared.BuildContributionDetailPanel` 承接，标签概览、属性加成明细和无属性明细提示都组合 `surface="dark"` 的公共子面板；业务弹窗只传选中标签行和属性 rows，不再重复手写同一段标签效果 JSX 或 `rounded-2xl border border-white/8 bg-black/20 p-4` / `rounded-xl border border-white/8 bg-black/25 px-4 py-3` 暗色面板 chrome。
|
||||
- `PlatformSubpanel` 补充：实体详情弹窗的技能预览 fallback、伤害 / 法力 / 冷却 / 距离数值卡、技能说明和附带状态标签区使用 `surface="dark" radius="xs"`；实体详情只保留技能数值、文案和状态标签数据，不再重复手写 `rounded-xl border border-white/8 bg-black/20 px-* py-*` 暗色小卡。
|
||||
- `PlatformSubpanel` 补充：宝贝识物工作台玩法预览卡使用 `surface="soft" radius="md" padding="md"`，只通过局部 `className` 保留玩法渐变和装饰层；工作台不再直接手写该类静态白底柔和卡片的边框、圆角和内边距。
|
||||
- `PlatformSubpanel` 补充：creation-agent 无 session / 加载提示块使用 `radius="sm" padding="lg"` 承接普通居中提示面板；工作台只传提示文案，不再手写 `platform-subpanel rounded-2xl px-5 py-4`。
|
||||
- `PlatformSubpanel` 补充：拼图结果页空草稿提示块使用 `radius="sm" padding="lg"` 承接普通居中提示面板；结果页只传提示文案，不再手写 `platform-subpanel rounded-2xl px-5 py-4`。
|
||||
- `PlatformMediaFrame`：接收 `src`、`fallbackSrc`、`alt`、`fallbackLabel`、`fallbackContent`、`aspect="auto" | "square" | "standard" | "landscape" | "wide" | "portrait" | "video"`、`surface="warm" | "editorDark" | "plain" | "soft" | "bright" | "none" | "bare"`、`loading`、`refreshKey`、`imageClassName`、`imageProps`、`className`、`fallbackShellClassName`、`fallbackClassName`、`previewOverlay`、`overlayInteractive`、`children` 和原生 `div` 的 `aria-*` / `data-*` 等属性；内部使用 `ResolvedAssetImage`，统一承接图片换签、fallback 图、无图 fallback 文案 / 自定义占位内容、fallback 外壳局部着色、固定比例、圆角、surface 背景和绝对定位 overlay。`standard` 用于 4:3 关卡 / 封面预览，`wide` 用于 9:5 宽图候选预览，`portrait` 用于 9:16 竖版场地底图 / 海报类资产，`soft` 用于由媒体框自身承接 `border border-[var(--platform-subpanel-border)] bg-white/68` 的白底柔和预览，`bright` 用于素材缩略图等需要 `border border-[var(--platform-subpanel-border)] bg-white/82` 的亮白预览槽，`none` 用于嵌在已有按钮 / 卡片交互壳里的纯图片与 fallback 内容，不抢外层边框、背景和选中态，`bare` 用于外层卡片已经提供边框和圆角的内嵌媒体框。自定义世界实体目录场景图片框、RPG 实体编辑器本地 `ImagePreview`、拼图结果页关卡列表正式图框、拼图发布弹窗封面关卡预览、拼消消结果页场地底图 / 素材图集 / 卡片预览网格、方洞结果页图片查看弹窗预览、方洞结果页封面 / 背景点击预览、方洞结果页形状 / 洞口贴图缩略图、宝贝识物结果页素材卡图片框、视觉小说结果页封面 / 资产字段图片预览、敲木鱼结果页主 9:16 背景 + 敲击物叠层预览、跳一跳结果页地块图集整图预览、大鱼吃小鱼关卡主图缩略图、大鱼吃小鱼素材工坊候选预览、大鱼吃小鱼场地背景竖版预览、creative-agent 模板确认预览，以及抓大鹅结果页物品素材列表缩略图、详情大图、视角缩略图和 UI 素材背景 / spritesheet 主图已先迁移；拼图关卡列表正式图、拼消消场地底图 / 素材图集这类外层白底媒体壳、宝贝识物素材卡顶部媒体槽、视觉小说资产字段、creative-agent 模板目录卡、跳一跳地块图集整图、大鱼关卡主图 / 工坊候选 / 场地背景主题槽、抓大鹅 UI 素材页白底预览壳，以及方洞封面 / 背景点击预览、方洞形状 / 洞口贴图缩略图这类外层按钮已承接渐变、边框、选中或 hover 交互壳的场景，内层统一使用 `surface="none"`；拼图发布弹窗封面关卡和 creative-agent 模板确认预览这类由媒体框自身承接白底柔和槽的场景使用 `surface="soft"`。后续只是“图片 / fallback / 比例 / overlay”的预览框优先使用该 Module；历史素材选择继续使用 `PlatformAssetPickerCard`，上传后预览继续使用 `PlatformUploadPreviewCard`，整块白底面板继续使用 `PlatformSubpanel`。
|
||||
- `PlatformMediaFrame` 补充：组件根节点固定带 `platform-media-frame` 稳定类名，业务测试可断言公共媒体框接入，不再依赖局部 Tailwind 色值作为组件归属判断。
|
||||
- `PlatformMediaFrame` 补充：拼图图库详情页封面轮播的内层正方形图片 / 暂无封面 fallback / 轮播 overlay 已迁移到 `PlatformMediaFrame aspect="square" surface="none"`；外层 `PlatformSubpanel radius="xl" padding="none"` 继续承接面板边框、圆角和裁切。
|
||||
- `PlatformMediaFrame` 补充：RPG 角色形象参考图缩略框和营地编组同行者头像框使用 `surface="editorDark"` 与固定尺寸 class 复用媒体框；这类只展示图片源 / fallback / 圆角边框的缩略框不再在业务 JSX 中手写 `img + overflow-hidden + border`。
|
||||
- `PlatformMediaFrame` 补充：需要运行时计算比例、裁剪或拖拽测量的媒体区域使用 `aspect="auto"`、`ref` 和 `imageProps`，由业务层只传动态 `style`、`draggable` 等图片属性和 overlay 操作层；RPG 作品封面上传裁剪操作区 / 结果预览、角色素材工作室形象预览 / 动作静态预览、场景幕背景预设、技能编辑 fallback 预览、技能列表缩略图和角色编辑顶部形象预览已迁移。后续“图片 + 动态比例 / 不可拖拽 / overlay 操作层”的场景优先扩展 `PlatformMediaFrame`，不在业务 JSX 中重新手写 `ResolvedAssetImage`、固定图片壳和 fallback 文案。
|
||||
- `PlatformMediaTileGrid`：接收 `items`、`columns="five" | "six"`、`gap="xs" | "sm"`、`aspect="auto" | "square"`、`surface="none" | "soft"`、`tileSurface="white" | "slate" | "bare"`、默认 `fallbackLabel`、默认图片 / fallback class 和局部 class；每个 item 接收稳定 `id`、`src`、`alt`、`refreshKey`、`fallbackLabel`、`fallbackContent`、`testId` 与局部 class。tile 的边框 / 底色 / 阴影统一由 `tileSurface` 承接，内部 `PlatformMediaFrame` 使用 `surface="none"`，避免重复叠加公共媒体框底色。跳一跳结果页地块池、跳一跳无图集 fallback 地块池、拼消消结果页卡片预览网格和抓大鹅物品 spritesheet 解析预览分组已先迁移。后续结果页只是展示一组同尺寸正方形素材 tile 时优先使用该 Module；单张大图预览继续用 `PlatformMediaFrame`，历史素材选择继续用 `PlatformAssetPickerGrid`，上传预览继续用 `PlatformUploadPreviewCard`。
|
||||
- `PlatformTagEditor`：接收 `title`、`tags`、`disabled`、`maxTags`、`error`、`addLabel`、`generateLabel`、`inputLabel`、`inputPlaceholder`、`emptyLabel`、`parseInput`、`onChange`、可选 `onGenerate` / `generateIcon`、`radius`、`padding` 和 `tone="amber" | "warm"`；内部持有新增输入态，统一处理标签去重、添加、删除、Enter 提交、Escape 取消、空态、可选 AI 生成按钮和错误提示。拼图结果页作品标签、敲木鱼结果页主题标签和抓大鹅结果页作品标签已先迁移。后续结果页只保留业务标签规范化函数和写回回调，不再重复手写 tag chip、删除按钮、输入框、添加 / 取消按钮和 AI 生成按钮。
|
||||
- `PlatformTagEditor` 补充：新增输入行外壳继续由 `PlatformSubpanel surface="soft" padding="tight"` 承接，输入框由 `PlatformTextField` 承接；标签编辑 Module 内部也遵守公共输入 / 子面板分工，不再把白底 input chrome 写成本地 class。
|
||||
- `PlatformAssetPickerCard`：接收 `imageSrc`、`imageAlt`、可选 `assetTitle` / `subtitle`、`surface="platform" | "editorDark"`、`selectLabel`、`selected`、`disabled`、`onClick`、`aria-label`、`cardRadiusClassName`、`imageShellClassName`、`imageClassName` 和 `bodyClassName`；图片读取统一走 `ResolvedAssetImage`，按钮禁用态、选中态、边框、hover、缩略图外壳和可选卡片内选择按钮由 Module 统一控制，`assetTitle` 专指卡片内展示标题，不占用原生 button `title` 属性。`PlatformAssetPickerGrid`：接收素材数组、读取 / 错误 / 空态、`getKey`、`getImageSrc`、`getImageAlt`、`getTitle`、`getSubtitle`、`getAriaLabel`、`isSelected`、`cardClassName` 和 `onSelect`；默认组合 `PlatformStatusMessage`、`PlatformEmptyState` 与 `PlatformAssetPickerCard`，业务页只保留素材字段映射、文案、选中判断和选择回调，不再重复手写缩略图卡片、选中 ring、虚线读取 / 空态和网格 JSX。白底平台弹窗使用默认 `platform` surface；RPG 大编辑器等暗色弹窗使用 `editorDark`，并通过 `imageShellClassName` 保留场景横图比例。视觉小说等同一弹窗里混有上传 / AI 生成错误时，可继续由外层错误条承接动作错误，只把历史素材读取 / 空态 / 网格交给 `PlatformAssetPickerGrid`。
|
||||
- `PlatformActionButton`：接收 `tone="primary" | "secondary" | "ghost" | "danger" | "success" | "warning" | "accent" | "accentSoft"`、`surface="platform" | "profile" | "editorDark"`、`size="xxs" | "xs" | "sm" | "md" | "lg"`、`shape="default" | "pill"`、`align="center" | "start"`、`fullWidth`、`children` 和原生 button props；`surface="platform"` 复用 `platform-button` 样式族，`surface="profile"` 的主按钮复用个人中心 `platform-primary-button`，`surface="editorDark"` 统一承接 RPG 暗色弹窗 / 运行面板里的普通取消、确认、刷新和编组动作，`tone="accent"` 承接琥珀实心 CTA，`tone="accentSoft"` 承接带局部 accent 变量的柔和强调按钮，根节点固定带 `platform-action-button--accent` / `platform-action-button--accent-soft` 稳定类名。认证表单的 48px 高按钮使用 `size="lg"`，暗色微型刷新 / 工具动作使用 `size="xxs" shape="pill"`，需要文件上传等 label 语义时使用 `asChild="label"` 复用同一套按钮外观，不把上传控件改成普通 button。推荐回复、列表内动作等需要左对齐时使用 `align="start"`，不要在业务 JSX 中重复写 `justify-start text-left`；创作中心错误重试、反馈页 header 返回和暗色次要动作等普通 ghost 动作同样走 `tone="ghost"` 与 `shape="pill"`，不在业务 JSX 中直接拼按钮 class。复制按钮仍使用 `CopyFeedbackButton`，可选项按钮卡仍使用 `PlatformDarkOptionCard`，像素风发送 / 强品牌动作继续保留专用布局。
|
||||
- `PlatformActionButton` 补充：反馈页内的“查看反馈与投诉记录”这类页面内次级文本动作使用 `tone="ghost" shape="pill" size="xs"`；业务组件只保留点击反馈，不再手写居中、字号、内边距和冷色文本按钮 class。
|
||||
- `PlatformActionButton` 补充：作品详情底部“作品改造 / 作品编辑”和“启动”使用 `surface="platform" shape="pill" size="lg" fullWidth`，保留 `platform-work-detail__remix / start` 局部 class 控制 sticky 底部栏位置、比例和品牌背景。
|
||||
- `PlatformActionButton` 补充：作品详情点赞按钮使用 `tone="accentSoft"` 并通过局部 `--platform-action-accent` 变量复用柔和强调 chrome；详情页只保留纵向排布、尺寸和可访问名称，不再手写点赞按钮边框、底色、文字和阴影。
|
||||
- `PlatformActionButton` 补充：创作中心作品卡积分激励的“领取积分 / 领取中”按钮使用 `tone="secondary" size="xxs"`；作品卡保留 `creation-work-card-incentive__button` 局部 class 控制三列布局、移动端跨列、紧凑高度和玻璃底，不再手写原生按钮 chrome。
|
||||
- `PlatformActionButton` 补充：拼图首访 onboarding 生成 / 登录 CTA 使用 `surface="editorDark" tone="accent" size="lg" fullWidth`，跳过按钮使用 `surface="editorDark" tone="ghost" shape="pill"` 并只保留右上角定位 class；首访页不再手写按钮基础 chrome。
|
||||
- `PlatformIconButton`：接收 `label`、`icon`、可选 `children`、可选 `variant="platformIcon" | "surfaceFloating" | "darkMini"`、`title`、`className`、`asChild="label"` 和原生 button / label props；默认 `platformIcon` 用于平台弹窗 header、搜索结果弹窗、工具栏、结果页选项删除等普通图标动作按钮，也用于保持 file input 原生语义的图标上传 label；`surfaceFloating` 用于通用创作图片面板里覆盖在图片或输入区上的白底圆形图标动作，短文案入口通过 `children` 渲染可见短标签但仍由 `label` 提供可访问名称；`darkMini` 用于上传预览卡右上角等覆盖在缩略图上的暗色小型图标动作。creation-agent composer 中的上传文档 / 上传参考图入口使用默认 `platformIcon`，只保留动态 label、title、busy 和 picker 回调；作品详情顶部返回 / 分享与封面轮播上一张 / 下一张入口也使用默认 `platformIcon`，并通过局部 class 保留详情页专属位置和尺寸。发送按钮、点赞按钮、带复制三态或强品牌动作继续保留专用布局。关闭语义复杂或属于个人中心 / 浮层关闭按钮时仍优先使用 `PlatformModalCloseButton`，带复制三态时使用 `CopyFeedbackButton`。同一面板内存在主图上传和提示词参考图上传时，两个 file input 必须使用不同可访问名称，避免业务测试或读屏用户只能看到多个同名“上传参考图”入口。
|
||||
- `PlatformIconBadge`：接收 `icon`、可选 `label`、`size="xs" | "sm" | "base" | "md" | "lg" | "xl" | "xxl"`、`shape="circle" | "rounded" | "xl"`、`tone="neutral" | "soft" | "softBright" | "hero" | "heroMuted" | "darkAmber" | "success" | "danger"` 和 `className`；统一承接非交互图标槽的中性 / 柔和 / hero / 暗色琥珀 / 成功 / 危险底色、文字色、尺寸、圆角和 `aria-hidden` / `aria-label`。根节点固定带 `platform-icon-badge` 稳定类名，业务测试可断言共享图标槽接入。视觉小说 runtime 面板标题、存档列表项，creative-agent 模板卡 / 模板确认 / 顶部 hero / 目标就绪 / 过程条目图标圆槽，创作类型弹层锁定卡小圆锁图标，大鱼吃小鱼发布失败弹窗图标槽，通用创作图片面板空主图上传占位图标槽，拼图结果页智能修订条图标槽，以及 GameCanvas 宝箱遭遇图标槽已先迁移。后续同类图标槽不再重复手写 `grid h-* w-*`、`inline-flex h-* w-* items-center justify-center`、`rounded-full`、`rounded-[0.85rem]`、`rounded-2xl`、neutral token class、白底柔和小圆槽、暗色琥珀图标槽或危险提示红色圆槽。
|
||||
- `PlatformIconBadge` 补充：宝贝识物工作台玩法预览卡内礼物图标槽使用 `size="xl" shape="rounded" tone="softBright"`，业务页只保留玩法色和投影覆盖，不再手写 `grid h-14 w-14 place-items-center rounded-* bg-white/*`。
|
||||
- `PlatformIconBadge` 补充：个人中心充值结果弹窗和支付确认遮罩里的 56px 圆形图标槽使用 `size="xl"` 并通过局部 `bg-white/10`、状态文字色 class 覆盖；弹窗只保留支付结果文案、支付状态图标和确认动作，不再手写 `flex h-14 w-14 items-center justify-center rounded-full bg-white/10` 图标容器。
|
||||
- `PlatformUploadTile`：接收 `label`、可选 `hint`、`icon`、`size="square" | "compact" | "panel"`、`surface="platform" | "editorDark"`、`showLabel`、`disabled`、`className`、`asChild="label"` 和原生 button / label props；默认渲染 `type="button"` 的平台虚线上传方块，`compact + showLabel={false}` 用于工作台里的纯图标虚线新增入口，`panel` 用于整行上传说明入口，`editorDark` 用于 RPG 大编辑器等暗色弹窗。label 模式保留 file input 原生关联语义，禁用时写入 `aria-disabled` 并阻断 label 默认点击。反馈页上传凭证、敲木鱼工作台新增功德词条入口、RPG 大编辑器参考图入口、角色素材工作室参考图入口和封面上传入口已迁移，后续图片 / 附件上传方块或紧凑虚线新增入口只保留业务选择文件 / 新增动作，不再重复写虚线入口 chrome。
|
||||
- `PlatformUploadPreviewCard`：接收 `imageSrc`、`imageAlt`、`removeLabel`、可选 `layout="square" | "inline"`、`surface="platform" | "editorDark"`、`caption`、`previewLabel`、`onPreview`、`onRemove`、`disabled`、`resolveAsset`、`imageRefreshKey`、`className`、`imageClassName`、`imageShellClassName`、`captionClassName`、`previewButtonProps`、`removeIcon` 和 `removeButtonProps`；默认 `square` 渲染平台缩略图壳、`object-cover` 预览图、可选标题行和可选移除按钮，square 右上移除按钮复用 `PlatformIconButton variant="darkMini"`，`inline + platform` 通过 `PlatformSubpanel surface="soft" padding="row"` 渲染白底横向已选素材条，`inline + editorDark` 通过 `PlatformSubpanel surface="dark" padding="row"` 渲染暗色编辑器横向参考图条。需要点击预览的参考图传 `previewLabel/onPreview`，需要 generated / OSS 资产换签的缩略图传 `resolveAsset`，需要展示文件名 / 素材名的参考图传 `caption`，不要在业务 JSX 中额外包一层缩略图标题栏或横向参考图条。反馈页上传凭证预览、通用创作图片面板的提示词参考图缩略图、抓大鹅封面编辑参考图缩略图、通用输入 Composer、creation-agent 已选参考图条、拼图结果页关卡引用图横条和 RPG 大编辑器参考图预览条已迁移，后续上传预览只保留素材数据、预览回调和删除回调，不在业务 JSX 中重复写预览卡 chrome。
|
||||
- `PlatformPillSwitch`：接收 `label`、`checked`、`disabled`、`className` 和原生 input props；内部固定 `role="switch"`、`type="checkbox"` 和 `sr-only` 输入，视觉层统一白底胶囊、开关轨道、圆点位置、hover / 禁用态。通用创作图片面板和抓大鹅封面编辑的 `AI重绘` 已迁移，后续同类胶囊开关只传受控 checked / onChange，不再手写 switch 轨道和圆点。
|
||||
- `PlatformToggleRow`：接收 `label`、`checked`、`onChange`、`disabled`、`mode="checkbox" | "status"`、`icon`、`onLabel`、`offLabel`、`onClick`、`surface="soft" | "plain"`、`className` 和 `labelClassName`；`checkbox` 模式用于结果页运行配置和角色可见性，`status` 模式用于 runtime 设置面板的只读开关状态，可选 `onClick` 时自身渲染为 button。视觉小说结果页运行配置 / 玩家可见开关、视觉小说 runtime 设置面板和拼消消创作工作台 AI 生成底图开关已先迁移，业务页不再重复手写 `flex min-h-12 ... bg-white/74 px-3`、checkbox class 或“开启 / 关闭”状态 pill。
|
||||
- `PlatformInfoBlock`：接收可选 `label`、`children`、`multiline`、`className`、`labelClassName` 和 `valueClassName`；统一承载平台弹窗 / 详情页中的短标签、无标签只读正文、白底圆角边框、内容换行、单行加粗排版和横向只读信息行的标签 / 值局部排版。错误弹窗与生成完成弹窗的来源、错误、状态块、分享弹窗正文，以及汪汪声浪预览卡场景 / 形象 / 难度 / 声浪信息行已先迁移，后续同类只读信息展示只传 label、内容和必要局部排版 class，纯正文块可省略 label，不在业务 JSX 中重复写 `rounded-[1rem] border ... bg-white/72 px-3 py-2`、`rounded-[1.25rem] border ... bg-white/72 p-4` 或 `rounded-[0.85rem] bg-white/74 px-* py-*`。
|
||||
- `PlatformInfoBlock` 补充：当前 Interface 支持 `variant="compactRow"` 承接预览卡里的密集横向 label / value 行，标签、值、圆角、白底和响应式内边距由公共组件控制；汪汪声浪预览卡四个信息行已去掉本地 `PREVIEW_INFO_*` class 常量。
|
||||
- `PlatformModalCloseButton`：接收 `label`、`variant="profile" | "profileCompact" | "floating" | "floatingPlain" | "platformIcon" | "pixel" | "editorDark"`、`icon` 和原生 button props；`profile` 复用个人中心 `platform-modal-close` 圆形按钮，`profileCompact` 复用个人中心小弹窗 `platform-profile-icon-button` 关闭按钮，`floating` 复用平台浮层右上角白底关闭按钮，`floatingPlain` 复用个人中心邀请 / 社区浮层的透明右上角关闭按钮，`platformIcon` 复用平台弹窗头部 `platform-icon-button` 关闭入口，`pixel` 复用 `UnifiedModal variant="pixel"` 的像素风圆形关闭入口，`editorDark` 承接 RPG 暗色弹窗中非像素风的圆形 X 关闭入口并固定带 `platform-modal-close-button--editor-dark` 稳定类名。认证入口、邀请码弹窗等平台弹窗头部关闭按钮使用 `variant="platformIcon"`，像素风 `UnifiedModal` 使用 `variant="pixel"`，自定义选择弹窗使用 `variant="editorDark"`，业务页可以追加局部 class，但不重新声明基础尺寸、圆角、默认图标和 `aria-label`。
|
||||
- `squareImageCropModel`：导出 `SquareImageCropRect`、`buildCenteredSquareImageCropRect(imageSize)` 和 `clampSquareImageCropRect(imageSize, crop)`；可复用裁剪数学留在 model，`SquareImageCropModal` 只承接弹窗 UI、拖拽交互和提交动作。
|
||||
|
||||
## 迁移顺序
|
||||
|
||||
1. 先迁移平台入口壳中的泥点提示和作品删除确认，验证普通提示与危险确认两个分支。
|
||||
2. 迁移 `PlatformErrorDialog`、`PlatformTaskCompletionDialog`、`PublishShareModal` 的复制反馈到 `useCopyFeedback` 与 `CopyFeedbackButton`，验证成功、失败和上下文切换复位。
|
||||
3. 迁移公开作品详情、RPG 作品详情、拼图广场详情、大鱼 runtime 分享和账号个人资料区中的作品号 / 用户号复制与分享复制状态；短代码 chip 使用 `CopyCodeButton`，分享按钮继续按场景使用 `CopyFeedbackButton` 或 `CopyFeedbackMessage`，避免页面继续散落 `copyState / shareState + setTimeout` 或三态按钮 JSX。
|
||||
4. 再迁移结果页、工作台和账号区域中只有单个确认按钮或确认 / 取消按钮的简单弹窗；拼图结果页关卡画面生成、抓大鹅结果页物品素材生成 / 重新生成的“确认消耗泥点”已使用 `UnifiedConfirmDialog` 的内嵌渲染模式，拼图 / 抓大鹅创作工作台的初始泥点确认已使用默认 portal 模式，大鱼吃小鱼结果页发布失败提示已通过 `confirmClassName` 保持整行确认按钮外观。
|
||||
5. 自定义世界实体目录的删除确认、批量删除确认和“至少保留一个可扮演角色”提示统一使用 `UnifiedConfirmDialog`，不再调用浏览器原生 `window.confirm` / `window.alert`。
|
||||
6. RPG 结果页整页重新生成确认由页面层使用 `UnifiedConfirmDialog` 承接，`useRpgCreationResultActions` 只保留执行命令和忙碌态保护，不再在 hook 内调用浏览器原生确认框。
|
||||
7. RPG 详情页删除确认由平台壳的共享作品删除弹窗承接；`useRpgEntryLibraryDetail` 只保留已确认后的删除命令、刷新和阶段回退，不再直接调用浏览器原生确认框。
|
||||
8. RPG 角色素材工作室的形象 / 动作泥点消耗确认使用 `UnifiedConfirmDialog portal={false}` 内嵌在工作室弹窗栈内；点击生成只打开确认，确认后再执行生成工作流。
|
||||
9. RPG 场景编辑器中的多幕数量、连接关系、主角色、幕预览和角色槽位阻断提示统一使用基于 `UnifiedConfirmDialog` 的编辑器提示弹窗，不再调用浏览器原生 `window.alert`。
|
||||
10. RPG 可扮演角色 / 场景角色的背景章节删除阻断提示由角色编辑器壳层承接，背景章节编辑控件只上报 `onNotice`，不直接调用原生弹窗。
|
||||
11. RPG 编辑器关闭未保存草稿时使用 `UnifiedConfirmDialog` 统一承接“确认关闭 / 继续编辑”，不再维护单独的关闭确认按钮样式。
|
||||
12. RPG 场景背景和作品封面生成结果未保存时，退出确认也使用 `UnifiedConfirmDialog`；像素风场景生成弹窗通过 `variant="pixel"` 适配视觉。
|
||||
13. 公开作品详情或运行态深链失效时，由平台入口壳展示 `UnifiedConfirmDialog` 的“作品不可用”提示；用户确认后再回到首页，错误处理分支不再调用浏览器原生 `window.alert`。
|
||||
14. 带复杂内容的专用 Module 可以保留自己的布局，但复制反馈仍应复用 `useCopyFeedback`；如果有可点击复制按钮，优先复用 `CopyFeedbackButton`；如果只展示复制结果提示，优先复用 `CopyFeedbackMessage`。
|
||||
15. 白底平台弹窗、详情页、结果页、目录页、个人页、认证入口、统一创作工作台和通用创作输入区的基础错误 / 成功 / 信息 / 警告 / 中性状态提示逐步迁移到 `PlatformStatusMessage`；RPG 结果页、拼图结果页、抓大鹅结果页、跳一跳结果页、敲木鱼结果页、拼消消结果页、宝贝识物结果页、方洞结果页、汪汪声浪结果页、视觉小说结果页、拼消消创作工作台、宝贝识物创作工作台、视觉小说创作工作台、汪汪声浪创作工作台、creative-agent 工作台、creation-agent operation banner、自定义世界实体目录、拼消消 runtime 白底错误条和平台作品详情分享复制反馈已使用 `surface="platform"` 承接发布检查、错误提示、进度提示、素材生成提示、资源未就绪提示、主线目标提示和复制反馈；个人中心、认证入口、统一创作工作台和创作输入区需要 profile token 外观时使用 `surface="profile"`；RPG 暗色编辑 / 运行面板和拼图首访 onboarding 里的普通错误 / 成功 / 信息 / 警告 / 中性提示使用 `surface="editorDark"`，背包故事档案 QA 提示、NPC 交易 / 赠礼 / 招募叙事提示和角色聊天错误提示已先迁移。运行态里的短错误 / 成功 / 命中反馈 chip 使用 `PlatformRuntimeStatusToast`，位置和玩法强品牌 HUD 仍留在 runtime 壳层；深色半透明游戏内提示和强品牌样式可以暂保留专用布局，避免状态条组件过早承接游戏视觉。
|
||||
16. 正方形图片裁剪的初始居中、边界 clamp 和裁剪矩形类型统一从 `squareImageCropModel` 导入，避免头像裁剪、拼图参考图裁剪等业务页面依赖弹窗组件文件里的 helper。
|
||||
17. 个人中心的账户充值、泥点账单、每日任务、兑换码、扫码、存档、玩过作品、邀请 / 社区、昵称修改、头像裁剪，以及平台筛选、创作图片预览、认证入口、邀请码弹窗、公开编号搜索结果弹窗、方洞结果页图片素材弹窗、视觉小说结果页资产 / 音频 / 编辑器弹窗、视觉小说 runtime 普通面板、creative-agent 模板确认弹窗、像素风 UnifiedModal 和自定义选择弹窗等圆形关闭按钮迁移到 `PlatformModalCloseButton`；后续新增弹窗关闭按钮先判断是否属于 `profile`、`profileCompact`、`floating`、`floatingPlain`、`platformIcon`、`pixel` 或 `editorDark` 七类，确有品牌化或运行态 HUD 语义时才保留专用按钮。
|
||||
17.1. 平台弹窗 header 和普通工具栏里的 `platform-icon-button` 迁移到 `PlatformIconButton`；历史图片选择弹窗、RPG 发布检查弹窗、creative-agent 侧边栏关闭 / 外观 / 设置入口、通用输入 Composer 上传 / 发送 / 移除参考图、creation-agent composer 上传文档 / 上传参考图、creation-agent 参考图移除、敲木鱼结果页新增主题标签入口、敲木鱼创作工作台功德词条删除入口、拼图结果页标签生成 / 标签新增 / 关卡详情关闭 / 发布弹窗关闭 / 删除关卡入口、视觉小说结果页素材选择 / 音频生成 / 保存草稿 / 运行配置入口、RPG 首页搜索结果清空入口、方洞结果页形状 / 洞口选项删除入口，以及抓大鹅结果页标签生成 / 标签新增 / 物品素材删除 / 参考图上传入口已先迁移。结果页内的普通平台弹窗关闭入口使用 `PlatformModalCloseButton variant="platformIcon"`；图标上传控件使用 `PlatformIconButton asChild="label"` 保留 label + file input 语义，不改成普通按钮；`PlatformIconButton` 的 label 模式会自动写入隐藏文本，保证内嵌 file input 仍能继承可访问名称。通用创作图片面板中覆盖在图片上的更换主图、移除主图、历史入口短标签按钮和提示词参考图上传入口，抓大鹅封面编辑中覆盖在封面图上的移除入口，以及敲木鱼创作工作台功德词条删除入口使用 `PlatformIconButton variant="surfaceFloating"`，不再手写白底圆形 / 短标签浮动按钮 chrome。运行态 HUD、带复制状态或需要专用交互禁用语义的图标按钮，先保留专用布局，等对应场景验证时再迁移。
|
||||
17.2. 非交互图标徽章迁移到 `PlatformIconBadge`；视觉小说 runtime 面板标题、存档列表项，creative-agent 模板卡 / 模板确认 / 顶部 hero / 目标就绪 / 过程条目图标圆槽，创作类型弹层锁定卡小圆锁图标，大鱼吃小鱼发布失败弹窗图标槽，通用创作图片面板空主图上传占位图标槽，拼图结果页智能修订条图标槽，以及 GameCanvas 宝箱遭遇图标槽已先迁移。后续同类图标槽只表达 icon、尺寸、形状和 neutral / soft / softBright / hero / heroMuted / darkAmber / success / danger 调性，不再重复中性、白底柔和、hero 叠层、暗色琥珀、成功或危险底色、文字色、居中和 shrink class。
|
||||
17.3. RPG 大编辑器主壳层和紧凑对话壳层的右上角关闭入口迁移到 `PlatformModalCloseButton variant="platformIcon"`；暗色编辑器仍保留原 `platform-icon-button` 视觉 token，但业务 JSX 不再手写 `button`、`aria-label` 和默认关闭图标。
|
||||
18. RPG 首页、公开广场、排行、作品架、个人中心充值 / 任务弹窗、视觉小说 runtime 普通白底面板、历史素材选择弹窗、视觉小说上传资产弹窗本地上传占位、自定义世界实体目录搜索无结果、大鱼吃小鱼结果页缺草稿提示、RPG 大编辑器纯展示暗色列表、背景故事空档案和 RPG 运行态设置保存禁用提示中的无操作空态 / 轻量读取态迁移到 `PlatformEmptyState`；后续空态如果包含 CTA、插画、复杂列表恢复动作或玩法 HUD，再保留专用布局。
|
||||
18.1. 历史图片 / 历史素材 / 可引用素材选择迁移到 `PlatformAssetPickerCard` 与 `PlatformAssetPickerGrid`；拼图历史图片弹窗、方洞历史生成、视觉小说历史素材选择器、RPG 大编辑器历史素材弹窗和抓大鹅封面编辑可引用素材网格已先迁移。后续素材选择只传素材数组、`imageSrc`、主副文案、可访问名称、surface、选中判断和选择回调，不再在业务页重复缩略图、边框、选中 ring、禁用态、`ResolvedAssetImage` 壳层、虚线读取 / 空态和网格 JSX。
|
||||
18.2. 平台白底圆角输入框和文本域迁移到 `PlatformTextField surface="platform"`；RPG 暗色弹窗 / 运行面板里的普通输入框、文本域和下拉框迁移到 `PlatformTextField surface="editorDark"` / `PlatformSelectField surface="editorDark"`；抓大鹅结果页作品名称 / 描述、封面描述、素材名称、批量新增 / 批量重生成物品名称，方洞结果页游戏名称、标签、简介、题材主题、反差规则、背景提示、形状数量、形状 / 洞口名称、形状目标洞口和图片提示词，拼图结果页作品名称 / 描述、关卡名称和智能修订输入，敲木鱼结果页作品标题 / 简介，视觉小说结果页的音乐生成、作品信息、开场、运行配置、角色、场景、阶段和世界观普通文本 / 下拉字段，以及视觉小说 / 抓大鹅 / 汪汪声浪 / 宝贝识物 / 拼消消 / 跳一跳创作工作台普通输入字段、敲木鱼创作工作台功德词条输入、creative-agent 模板确认调整弹层关卡数输入已先迁移。通用输入 Composer、通用创作图片输入面板的提示词文本域、自定义世界实体目录搜索框、认证验证码答案输入、短信 / 密码登录、重置密码、绑定手机号、邀请码、账号安全表单字段、个人中心兑换码 / 邀请码输入、自定义选择弹窗角色名字 / 背景补充 / 生成模式 / 世界描述、角色聊天草稿、拼图首访 onboarding 提示词文本域和平台反馈页问题描述 / 联系电话也使用 `PlatformTextField` / `PlatformSelectField`；浮动胶囊 Composer 可继续由 `.creative-agent-composer--floating textarea` 覆盖尺寸和背景，图片输入面板可通过局部 class 保留高度与浮动上传按钮避让，实体目录搜索框可通过局部 class 保留紧凑圆角和底色，验证码答案输入和认证表单字段可通过局部 class 保留表单高度、横向验证码按钮布局和原生 `label` 关联，个人中心兑换码 / 邀请码输入通过局部 class 保留大写和居中，暗色聊天草稿和首访提示词文本域可通过局部 class 保留沉浸式底色 / 高度，反馈页字段可通过局部 class 保留透明嵌入式视觉，不在业务 JSX 中手写 textarea / input / select chrome。默认密度用于结果页主表单，`density="compact"` 用于选项卡片、工具条、认证提示内或反馈页联系电话的紧凑字段，`density="roomy"` 用于宽内边距文本域、关卡详情字段、首访提示词文本域或反馈页问题描述；默认 `tone="warm"`，玩法需要保留调性焦点色时使用 `tone="rose"`、`tone="emerald"` 或 `tone="sky"`，不要在业务 JSX 中重复写 `focus:border-* focus:ring-*`。后续结果页、工作台、目录工具条、认证提示、认证表单、个人中心轻量表单、反馈表单、首访页或 RPG 暗色弹窗内的普通文本输入 / 下拉框只传受控值、事件、可访问名称、占位符、选项和局部布局 class，不再重复基础边框、背景、内边距、字号、禁用态和焦点色。
|
||||
18.2.1. 个人中心昵称弹窗输入框迁移到 `PlatformTextField surface="editorDark"`；昵称状态机、校验、保存和弹窗壳层不随输入框 chrome 收口改动。
|
||||
18.3. 平台字段标签迁移到 `PlatformFieldLabel`；视觉小说结果页、抓大鹅结果页作品 / 封面 / 素材字段标题、方洞结果页主信息 / 形状 / 洞口 / 历史图片字段标题、拼图结果页关卡详情 / 发布弹窗字段标题、拼消消创作工作台作品标题 / 简介 / 主题词、跳一跳创作工作台主题、大鱼素材弹窗 prompt、RPG 发布弹窗发布检查 / 封面设置、汪汪声浪轻配置编辑器、宝贝识物工作台、通用创作图片输入面板主图 / 提示词标题，以及认证登录 / 绑定 / 邀请码 / 账号安全表单标题、平台反馈页问题描述 / 联系电话标题已先迁移。后续结果页、编辑弹窗、工作台、通用创作输入面板、反馈表单或认证表单中只表达字段名称的小标题，优先选择 `field` / `section` / `form` / `pill` / `accentPill`，不要在业务 JSX 中重复拼字段标题 class；认证表单、反馈表单和提示词字段保留外层原生 `label`，带品牌化插画、运行态 HUD 或复杂步骤标题时可暂保留专用标题。
|
||||
18.3.1. 个人中心存档 / 玩过弹窗里的简单空态、分区标题和已玩作品白底按钮卡分别迁移到 `PlatformEmptyState`、`PlatformFieldLabel` 与 `PlatformSubpanel`；`SaveArchiveCard` 带图片遮罩和加载视觉，仍保留专用实现，后续需要单独视觉验收后再决定是否收口。
|
||||
18.3.2. 平台入口壳中的纯 Suspense fallback、作品详情读取 / 错误提示、Agent 工作区恢复提示、RPG runtime 主阶段懒加载提示和 `CreationResultRecoveryPanel` 外壳迁移到 `PlatformSubpanel`；加载 / 错误提示使用 `radius="sm" padding="none"`，带恢复动作的结果恢复面板使用 `radius="xl" padding="none"`，玩法 runtime overlay 后续单独评估。
|
||||
18.3.3. 个人中心钱包账单弹窗里的空态和账单行分别迁移到 `PlatformEmptyState` 与 `PlatformSubpanel`；账单展示只保留收支内容、余额和时间，不在业务 JSX 重复白底列表行 chrome。
|
||||
18.3.4. 个人中心邀请弹窗内部的二维码卡、邀请码卡、成功邀请列表、邀请用户行、小标题和简单空态分别迁移到 `PlatformSubpanel`、`PlatformFieldLabel` 与 `PlatformEmptyState`；外层弹窗、query 自动打开、复制邀请、提交邀请码和社区面板信息架构不随本轮改变。
|
||||
18.3.5. 个人中心任务中心任务条目迁移到 `PlatformSubpanel`；任务选择、领取、奖励和完成态仍由任务 ViewModel / 业务流程控制。
|
||||
18.3.6. 个人中心充值弹窗 Native 支付二维码确认面板迁移到 `PlatformSubpanel`；支付渠道选择、二维码生成和确认支付流程不随 UI chrome 收口改动。
|
||||
18.3.7. 个人中心充值弹窗商品整卡按钮迁移到 `PlatformSubpanel as="button" interactive`；支付渠道选择、商品展示、提交中态和购买回调不随按钮卡 chrome 收口改动。
|
||||
18.4. 平台白底分段 Tab / 二选一 / 四选一配置项迁移到 `PlatformSegmentedTabs`；拼图结果页、抓大鹅结果页、抓大鹅素材配置、抓大鹅创作 / 结果页难度选择、视觉小说结果页和 creative-agent 模板确认弹窗已先迁移。后续同类控件只传选项、当前 id、变更回调、列数、尺寸、调性和外壳形态，不再在业务 JSX 中重复容器边框、`bg-white/62`、选中态和 `aria-pressed`。
|
||||
18.4.1. `PlatformSegmentedTabs` 支持 `semantics="tabs"`、`tone="underline"`、`size="tab"` 和 `columns="one"`，用于承接认证入口短信 / 密码登录切换这类真实 Tab 语义；业务页不再维护本地 `LoginTabButton`、`role="tab"`、`aria-selected` 和下划线选中态。
|
||||
18.5. 平台只读信息块迁移到 `PlatformInfoBlock`；错误弹窗和生成完成弹窗的来源、错误和状态展示、分享弹窗正文，以及汪汪声浪预览卡场景 / 形象 / 难度 / 声浪信息行已先迁移。后续弹窗、详情页或预览卡里只是展示短标签 + 只读正文，或无标签纯只读正文时，优先使用该 Module；横向信息行通过 `labelClassName` / `valueClassName` 保留标签和值排版，不在业务 JSX 中重复白底信息块 chrome。
|
||||
18.5.1. 平台来源 / 状态 / 错误这类可复制报告弹窗迁移到 `PlatformReportDialog`；`PlatformErrorDialog` 和 `PlatformTaskCompletionDialog` 已先迁移，业务弹窗只保留标题、字段语义和黑名单过滤，不再重复维护 `UnifiedModal`、`CopyFeedbackButton`、`useCopyFeedback`、报告拼装和 `PlatformInfoBlock` footer 组合。后续同类“字段展示 + 复制整段报告”弹窗优先复用该 Module。
|
||||
18.6. 平台统计小卡和轻量状态 chip 迁移到 `PlatformStatGrid`；拼消消结果页素材摘要、方洞结果页封面状态 chip、抓大鹅结果页难度摘要、creative-agent 模板确认摘要和自定义世界实体目录世界页档案规模已先迁移。后续结果页里只表达数值 / 标签摘要时，优先传 `items`、列数、密度、surface 和 label/value 顺序，不再在业务 JSX 中重复手写统计卡 chrome。
|
||||
18.6.1. 平台普通进度条迁移到 `PlatformProgressBar`；creation-agent 主进度 / operation banner、RPG 结果页生成提示、RPG 实体目录生成中提示、开场 CG 生成占位、拼图关卡画面生成进度、生成页当前步骤线性进度、抓大鹅批量物品素材生成进度和自定义世界生成选择弹窗进度提示已先迁移。creation-agent operation banner 的状态外壳也迁移到 `PlatformStatusMessage surface="platform" remapSurface`，避免业务 JSX 继续组合 `platform-remap-surface platform-banner` 和 `platform-banner--*`。后续生成进度、素材进度或实体目录进度只保留进度值、显示文案、主题色、必要覆盖层和业务状态，不再重复写 `role="progressbar"`、`platform-progress-track`、fill 宽度和最小可见宽度计算；未知进度用 `indeterminate`。生成页环形总进度继续保留 `GenerationProgressHero` 专用 SVG。
|
||||
18.6.2. 平台单个胶囊状态 / 标签 chip 迁移到 `PlatformPillBadge`；宝贝识物结果页发布状态、主题标签与占位资源 overlay，宝贝识物 / 拼图 / 抓大鹅 / 视觉小说工作台 BETA chip、汪汪声浪轻配置 chip、汪汪声浪结果页草稿 chip、汪汪声浪预览 VS chip、敲木鱼结果页飘字 chip、creative-agent 顶部阶段 / 过程计数 / 条目 meta chip、通用音频输入面板限制标签、自定义世界实体目录批量选择 / 生成中 / 开局 CG / 可扮演角色元信息 badge、RPG 首页公开作品卡 / 搜索结果 / 充值商品 / 移动端创建入口 / 桌面发现区 chip、RPG 世界详情静态元信息 chip、平台作品详情主题标签、RPG 角色身份 / 等级 / 技能出手方式 / 技能详情与状态标签 / 背景故事解锁状态 / 好感等级 / 角色资产工作室动作状态 / 角色编辑技能动作状态 / 角色资源应用状态 / 场景角色选择状态 / 地标当前连接状态 / 地图节点当前状态 / 地图节点方向标签 / 地图场景切换方向标签 / 作品封面来源状态 / 开局物品标签、NPC 交易数量 / 赠礼好感和背包工坊材料需求等暗色展示 chip、抓大鹅批量新增 / 批量重生成物品名称预览 chip、抓大鹅 / RPG / 拼图 / 方洞结果页自动保存状态、抓大鹅结果页当前难度 badge、拼图结果页关卡生成中 overlay / 列表 badge、大鱼吃小鱼结果页终局 / 关卡元信息 / 发布校验成功 badge、RPG 开发资产诊断数量 / 加载状态 badge、RPG 发布弹窗封面来源 badge、账号弹窗主题状态 / 会话数量 / 设备状态 badge、汪汪声浪生成页和通用生成页右上状态 badge、创作类型弹层锁定 badge、通用创作图片面板提交按钮内泥点消耗标签，以及个人中心泥点账单余额、玩过总时长和玩过作品类型 chip 已先迁移。后续只表达一个状态、标签、分类 chip 或按钮内消耗小胶囊时使用该 Module，不在业务 JSX 中重复拼 `rounded-full border bg-* text-* px-* py-*`；个人中心玫瑰色 chip 使用 `tone="profile"` / `tone="profileAccent"`，RPG 暗色展示 chip 使用 `dark*` tone，密集目录元信息用 `size="xxs"`，平台白底柔和状态使用 `tone="muted"`，实心中性详情标签使用 `tone="neutralSolid"`，按钮内浅色叠层使用 `tone="lightOverlay"`，多项统计摘要继续使用 `PlatformStatGrid`。可点击复制 / 分享胶囊 chip 继续由 `CopyCodeButton` / `CopyFeedbackButton` 管复制状态，并通过 `actionAppearance="pill"` 复用 `PlatformPillBadge` chrome。
|
||||
18.6.2.1. 抓大鹅创作工作台提交按钮内的泥点消耗标签使用 `PlatformPillBadge tone="lightOverlay" size="xs"`；工作台只保留泥点数值和提交状态，不再手写 `rounded-full bg-white/24 px-2 py-0.5`。
|
||||
18.6.3. 平台媒体悬浮短标签迁移到 `PlatformOverlayBadge`，复合控件内部的紧凑槽位编号迁移到 `PlatformSlotBadge`；RPG 场景幕预览左上幕标签和每幕角色槽位的“主 / 2 / 3”标记已先迁移。后续覆盖在图片、素材预览或舞台画面上的非交互短标签只传文案、位置和局部 class，绝对定位、白底半透明、边框、阴影与字距由 `PlatformOverlayBadge` 承接；角色槽、步骤槽等复合按钮里的小圆形序号只传文案和 active / inactive 语义，由 `PlatformSlotBadge` 承接。普通状态 / 分类仍使用 `PlatformPillBadge`，外层按钮、人物舞台布局和运行态 HUD 不迁入这两个小 Module。
|
||||
18.6.3.1. `PlatformOverlayBadge` 支持 `tone="muted"`、`size="compact"` 和 `offset="tight"`，用于素材缩略图右上角“占位图”等更紧凑的非交互浮层；宝贝识物结果页素材卡占位图标记已迁移到该组合。后续这类贴在媒体框上的短标签优先使用 overlay badge，不再把 `PlatformPillBadge` 绝对定位到图片内。
|
||||
18.6.3.2. `PlatformSlotBadge` 支持 `tone="soft"` 和 `size="md"`，用于 creative-agent 阶段时间线这类白底柔和步骤圆点；时间线外层阶段卡、进行中 / 已完成 / 未开始语义配色仍保留在业务 Module，公共徽标只承接圆点尺寸、白底、边框和图标居中。
|
||||
18.6.4. 物品格、奖励格等缩略图右下角的数量角标迁移到 `PlatformQuantityBadge`；背包物品格和 RPG 冒险面板 / 覆盖层的奖励物品数量已先迁移。后续同类右下角数量只传数量值，绝对定位、黑底半透明、圆角、边框和字号由该 Module 承接；可交互物品按钮、选中态、稀有度边框、图标来源和详情弹窗仍留在业务 Module。
|
||||
18.6.5. RPG 冒险面板和覆盖层里的任务目标状态、任务日志状态、当前幕、剩余交谈等纯展示暗色 chip 复用 `PlatformPillBadge` 的 `dark*` tone；任务 presentation / 日志状态只返回语义 tone，不再携带完整 `border / bg / text` class。运行态行动按钮、任务面板打开按钮和需要 hover / click 语义的胶囊仍保留专用按钮布局。
|
||||
18.6.6. RPG 角色面板里的标签数、适配倍数、性别和装备稀有度等纯展示暗色 chip 复用 `PlatformPillBadge darkNeutral / darkEmerald / darkAmber`；构筑适配倍数只保留 multiplier 计算，不再手写 emerald 胶囊 chrome。后续带复杂数值拆解的统计 / 加成类展示能力再单独收口。
|
||||
18.6.7. RPG 首页作品卡里的发布状态、元信息、主标签，以及存档卡右上恢复 / 最近游玩时间等暗色静态 chip 复用 `PlatformPillBadge dark*`；作品卡 / 存档卡只保留可点击卡片、删除动作、进入 / 继续创作箭头和业务文案。
|
||||
18.6.8. 自定义世界实体目录里的基础设定词条标签复用 `PlatformPillBadge darkSoft`；目录页只保留词条解析和空值展示逻辑，不再手写白字暗底 tag chrome。
|
||||
18.7. 平台白底子面板迁移到 `PlatformSubpanel`；拼图结果页作品信息 / 智能修订条 / 关卡卡片、敲木鱼结果页主预览面板 / 元信息、敲木鱼工作台功德词条、拼图图片生成模式选择器菜单外壳、跳一跳结果页预览 / 操作面板 / 排行榜 / 轻量媒体壳、拼消消创作工作台左侧表单面板、拼消消结果页预览 / 统计 / 操作面板 / 轻量媒体壳、方洞结果页封面 / 主信息 / 形状 / 洞口标准面板、方洞形状 / 洞口选项卡与缩略图按钮、RPG 结果页开发资产诊断摘要 / 条目 / 空态、RPG 发布弹窗封面预览壳、通用音频输入面板、视觉小说创作工作台画风选择面板、视觉小说结果页素材 / 音频小面板、视觉小说结果页作品 / 开场 / 运行配置 / 世界观标准编辑面板、视觉小说结果页角色 / 场景 / 阶段列表项与空态、视觉小说 runtime 历史条目 / 存档列表、抓大鹅创作工作台难度小面板、抓大鹅结果页作品 / 难度 / 统计 / UI素材预览标准面板 / 物品图集分组卡 / 批量素材生成进度卡、汪汪声浪结果页草稿摘要 / 素材槽 / 预览卡、平台反馈页问题描述 / 上传凭证 / 联系方式区块、自定义世界实体目录世界基调 / 角色维度 / 基本设定条目 / 场景幕级缩略图 / 目录卡片媒体壳 / 目录卡片整卡壳，以及 creative-agent 工作台标准白底面板 / 关卡计划小卡和通用输入 Composer 普通 panel 外壳已先迁移。后续仅表达“白底子面板 + 标题 / 右侧动作 + 内容”“不需要 fallback / overlay 的白底轻量媒体壳”或“白底整卡点击列表项”的片段优先使用该 Module；标准面板使用 `surface="platform"`，选中 / 删除预备等危险整卡态使用 `surface="danger"`，大圆角标准面板使用 `radius="xl" padding="lg"`，小型白底卡片或小型浮层菜单使用 `surface="flat"`，不要在业务 JSX 里继续覆盖 flat 的圆角和底色，轻量媒体壳使用 `surface="flat" padding="none"`，整卡或缩略图点击使用 `as="button" interactive`；暗色运行态 HUD、通用输入 Composer 浮动胶囊或强玩法品牌面板可继续保留专用布局。
|
||||
18.7.1. 账号设置入口卡、主题选择卡、当前主题状态、账号绑定卡、密码 / 安全 / 设备 / 操作记录区块，以及设备 / 操作记录内的白底列表行已迁移到 `PlatformSubpanel`；账号弹窗只保留绑定、换绑、撤销会话和日志展示语义，不再直接拼 `platform-subpanel rounded-2xl` 或内层白底列表边框。
|
||||
18.7.2. RPG 世界详情页的世界信息统计卡、关键角色 / 关键场景预览卡和操作区标题已迁移到 `PlatformSubpanel` 与 `PlatformFieldLabel variant="section"`；详情页只保留作品展示、启动、编辑、发布、下架和删除动作语义，不再直接拼小型 `platform-subpanel` 卡片或本地 section 标题 class。
|
||||
18.7.3. 大鱼吃小鱼结果页的关卡卡片、场地背景卡、发布校验卡、空草稿提示和素材工坊 PROMPT 信息块已迁移到 `PlatformSubpanel`；结果页只保留大鱼玩法的青色主题按钮、预览背景、素材生成动作和发布校验语义，不再直接拼 `rounded-[1.45rem] border ... bg-[var(--platform-subpanel-fill)] p-4` 或 `rounded-[1.25rem] border ... bg-white/72 p-4`。
|
||||
18.7.4. 平台媒体预览框迁移到 `PlatformMediaFrame`；自定义世界实体目录场景图片框、RPG 实体编辑器 `ImagePreview`、拼图结果页关卡列表正式图框、拼图发布弹窗封面关卡预览、拼消消结果页场地底图 / 素材图集 / 卡片预览网格、方洞结果页图片查看弹窗预览、方洞结果页封面 / 背景点击预览、方洞结果页形状 / 洞口贴图缩略图、宝贝识物结果页素材卡图片框、视觉小说结果页封面 / 资产字段图片预览、敲木鱼结果页主 9:16 背景 + 敲击物叠层预览、跳一跳结果页地块图集整图预览、大鱼吃小鱼关卡主图缩略图、大鱼吃小鱼素材工坊候选预览、大鱼吃小鱼场地背景竖版预览、creative-agent 模板确认预览、拼图图库详情页封面轮播媒体框、认证验证码图片，以及抓大鹅结果页物品素材列表缩略图、详情大图、视角缩略图、UI 素材背景 / UI spritesheet / 物品 spritesheet 主图预览已先迁移。拼图发布弹窗封面关卡预览、creative-agent 模板确认预览和认证验证码图片使用 `surface="soft"` 承接白底柔和边框，业务 JSX 只保留局部圆角、高度或 fallback 渐变差异；拼图关卡列表正式图、拼消消场地底图 / 素材图集、宝贝识物素材卡顶部媒体槽、视觉小说资产字段、creative-agent 模板目录卡、跳一跳地块图集整图、大鱼关卡主图 / 工坊候选 / 场地背景主题槽、拼图图库详情页封面轮播媒体框、方洞封面 / 背景点击预览、方洞形状 / 洞口贴图缩略图和抓大鹅 UI 素材页白底预览壳 / 详情视角缩略图嵌在保留媒体壳或交互态的外层壳内，使用 `surface="none"` 只承接图片 / fallback；抓大鹅素材列表缩略图和详情大图使用 `surface="bright"` 承接亮白素材槽，并通过容器属性透传保留测试 id / aria。后续需要图片源、fallback 图、fallback 文案 / 自定义占位内容、fallback 外壳局部着色、固定比例或 overlay 的预览框只传素材地址、可访问名称、比例、surface、刷新 key 和覆盖层，不再在业务 JSX 中重复拼图片框渐变、无图占位、`aspect-*`、基础边框 / 底色和绝对定位 overlay。
|
||||
18.7.5. 汪汪声浪结果页草稿编译小卡迁移到 `PlatformSubpanel surface="flat"`，跳一跳结果页排行榜行卡迁移到 `PlatformSubpanel surface="flat"`，排行榜无成绩空态迁移到 `PlatformEmptyState surface="subpanel"`；结果页只保留玩法文案、排行字段和错误 / 空态文案，不再手写白底小卡圆角、边框、底色和 padding。
|
||||
18.7.6. creative-agent 模板目录卡迁移到 `PlatformSubpanel as="button" interactive surface="flat"`，卡内 16:9 预览迁移到 `PlatformMediaFrame aspect="landscape" surface="none"`；工作台只保留模板选择、标题、摘要、预览渐变局部样式和泥点范围，不再手写白底按钮卡、16:9 图片框或图标 fallback 容器。
|
||||
18.7.7. `PlatformSubpanel` 支持 `surface="dark"`、`radius="xs"` 和 `padding="xs"`，用于承接暗色编辑 / 运行面板中的小型信息卡；RPG 冒险面板 / 覆盖层任务目标、区域、进度、任务摘要卡、奖励条、描述卡、任务更新提示、任务日志条目、冒险统计总览和统计卡、任务完成领奖提示、奖励缓存、战斗结束、战利品面板和奖励物品详情描述 / 效果 / 标签，自定义世界实体目录角色维度小卡，自定义选择弹窗当前角色信息块，RPG 大编辑器场景幕背景信息、预设背景和场景连接关系面板，角色面板个人线阶段 / 背景 / 性格块 / 装备行，好感状态卡的等级摘要 / 进度面板，背景故事公开印象 / 已解锁章节 / 锁定章节面板，角色详情装备 / 背包 / 旅程 / 背景 / 性格小卡，通用角色技能卡，实体详情主分区壳和最近回响里的后果 / 编年 / 载体 / 场景残留卡，背包文书 / 故事档案 / 工坊分区与非交互条目卡，NPC 交易数量 / 库存 / 详情 / 总价 / 交易详情装备与使用属性，以及角色聊天状态 / 总结等静态信息卡已先迁移。RPG 大编辑器本地 `EditorInfoPanel` / `SectionPanel` 和实体详情本地 `Section` 只保留标题、右侧动作、subtitle 或内容插槽，暗色面板 chrome 继续由 `PlatformSubpanel surface="dark"` 承接；可扮演角色背景故事、关系、技能、物品和世界基础设定等编辑分区不再手写外层暗色面板。后续暗色小信息卡只保留标题、图标、值和必要动作，不再重复手写 `rounded-xl border border-white/10 bg-black/* px-* py-*`。
|
||||
18.7.7.1. `PlatformSubpanel` 支持 `surface="darkSky" | "darkEmerald" | "darkAmber" | "darkRose"`，用于承接暗色编辑 / 运行面板中的强调态结构化信息面板；实体详情私聊提示、队友收束、玩家等级进度、角色面板等级 / 收束状态、任务奖励好感度 / 货币 / 经验数值卡、RPG 大编辑器上传封面中提示、地图场景切换目标场景面板和共享构筑状态标签外壳已先迁移。后续同类只读或半结构化提示只传 surface、radius、padding 和业务内容，不再手写 `border-*-400/18 bg-*-500/8` 暗色 tint 面板。
|
||||
18.7.8. 拼图图库详情页封面轮播壳迁移到 `PlatformSubpanel radius="xl" padding="none"`，内层图片 / fallback / 轮播 overlay 迁移到 `PlatformMediaFrame surface="none"`；详情页只保留图片 slide 数据、轮播按钮和 fallback 文案，不再手写 `rounded-[1.5rem] border border-[var(--platform-subpanel-border)] bg-[var(--platform-subpanel-fill)]` 静态封面面板或直接依赖底层 `ResolvedAssetImage`。
|
||||
18.7.9. 抓大鹅结果页物品详情五视角面板迁移到 `PlatformSubpanel radius="xl" padding="sm"` 并通过局部 `sm:p-5` 保留桌面间距；详情页只保留视角预览、缩略图切换和素材名称字段，不再手写 `platform-subpanel min-h-0 rounded-[1.5rem] p-3 sm:p-5`。
|
||||
18.7.10. RPG 暗色弹窗里的可选项按钮卡迁移到 `PlatformDarkOptionCard`；NPC 交易模式、交易物品行、赠礼候选、招募替换候选、角色素材工作室动作预览格、营地编组替换位按钮和角色聊天建议按钮已先迁移。业务页只传 selected、tone、点击回调和内容布局，不再重复写选中 / 未选中暗色卡片边框、底色、hover 和 disabled chrome；像素风 footer 按钮、强品牌动作按钮和含复杂禁用语义的动作按钮继续保留专用布局。
|
||||
18.7.11. 发布分享弹窗渠道 tile 按钮迁移到 `PlatformSubpanel as="button" interactive surface="flat"`；复制反馈状态、渠道枚举和品牌图标继续留在分享弹窗内。
|
||||
18.7.12. 平台入口创作类型弹层玩法卡片迁移到 `PlatformSubpanel as="button" surface="platform" radius="xl" padding="none"`；玩法图片蒙版、锁定 badge、标题副标题和分流回调继续由弹层组件持有。
|
||||
18.7.13. creation-agent 工作台聊天区外壳迁移到 `PlatformSubpanel radius="xl" padding="none"`；消息列表、上传预览、错误提示和输入区继续由工作台组件持有。
|
||||
18.7.14. 绑定手机号页左侧的“当前登录身份”提示块迁移到 `PlatformSubpanel as="div" radius="sm" padding="md"`；认证页只保留品牌说明、当前用户显示名和绑定流程，不再手写 `platform-subpanel` 信息块外壳。
|
||||
18.8. 平台标签编辑器迁移到 `PlatformTagEditor`；拼图、敲木鱼和抓大鹅结果页标签编辑已先迁移。后续标签编辑只把 parse / normalize 和保存语义留在业务页，新增输入状态、删除 chip、空态、AI 生成按钮和错误提示统一由 Module 承接。
|
||||
19. 个人中心充值、任务、兑换、邀请、支付结果等弹窗里的普通主动作按钮迁移到 `PlatformActionButton surface="profile"`；RPG 首页作品卡删除小动作、RPG 作品详情、RPG / 拼图 / 抓大鹅 / 跳一跳 / 敲木鱼 / 拼消消 / 宝贝识物 / 方洞 / 汪汪声浪 / 视觉小说 / 大鱼吃小鱼结果页、自定义世界实体目录小动作、生成结果恢复面板、通用生成页重试 / 中断动作、法律信息弹窗 footer、公共确认弹窗 footer、统一创作工作台、统一创作页壳层、拼图创作工作台、拼消消创作工作台、宝贝识物创作工作台、视觉小说创作工作台、汪汪声浪创作工作台、creation-agent 推荐回复、creative-agent 工作台、creative-agent 模板确认弹窗、创作中心错误重试、创作中心作品卡积分激励领取按钮、反馈页 header 返回、通用创作输入面板、认证表单、敲木鱼 fallback 返回、跳一跳结算、拼消消 runtime header / 结算弹窗和视觉小说 runtime 普通白底面板里的普通主动作 / 次动作 / 危险动作迁移到 `PlatformActionButton surface="platform"`；RPG 暗色弹窗 / 运行面板中的角色自定义 footer、生成 footer、地图切换确认、营地编组普通动作、角色聊天刷新动作、角色素材工作室本地 `ActionButton`，以及 RPG 大编辑器暗色面板内的保存 / 角色槽动作都迁移到 `PlatformActionButton surface="editorDark"`。若业务侧仍需要 `stopPropagation`、局部 tone 映射或内容排版差异，可以保留局部 `ActionButton` 包装层，但包装层本体应委托共享按钮，而不是继续直接渲染原生 `<button>`。统一创作工作台、统一创作页壳层、玩法创作工作台、结果页返回按钮和反馈页 header 返回使用 `tone="ghost"`，提交 / 生成 / 发布 / 保存按钮使用默认主动作，素材槽小按钮、作品卡角落小动作、拼图图片生成模式选择器触发器和白底面板行内动作使用 `size="xs"` 与 `shape="pill"`，积分激励领取这类密集卡片小动作使用 `size="xxs"` 并由局部卡片 class 保留响应式布局，暗色微型刷新动作使用 `size="xxs" shape="pill"`，左对齐回复 / 列表动作使用 `align="start"`，认证表单提交、验证码、第三方登录和邀请码提交按钮使用 `size="lg"` 保持 48px 高度，文件上传 label 使用 `asChild="label"` 保持上传语义；复制邀请、错误复制、完成复制和分享复制继续使用 `CopyFeedbackButton` 管状态，并通过 `actionSurface` 复用动作按钮外观。大鱼吃小鱼结果页资产工坊 footer、关卡主图 / 动作入口和场地背景生成这类白底平台动作也使用 `shape="pill" size="xs"`，深色 hero 返回 / 测试 / 发布按钮保留玩法品牌布局。后续带复制三态的按钮不改用普通 ActionButton，避免复制状态分支回流业务页；暗色可选项卡继续使用 `PlatformDarkOptionCard`，像素风发送按钮和强品牌动作继续保留专用布局。
|
||||
19.1. `CopyFeedbackButton` 支持 `actionShape`，用于在复用共享复制状态机时直接对齐 `PlatformActionButton` 的圆角外观；拼图广场详情 hero 的“分享作品”已使用 `actionSurface="editorDark" actionShape="pill"`，不再手写复制按钮 rounded / border / bg class。
|
||||
19.2. 拼图广场详情 hero 的返回、上一张 / 下一张关卡图入口迁移到 `PlatformIconButton variant="darkMini"`，修改作品和进入第 1 关迁移到 `PlatformActionButton`，分享动作继续使用 `CopyFeedbackButton` 但复用共享动作按钮 chrome；详情页只保留轮播、复制和跳转语义，不再手写 hero 区按钮壳。
|
||||
19.3. 个人中心充值商品卡里的“购买 / 处理中”胶囊暂保留局部 `span`，不直接套用 `PlatformActionButton`，避免在 `PlatformSubpanel as="button"` 内再嵌套交互按钮；待出现第二个同形态的非交互 action chip 后，再决定是否沉淀独立的共享展示基元。
|
||||
19.3.1. RPG 首页创作 / 草稿顶栏的钱包快捷入口迁移到同文件适配器 `TopbarWalletShortcutButton`，内部复用 `PlatformActionButton tone="accentSoft" shape="pill" size="xs"` 与 `PlatformIconBadge`；移动端和桌面端继续保留 `.platform-mobile-create-wallet-chip`、`.platform-desktop-create-wallet-chip` 和 `.platform-desktop-search` 兼容 class，承接移动端余额截断、桌面顶栏胶囊底色以及既有测试锚点。入口点击仍统一走 `openRechargeOrRewardCodeModal`，不把充值 / 兑换码平台分流逻辑改散到两个顶栏分支里。
|
||||
19.3.2. 个人中心昵称修改、账户充值、每日任务和兑换码四类标准头部弹窗迁移到 `UnifiedModal`；`UnifiedModal` 新增 `closeVariant`、`closeOnEscape`、`titleClassName` 和 `descriptionClassName`，用于在收口弹窗壳层时保留个人中心 `profile / profileCompact` 关闭按钮、居中浮层布局和标题层级。上述弹窗统一通过 `closeOnBackdrop={false}`、`closeOnEscape={false}` 保持原有交互语义，不把 backdrop / Escape 关闭行为悄悄带进个人中心；邀请、玩过作品等结构更复杂的二级弹层继续按同一壳层策略逐步迁移。
|
||||
19.3.3. 个人中心支付结果提示和支付确认遮罩迁移到 `UnifiedModal` 的 headerless 模式；`UnifiedModal` 新增 `showHeader`，用于在保留 `role="dialog"`、可访问名称、遮罩和 z-index 语义的同时，允许业务页自己排版 icon badge、轻量标题和正文。支付结果提示与确认遮罩统一使用 `showHeader={false}`、`showCloseButton={false}`、`closeOnBackdrop={false}`、`closeOnEscape={false}`，继续保持阻断式确认语义；业务页只保留图标、文案和按钮，不再手写 backdrop、dialog aria 和面板壳层。
|
||||
19.3.4. 个人中心移动端顶栏的“扫码”“打开设置”入口迁移到 `PlatformIconButton`；页面继续保留 `.platform-profile-header__icon-button` 局部 class 控制位置、尺寸和主题色，交互语义与可访问名称统一由共享按钮承接，不再在 `RpgEntryHomeView` 里手写图标按钮的 `type`、`aria-label` 和基础 chrome。
|
||||
19.3.5. 发现页分类筛选弹窗与个人中心扫码面板迁移到 `UnifiedModal`；分类筛选继续复用本地选项栅格和底部动作区样式，但 backdrop、dialog 语义、头部关闭入口和 `closeOnEscape={false}` 统一收口到共享壳层。扫码面板复用 `showHeader={false}` 模式保留深色自定义头部、摄像头 viewport 和状态提示，同时显式保持 `closeOnBackdrop={false}`、`closeOnEscape={false}`，确保不会把扫码中的资源清理语义改散到页面外层。
|
||||
19.3.6. 个人中心泥点账单弹窗迁移到 `UnifiedModal` 的 headerless 模式；共享壳层承接 `dialog` 语义、层级和关闭策略，账单弹窗继续保留自定义渐变面板、浮动关闭按钮、余额 badge、列表 / 空态 / 错误态布局以及 `closeOnBackdrop={false}`、`closeOnEscape={false}` 的原有交互，不再手写 `fixed inset-0` 遮罩壳层。
|
||||
19.3.7. 个人中心“玩过作品”面板迁移到 `UnifiedModal` 的 headerless 模式；共享壳层承接 `dialog` 语义、层级与关闭策略，面板继续保留 `PLAYED` kicker、总时长 badge、浮动关闭按钮、`可继续 / 玩过` 双分区、作品卡与空态布局，以及 `closeOnBackdrop={false}`、`closeOnEscape={false}` 的原有交互。存档入口仍留在同一个“玩过”面板内，不再回退成独立的 `SAVE ARCHIVE` / `ARCHIVE` 壳层。
|
||||
19.3.8. 个人中心邀请相关弹层中的 live 分支迁移到 `UnifiedModal` 的 headerless 模式；玩家社区与填邀请码继续保留浮动关闭按钮、居中标题、二维码卡片、邀请码表单 / 已填写空态和成功 / 失败提示，但 `dialog` 语义、层级与关闭策略统一由共享壳层承接。`community / redeem` 两条真实入口继续显式保持 `closeOnBackdrop={false}`、`closeOnEscape={false}`；历史 `invite` 分支暂不扩张能力面，只随同一壳层复用现状内容。
|
||||
19.3.9. 个人中心昵称旁的铅笔入口迁移到 `PlatformIconButton`；页面继续保留 `.platform-profile-edit-button` 局部 class 控制 1.45rem 紧凑尺寸、边框与浅色底，但按钮语义、默认 `type="button"` 和共享 icon chrome 统一由公共组件承接，不再在 `RpgEntryHomeView` 里手写原生图标按钮。
|
||||
19.3.10. RPG 首页推荐运行态卡片底部的点赞 / 分享 / 改造入口迁移到 `PlatformIconButton`；推荐卡继续保留 `.platform-recommend-work-meta__action*` 局部 class 控制透明圆角按钮尺寸、间距和玩法主题色，同时显式保留 `onPointerDown` / `onClick` 里的 `stopPropagation`，避免图标动作把推荐卡纵向拖拽切换误触发。后续任何耦合 swipe / drag 手势的图标动作都沿用“共享按钮承接语义，本地 class 保留视觉与手势隔离”的策略。验证命令：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "logged in recommend runtime preloads adjacent work previews and drag switches like video feed"`。
|
||||
19.3.11. 创作中心公开作品卡右上角的分享快按钮迁移到 `PlatformIconButton`；作品卡继续保留 `.creation-work-card__quick-action-button` 局部 class 承接卡片角落定位和尺寸，并显式保留 `stopPropagation`、关闭 swipe action、清理 `suppressOpenRef` 与分享回调顺序，避免右上角分享入口误触整卡打开或遗留左滑状态。验证命令：`npm run test -- src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx`。
|
||||
19.3.12. RPG 首页个人中心的统计卡、统计骨架、常用功能入口、设置行与法律信息入口抽离到 `src/components/platform-entry/PlatformProfilePrimitives.tsx`；`RpgEntryHomeView` 只继续保留账户数据、图片资源、点击回调和打开弹层的控制器，不再把这一组纯展示原子和个人中心页面编排混在同一个 7k+ 首页文件里。组件级验证新增 `src/components/platform-entry/PlatformProfilePrimitives.test.tsx`，并继续复用 `RpgEntryHomeView.recharge.test.tsx` 的个人中心集成断言。验证命令：`npm run test -- src/components/platform-entry/PlatformProfilePrimitives.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "mobile profile page matches the reference layout sections|profile stats cards are centered without update timestamp|profile page shows legal entries and hides archive shortcuts"`。
|
||||
19.3.13. RPG 首页个人中心的充值 / 钱包 / 每日任务 / 邀请 / 兑换码等商业与账户控制逻辑收口到 `src/components/platform-entry/usePlatformProfileCenterController.ts`；`RpgEntryHomeView` 仅保留个人中心展示、昵称头像编辑、扫码入口和页面级编排 / 交互，不再直接承接账户动作分流、商业状态派生和面板控制。该收口默认保持现有弹层与充值链路语义不变，避免在职责迁移时顺带扩张行为面。验证命令：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`。
|
||||
19.3.14. RPG 首页个人中心的“玩过 / 可继续”历史弹层抽到 `src/components/platform-entry/PlatformProfilePlayedWorksModal.tsx`；`RpgEntryHomeView` 不再内联 `SaveArchiveCard`、`ProfilePlayedWorksModal` 和旧的 `ProfileSaveArchivesModal`。当前真实产品语义已经把存档恢复并入“玩过”弹层的“可继续”分区，因此未连通的 `saveArchives` profile popup 分支一并删除，避免继续维护没有入口的独立壳层。组件级验证新增 `src/components/platform-entry/PlatformProfilePlayedWorksModal.test.tsx`，并继续复用 `RpgEntryHomeView.recharge.test.tsx` 的个人中心集成断言。验证命令：`npm run test -- src/components/platform-entry/PlatformProfilePlayedWorksModal.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`。
|
||||
19.3.15. 个人中心标准头部弹窗与白底副弹层壳层统一抽到 `src/components/platform-entry/PlatformProfileModalShell.tsx`；`PlatformProfileModalShell` 负责标准账户弹窗的 overlay、header、title、description、close variant 和 `closeOnBackdrop={false} / closeOnEscape={false}` 约束，`PlatformProfileSecondaryModalShell` 负责白底副弹层的 overlay、floating close、`bodyClassName="!p-0"` 和内容外壳。`RpgEntryHomeView` 内的昵称修改、账户充值、每日任务、兑换码、泥点账单与“玩过”弹层已接到共享壳层，页面不再重复手写个人中心弹窗的基础 chrome 与关闭策略。
|
||||
19.3.15.1. `PlatformProfileModalShell` 继续补齐标准 footer 插槽：壳层现已直接透传 `UnifiedModal.footer` 与 `footerClassName`，`RpgEntryHomeView.tsx` 的昵称修改弹窗不再把双按钮动作区塞在 body 末尾，而是改成标准 profile modal footer。后续个人中心里同类“表单 body + 底部双按钮动作区”弹窗，优先走 `PlatformProfileModalShell + footer`，不要把共享按钮再手写回内容区。
|
||||
19.3.15.2. `PlatformProfileModalShell` 的 footer 接法继续扩展到单 CTA 表单收尾：`PlatformProfileRewardCodeRedeemModal.tsx` 的兑换动作已迁到标准 profile footer，body 仅保留输入与反馈消息；后续个人中心里这种“输入表单 + 底部唯一主动作”弹窗，也优先复用壳层 footer，而不是把按钮继续塞在内容区。验证命令：`npx vitest run src/components/platform-entry/PlatformProfileModalShell.test.tsx src/components/platform-entry/PlatformProfileRewardCodeRedeemModal.test.tsx src/components/common/PlatformAssetPickerCard.test.tsx src/components/visual-novel-runtime/VisualNovelRuntimePanels.emptyState.test.tsx src/components/auth/AccountModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.16. RPG 首页个人中心的邀请好友 / 填邀请码 / 玩家社区三态弹层抽到 `src/components/platform-entry/PlatformProfileReferralModal.tsx`；组件统一复用 `PlatformProfileSecondaryModalShell` 承接居中白底浮层、floatingPlain 关闭按钮和成功 / 失败提示区，`RpgEntryHomeView` 不再内联邀请码规范化、社区二维码卡片和邀请用户头像行。组件级验证新增 `src/components/platform-entry/PlatformProfileReferralModal.test.tsx`，首页继续复用 `RpgEntryHomeView.recharge.test.tsx` 的邀请链路断言。验证命令：`npm run test -- src/components/platform-entry/PlatformProfileReferralModal.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "renders invite panel with shared profile content|submits redeem panel with the shared form shell|renders community QR panels|profile community shortcut shows reward subtitle and invited users|invite query opens redeem modal directly for logged in users|profile redeem invite query modal submits code after login"`、`npm run typecheck`。
|
||||
19.3.17. RPG 首页个人中心的账户充值弹层抽到 `src/components/platform-entry/PlatformProfileRechargeModal.tsx`；组件承接 Native 二维码生成、点数 / 会员 tab、套餐卡片、空态和错误重试，继续复用 `PlatformProfileModalShell` 与平台白底卡片 token，`RpgEntryHomeView` 不再内联 `useWechatNativeQrCode`、`RechargeProductCard` 和 `ProfileRechargeModal`。组件级验证新增 `src/components/platform-entry/PlatformProfileRechargeModal.test.tsx`，首页继续复用 `RpgEntryHomeView.recharge.test.tsx` 的充值入口与 Native 二维码断言。验证命令：`npm run test -- src/components/platform-entry/PlatformProfileRechargeModal.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "renders point products and forwards buy action|shows empty state when the selected tab has no products|profile recharge modal shows native qr code on desktop web by default|create tab wallet chip opens recharge when recharge entry is enabled"`、`npm run typecheck`。
|
||||
19.3.18. RPG 首页个人中心的泥点账单、每日任务和兑换码三类标准 profile 弹层分别抽到 `src/components/platform-entry/PlatformProfileWalletLedgerModal.tsx`、`src/components/platform-entry/PlatformProfileTaskCenterModal.tsx` 与 `src/components/platform-entry/PlatformProfileRewardCodeRedeemModal.tsx`；账单继续复用 `PlatformProfileSecondaryModalShell`，任务和兑换码继续复用 `PlatformProfileModalShell`，页面不再内联账单余额 badge、任务领取列表和兑换码输入提交实现。三者均新增组件级测试，并继续复用 `RpgEntryHomeView.recharge.test.tsx` 的真实入口断言。验证命令：`npm run test -- src/components/platform-entry/PlatformProfileWalletLedgerModal.test.tsx src/components/platform-entry/PlatformProfileTaskCenterModal.test.tsx src/components/platform-entry/PlatformProfileRewardCodeRedeemModal.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "renders ledger entries with shared balance presentation|retries from the shared error state|renders claimable tasks and forwards claim action|keeps incomplete tasks disabled|submits on button click and enter key|disables submit when the code is blank|opens wallet ledger modal from narrative coin card|profile daily task shortcut reflects task progress and claim updates|wallet ledger modal shows empty and error states|opens reward code modal from profile action on mobile|create tab wallet chip opens reward code when recharge entry is hidden"`、`npm run typecheck`。
|
||||
19.3.19. RPG 首页个人中心的支付结果提示、支付确认遮罩与扫码面板继续向共享组件收口：支付结果 / 确认中弹层统一抽到 `src/components/common/PlatformStatusDialog.tsx`，扫码面板统一抽到 `src/components/platform-entry/PlatformProfileQrScannerModal.tsx`；`RpgEntryHomeView` 仅保留支付状态映射、扫码打开关闭和结果写回，不再内联 `RechargePaymentResultModal`、`RechargePaymentConfirmationMask`、`ProfileQrScannerModal`、`BarcodeDetector` 启动逻辑和 profile 弹层壳层参数。组件级验证新增 `src/components/common/PlatformStatusDialog.test.tsx` 与 `src/components/platform-entry/PlatformProfileQrScannerModal.test.tsx`，首页继续复用 `RpgEntryHomeView.recharge.test.tsx` 的支付 / 扫码入口断言。验证命令：`npm run test -- src/components/common/PlatformStatusDialog.test.tsx`、`npm run test -- src/components/platform-entry/PlatformProfileQrScannerModal.test.tsx`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile recharge modal jumps to h5 payment on mobile web by default|profile recharge modal posts mini program payment request and reacts to success hash result|profile recharge modal releases submitting state and shows virtual payment failure detail|profile recharge modal eventually shows error text even when hashchange is not dispatched|profile recharge modal resumes virtual payment confirmation when pageshow returns with paid order|profile recharge modal blocks tab navigation while virtual payment confirmation is pending|profile scan action opens camera scanner instead of recharge panel"`、`npm run typecheck`。
|
||||
19.3.20. `PlatformStatusDialog` 继续扩展到 notice 场景：组件新增 header notice 布局、body content、close button、backdrop / Escape 关闭路径以及动作按钮样式透传；`PlatformEntryFlowShellImpl` 里的 `draftGenerationPointNotice` / `workNotFoundRecoveryDialog` 和 `RpgCreationEntityEditorShared.tsx` 里的 `EditorNoticeDialog` 已接入。创作入口泥点不足、作品不可用恢复和 RPG 大编辑器规则阻断提示不再各自维护 `UnifiedConfirmDialog` 壳层，只保留标题、正文、辅助提示和关闭回调。验证命令：`npm run test -- src/components/common/PlatformStatusDialog.test.tsx`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "bark battle form checks mud points before creating a draft|puzzle form checks mud points before creating a draft|match3d form checks mud points before creating a draft|direct missing public work detail shows unified dialog before returning home"`、`npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx -t "可扮演角色至少保留一个背景章节时使用统一提示弹窗|场景连接缺少可连接目标时使用统一提示弹窗|场景保存缺少主角色时使用统一提示弹窗"`、`npm run typecheck`。
|
||||
19.3.21. `PlatformStatusDialog` 继续收口规则阻断和搜索未命中提示：`CustomWorldEntityCatalog.tsx` 的 `minimum-playable` 规则阻断从删除确认分支中拆出，改由独立 `PlatformStatusDialog` 承接；`PlatformEntryFlowShellImpl` 的公开编号搜索弹层拆成“命中用户继续走 `UnifiedModal + PlatformSubpanel`”与“未找到结果改走 `PlatformStatusDialog`”两条分支。业务页不再让规则阻断提示和危险删除确认共用同一套 confirm config，也不再在搜索结果 modal 内同时维护用户信息和错误态两套内容布局。验证命令：`npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx -t "最后一个可扮演角色不可删除时使用平台状态弹窗"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "searching unmatched public work code shows not-found search result dialog|public code search shows public user summary in shared search result modal and clears it on close"`、`npm run typecheck`。
|
||||
19.3.22. 标准泥点消耗确认弹窗收口到 `src/components/common/PlatformMudPointConfirmDialog.tsx`；组件固定承接“确认消耗泥点 + 消耗 N 泥点”的同形态标题、正文骨架和确认 / 取消动作，业务页只保留点数、补充说明和确认回调。`PuzzleCreationWorkspace.tsx`、`Match3DCreationWorkspace.tsx`、`PuzzleResultView.tsx`、`Match3DResultView.tsx` 以及 `RpgCreationRoleAssetStudioModalImpl.tsx` 已迁移；其中角色形象生成 / 动作草稿生成继续通过自定义 title 和补充说明承接工坊语义，但不再各自拼接 `UnifiedConfirmDialog` 的相同文案和内容结构。后续同类泥点确认优先复用该 Module；像 runtime 道具确认、预计消耗区间确认这类节奏不同的弹层再单独评估是否扩展变体。
|
||||
19.3.23. 平台危险确认弹窗收口到 `src/components/common/PlatformDangerConfirmDialog.tsx`；组件固定承接“确认 / 取消 + 危险主动作”的标准骨架，并透传忙碌态、遮罩关闭策略、按钮文案和局部面板样式。`PlatformEntryFlowShellImpl.tsx` 的删除作品确认、`RpgCreationResultViewImpl.tsx` 的重新生成确认，以及 `CustomWorldEntityCatalog.tsx` 的删除角色 / 批量删除确认已迁移；业务页继续保留标题、说明文案和确认回调，不再各自拼接 `UnifiedConfirmDialog` 的危险按钮配置。后续删除、覆盖、清空等危险动作优先复用该 Module，再按需要补充更窄的语义 wrapper。
|
||||
19.3.24. 平台未保存离开确认弹窗收口到 `src/components/common/PlatformUnsavedLeaveConfirmDialog.tsx`；组件固定承接“继续编辑 + 确认离开”的标准骨架，并按 `platform / pixel` 两类确认风格兜底默认遮罩和面板样式。`RpgCreationEntityEditorShared.tsx` 中的关闭未保存修改确认、生成结果未保存退出确认和普通结果未保存退出确认已迁移；业务页只保留标题、确认按钮文案和未保存提示内容，不再各自拼接 `UnifiedConfirmDialog` 的 cancel/confirm 组合和重复壳层 class。
|
||||
19.3.25. 平台单按钮已读状态弹窗收口到 `src/components/common/PlatformAcknowledgeStatusDialog.tsx`；组件固定承接“状态提示 + 知道了”这一类单按钮确认已读语义，并透传 action surface / size / fullWidth / class、header、关闭路径和局部 panel 覆写。`BigFishResultView.tsx` 的发布失败提示、`RpgEntryHomeView.tsx` 的支付结果提示、`RpgCreationEntityEditorShared.tsx` 的编辑器 notice、`PlatformEntryFlowShellImpl.tsx` 的泥点提示 / 作品不可用 / 搜索未命中提示，以及 `CustomWorldEntityCatalog.tsx` 的“无法删除”阻断提示已迁移；业务页继续保留 status、标题、说明和关闭回调，不再各自手写 `PlatformStatusDialog` 的 `action={{ label: '知道了', onClick: onClose }}` 结构。
|
||||
19.3.26. profile 侧重复的 `error / loading / empty / content` 分支统一收口到 `src/components/common/PlatformAsyncStatePanel.tsx`；该 Module 只承接互斥状态切换，不承接需要和内容并存的 success / error banner。`PlatformProfileReferralModal.tsx`、`PlatformProfileWalletLedgerModal.tsx`、`PlatformProfilePlayedWorksModal.tsx`、`PlatformProfileTaskCenterModal.tsx` 与 `PlatformProfileRechargeModal.tsx` 已接入。后续 profile 或白底 panel 侧若只是同形态互斥异步状态，优先传 slot 复用该骨架，不再把 `loading skeleton` / `empty state` / `retry error` 直接写回业务页。
|
||||
19.3.27. `PlatformSegmentedTabs` 支持 `layout="scroll"` 承接横向可滚动 tab rail；`CustomWorldCreationStartCard.tsx`、`CustomWorldWorkTabs.tsx` 和 `RpgEntryHomeView.tsx` 的排行 tab、分类筛选项已接入。共享组件先统一 `tablist/tab` 语义、滚动容器和基础交互；当同一类皮肤在首页、作品架、分类筛选或个人中心内重复出现时，再沉淀到 `src/components/common/PlatformSegmentedTabPresets.tsx` 的薄 preset，避免业务页继续复制 `itemClassName`，也避免把一次性玩法配置项抽成过胖公共组件。
|
||||
19.3.28. `PixelCloseButton.tsx` 保持为 RPG 语义薄封装，底层改为复用 `src/components/common/PlatformModalCloseButton.tsx` 的 `variant="pixel"`；共享 close button 统一承接像素风基础 chrome、`absolute / inline` placement、默认 `title=label` 和可选 `stopPropagation` 冒泡拦截，`CharacterChatModal.tsx` 与 `MapModal.tsx` 的 inline / absolute 真实 importer 已补测试。后续需要像素风关闭按钮时优先使用 `PlatformModalCloseButton variant="pixel"` 或继续复用 `PixelCloseButton` 语义壳，不再手写本地 close button。
|
||||
19.3.29. 平台入口创作前置泥点阻断提示抽到 `src/components/platform-entry/PlatformDraftGenerationPointNoticeDialog.tsx`，并用 `DraftGenerationPointNotice` union（`insufficient-points` / `balance-load-failed`）承接业务真相；`PlatformEntryFlowShellImpl.tsx` 不再直接拼 `PlatformAcknowledgeStatusDialog` 的标题、说明和 amber icon 条件分支。后续若只是平台入口里的泥点前置检查提示，优先继续扩展这个局部语义 wrapper；不要急着在 `common/` 抽泛化 `BlockingNoticeDialog`，避免把底层状态弹窗的样式透传再次包装一层。
|
||||
19.3.30. `PlatformSegmentedTabs` 继续承接首页 / 结果页里剩余的横向 rail 与二选一切换：`RpgEntryHomeView.tsx` 的 discover channel bar、移动端 / 桌面端分类 chip rail，`CustomWorldEntityCatalog.tsx` 的 `RESULT_TABS` sticky rail，以及 `PlatformProfileRechargeModal.tsx` 的“泥点充值 / 会员卡”切换条已迁移。`CustomWorldEntityCatalog` 通过 `ReactNode label` 保留“标题 + count”两行内容；`RpgEntryHomeView`、创作入口、作品架和个人中心里稳定复用的频道下划线、创作 pill rail、二列 option segment 皮肤沉淀到 `PlatformSegmentedTabPresets`，业务页只保留 items、activeId 和回调。同类切换在测试里应优先按 `role="tablist" / "tab"` 查询，不再把这些切换项当普通 button；一次性玩法配置项继续直接组合 `PlatformSegmentedTabs`。
|
||||
19.3.31. 简单泥点确认流的开关状态机收口到 `src/components/common/useMudPointConfirmController.ts`；该 hook 只承接 `open / requestOpen / close / confirm` 四个动作，`confirm` 固定先关弹窗再执行回调，不持有 `points / title / description / confirmDisabled` 之类业务字段。`PuzzleCreationWorkspace.tsx`、`Match3DCreationWorkspace.tsx` 和 `Match3DResultView.tsx` 的两个批量素材面板已接入；`PuzzleCreationWorkspace` 仍在业务页判断“只有 `aiRedraw` 才弹确认”。`PuzzleResultView.tsx` 与 `RpgCreationRoleAssetStudioModalImpl.tsx` 这类要么节奏不同、要么携带 pending payload 的场景先保留本地状态机，不把 hook 扩成泛型动作路由器。
|
||||
19.3.32. 标准平台 modal header 的关闭入口继续统一到 `PlatformModalCloseButton variant="platformIcon"`；结果页 / 工具页里重复的白底 portal 弹窗壳层进一步收口到 `src/components/common/PlatformToolModalShell.tsx`，由它统一承接平台主题 overlay、白底 remap panel、标准 header/body/footer spacing、关闭按钮和遮罩 / Escape 关闭策略。`PuzzleResultView.tsx` 的关卡详情 / 发布弹窗、`Match3DResultView.tsx` 的封面 / 发布工具弹窗，以及 `PuzzleHistoryAssetPickerDialog.tsx` 的历史素材弹窗已迁移；`UnifiedModal` 新增 `ariaLabel` 以支持“可见标题随业务对象变化、可访问名称保持固定”的场景。像素风 runtime、drawer collapse、玩法规则面板和运行态专属 overlay 继续保留本地 close 语义，不把 `PlatformToolModalShell` 硬塞进非平台白底工具弹窗场景。
|
||||
19.3.33. `PlatformAsyncStatePanel` 从 profile modal 扩展到作品架：`CustomWorldCreationHub.tsx` 的作品架主体现在也统一通过 `loadingState / emptyState / children` 三个 slot 切换，保留外层 error + 重试提示不并入共享状态骨架。后续白底作品架或列表 panel 若只是互斥的 `loading / empty / content`，优先直接复用 `PlatformAsyncStatePanel`，不要再在业务 JSX 中重复拼 skeleton 和“当前筛选下没有内容”的分支。验证命令：`npx vitest run src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx`、`npm run check:encoding`。
|
||||
19.3.34. `CopyFeedbackButton.tsx` 的 `actionSurface` 分支继续向共享按钮收口：带平台动作外观的复制按钮现在直接组合 `PlatformActionButton`，仅保留 `pill` 分支继续复用 `PlatformPillBadge` 风格。复制反馈按钮不再手动调用 `getPlatformActionButtonClassName` 拼平台按钮基础 chrome；后续同类“复制状态机 + 平台动作按钮”组合也优先走 `CopyFeedbackButton + PlatformActionButton`，不要在业务页或按钮组件里重新混写图标、文案、aria 和 class。验证命令：`npm run test -- src/components/common/CopyFeedbackButton.test.tsx src/components/common/PlatformActionButton.test.tsx`。
|
||||
19.3.35. 详情页头部动作组合收口到 `src/components/common/PlatformDetailTopbar.tsx` 与 `src/components/common/PlatformDetailShareActions.tsx`；前者只承接“返回 / 标题 / 右侧动作槽位”的 topbar 骨架，并允许 `pill` / `icon` 两种返回按钮语义，后者只承接“前置 badge 区块 + 作品号复制 + 分享复制”这一组稳定动作，不吸收详情页自己的标题、摘要、作者、封面轮播或业务 CTA。`RpgEntryWorldDetailView.tsx` 已接入完整的 overlay 版动作组合，统一世界主题 badge、作者、发布时间、作品号和分享入口；`PlatformWorkDetailView.tsx` 已接入 icon topbar 与 solid 版作品号复制动作，并继续保留公开详情页自己的顶部 icon 分享入口和分享反馈提示。后续同类详情页若只是复用返回按钮骨架、标题居中布局或作品号 / 分享动作排列，优先直接组合这两个 Module，不要把整页 detail header 抽成巨型配置对象。验证命令：`npx vitest run src/components/common/PlatformDetailTopbar.test.tsx src/components/common/PlatformDetailShareActions.test.tsx src/components/rpg-entry/RpgEntryWorldDetailView.test.tsx src/components/platform-entry/PlatformWorkDetailView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check -- src/components/common/PlatformDetailTopbar.tsx src/components/common/PlatformDetailTopbar.test.tsx src/components/common/PlatformDetailShareActions.tsx src/components/common/PlatformDetailShareActions.test.tsx src/components/rpg-entry/RpgEntryWorldDetailView.tsx src/components/platform-entry/PlatformWorkDetailView.tsx`。
|
||||
19.3.36. `PlatformToolModalShell` 继续承接 RPG 结果页发布检查弹窗；`RpgCreationResultActionBar.tsx` 只保留发布检查、封面预览、封面设置和发布动作语义，不再直接维护 `createPortal`、平台主题 overlay、白底 remap panel、header close、body/footer spacing 和遮罩关闭逻辑。后续结果页 / 工具页里同形态的白底 portal 弹窗优先迁移到 `PlatformToolModalShell`；编辑器大壳、暗色 runtime overlay 和需要专属布局的面板继续保留局部 shell。
|
||||
19.3.37. `PlatformToolModalShell` 继续承接方洞结果页图片槽弹窗；`SquareHoleResultView.tsx` 的封面 / 背景 / 形状 / 洞口图片查看与历史选择弹窗只保留当前图、上传、AI 生成和历史素材选择语义，不再直接维护 `createPortal`、主题 overlay、白底 remap panel、header close 和滚动 body。该弹窗使用 `ariaLabel` 保持“封面图查看 / 背景图查看”等固定可访问名称，历史生成区继续由 `PlatformAssetPickerGrid` 承接读取、错误和空态。
|
||||
19.3.38. `PlatformToolModalShell` 继续承接视觉小说结果页素材选择弹窗；`VisualNovelAssetPickerDialog` 只保留本地上传、AI 图片生成、历史素材读取、错误提示和素材选择回调，不再直接维护 `createPortal`、平台主题 overlay、白底 remap panel、header close 和滚动 body。视觉小说音频生成弹窗需要保留生成中禁止关闭，实体编辑器弹窗需要保留编辑 footer，本轮先不混入同一提交，后续逐个迁移并补对应交互测试。
|
||||
19.3.35. 白底 / 暗色面板里的轻量空态和普通 CTA 继续按共享组件收口：`PuzzleResultView.tsx` 的“还没有可编辑的拼图草稿”、`RpgCreationAssetDebugPanel.tsx` 的“没有可诊断项”、`VisualNovelEntityGrid` 的空实体列表、`AccountModal.tsx` 里账号安全分区的“无安全限制 / 无登录设备 / 无操作记录”以及 `LoginScreen.tsx` 的“当前登录入口暂不可用”都改为 `PlatformEmptyState`；`Match3DResultView.tsx` 的引用素材列表直接交给 `PlatformAssetPickerGrid` 自己处理空态。`AdventureEntityModal.tsx` 的私聊按钮、`InventoryPanel.tsx` 的锻造 / 合成按钮、`RpgAdventurePanel.tsx` 底部 `队伍 / 背包 / 换一换 / 退出聊天` 按钮，以及 `RpgAdventurePanelOverlays.tsx` 里的“查看任务 / 保存并退出”都改为 `PlatformActionButton surface="editorDark"`，业务页只贴回局部 sky / emerald / runtime 皮肤。后续白底子面板里的只读空态优先使用 `PlatformEmptyState surface="subpanel"`；暗色编辑 / 运行面板里的普通动作优先使用 `PlatformActionButton surface="editorDark"`，若还需要 stopPropagation、局部字号或图标排版，可保留薄包装层，但不要再回退到原生 `<button>` 基础 chrome。验证命令：`npm run test -- src/components/puzzle-result/PuzzleResultView.test.tsx src/components/rpg-creation-result/RpgCreationAssetDebugPanel.test.tsx src/components/AdventureEntityModal.test.tsx src/components/InventoryPanel.test.tsx src/components/auth/AccountModal.test.tsx src/components/rpg-runtime-panels/RpgAdventurePanel.test.tsx src/components/rpg-runtime-panels/RpgAdventurePanel.npcChat.test.tsx src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformActionButton.test.tsx`、`npm run check:encoding`。
|
||||
19.3.36. `VisualNovelEntityGrid` 的空态也继续收口到 `PlatformEmptyState surface="subpanel" size="inline"`；角色 / 场景 / 剧情阶段共用这一网格组件后，白底实体列表里的“暂无角色 / 暂无场景 / 暂无剧情阶段”等同构空态不再回退成 `PlatformSubpanel`。同时，`RpgCreationRoleAssetStudioModalImpl.tsx` 与 `RpgCreationEntityEditorShared.tsx` 保留局部 `ActionButton` 语义壳，但按钮本体已统一委托给 `PlatformActionButton surface="editorDark"`，只在包装层补最小的 `stopPropagation`、tone 映射和局部 class 适配。后续类似“暗色编辑器局部包装按钮”优先沿用这种薄包装模式，不再直接手写原生 `<button>` 基础 chrome。验证命令：`npm run test -- src/components/visual-novel-result/VisualNovelResultView.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformActionButton.test.tsx`、`npm run check:encoding`。
|
||||
19.3.37. 暗色编辑器里的局部动作按钮继续往共享 `editorDark` button 收口：`CustomWorldNpcVisualEditor.tsx` 的本地 `ActionButton` 和 `SkillEffectPreview.tsx` 的“重新预览”按钮都改为委托 `PlatformActionButton surface="editorDark"`。这类局部包装仍可保留 `stopPropagation`、图标布局、`tone` 映射和少量局部视觉覆写，但按钮本体不再直接使用原生 `<button>` 承接边框 / 底色 / hover / disabled chrome。验证命令：`npm run test -- src/components/common/PlatformActionButton.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.38. `PlatformAsyncStatePanel` 继续从 profile / 作品架扩展到首页公开分区：`RpgEntryHomeView.tsx` 的移动端排行、发现页寓教于乐 / 默认公开 feed、桌面首页“今日游戏 / 推荐”、桌面发现页寓教于乐 / 默认公开 feed，以及“我的创作”分区都统一改成 `loadingState / emptyState / children` 三个 slot 切换。页面继续把 `platformError` 保留在状态壳外层，让错误提示可以和内容并存；`recommend runtime`、分类筛选和其它含二级筛选 / 运行态语义的分支暂不并入这次收口。后续首页、作品架或白底列表若只是纯 `loading / empty / content` 互斥状态，优先直接复用 `PlatformAsyncStatePanel`，不要再把空态与读取态分支手写回业务 JSX。验证命令：`npx vitest run src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.39. 桌面首页里的轻量可点击扁平行统一收口到 `src/components/common/PlatformNavigableListItem.tsx`；该 Module 只承接 `button + 左侧主内容 + 右侧 affordance` 的结构、默认 `type="button"` 和 `leading / trailing` 插槽，不承接卡片封面、复杂摘要或 runtime 专属交互。`RpgEntryHomeView.tsx` 的搜索结果行、桌面“最近作品”、桌面“最近浏览”以及桌面“今日游戏”趋势行已接入。教培 promo card、分类卡片、世界卡和 runtime 列表项继续保留各自语义，等出现更多同构 desktop flat row 再逐步扩覆盖面。验证命令：`npx vitest run src/components/common/PlatformNavigableListItem.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.40. `PlatformNavigableListItem` 继续从桌面首页扩展到 profile 设置行：`src/components/platform-entry/PlatformProfilePrimitives.tsx` 里的 `ProfileSettingsRow` 现已统一委托共享 `button + leading + trailing` 骨架，保留本地 `platform-profile-settings-row` class 承接行间分隔、icon 胶囊和字号微调。后续 profile / 账户中心里同类“左图标标题 + 右箭头”的轻量导航行，优先直接复用 `PlatformNavigableListItem`，不要再回退成原生 `<button>` 手写布局。验证命令：`npx vitest run src/components/platform-entry/PlatformProfilePrimitives.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.41. `PlatformAsyncStatePanel` 继续补齐首页分类分支：`RpgEntryHomeView.tsx` 的移动端“发现 -> 分类”、桌面发现页“分类”以及桌面首页“作品分类”模块都改成共享状态壳承接外层 `loading / empty / content` 切换，分类控制条与排序按钮继续保留在内容 slot 中；筛选后无结果的“当前筛选下没有作品。”也统一改由内层 `PlatformAsyncStatePanel` 切换，不再在三处 JSX 中各自手写空态分支。后续同类“外层数据可用性 + 内层筛选空态”面板优先沿用这套双层状态壳，不要回退成嵌套 ternary。验证命令：`npx vitest run src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.42. `PlatformAsyncStatePanel` 继续从首页扩展到公共素材网格、runtime 面板和账号子区块：`PlatformAssetPickerGrid` 现已统一用共享状态壳承接 `loading / empty / content`，但继续把 `error` banner 留在外层，以保持“错误提示可与内容或加载态并存”的原语义；`VisualNovelSavePanel.tsx` 的存档列表，以及 `AccountModal.tsx` 里的“安全状态 / 当前登录设备 / 账号操作记录”三个子区块也都改成各自使用 `PlatformAsyncStatePanel`。后续白底列表、素材选择器或账号子面板若只是标准互斥异步状态，优先按这三种接法复用共享状态壳，不再把读取态和空态分支手写回组件内部。验证命令：`npx vitest run src/components/common/PlatformAssetPickerCard.test.tsx src/components/visual-novel-runtime/VisualNovelRuntimePanels.emptyState.test.tsx src/components/auth/AccountModal.test.tsx src/components/platform-entry/PlatformProfileRewardCodeRedeemModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.43. 轻量按钮漏网继续向共享按钮收口：`PlatformTagEditor.tsx` 的标签 chip 删除入口已改成紧凑 `PlatformIconButton`，保留 `label="删除标签 ${tag}"`、透明背景和原 chip 高度，不再手写裸 `<button>`；`RpgEntryCharacterSelectView.tsx` 两处重复的“返回”按钮已统一沉到文件内 `CharacterSelectBackButton`，底层委托 `PlatformActionButton surface="editorDark"`，保留原有暗色视觉与文案。后续同类“局部 chip 删除按钮”优先先用 `PlatformIconButton` 压缩尺寸和视觉；暗色轻量返回 / 返回上一级 CTA 则优先用 `PlatformActionButton surface="editorDark"` 包一层局部 helper，不再复制原生 `<button>` class。验证命令：`npx vitest run src/components/common/PlatformTagEditor.test.tsx src/components/rpg-entry/RpgEntryCharacterSelectView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.44. 暖色生成页顶部返回入口开始沉淀共享壳：`GenerationProgressHero.tsx` 新增 `GenerationHeaderBackButton`，统一承接 `ArrowLeft + 文案 + 透明背景` 的暖色生成页返回按钮骨架，并底层复用 `PlatformIconButton variant="darkMini"`；`CustomWorldGenerationView.tsx` 与 `BarkBattleGeneratingView.tsx` 已接入，继续保留各自 `backLabel`、禁用态和局部暖色文字样式。后续同类生成页、等待页或暖色 hero 顶栏若只是“左箭头 + 返回文案”的轻量返回入口，优先复用这个小组件，不再各自手写 `ArrowLeft`、透明按钮背景和字号间距。验证命令：`npx vitest run src/components/CustomWorldGenerationView.test.tsx src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx src/components/common/PlatformIconButton.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.45. 白底 / 浅色结果页与工作台顶部的轻量返回入口继续收口到 `src/components/common/PlatformBackActionButton.tsx`；该 Module 固定承接 `PlatformActionButton tone="ghost" size="xs"` 上的 `ArrowLeft + 返回文案` 骨架，并只暴露 `compact / regular` 两档尺寸，分别覆盖紧凑结果页 header 与标准白底结果页顶栏。当前 `PuzzleResultView.tsx`、`SquareHoleResultView.tsx`、`Match3DResultView.tsx`、`VisualNovelResultView.tsx` 四个结果页已接入 `variant="compact"`，`PuzzleClearResultView.tsx`、`JumpHopResultView.tsx`、`WoodenFishResultView.tsx` 三个结果页已接入 `variant="regular"`，`BabyObjectMatchResultView.tsx` 继续使用紧凑款并保留 `className="px-3"` 贴合原横向留白。暖色生成页顶部返回入口继续走 `GenerationHeaderBackButton`，`BigFishResultView.tsx` 这类 dark hero / 强品牌 special case 继续保留 `PlatformIconButton variant="darkMini"` 路线，不强行并入同一个白底返回按钮基元。后续白底结果页、浅色工作台或普通 platform 顶栏里若只是“左箭头 + 返回”轻量返回入口，优先直接复用 `PlatformBackActionButton`，只在局部补尺寸和少量外边距，不再各页重复手写 ghost button class。
|
||||
19.3.46. `PlatformNavigableListItem` 继续从桌面 flat row 扩展到首页公开列表里的排行行与分类行；`RpgEntryHomeView.tsx` 的 `PlatformRankingItem` 和 `PlatformCategoryGameItem` 现在都统一委托共享 `button + leading + body + trailing` 骨架，同时保留原有 `platform-ranking-item__*`、`platform-category-game-item__*` 局部 class 承接封面尺寸、标题摘要、公开 badge、metric 和右侧 `试玩 / 进入` affordance。后续首页、发现页或 profile 侧同类“封面 + 文本主体 + 右侧动作提示”的浅色导航行，优先先尝试复用 `PlatformNavigableListItem` 并把局部视觉挂在业务 class 上，不要为了这类 row 再回退成原生 `<button>` 手写布局；但教培 promo card、runtime 列表项和带复杂手势的卡片仍保留本地语义，不把共享行骨架扩成万能作品卡。验证命令：`npx vitest run src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.47. `PlatformDarkModalFooter` 继续从标准双按钮 footer 扩展到 detail / confirm 收尾：`NpcModals.tsx` 的交易详情单按钮 footer 与 `MapModal.tsx` 的场景切换确认 footer 已接入共享 dark footer frame，分别保留“关闭”单 CTA 和“取消 / 确认前往”双 CTA 的业务语义、按钮 tone 与禁用态。后续 dark / pixel modal 里若只是标准底部分隔线 + 常规动作区排布，优先直接复用 `PlatformDarkModalFooter`，即使只有单个按钮也不再手写 `flex justify-end`；但像 `SquareImageCropModal.tsx` 这类白底弹窗 footer、sticky 工作台 footer 和运行态 HUD 工具条继续留在各自语义壳层，不强行混到 dark footer 抽象里。验证命令：`npx vitest run src/components/NpcModals.test.tsx src/components/MapModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.48. `RpgEntryHomeView.tsx` 里的分类筛选工具条继续从页面内重复 JSX 收口到 `src/components/common/PlatformFilterToolbar.tsx`；该 Module 只承接“筛选按钮 + 横向 tabs + 排序按钮”的结构排布，暴露 `mobile / desktop` 两种 layout 以覆盖移动端 divider + 独立排序行和桌面端同排布局差异，但不持有分类列表、筛选状态、空态或排序逻辑。当前 RPG 首页分类区已接入，后续若其它白底列表页也出现同构的筛选壳层，可直接复用这套薄结构组件；若场景只是在单页内局部重复、接口会为了兼容业务差异不断膨胀，则优先退回文件内 helper，不把 `common` 扩成假的“万能筛选条”。验证命令：`npx vitest run src/components/common/PlatformFilterToolbar.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.49. `SquareImageCropModal.tsx` 的白底 modal 壳层与 footer 已收口到 `src/components/common/UnifiedModal.tsx`；`UnifiedModal` 为此只薄补了 `titleId` 与 `closeIcon` 透传，继续由调用方决定 `closeOnBackdrop`、`closeOnEscape`、`portal`、header/footer 样式和按钮内容，不额外掺入 profile 业务语义，也不让 `common/` 反向依赖 `platform-entry/`。`SquareImageCropModal.tsx` 继续保留裁剪拖拽、pointer capture、保存禁用态与两列等宽 footer 行为，只把 header / body / footer 外壳交给共享 modal 承接。后续 `common` 级白底工具弹窗若只是标准标题栏 + 内容区 + footer 按钮排布，优先先看 `UnifiedModal` 是否够用，再决定是否需要新的薄壳；不要为了一个弹窗把 `PlatformProfileModalShell` 之类带页面语义的壳层倒灌回 `common`。验证命令：`npx vitest run src/components/common/SquareImageCropModal.test.tsx src/components/common/UnifiedModal.test.tsx src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.50. `CreativeImageInputPanel.tsx` 里内嵌的 white tool modal 继续并回 `UnifiedModal` 体系：参考图预览与主图预览都改成直接复用 `src/components/common/UnifiedModal.tsx`，继续保留各自 `max-w` / `max-h` 节奏、点击遮罩关闭与紧凑 header；移除图片确认改成复用 `src/components/common/UnifiedConfirmDialog.tsx`，不再在 panel 内手写 `platform-modal-backdrop + platform-modal-shell + 两列按钮`。这次没有新增 `PlatformImagePreviewModal`，因为当前预览弹窗差异还只在尺寸和文案层，继续直接组合 `UnifiedModal` 更深、更稳。后续 `common` 级图片面板若出现同类“预览大图 + 单标题栏 + 关闭按钮”弹窗，优先先复用 `UnifiedModal` 并把尺寸/文案留在调用方；只有当至少两到三个调用点开始重复同一套 preview body/header adapter 时，再考虑补新的薄壳。验证命令：`npx vitest run src/components/common/CreativeImageInputPanel.test.tsx src/components/common/UnifiedModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.51. `PlatformReportDialog.tsx` 与 `PublishShareModal.tsx` 共同的工具信息弹窗壳层继续收口到 `src/components/common/PlatformUtilityInfoModal.tsx`；该 Module 只承接平台主题 overlay、白底 panel，以及 body / footer 的基础间距与标准 footer frame，底层继续委托 `UnifiedModal.tsx`，不吸收报告字段列表、分享正文、复制逻辑、渠道按钮或品牌图标这些业务内容。`PlatformReportDialog.tsx` 继续保留 `PlatformInfoBlock` 字段列表与 joined report copy 行为，`PublishShareModal.tsx` 继续保留分享文案、主复制动作和渠道按钮网格；后续 `common` 级白底工具信息弹窗若只是重复这套“共享 modal 外壳 + 业务正文 / footer 内容”的骨架，优先复用 `PlatformUtilityInfoModal`，只有当正文编排或 footer 交互明显偏离时才回退到直接组合 `UnifiedModal`。验证命令：`npx vitest run src/components/common/PlatformUtilityInfoModal.test.tsx src/components/common/PlatformReportDialog.test.tsx src/components/common/PublishShareModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.52. profile 白底 modal 里的摘要头、列表骨架和内容行继续沉到 `src/components/common/PlatformProfileSummaryHeader.tsx`、`src/components/common/PlatformProfileSkeletonList.tsx` 与 `src/components/common/PlatformProfileContentRow.tsx`；这三个 Module 只承接 `kicker + title + badge` 的摘要层次、重复 skeleton 列表行，以及 `PlatformSubpanel` 上的 `div / button` 内容行语义，不持有账单金额、任务进度、邀请用户信息、充值商品结构或 modal 状态切换逻辑。`PlatformProfileWalletLedgerModal.tsx`、`PlatformProfileTaskCenterModal.tsx`、`PlatformProfilePlayedWorksModal.tsx`、`PlatformProfileReferralModal.tsx` 与 `PlatformProfileRechargeModal.tsx` 已接入；后续 profile 副弹层若只是重复这三类白底内容骨架，优先继续复用这组薄组件，不再把 skeleton、摘要头和 row chrome 写回各自 modal。验证命令：`npx vitest run src/components/common/PlatformProfileModalContent.shared.test.tsx src/components/platform-entry/PlatformProfileTaskCenterModal.test.tsx src/components/platform-entry/PlatformProfileWalletLedgerModal.test.tsx src/components/platform-entry/PlatformProfilePlayedWorksModal.test.tsx src/components/platform-entry/PlatformProfileReferralModal.test.tsx src/components/platform-entry/PlatformProfileRechargeModal.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.53. 认证入口白底弹窗壳层收口到 `src/components/auth/PlatformAuthModalShell.tsx`；该 Module 只承接平台主题 overlay、`platform-auth-card`、标准标题栏、关闭按钮、点击遮罩关闭和禁用 Escape 的认证弹窗策略，不持有短信 / 密码登录、重置密码、邀请码规范化、法律协议或错误状态。`LoginScreen.tsx` 与 `RegistrationInviteModal.tsx` 已接入，业务组件只保留表单状态与提交流程。后续认证域新增同形态白底弹窗时优先复用该壳层；账号安全详情和绑定手机号这类布局差异较大的卡片先独立评估，不把 auth shell 扩成万能认证容器。验证命令：`npx vitest run src/components/auth/PlatformAuthModalShell.test.tsx src/components/auth/AuthGate.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.54. 账号 / 运行态 / onboarding 这轮继续分场景收口：`AccountModal.tsx` 的设置入口外层 overlay 与 auth card 壳层复用 `PlatformAuthModalShell`，并通过 `overlaySpacing`、`overlayStyle`、`showHeader` 和尺寸透传保留账号弹窗的 safe-area 与 direct account 唯一 dialog 语义；拼图运行态新增 `src/components/puzzle-runtime/PuzzleRuntimeModalShell.tsx`，只在 `puzzle-runtime` 内承接道具确认、设置、退出改造提示、失败弹窗和通关结算的 overlay / dialog / footer / button 骨架，原图查看、拖拽 ghost、飞行动画和全屏 runtime 容器不纳入 modal 收口；抓大鹅与跳一跳结算弹窗分别在 `Match3DRuntimeShell.tsx` 和 `JumpHopRuntimeShell.tsx` 内提取本地结算壳层 / summary / actions，保留玩法视觉身份；拼图 onboarding 首屏继续保留沉浸式全屏体验，只把登录保存覆盖层迁入 `UnifiedModal`，保持无关闭按钮、禁用遮罩关闭和禁用 Escape。后续 runtime 专属弹窗优先先抽玩法目录内薄壳；只有出现跨玩法稳定同构接口时再上升到 `common/`，不要把 `PlatformToolModalShell` 强行套到像素 / 游戏运行态 overlay。验证命令：`npm run test -- src/components/auth/AccountModal.test.tsx src/components/auth/PlatformAuthModalShell.test.tsx src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleOnboardingView.test.tsx src/components/match3d-runtime/Match3DRuntimeShell.test.tsx src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3.55. 拼图 / 拼消消运行态的剩余阻断层继续按玩法目录局部收口：`src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleRuntimeBlockingOverlay.tsx` 只承接平台入口里拼图“正在准备下一关”的短暂阻断层，继续复用 `UnifiedModal` 的遮罩、dialog 语义和关闭禁用策略，但不把这类运行态等待面板直接提升到 `common/`；`src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.tsx` 则在玩法目录内新增 `PuzzleClearRuntimeOverlayShell`、`PuzzleClearRuntimePendingOverlay` 与 `PuzzleClearRuntimeSettlementDialog`，把 `!activeRun` 的等待层和 `level_cleared / finished / level_failed` 的结算层统一成一条本地结构线，同时保留拼消消自己的视觉和动作分流。拖拽 ghost、swap flight、补牌 / 消除动画、全屏 runtime 容器和其它强玩法视觉层不算旧 modal 债务，不跟这条线混收。验证命令：`npm run test -- src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleRuntimeBlockingOverlay.test.tsx src/components/platform-entry/PlatformEntryFlowShellImpl.test.ts src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
19.3. creative-agent 首页的侧边栏菜单、账号入口、开启新对话、我的创作、首页激励 CTA 和 prompt suggestion 按钮迁移到 `PlatformIconButton` / `PlatformActionButton`；首页继续保留 `creative-agent-home__*` 本地 class 承接透明顶栏、抽屉和品牌化胶囊视觉，不把视觉回收和语义收口绑成一次大改。`Beta` 徽标和历史记录纯文本行暂保留本地实现，等出现更多同构轻量列表行后再评估是否抽新的共享 row primitive。
|
||||
19.4. 大鱼吃小鱼结果页 hero 的返回入口迁移到 `PlatformIconButton variant="darkMini"`，测试 / 发布动作迁移到 `PlatformActionButton surface="editorDark"`；结果页只保留测试运行、发布提交和文案状态语义，不再手写 hero 顶栏按钮壳。
|
||||
19.4.1. 大鱼吃小鱼结果页的发布失败弹层迁移到 `src/components/common/PlatformStatusDialog.tsx`；`PlatformStatusDialog` 补充自定义图标、可访问标签和动作按钮样式透传后，`BigFishResultView` 不再保留 `BigFishResultErrorModal` 内联的 `UnifiedConfirmDialog + PlatformIconBadge` 组合。结果页只保留失败文案和关闭回调，发布失败的状态图标、遮罩、白底面板和“知道了”主动作统一由共享状态弹层承接。验证命令：`npm run test -- src/components/common/PlatformStatusDialog.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx`、`npm run typecheck`。
|
||||
20. 平台方形上传入口和紧凑虚线新增入口迁移到 `PlatformUploadTile`，上传后的图片预览迁移到 `PlatformUploadPreviewCard`；反馈页上传凭证入口 / 预览、敲木鱼工作台新增功德词条入口、通用创作图片面板的提示词参考图缩略图、抓大鹅封面编辑参考图缩略图、通用输入 Composer 已选参考图条、creation-agent 已选参考图条和拼图结果页关卡引用图横条已先迁移。方形缩略图使用默认 `layout="square"`，横向“已选择参考图 / 文件名 / 素材名 / 移除”条使用 `layout="inline"`；只读引用图条不传 `onRemove`，避免公共组件额外渲染删除入口。后续继续收口结果页素材上传、工作台参考图上传、紧凑虚线新增入口等上传 / 动作块时，业务页只保留文件选择、预览数组、预览回调、删除回调、校验逻辑或新增回调，上传方块外观、主副文案、缩略图壳、预览按钮、标题行、横向已选条、移除按钮和禁用态统一由 Module 承接；工具栏中的小图标上传仍继续使用 `PlatformIconButton asChild="label"`。
|
||||
21. 图片编辑面板中的白底胶囊开关迁移到 `PlatformPillSwitch`；通用创作图片面板和抓大鹅封面编辑的 `AI重绘` 已先迁移。后续同类开关只保留受控布尔值和状态变更回调，switch 输入语义、轨道、圆点、白底浮层和禁用态统一由 Module 承接。
|
||||
22. 设置面板、结果页运行配置和工作台白底配置项中的整行开关迁移到 `PlatformToggleRow`；视觉小说结果页、runtime 设置面板和拼消消创作工作台 AI 生成底图开关已先迁移。后续整行配置项只保留字段写回和可选点击动作，不再重复开关行 chrome、checkbox class 或状态 pill。
|
||||
22.1. RPG 创作侧标准 dark header / footer 动作继续向共享按钮收口：`RpgCreationRoleAssetStudioModalImpl.tsx` 的 header“关闭”、`RpgCreationEntityEditorShared.tsx` 的 footer“取消”、`RpgCreationRoleAssetStudioFooter.tsx` 的“保存到当前角色”都改为委托 `PlatformActionButton surface="editorDark"`。局部壳层只继续保留 `stopPropagation`、tone 映射、布局和极少量字号/宽度贴合；标准暗色编辑器里的 close / cancel / save CTA 不再各自手写原生 `<button>` 基础 chrome。
|
||||
22.2. RPG runtime overlay 里的标准 dark CTA 和可点击 dark row 继续向共享原子收口：`RpgAdventurePanelOverlays.tsx` 的 goal panel“知道了”、任务详情里的“领取任务 / 返回交付”、任务完成提示里的“打开任务日志”都改为委托 `PlatformActionButton surface="editorDark"`；设置面板里的“运行统计”入口改为 `PlatformSubpanel as="button" surface="dark"`。像素风 choice button、HUD launcher、奖励物品格和输入 composer 这类 runtime 专属控件继续保留独立语义，不并回普通平台按钮。
|
||||
22.3. NPC dark modal footer 与暗色明细空态继续向共享原子收口：`NpcModals.tsx` 里的交易 / 赠礼 / 招募弹窗 footer 按钮和物品详情“关闭”按钮都改为委托 `PlatformActionButton surface="editorDark"`，交易右侧“请选择一件物品”提示改为 `PlatformEmptyState surface="editorDark"`；`CharacterInfoShared.tsx` 里的 `BuildContributionDetailPanel` 空明细也改为 `PlatformEmptyState surface="editorDark"`。数量 stepper、赠礼 / 招募 option card、标签强度按钮这类带更强业务语义的控件继续保留局部实现。
|
||||
22.4. 暗色 / 像素 modal 的标准 footer 布局统一收口到 `src/components/common/PlatformDarkModalFooter.tsx`；该 Module 只承接 dark footer 的顶部分隔线、padding 和常见动作区排布，不承接“取消 / 确认”业务语义。`NpcModals.tsx` 的交易 / 赠礼 / 招募 footer、`SelectionCustomizationModals.tsx` 的 `SelectionModal` footer、`RpgAdventurePanelOverlays.tsx` 的 goal panel footer、`InventoryItemViews.tsx` 的详情 footer wrapper，以及 `CompanionCampModal.tsx` 的“营地气氛”内容 footer 已接入。sticky 工作台 footer、正文里的单独 CTA 收尾和 runtime HUD 工具条继续保留局部布局；后续 dark / pixel modal 若只是同构 footer chrome，优先直接复用这个 Module，不再重复手写 `border-t border-white/10 + px/py + justify-end gap-*` 组合。验证命令：`npx vitest run src/components/common/PlatformDarkModalFooter.test.tsx src/components/CompanionCampModal.test.tsx src/components/NpcModals.test.tsx src/components/SelectionCustomizationModals.test.tsx src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/common/PlatformReportDialog.test.tsx src/components/platform-entry/PlatformErrorDialog.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformReportDialog.test.tsx src/components/platform-entry/PlatformTaskCompletionDialog.test.tsx`
|
||||
- `npm run test -- src/components/common/CopyFeedbackButton.test.tsx src/components/puzzle-gallery/PuzzleGalleryDetailView.test.tsx`
|
||||
- `npm run test -- src/components/creative-agent/CreativeAgentHome.test.tsx src/components/auth/BindPhoneScreen.test.tsx`
|
||||
- `npm run test -- src/components/creative-agent/CreativeAgentHome.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx`
|
||||
- `npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx -t "renders generated formal previews with accurate status copy"`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`
|
||||
- `npm run test -- src/components/common/UnifiedConfirmDialog.test.tsx`
|
||||
- `npm run test -- src/components/common/useCopyFeedback.test.tsx`
|
||||
- `npm run test -- src/components/common/CopyFeedbackButton.test.tsx`
|
||||
- `npm run test -- src/components/common/CopyCodeButton.test.tsx`
|
||||
- `npm run test -- src/components/common/PublishShareModal.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/platform-entry/PlatformEntryCreationTypeModal.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/common/CopyFeedbackButton.test.tsx src/components/common/CopyCodeButton.test.tsx src/components/rpg-entry/RpgEntryWorldDetailView.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/CharacterInfoShared.test.tsx src/components/AdventureEntityModal.test.tsx`
|
||||
- `npm run test -- src/components/CharacterInfoShared.test.tsx src/components/AdventureEntityModal.test.tsx -t "BuildContributionDetailPanel|技能详情静态标签"`
|
||||
- `npm run test -- src/components/CharacterInfoShared.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformEmptyState.test.tsx -t "CharacterSkillsList|supports dark compact subpanel cards"`
|
||||
- `npm run test -- src/components/CharacterInfoShared.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/AdventureEntityModal.test.tsx -t "物品空态|技能详情静态标签"`
|
||||
- `npm run test -- src/components/AdventureEntityModal.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "主分区|最近回响|supports dark compact subpanel cards"`
|
||||
- `npm run test -- src/components/AdventureEntityModal.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "私聊和队友收束|tinted dark information panels"`
|
||||
- `npm run test -- src/components/InventoryPanel.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformStatusMessage.test.tsx -t "背包文书|背包工坊|supports dark compact subpanel cards|supports editor dark surface"`
|
||||
- `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "可扮演角色技能动作状态|supports dark compact subpanel cards"`
|
||||
- `npm run test -- src/components/CharacterDetailModal.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx`
|
||||
- `npm run test -- src/components/CharacterPanel.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx`
|
||||
- `npm run test -- src/components/CharacterPanel.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "角色面板详情静态信息|tinted dark information panels"`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/BackstoryArchive.test.tsx src/components/AffinityStatusCard.test.tsx`
|
||||
- `npm run test -- src/components/MapModal.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformOverlayBadge.test.tsx src/components/common/PlatformSlotBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformQuantityBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformIconBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/rpg-runtime-panels/RpgAdventurePanel.test.tsx src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx`
|
||||
- `npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx -t "quest offer accept button reuses the shared accepted-quest follow-up chain"`
|
||||
- `npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx src/components/common/PlatformPillBadge.test.tsx -t "quest offer accept button|supports dark RPG badge tones"`
|
||||
- `npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "adventure statistics panel|supports dark compact subpanel cards"`
|
||||
- `npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx src/components/common/PlatformQuantityBadge.test.tsx -t "quest offer accept button|quest reward strip|quest completion notice|battle reward modal|supports dark compact subpanel cards|supports dark RPG badge tones|renders a dark bottom-right quantity badge"`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "wallet ledger|profile played modal summary"`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile recharge modal trusts per-product first bonus display after points recharge"`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile community shortcut shows reward subtitle and invited users"`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "confirms virtual payment after returning without hash result|releases submitting state after cancelled wechat pay result"`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/CopyFeedbackMessage.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformStatusMessage.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformRuntimeStatusToast.test.tsx src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx src/components/wooden-fish-runtime/WoodenFishRuntimeShell.test.tsx src/components/square-hole-runtime/SquareHoleRuntimeShell.test.tsx src/components/edutainment-runtime/BabyLoveDrawingRuntimeShell.test.tsx`
|
||||
- `npm run test -- src/components/CharacterChatModal.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformDarkOptionCard.test.tsx`
|
||||
- `npm run test -- src/components/CompanionCampModal.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformDarkOptionCard.test.tsx`
|
||||
- `npm run test -- src/components/CompanionCampModal.test.tsx src/components/common/PlatformMediaFrame.test.tsx`
|
||||
- `npm run test -- src/components/SelectionCustomizationModals.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/common/PlatformProgressBar.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformStatusMessage.test.tsx src/components/creation-agent/CreationAgentWorkspace.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformStatusMessage.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx -t "场景图片保存后会同步更新编辑页和场景列表"`
|
||||
- `npm run test -- src/components/common/PlatformEmptyState.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformEmptyState.test.tsx src/components/visual-novel-runtime/VisualNovelRuntimePanels.emptyState.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformEmptyState.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx -t "可扮演角色空态复用暗色平台空态"`
|
||||
- `npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx src/components/common/PlatformEmptyState.test.tsx -t "settings save-disabled hint|dark editor dashed empty state"`
|
||||
- `npm run test -- src/components/NpcModals.test.tsx -t "NPC 弹窗空态复用暗色平台空态"`
|
||||
- `npm run test -- src/components/NpcModals.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "NPC 交易静态信息卡|supports dark compact subpanel cards"`
|
||||
- `npm run test -- src/components/rpg-runtime-panels/RpgAdventurePanel.questOffer.test.tsx -t "quest offer accept button reuses the shared accepted-quest follow-up chain|quest log empty state reuses dark PlatformEmptyState chrome"`
|
||||
- `npm run test -- src/components/common/PlatformAssetPickerCard.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformActionButton.test.tsx`
|
||||
- `npm run test -- src/components/platform-entry/PlatformEntryFlowShellImpl/PuzzleOnboardingView.test.tsx src/components/common/PlatformActionButton.test.tsx src/components/common/platformActionButtonModel.test.ts`
|
||||
- `npm run test -- src/components/common/platformActionButtonModel.test.ts src/components/common/PlatformActionButton.test.tsx src/components/SelectionCustomizationModals.test.tsx src/components/CompanionCampModal.test.tsx src/components/MapModal.test.tsx src/components/CharacterChatModal.test.tsx`
|
||||
- `npm run test -- src/components/unified-creation/shared/PuzzleImageModelPicker.test.tsx src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/common/PlatformActionButton.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformIconButton.test.tsx`
|
||||
- `npm run test -- src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformIconButton.test.tsx`
|
||||
- `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformIconButton.test.tsx`
|
||||
- `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformActionButton.test.tsx`
|
||||
- `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformActionButton.test.tsx src/components/common/platformActionButtonModel.test.ts`
|
||||
- `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformPillBadge.test.tsx src/components/common/CopyCodeButton.test.tsx`
|
||||
- `npm run test -- src/components/platform-entry/PlatformWorkDetailView.test.tsx src/components/common/PlatformStatusMessage.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformIconBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformIconBadge.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx -t "shows publish failures in a dismissible modal"`
|
||||
- `npm run test -- src/components/common/PlatformIconBadge.test.tsx src/components/common/CreativeImageInputPanel.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformIconBadge.test.tsx src/components/game-canvas/GameCanvasEntityLayer.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformIconBadge.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformIconButton.test.tsx src/components/common/CreativeImageInputPanel.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformUploadTile.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformUploadTile.test.tsx src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformUploadPreviewCard.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformIconButton.test.tsx src/components/common/PlatformUploadPreviewCard.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformUploadPreviewCard.test.tsx src/components/common/CreativeImageInputPanel.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformUploadPreviewCard.test.tsx src/components/creative-agent/CreativeAgentInputComposer.test.tsx src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformIconButton.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformUploadPreviewCard.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillSwitch.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformToggleRow.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformFieldLabel.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx src/components/edutainment-creation/BabyObjectMatchWorkspace.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformFieldLabel.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformFieldLabel.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformFieldLabel.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformFieldLabel.test.tsx src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx src/components/unified-creation/workspaces/JumpHopCreationWorkspace.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx src/components/CustomWorldResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/wooden-fish-result/WoodenFishResultView.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx src/components/edutainment-creation/BabyObjectMatchWorkspace.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/common/PlatformToggleRow.test.tsx src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx src/components/unified-creation/workspaces/JumpHopCreationWorkspace.test.tsx`
|
||||
- `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformEmptyState.test.tsx`
|
||||
- `npm run test -- src/components/creative-agent/CreativeAgentInputComposer.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/creative-agent/CreativeAgentHome.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformStatusMessage.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/common/CreativeImageInputPanel.test.tsx`
|
||||
- `npm run test -- src/components/common/CreativeImageInputPanel.test.tsx src/components/common/PlatformFieldLabel.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile nickname modal"`
|
||||
- `npm run test -- src/components/common/PlatformTextField.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile community shortcut|profile redeem invite"`
|
||||
- `npm run test -- src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformFieldLabel.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile daily task"`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "profile recharge modal shows native qr code"`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "profile played modal|profile page keeps save archives inside played stats panel"`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/platform-entry/PlatformEntryFlowShellImpl.test.ts`
|
||||
- `npm run test -- src/components/rpg-runtime-shell/RpgRuntimeStageRouter.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "wallet ledger"`
|
||||
- `npm run test -- src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformIconButton.test.tsx`
|
||||
- `npm run test -- src/components/creative-agent/CreativeAgentTemplateConfirmPanel.test.tsx src/components/common/PlatformTextField.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/common/PlatformTagEditor.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/SelectionCustomizationModals.test.tsx src/components/CharacterChatModal.test.tsx`
|
||||
- `npm run test -- src/components/SelectionCustomizationModals.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/auth/CaptchaChallengeField.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformMediaFrame.test.tsx`
|
||||
- `npm run test -- src/components/auth/AuthGate.test.tsx src/components/auth/AccountModal.test.tsx src/components/auth/BindPhoneScreen.test.tsx src/components/auth/CaptchaChallengeField.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformFieldLabel.test.tsx`
|
||||
- `npm run test -- src/components/platform-entry/PlatformFeedbackView.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformFieldLabel.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx src/components/common/PlatformTextField.test.tsx src/components/common/PlatformEmptyState.test.tsx -t "reward code|invite query|profile redeem invite|daily task"`
|
||||
- `npm run test -- src/components/common/PlatformSegmentedTabs.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx src/components/match3d-result/Match3DResultView.test.tsx src/components/creative-agent/CreativeAgentTemplateConfirmPanel.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformSegmentedTabs.test.tsx src/components/auth/AuthGate.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformInfoBlock.test.tsx src/components/platform-entry/PlatformErrorDialog.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformInfoBlock.test.tsx src/components/bark-battle-creation/BarkBattleResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformStatGrid.test.tsx src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/edutainment-result/BabyObjectMatchResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx src/components/bark-battle-creation/BarkBattleResultView.test.tsx src/components/edutainment-creation/BabyObjectMatchWorkspace.test.tsx src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx`
|
||||
- `npm run test -- src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx src/components/common/PlatformPillBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/wooden-fish-result/WoodenFishResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/creative-agent/CreativeAgentWorkspace.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx`
|
||||
- `npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx src/components/common/PlatformPillBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillBadge.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "wallet ledger|profile played modal summary"`
|
||||
- `npm run test -- src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx src/components/CustomWorldGenerationView.test.tsx src/components/common/PlatformPillBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/CreativeAudioInputPanel.test.tsx src/components/common/PlatformPillBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformProgressBar.test.tsx src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/CustomWorldResultView.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx src/components/CustomWorldGenerationView.test.tsx src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/common/CreativeAudioInputPanel.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/wooden-fish-result/WoodenFishResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/creation-agent/CreationAgentWorkspace.test.tsx`
|
||||
- `npm run test -- src/components/NpcModals.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformStatusMessage.test.tsx`
|
||||
- `npm run test -- src/components/NpcModals.test.tsx src/components/common/PlatformDarkOptionCard.test.tsx`
|
||||
- `npm run test -- src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx src/components/common/PlatformDarkOptionCard.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/bark-battle-creation/BarkBattleResultView.test.tsx`
|
||||
- `npm run test -- src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformStatGrid.test.tsx`
|
||||
- `npm run test -- src/components/jump-hop-result/JumpHopResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/jump-hop-result/JumpHopResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformEmptyState.test.tsx`
|
||||
- `npm run test -- src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx`
|
||||
- `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/visual-novel-runtime/VisualNovelRuntimePanels.emptyState.test.tsx src/components/visual-novel-runtime/VisualNovelRuntimeShell.test.tsx`
|
||||
- `npm run test -- src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/creative-agent/CreativeAgentTemplateConfirmPanel.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformStatGrid.test.tsx`
|
||||
- `npm run test -- src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformMediaFrame.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/creative-agent/CreativeAgentTemplateConfirmPanel.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryWorldDetailView.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformFieldLabel.test.tsx`
|
||||
- `npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformFieldLabel.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformSubpanel.test.tsx src/components/puzzle-gallery/PuzzleGalleryDetailView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/puzzle-gallery/PuzzleGalleryDetailView.test.tsx`
|
||||
- `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformSubpanel.test.tsx -t "作品封面上传|tinted dark information panels"`
|
||||
- `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformPillBadge.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/edutainment-result/BabyObjectMatchResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/jump-hop-result/JumpHopResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/big-fish-result/BigFishResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformMediaFrame.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`
|
||||
- `npm run test -- src/components/wooden-fish-result/WoodenFishResultView.test.tsx src/components/common/PlatformSubpanel.test.tsx src/components/common/PlatformMediaFrame.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformMediaTileGrid.test.tsx src/components/jump-hop-result/JumpHopResultView.test.tsx src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformTagEditor.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx src/components/wooden-fish-result/WoodenFishResultView.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformTextField.test.tsx src/components/common/PlatformTagEditor.test.tsx`
|
||||
- `npm run test -- src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformEmptyState.test.tsx src/components/common/PlatformTextField.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformPillSwitch.test.tsx src/components/common/CreativeImageInputPanel.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformModalCloseButton.test.tsx`
|
||||
- `npm run test -- src/components/common/UnifiedModal.test.tsx src/components/common/PlatformModalCloseButton.test.tsx src/components/common/UnifiedConfirmDialog.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformModalCloseButton.test.tsx src/components/SelectionCustomizationModals.test.tsx`
|
||||
- `npm run test -- src/components/common/squareImageCropModel.test.ts`
|
||||
- `npm run test -- src/components/platform-entry/PlatformEntryFlowShellImpl.test.ts`
|
||||
- `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx`
|
||||
- `npm run test -- src/components/CustomWorldResultView.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/useRpgEntryAgentDraftRestore.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "direct missing public work detail"`
|
||||
- `npm run test -- src/components/rpg-creation-asset-studio/RpgCreationRoleAssetStudioModal.test.tsx`
|
||||
- `npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx`
|
||||
- `npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx src/components/common/PlatformEmptyState.test.tsx`
|
||||
- `npm run test -- src/components/big-fish-result/BigFishResultView.test.tsx src/components/common/PlatformStatusMessage.test.tsx`
|
||||
- `npm run test -- src/components/auth/AuthGate.test.tsx`
|
||||
- `npm run test -- src/components/auth/AuthGate.test.tsx src/components/common/PlatformModalCloseButton.test.tsx`
|
||||
- `npm run test -- src/components/auth/AccountModal.test.tsx`
|
||||
- `npm run test -- src/components/auth/AccountModal.test.tsx src/components/common/PlatformSubpanel.test.tsx`
|
||||
- `npm run test -- src/components/common/CreativeImageInputPanel.test.tsx`
|
||||
- `npm run test -- src/components/unified-creation/workspaces/JumpHopCreationWorkspace.test.tsx src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx`
|
||||
- `npm run test -- src/components/puzzle-result/PuzzleResultView.test.tsx`
|
||||
- `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`
|
||||
- `npm run test -- src/components/jump-hop-result/JumpHopResultView.test.tsx src/components/wooden-fish-result/WoodenFishResultView.test.tsx`
|
||||
- `npm run test -- src/components/puzzle-clear-result/PuzzleClearResultView.test.tsx src/components/edutainment-result/BabyObjectMatchResultView.test.tsx`
|
||||
- `npm run test -- src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx src/components/edutainment-creation/BabyObjectMatchWorkspace.test.tsx`
|
||||
- `npm run test -- src/components/visual-novel-creation/VisualNovelAgentWorkspace.test.tsx`
|
||||
- `npm run test -- src/components/visual-novel-result/VisualNovelResultView.test.tsx`
|
||||
- `npm run test -- src/components/bark-battle-creation/BarkBattleConfigEditor.test.tsx src/components/bark-battle-creation/BarkBattleResultView.test.tsx`
|
||||
- `npm run test -- src/components/unified-creation/UnifiedCreationPage.test.tsx`
|
||||
- `npm run test -- src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx`
|
||||
- `npm run test -- src/components/square-hole-result/SquareHoleResultView.test.tsx src/components/common/PlatformModalCloseButton.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformActionButton.test.tsx src/components/common/PlatformStatusMessage.test.tsx src/components/unified-creation/shared/PuzzleHistoryAssetPickerDialog.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformAssetPickerCard.test.tsx src/components/unified-creation/shared/PuzzleHistoryAssetPickerDialog.test.tsx src/components/square-hole-result/SquareHoleResultView.test.tsx src/components/visual-novel-result/VisualNovelResultView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformAssetPickerCard.test.tsx src/components/CustomWorldEntityEditorModal.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformActionButton.test.tsx src/components/common/platformActionButtonModel.test.ts`
|
||||
- `npm run test -- src/components/creative-agent/CreativeAgentInputComposer.test.tsx src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/common/PlatformIconButton.test.tsx`
|
||||
- `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx -t "保存修改|保存角色"`
|
||||
- `npm run test -- src/components/wooden-fish-runtime/WoodenFishRuntimeShell.test.tsx src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx src/components/puzzle-clear-runtime/PuzzleClearRuntimeShell.test.tsx`
|
||||
- `npm run test -- src/components/creation-agent/CreationAgentWorkspace.test.tsx src/components/common/PlatformActionButton.test.tsx src/components/common/platformActionButtonModel.test.ts`
|
||||
- `npm run test -- src/components/creative-agent/CreativeAgentWorkspace.test.tsx src/components/creative-agent/CreativeAgentTemplateConfirmPanel.test.tsx`
|
||||
- `npm run test -- src/components/CustomWorldGenerationView.test.tsx src/components/common/PlatformActionButton.test.tsx`
|
||||
- `npm run test -- src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/platform-entry/PlatformFeedbackView.test.tsx src/components/common/PlatformActionButton.test.tsx`
|
||||
- `npm run test -- src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/common/PlatformActionButton.test.tsx src/index.test.ts`
|
||||
- `npm run test -- src/components/common/PlatformUploadTile.test.tsx src/components/platform-entry/PlatformFeedbackView.test.tsx`
|
||||
- `npm run test -- src/components/common/PlatformUploadPreviewCard.test.tsx src/components/common/PlatformUploadTile.test.tsx src/components/platform-entry/PlatformFeedbackView.test.tsx`
|
||||
- `npm run test -- src/components/CustomWorldEntityEditorModal.test.tsx -t "场景编辑器会在场景内展示槽位化多幕配置并保存"`
|
||||
- `rg -n "window\\.confirm|window\\.alert" src/components src/services src/hooks -g '*.tsx' -g '*.ts'`
|
||||
- 涉及 JSX 迁移时同步运行对应页面交互测试。
|
||||
@@ -1,30 +0,0 @@
|
||||
# 【前端架构】Profile Dashboard Presentation 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`RpgEntryHomeView.tsx` 的“我的数据”、钱包 chip 和“玩过”弹窗共用一批展示规则：泥点数量压缩、累计时长固定小时展示、单作品游玩时长压缩、作品类型标签和作品 ID 兜底。原先这些规则散在页面 **Implementation** 内，导致格式口径只能靠 UI 集成测试间接保护。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/rpg-entry/rpgEntryProfileDashboardPresentation.ts`，作为个人数据展示 **Module**。该 **Module** 的 **Interface** 收口为：
|
||||
|
||||
- `buildProfileDashboardPresentation(dashboard)`：统一生成钱包余额、钱包文案、累计时长文案和已玩数量文案。
|
||||
- `formatDashboardCount(value)`：统一泥点和计数压缩规则。
|
||||
- `formatTotalPlayTimeHours(playTimeMs)`：统一“累计游戏时长”固定小时口径。
|
||||
- `formatCompactPlayTime(playTimeMs)`：统一“玩过”单作品紧凑时长。
|
||||
- `formatPlayedWorkType(value)` 与 `formatPlayedWorkId(work)`：统一“玩过”列表里的玩法标签和作品号兜底。
|
||||
|
||||
`RpgEntryHomeView.tsx` 只消费这些 presentation 函数，保留卡片、弹窗和点击处理。个人数据展示规则的 **Locality** 转移到该 **Module** 与纯测试，后续修改计数、时长或作品类型标签不再穿透页面 JSX。
|
||||
|
||||
## 约定
|
||||
|
||||
- `formatDashboardCount` 与公开作品卡片的 `formatCompactCount` 不合并，二者展示口径不同。
|
||||
- “累计游戏时长”固定以小时展示，避免个人数据卡在分钟 / 天之间跳动。
|
||||
- “玩过”列表当前仍按历史契约用 `profileId || worldKey` 展示作品号；若后端未来下发 `publicWorkCode`，应在此 **Module** 改口径。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/rpg-entry/rpgEntryProfileDashboardPresentation.test.ts`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
- 针对变更文件执行 ESLint
|
||||
@@ -1,31 +0,0 @@
|
||||
# 【前端架构】Profile Funds ViewModel 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`RpgEntryHomeView.tsx` 原先直接维护钱包账单来源文案、金额正负号、账单余额兜底、充值价格、充值商品主值和会员摘要文案。这些规则散在页面 **Implementation** 内，且已与 `ProfileWalletLedgerEntry.sourceType` 契约产生漂移：后端可返回 `puzzle_author_incentive_claim`，页面没有对应中文 label，会把原始枚举值外显给用户。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/rpg-entry/rpgEntryProfileFundsViewModel.ts` 作为个人资金展示 **Module**。该 **Module** 的 **Interface** 收口为：
|
||||
|
||||
- `getWalletLedgerSourceLabel(sourceType)`：统一账单来源中文文案，补齐 `puzzle_author_incentive_claim`。
|
||||
- `formatWalletLedgerAmount(amountDelta)`：统一账单金额正负号。
|
||||
- `buildWalletLedgerPresentation(ledger, fallbackBalance)`：统一余额兜底与账单行 presentation。
|
||||
- `formatRechargePrice(priceCents)` 与 `buildRechargeProductValueLabel(product)`：统一充值商品价格与主值文案。
|
||||
- `buildMembershipLabel(membership, formatTime)`：统一会员摘要文案，并保留页面现有时间格式 Adapter。
|
||||
|
||||
`RpgEntryHomeView.tsx` 只消费该 **Module** 输出，保留弹窗布局、支付流程、微信渠道和轮询副作用。资金展示规则的 **Locality** 收口到纯函数测试，后续新增账单来源或调整价格 / 会员文案时不再穿透页面 JSX。
|
||||
|
||||
## 约定
|
||||
|
||||
- 未知账单来源仍保留原始 sourceType 兜底，避免新后端枚举被空白吞掉。
|
||||
- 账单余额继续沿用既有口径：有账单时取第一条 `balanceAfter`，无账单时使用外部 fallback balance。
|
||||
- 本次只收展示 **Interface**，不迁移支付确认、微信跳转、订单轮询或弹窗状态。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/rpg-entry/rpgEntryProfileFundsViewModel.test.ts`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "wallet ledger|profile recharge modal shows native qr code"`
|
||||
- 针对变更文件执行 ESLint
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,29 +0,0 @@
|
||||
# 【前端架构】Profile Task ViewModel 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`RpgEntryHomeView.tsx` 的“每日任务”卡片与任务弹窗共用同一批展示规则：任务优先级、可领取 / 未完成选择、进度 clamp、奖励兜底、状态标签和按钮文案。原先这些规则散在巨型页面 **Implementation** 中，UI JSX 既要渲染，又要知道任务状态排序和兜底口径。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/rpg-entry/rpgEntryProfileTaskViewModel.ts`，作为每日任务展示模型 **Module**。该 **Module** 的 **Interface** 收口为：
|
||||
|
||||
- `selectProfileTaskCenterTasks(tasks)`：统一任务中心只展示一条可操作任务，按 claimable / incomplete 优先级并保持原始顺序。
|
||||
- `selectProfileTaskCardTask(tasks)`：统一任务卡兜底顺序，先可操作，再 claimed，再非 disabled。
|
||||
- `buildProfileTaskCardSummary(center)`：统一任务卡的奖励、阈值、进度百分比与动作文案。
|
||||
- `buildProfileTaskProgressLabel(task)`、`getProfileTaskStatusLabel(status)`、`getProfileTaskClaimButtonLabel(task, isClaiming)`：统一任务弹窗中的进度、状态和按钮文案。
|
||||
|
||||
`RpgEntryHomeView.tsx` 只消费这些 ViewModel 函数，保留弹窗、按钮和点击处理。每日任务展示规则的 **Locality** 转移到 ViewModel **Module** 与纯测试，后续新增任务状态或修改展示优先级不再穿透 UI。
|
||||
|
||||
## 约定
|
||||
|
||||
- 任务中心只露出当前最需要用户处理的一条任务。
|
||||
- 任务进度必须按 `0..threshold` clamp，避免异常后端进度撑破卡片进度条。
|
||||
- `pause` / `claim` 等副作用仍留在页面和后端 client；ViewModel 只做展示派生。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/rpg-entry/rpgEntryProfileTaskViewModel.test.ts`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
- 针对变更文件执行 ESLint
|
||||
@@ -1,40 +0,0 @@
|
||||
# 【前端架构】Public Gallery ViewModel 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`RpgEntryHomeView.tsx` 同时承担首页、发现、分类、排行、搜索和公开作品卡片渲染。公开作品的 category 分组、跨来源去重、搜索归一化、作品号匹配、时间戳解析和列表排序原本都放在页面巨型 **Implementation** 中，导致公开作品规则与 JSX 交错，新增玩法时难以判断该改页面、卡片还是平台入口规则。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts`，作为公开作品 ViewModel **Module**。该 **Module** 的 **Interface** 收口为：
|
||||
|
||||
- `buildPublicGalleryCardKey(entry)`：复用平台公开作品身份规则，补齐 jump-hop / wooden-fish 等玩法 key。
|
||||
- `buildPublicCategoryGroups(featuredEntries, latestEntries)`：统一去重、标签兜底和分类排序。
|
||||
- `getPlatformPublicEntries(featuredEntries, latestEntries)` / `getAllPlatformPublicEntries(featuredEntries, latestEntries)`：统一公开作品合并规则。
|
||||
- `getPlatformSearchableWorkIds(entry)`、`filterPlatformWorkSearchResults(entries, keyword)` 与 `isExactPublicWorkCodeSearch(entries, keyword)`：统一搜索归一化、compact code 匹配和排序。
|
||||
- `parsePlatformEntryTimestamp(value)` / `getPlatformWorldTimestamp(entry)`：统一兼容 ISO 与后端 seconds.microsZ 时间戳。
|
||||
- `filterTodayPublishedEntries(entries)`：统一“今日游戏”本地自然日筛选。
|
||||
- `getPlatformWorldLikeCount(entry)` / `getPlatformWorldPlayCount(entry)` / `getPlatformWorldRemixCount(entry)`、`buildPlatformRankingEntries(entries, tab)` 与 `getPlatformRankingMetricValue(entry, tab)`：统一公开卡片指标读取、排行 Tab 排序与取值。
|
||||
- `DEFAULT_PLATFORM_CATEGORY_KIND_FILTER`、`DEFAULT_PLATFORM_CATEGORY_SORT_MODE`、`PLATFORM_CATEGORY_KIND_FILTERS`、`PLATFORM_CATEGORY_SORT_OPTIONS`、`getPlatformCategoryKindFilterOption(kindFilter)`、`getPlatformCategorySortOption(sortMode)` 与 `getNextPlatformCategorySortMode(sortMode)`：统一分类频道的筛选 / 排序选项、默认值、label 兜底和排序循环。
|
||||
- `getPlatformCategoryKindFilter(entry)`、`matchesPlatformCategoryKindFilter(entry, kindFilter)`、`sortPlatformCategoryEntries(entries, sortMode)` 与 `getPlatformCategoryPrimaryMetric(entry)`：统一分类频道的玩法过滤、排序和主指标展示。
|
||||
|
||||
`RpgEntryHomeView.tsx` 只消费这些 ViewModel 函数，保留渲染、事件处理和账号状态。公开作品规则的 **Locality** 转移到 ViewModel **Module** 与其测试，页面不再持有这批纯规则。
|
||||
|
||||
## 约定
|
||||
|
||||
- 公开作品身份 key 与平台入口推荐流保持一致，优先复用 `platformPublicGalleryFlow`。
|
||||
- 搜索应同时匹配作品号、`profileId`、`workId`、标题、作者、摘要和副标题。
|
||||
- 搜索排序先看标题前缀，再看作品号 compact 前缀，最后按发布时间 / 更新时间倒序。
|
||||
- 时间解析必须保留后端 `seconds.microsZ` 兼容。
|
||||
- 分类筛选与排序的选项顺序、默认值、中文 label 和“综合 -> 最新 -> 游玩 -> 点赞 -> 综合”循环属于 ViewModel **Interface**；页面只能消费该 **Interface**，不得在 `RpgEntryHomeView.tsx` 复写数组或 fallback 文案。
|
||||
|
||||
## 后续深化
|
||||
|
||||
下一步可把移动 / 桌面 discover feed 的数据准备继续迁入 ViewModel，但卡片 JSX 与交互状态仍留页面内。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
- 针对变更文件执行 ESLint
|
||||
@@ -1,31 +0,0 @@
|
||||
# 【前端架构】Public Work Presentation 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`RpgEntryHomeView.tsx` 的作品卡、推荐 runtime meta、排行项、分类项、搜索结果和桌面 hero 共用公开作品玩法类型 label 与紧凑计数格式。原先 `describePublicGalleryCardKind` 与 `formatCompactCount` 放在页面 **Implementation** 内，导致新增玩法或调整数字展示时需要穿过多段 JSX。公开作者 lookup key 与头像首字也曾由页面手写，页面既要知道公开作品作者来源优先级，又要知道 `code:` / `id:` 前缀约定。
|
||||
|
||||
## 决策
|
||||
|
||||
在 `src/components/rpg-entry/rpgEntryWorldPresentation.ts` 追加单作品展示 **Interface**：
|
||||
|
||||
- `describePlatformPublicWorkKind(entry)`：统一公开作品玩法类型 label，并继续复用 `formatPlatformWorkDisplayTag` 的 4 字截断口径。
|
||||
- `formatPlatformCompactCount(value)`：统一游玩、改造、点赞、排行和分类指标的紧凑数字展示。
|
||||
- `resolvePlatformPublicWorkAuthorLookup(entry)`：统一公开作者查询 lookup，优先使用 `authorPublicUserCode`，否则回退 `ownerUserId`，并用结构化 `{ key, source, value }` 避免页面复写前缀规则。
|
||||
- `formatPlatformPublicAuthorAvatarLabel(authorDisplayName)`：统一公开作者头像无图时的首字兜底。
|
||||
|
||||
`RpgEntryHomeView.tsx` 删除本地类型 label、紧凑计数、公开作者 lookup 与头像首字 **Implementation**，仅消费 `rpgEntryWorldPresentation.ts`。认证请求、缓存和失败兜底仍留页面侧 Adapter；集合筛选、排序和指标选择仍留在 `rpgEntryPublicGalleryViewModel.ts`，避免单作品展示 **Module** 与集合 **Module** 混杂。
|
||||
|
||||
## 约定
|
||||
|
||||
- 紧凑计数保留既有口径：`10000` 显示 `1.0万`，`100000000` 显示 `1.0亿`，一万以下不加千分位。
|
||||
- 玩法类型 label 继续遵循 4 字展示限制，例如“大鱼吃小鱼”外显为“大鱼吃小”。
|
||||
- 公开作者 lookup 的 `key` 只用于缓存索引；真正调用公开用户 Adapter 时以 `source` 和 `value` 分发，页面不得解析 `code:` / `id:` 前缀。
|
||||
- 本次不迁移排行 metric label / value 配对；该规则属于集合排序 **Module** 的后续切片。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/rpg-entry/rpgEntryWorldPresentation.test.ts`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend|ranking|category"`
|
||||
- 针对变更文件执行 ESLint
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,32 +0,0 @@
|
||||
# 【前端架构】Ranking ViewModel 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
平台发现页排行频道以 `PlatformRankingTab` 决定 tab 文案、空态文案、排序字段和指标展示。原先排序与指标取值在 `rpgEntryPublicGalleryViewModel.ts`，而 tab label、metric label 与 empty text 留在 `RpgEntryHomeView.tsx`，页面还用类型断言寻找 active config，导致同一个排行语义的 **Interface** 分散。
|
||||
|
||||
## 决策
|
||||
|
||||
在 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts` 收口排行 **Interface**：
|
||||
|
||||
- `DEFAULT_PLATFORM_RANKING_TAB` 与 `PLATFORM_RANKING_TABS`：统一 tab 顺序、tab label、metric label 与空态文案。
|
||||
- `getPlatformRankingTabConfig(tab)`：统一 active tab 配置兜底。
|
||||
- `getPlatformRankingMetric(entry, tab)`：统一 metric label 与 value，避免 label/value 漂移。
|
||||
- `buildPlatformRankingEntries(entries, tab)` 继续承载排序规则。
|
||||
|
||||
`RpgEntryHomeView.tsx` 只保留 active tab 状态、点击与渲染，不再理解“热门榜=游玩值”“新品榜=近 7 日值”等映射。排行规则的 **Locality** 收口到 PublicGallery ViewModel。
|
||||
|
||||
## 约定
|
||||
|
||||
- 默认排行 tab 保持 `hot`。
|
||||
- tab 顺序保持“热门榜 / 改造榜 / 新品榜 / 点赞榜”。
|
||||
- 排序口径保持：`hot=playCount`、`remix=remixCount`、`new=recentPlayCount7d`、`like=likeCount`。
|
||||
- “新品榜”仍按近 7 日游玩数排序，不改为发布时间排序。
|
||||
- 页面层继续保留最多显示 30 条的展示限制。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "bottom category tab becomes ranking and switches ranking metrics|ranking"`
|
||||
- 针对变更文件执行 ESLint
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,31 +0,0 @@
|
||||
# 【前端架构】Recommend Feed ViewModel 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
平台首页推荐 feed、发现页推荐频道、桌面推荐格和正式 runtime 的上一条 / 下一条选择共用一批展示规则：公开作品跨来源去重、过滤寓教于乐隐藏内容、按精选优先再最新兜底、active key 失效时回到首项、前后相邻条目回环且单条目不自循环。原先这些规则分别散在 `RpgEntryHomeView.tsx` 与 `PlatformEntryFlowShellImpl.tsx` 的 **Implementation** 内，导致推荐预览与正式 runtime 之间存在口径漂移风险。
|
||||
|
||||
## 决策
|
||||
|
||||
在 `src/components/rpg-entry/rpgEntryPublicGalleryViewModel.ts` 追加推荐 feed **Interface**：
|
||||
|
||||
- `dedupePlatformPublicGalleryEntries(entries)`：统一公开作品按 `buildPublicGalleryCardKey` 去重，后出现来源覆盖旧值。
|
||||
- `buildPlatformRecommendFeedEntries(featuredEntries, latestEntries)`：统一推荐 feed 的精选 + 最新合并、隐藏寓教于乐内容与去重顺序。
|
||||
- `selectPlatformRecommendFeedWindow(entries, activeEntryKey)`：统一推荐页当前项、上一项、下一项和 active key 失效兜底。
|
||||
- `selectAdjacentPlatformRecommendEntry(entries, direction, baseEntryKey)`：统一正式 runtime 上一条 / 下一条回环选择，并避免单作品自循环。
|
||||
|
||||
`RpgEntryHomeView.tsx` 不再自建 `Map` 或手写取模；`PlatformEntryFlowShellImpl.tsx` 的 runtime 推荐条目也改用同一 **Module**。推荐 feed 的 **Locality** 回到 PublicGallery ViewModel，页面与 runtime 只保留 UI、动画和启动副作用。
|
||||
|
||||
## 约定
|
||||
|
||||
- 推荐 feed 仍只展示普通公开作品；寓教于乐内容由独立频道控制，不进入推荐 runtime 队列。
|
||||
- 去重保留既有“后出现来源覆盖旧值、插入位置不变”的行为。
|
||||
- active key 缺失或失效时，展示窗口回到首个推荐作品；单个作品没有上一条 / 下一条预览。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend|edutainment"`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "logged out home recommendation next starts the next puzzle work"`
|
||||
- 针对变更文件执行 ESLint
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,42 +0,0 @@
|
||||
# RecommendSwipeDeckModel 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
移动端推荐首页的纵向 swipe deck 曾把拖拽阈值、offset clamp、commit 方向、rail class 和分享文案直接放在 `RpgEntryHomeView.tsx` Implementation 内。页面因此同时理解 DOM pointer 副作用、动画副作用与推荐卡纯规则，后续调整手势阈值或分享文案时缺少稳定测试面。
|
||||
|
||||
## 决策
|
||||
|
||||
- 新增 `src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.ts` 作为 Recommend Swipe Deck Module。
|
||||
- Module Interface 收口：
|
||||
- `hasRecommendDragStarted`
|
||||
- `clampRecommendDragOffset`
|
||||
- `resolveRecommendDragCommitDirection`
|
||||
- `resolveRecommendCommitOffset`
|
||||
- `buildRecommendSwipeRailClassName`
|
||||
- `shouldAnimateRecommendSwipe`
|
||||
- `buildRecommendShareText`
|
||||
- `RpgEntryHomeView.tsx` 保留 pointer capture、DOM 高度读取、`setTimeout`、clipboard、like/remix/open 等副作用 Adapter；推荐卡纯规则不再散落在页面 Implementation 内。
|
||||
|
||||
## Interface 约束
|
||||
|
||||
- swipe 阈值、commit 动画时长和 drag fallback limit 只从 Module 导出，不在页面重复定义。
|
||||
- `deltaY < 0` 表示上滑进入下一条，返回方向 `1`；`deltaY > 0` 表示下滑进入上一条，返回方向 `-1`。
|
||||
- 未达到 commit 阈值时必须返回 `null`，页面 Adapter 只负责把 offset 归零。
|
||||
- rail class 仅由 `offsetY` 与 `commitDirection` 决定，CSS class 名保持现有命名。
|
||||
- 分享文案只使用公开作品名、作品号和详情 URL；公开作品码解析与复制副作用仍在页面 Adapter。
|
||||
|
||||
## Depth / Leverage / Locality
|
||||
|
||||
- **Depth**：页面传入少量数值或公开作品身份，即可得到拖拽状态、提交方向、动画 class 和分享文案。
|
||||
- **Leverage**：调整推荐 swipe 体验时只需改 Module 与单测，交互测试仍护页面 Adapter。
|
||||
- **Locality**：pointer 事件生命周期与纯规则分离，推荐卡手势和分享规则集中到一个小 Module。
|
||||
|
||||
## 验收
|
||||
|
||||
- `npm run test -- src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.test.ts`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend|edutainment"`
|
||||
- `npm run test -- src/components/rpg-entry/rpgEntryPublicGalleryViewModel.test.ts -t "recommend"`
|
||||
- `npx eslint src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.ts src/components/rpg-entry/rpgEntryRecommendSwipeDeckModel.test.ts --max-warnings 0`
|
||||
- `npx eslint src/components/rpg-entry/RpgEntryHomeView.tsx --quiet`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
@@ -1,32 +0,0 @@
|
||||
# 【前端架构】Runtime Client Family 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
多个小游戏 runtime client 都重复实现路径编码、JSON header / body、runtime guest token、认证影响策略和重试参数。重复逻辑分散在各玩法文件后，新增玩法容易遗漏 guest auth 或 retry 语义，也让测试必须逐玩法检查同一请求骨架。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/services/runtimeRequest.ts`，作为 Runtime Client Family 的请求 **Module**。其 **Interface** 包含：
|
||||
|
||||
- `buildRuntimeApiPath(basePath, ...segments)`：统一对 runtime path segment 执行 `encodeURIComponent`。
|
||||
- `requestRuntimeJson(params)`：统一设置 method、JSON body、`Content-Type`、runtime guest `Authorization`、auth options 和 retry options。
|
||||
|
||||
`match3dRuntimeClient.ts`、`squareHoleRuntimeClient.ts`、`bigFishRuntimeClient.ts`、`barkBattleRuntimeClient.ts`、`puzzleRuntimeClient.ts` 的公开 / 推荐运行态请求、`jumpHopClient.ts` 与 `woodenFishClient.ts` 的正式 run 请求，以及 `visualNovelRuntimeClient.ts` 的公开列表、run 读取、history 读取和 regenerate JSON 请求已迁入此 **Module**，并保留原有导出函数名、错误文案、返回契约和重试常量。点击 / 投入 / 成绩提交等玩法专属 payload 归一化仍留在各自 client 内，避免把领域规则塞进通用请求 **Implementation**。
|
||||
|
||||
## 约定
|
||||
|
||||
- Runtime client 不再手写 `encodeURIComponent` 拼 path；应优先使用 `buildRuntimeApiPath`。
|
||||
- Runtime JSON 请求不再手写 `Content-Type`、guest `Authorization` 和 `buildRuntimeGuestAuthOptions` 合并；应优先使用 `requestRuntimeJson`。
|
||||
- 玩法专属 payload 归一化、返回值适配和中文错误文案仍属于各玩法 client。
|
||||
- 每迁移一个 client，必须保留原导出函数名与原调用方契约。
|
||||
|
||||
## 后续深化
|
||||
|
||||
下一批可评估是否扩展 `requestRuntimeJson` 支持 `timeoutMs` / `signal`，再迁移 Visual Novel start 请求；Visual Novel SSE、平台存档、平台 checkpoint，以及 Puzzle `pause` / `props` 继续保留各自现有 auth / stream 语义，暂不纳入通用 JSON helper。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/services/runtimeRequest.test.ts src/services/recommendedRuntimeGuestLaunch.test.ts src/services/match3d-runtime/match3dRuntimeAdapter.test.ts`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
- 针对变更文件执行 ESLint
|
||||
@@ -1,36 +0,0 @@
|
||||
# SSE 客户端传输层收口约定
|
||||
|
||||
更新时间：`2026-06-03`
|
||||
|
||||
## 背景
|
||||
|
||||
前端多个服务 client 需要读取 Server-Sent Events，包括创作 Agent、创意互动 Agent、视觉小说运行态和微信充值订单状态。旧实现分别在各自文件里手写事件边界查找、`TextDecoder` 解码、JSON 解析和流结束 flush，容易出现 CRLF / LF 边界不一致、UTF-8 多字节字符尾部丢失、错误事件处理漂移，以及长连接达到最终状态后没有及时释放的问题。
|
||||
|
||||
## 决策
|
||||
|
||||
前端 SSE 的传输层统一收口到 `src/services/sseStream.ts`：
|
||||
|
||||
- `readSseStream` 负责读取 `Response.body`、识别 `\n\n` 与 `\r\n\r\n` 事件边界、合并多行 `data:`、flush `TextDecoder` 尾部缓冲，并支持事件处理函数返回 `false` 后取消 reader。
|
||||
- `readSseJsonStream` 只在传输事件基础上解析 JSON object，空 data 与异常 JSON 继续按旧口径静默跳过。
|
||||
- 各业务 client 只保留领域事件归一化、最终结果聚合和中文错误文案，不再重复实现 SSE 边界扫描、reader 循环或 UTF-8 flush。
|
||||
- OpenAI 兼容流、`[DONE]` 哨兵或其它非 JSON SSE 可直接使用 `readSseStream`；业务 JSON 事件优先使用 `readSseJsonStream`。
|
||||
|
||||
## 落地范围
|
||||
|
||||
本次先收口以下客户端：
|
||||
|
||||
- `src/services/aiService.ts`
|
||||
- `src/services/creation-agent/creationAgentSse.ts`
|
||||
- `src/services/creative-agent/creativeAgentSse.ts`
|
||||
- `src/services/visual-novel-runtime/visualNovelRuntimeSse.ts`
|
||||
- `src/services/rpg-entry/rpgProfileClient.ts`
|
||||
- `src/services/llmClient.ts`
|
||||
|
||||
后续新增 SSE client 时不得复制 `findSseEventBoundary`、`parseSseEventBlock` 或手写 reader 循环；若确实需要特殊 framing，应先扩展 `sseStream.ts` 的传输能力，再在业务 client 中处理领域语义。
|
||||
|
||||
## 验收
|
||||
|
||||
- `src/services/sseStream.test.ts` 覆盖 CRLF / LF 边界、UTF-8 尾部 flush、异常 JSON 跳过和提前停止取消 reader。
|
||||
- `src/services/llmClient.test.ts` 覆盖 OpenAI 兼容文本流、异常 JSON 跳过和 `[DONE]` 后提前停止。
|
||||
- 已有 OpenAI 兼容文本流、NPC 聊天流、创作 Agent、创意互动 Agent、视觉小说运行态和充值订单状态测试继续通过。
|
||||
- `npm run typecheck` 不产生新的类型错误。
|
||||
@@ -1,34 +0,0 @@
|
||||
# 【前端架构】Work Shelf Module 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
创作中心作品架需要同时展示 RPG、拼图、抓大鹅、方洞、跳一跳、敲木鱼、视觉小说、Bark Battle 和宝贝识物等作品。`creationWorkShelf.ts` 已经统一了卡片标题、摘要、封面、发布码、分享路径、指标、生成态和动作 Adapter。后续深化前，`CustomWorldCreationHub.tsx` 虽已不再按玩法 `kind` 分发点击，但生产调用仍向 Hub 传入多玩法 raw items 与 open/delete/claim 回调列阵，Hub Interface 仍偏 shallow。
|
||||
|
||||
## 决策
|
||||
|
||||
`CreationWorkShelfItem.actions.open` 是打开作品的正式 **Interface**。`CustomWorldCreationHub.tsx` 只负责卡片点击与 `onOpenShelfItem` 通知，然后调用 `item.actions.open()`，不再根据 `item.source.kind` 分发玩法。
|
||||
|
||||
`buildCreationWorkShelfItemsFromSources` 是作品架 source registry 的正式 **Interface**。每个玩法提供一个 `CreationWorkShelfSourceAdapter`，Adapter 负责把玩法数据、删除权限、打开动作和特殊动作映射为 `CreationWorkShelfItem[]`。registry 统一执行 flatten、运行态覆盖、持久化生成态兜底和更新时间排序。
|
||||
|
||||
`CustomWorldCreationHub.tsx` 的生产 **Interface** 收敛为 `shelfItems: CreationWorkShelfItem[]` 加 `loading/error/onRetry/mode/recentWorkItems/onOpenShelfItem/deletingWorkId/claimingPuzzleProfileId` 等 UI 状态。平台壳 `PlatformEntryFlowShellImpl.tsx` 在外层作为 Adapter 调用 `buildCreationWorkShelfItems` 注入完整 open/delete/claim actions 后再传给 Hub；Hub 不再接触各玩法 raw items、删除权限布尔值或玩法专属打开回调。
|
||||
|
||||
测试文件通过 `CustomWorldCreationHub.testAdapter.tsx` 把旧 fixture 转成 `shelfItems`，避免测试继续强化生产 Hub 的旧浅 Interface。
|
||||
|
||||
此决策让 `creationWorkShelf.ts` 的 **Module** 更 deep：
|
||||
|
||||
- **Implementation**：玩法差异、草稿 / 已发布分支、profileId 进入方式和回调绑定都留在 Work Shelf Adapter 内。
|
||||
- **Interface**：Hub 只需要 `CreationWorkShelfItem[]`；后续调用方也可只传 `CreationWorkShelfSourceAdapter[]`，不需要知道每种玩法的打开规则、状态覆盖和排序规则。
|
||||
- **Leverage**：新增玩法时只补 shelf item 映射与 Adapter，Hub 不再新增 switch 分支。
|
||||
- **Locality**：作品架点击行为、source flatten、运行态覆盖和排序错误集中在 `creationWorkShelf.ts` 与其测试里定位。
|
||||
|
||||
## 后续深化
|
||||
|
||||
`buildCreationWorkShelfItems` 仍保留旧长参数兼容入口，但其 **Implementation** 已改为组装 `CreationWorkShelfSourceAdapter[]` 后复用 `buildCreationWorkShelfItemsFromSources`。下一步可让平台壳直接传入 source adapters，从而继续减少按玩法平铺的参数数量。`deletingWorkId` 与 `claimingPuzzleProfileId` 仍是 Hub UI 状态，可后续下沉到 shelf item/action busy state。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/custom-world-home/creationWorkShelf.test.ts src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx`
|
||||
- `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "creation hub published work can open detail view before deleting from detail page|creation hub published work enters existing detail view|creation hub published work card reveals delete action after card action reveal"`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
- 针对变更文件执行 ESLint
|
||||
@@ -1,56 +0,0 @@
|
||||
# 【前端架构】平台入口 Public Gallery Flow Module 收口计划
|
||||
|
||||
## 背景
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 同时承载平台入口、推荐流、公开作品详情、运行态启动和作品架刷新。公开作品列表中的身份识别、跨玩法去重、时间排序和推荐运行态类型判定原本散落在入口巨型实现中，后续每新增一种玩法都需要在巨型文件内追加判断，影响前端架构的复用、统一和扩展。
|
||||
|
||||
## 决策
|
||||
|
||||
新增 `src/components/platform-entry/platformPublicGalleryFlow.ts`，作为平台入口公开作品流的 **Module**。该 Module 的 **Interface** 固定收口为：
|
||||
|
||||
- `getPlatformPublicGalleryEntryKey(entry)`：按玩法类型、作者和 `profileId` 生成公开作品身份。
|
||||
- `getPlatformRecommendRuntimeKind(entry)`：把公开作品卡映射为推荐运行态 kind。
|
||||
- `resolvePlatformRecommendRuntimeStartIntent(entry, deps)`：把公开作品卡映射为推荐 runtime 启动意图、错误落点和 embedded / returnStage 参数。
|
||||
- `isPlatformRecommendRuntimeReadyForEntry(entry, state)`：用标量 ready state 判定当前推荐 runtime 是否已能承接该公开作品。
|
||||
- `isSamePlatformPublicGalleryEntry(left, right)`：按公开作品身份比较。
|
||||
- `mergePlatformPublicGalleryEntries(rpgEntries, puzzleEntries)`：统一完成 RPG 与各玩法公开作品去重、覆盖和倒序排序。
|
||||
- `buildPlatformPublicGalleryFeeds(input)`：统一构造 `featuredEntries` 与 `latestEntries`，收口各玩法可见性 gate、mapper 矩阵、汪汪声浪 works fallback 和推荐首屏 `slice(0, 6)`。
|
||||
|
||||
入口壳层只调用这些函数，不再在 `PlatformEntryFlowShellImpl.tsx` 内手写公开作品身份、排序规则、公开作品流聚合矩阵、推荐 runtime 启动能力矩阵和 ready 判定。ready 判定只接布尔值与拼图 profile id，不把各玩法 run snapshot 类型拖入 Module。
|
||||
|
||||
## 玩法身份规则
|
||||
|
||||
- `big-fish`、`puzzle`、`jump-hop`、`wooden-fish`、`match3d`、`square-hole`、`visual-novel`、`bark-battle` 使用自身 `sourceType` 作为 key kind。
|
||||
- `edutainment` 使用 `edutainment:${templateId}` 作为 key kind，避免后续幼教类模板共用 `sourceType` 时互相覆盖。
|
||||
- 没有 `sourceType` 的 RPG 公开作品回退为 `rpg`。
|
||||
- 最终 key 格式为 `${kind}:${ownerUserId}:${profileId}`。
|
||||
- 合并时后进入的相同 key 会覆盖先进入的卡片，然后按 `publishedAt ?? updatedAt` 新到旧排序；非法时间按 `0` 处理。
|
||||
- 公开作品流聚合时，大鱼吃小鱼、宝贝识物和视觉小说必须受各自可见性 gate 控制；汪汪声浪优先用 gallery entries，gallery 为空时才从 works 中筛 `status === 'published'` 作为 fallback。
|
||||
|
||||
## 推荐 runtime 启动意图
|
||||
|
||||
- `resolvePlatformRecommendRuntimeStartIntent` 只表达推荐 runtime 的启动目标，不执行鉴权、运行态 API、错误 setter、缓存、request key 或 UI 状态更新。
|
||||
- 大鱼吃小鱼、拼图、跳一跳、敲木鱼、抓大鹅、方洞挑战、视觉小说、汪汪声浪和宝贝识物返回对应启动 intent；RPG 维持当前无嵌入 runtime 的 `mark-ready` 行为。
|
||||
- 大鱼吃小鱼、拼图、抓大鹅、方洞挑战和汪汪声浪在公开卡无法拼出启动 work 时返回 `blocked`，同时给出 `errorTarget`，由壳层 Adapter 分发到对应玩法错误 setter。
|
||||
- 拼图优先使用同 `profileId` 的 `selectedPuzzleDetail`，否则从公开卡映射兼容 work 摘要。
|
||||
- 抓大鹅 public detail -> work mapper 必须作为 Adapter 注入，继续由 Match3D Runtime Profile Module 维护 `generatedItemAssets` 归一化与背景资产提升。推荐 runtime 固定沿用旧参数 `returnStage = 'work-detail'` 与 `embedded = true`。
|
||||
- 汪汪声浪优先使用推荐流已持有的 `barkBattleGalleryEntries`，再回退公开卡映射；不额外读取作品架列表。
|
||||
|
||||
## 推荐 runtime ready 判定
|
||||
|
||||
- `isPlatformRecommendRuntimeReadyForEntry` 先要求 `state.activeKind` 与当前公开作品的 `getPlatformRecommendRuntimeKind(entry)` 相同，否则返回 `false`。
|
||||
- 大鱼吃小鱼、跳一跳、敲木鱼、抓大鹅、方洞挑战和视觉小说只看对应 `has*Run` 布尔值，保持旧行为，不在本 Module 内解析 run snapshot。
|
||||
- 拼图只看 `puzzleRunEntryProfileId` 或 `puzzleRunCurrentLevelProfileId` 是否等于当前公开作品 `profileId`。
|
||||
- 汪汪声浪和 RPG 在 kind 匹配时沿用旧 `ready = true` 行为；宝贝识物只看 `hasBabyObjectMatchDraft`。
|
||||
- 若未来要修正同玩法旧 run 误判或 RPG 无嵌入 runtime 的旧行为，应另立行为变更任务；本 Module 先只收口现有规则。
|
||||
|
||||
## 后续深化
|
||||
|
||||
下一步可继续把平台入口的作品架刷新、删除确认和直达恢复逻辑收口成更深的 Work Shelf **Module**。当前 `platformPublicGalleryFlow` 先提供一个稳定 seam，使公开作品 identity、runtime kind、推荐 runtime 启动意图与 ready 判定的修改集中在一处。
|
||||
|
||||
## 验证
|
||||
|
||||
- `npm run test -- src/components/platform-entry/platformPublicGalleryFlow.test.ts`
|
||||
- `npm run typecheck`
|
||||
- `npm run check:encoding`
|
||||
- 针对变更文件执行 ESLint
|
||||
@@ -1,38 +0,0 @@
|
||||
# 【后端架构】Puzzle Publish Asset Gate 收紧计划
|
||||
|
||||
## 背景
|
||||
|
||||
拼图前端恢复链路已由 `platformPuzzleDraftRecoveryModel.ts` 收紧：只有首图、关卡画面、UI spritesheet 与关卡背景资产包完整时，才把恢复草稿抬为完成态。但后端仍有两处待发布门槛偏弱：
|
||||
|
||||
- `module-puzzle::validate_publish_requirements(...)` 只校验作品名、描述、标签、关卡名与 cover。
|
||||
- `api-server::puzzle::tags::is_puzzle_session_snapshot_publish_ready(...)` 也只校验同一组轻字段，并据此把 session stage 置为 `ready_to_publish`。
|
||||
|
||||
这会让只有首图但缺关卡正式画面、UI spritesheet 或关卡背景的半成品显示为可发布或进入待发布 stage。
|
||||
|
||||
## 决策
|
||||
|
||||
后端拼图待发布门槛统一收紧到完整首关资产包：
|
||||
|
||||
- `module-puzzle` 在 `validate_publish_requirements` 中新增资产 blocker，业务规则继续留在领域模块。
|
||||
- `api-server` 的 session snapshot ready 判定复用同一资产语言，避免标签生成后把半成品 session stage 改成 `ready_to_publish`。
|
||||
- 本切片不改 SpacetimeDB schema、不改 DTO 字段、不改路由、不改计费和发布动作副作用。
|
||||
|
||||
## 接口约束
|
||||
|
||||
- 仍保留既有作品名、描述、标签数量、关卡名、cover 校验。
|
||||
- 每个关卡必须具备：
|
||||
- `cover_image_src`；
|
||||
- `level_scene_image_src` 或 `level_scene_image_object_key`；
|
||||
- `ui_spritesheet_image_src` 或 `ui_spritesheet_image_object_key`；
|
||||
- `level_background_image_src` 或 `level_background_image_object_key`。
|
||||
- 缺正式关卡画面、UI spritesheet、关卡背景时，各自输出明确 blocker。
|
||||
- `build_result_preview(...).publish_ready` 与 `is_puzzle_session_snapshot_publish_ready(...)` 必须在同一类缺资产草稿上返回 false。
|
||||
- `api-server` 从 action payload 构造 fallback session 时，缺资产 levels snapshot 应停留 `image_refining`，不得进入 `ready_to_publish`。
|
||||
|
||||
## 验收
|
||||
|
||||
- `cargo test -p module-puzzle --manifest-path server-rs/Cargo.toml validate_publish_requirements`
|
||||
- `cargo test -p api-server --manifest-path server-rs/Cargo.toml puzzle_image_generation`
|
||||
- `npm run check:encoding`
|
||||
- `git diff --check`
|
||||
- 修改后按仓规尝试 `npm run api-server` 拉起后端并确认 `/healthz`。
|
||||
@@ -194,7 +194,7 @@ cargo test -p api-server app --manifest-path server-rs/Cargo.toml
|
||||
|
||||
后续建议继续拆分：
|
||||
|
||||
- `match3d`: `draft.rs`、`background_and_cover.rs`、`material_sheet.rs`。
|
||||
- `match3d`: `draft.rs`、`background_and_cover.rs`、`material_sheet.rs`、`apimart_image.rs`。
|
||||
- `puzzle`: `session_form.rs`、`draft_compile.rs`、`image_provider.rs`、`errors.rs`。
|
||||
- `custom_world`: `publish_gate.rs`、`foundation_job.rs`、`foundation_assets.rs`、`errors.rs`。
|
||||
- `square_hole`: `config.rs`、`errors.rs`。
|
||||
|
||||
@@ -215,7 +215,7 @@ Handler 主要在 `story.rs`、`combat.rs`、`runtime_inventory.rs`：
|
||||
| Square Hole 图片重生成 | OpenAI/VectorEngine GPT image helper | URL 下载或 base64/data URL 解码 | `LegacyAssetPrefix::SquareHoleAssets` | 方洞作品图片槽位相关 kind | profile/work + image slot | 调用方包裹 | 生成成功但入库失败保留 Data URL 回包 |
|
||||
| Custom World 场景/封面 | VectorEngine GPT image 2 / OpenAI helper | URL 下载或 base64 解码 | `LegacyAssetPrefix::CustomWorldScenes` 等 | scene/cover/opening storyboard | `custom_world_profile` 或 profile/landmark/scene slot | `custom_world_ai.rs` 调用方包裹 | entity/scene 生成存在 LLM fallback；资产持久化失败按当前错误口径返回 |
|
||||
| Puzzle 图片 | GPT image 2 generations/edits | 无参考图 JSON 创建；有参考图 multipart 编辑；base64/URL 结果归一 | `LegacyAssetPrefix::PuzzleAssets` | puzzle level/background/generated image，另有 `puzzle_background_music` | puzzle profile/run/level slot | `puzzle.rs` 调用方包裹 | connectivity 可按既有规则跳过部分计费；运行态 fallback 保持原逻辑 |
|
||||
| Match3D 图片 | VectorEngine/OpenAI image helper | 下载、切图、透明化、校准后入库 | `LegacyAssetPrefix::Match3DAssets` | cover/background/item material sheet，音频 kind 另列 | match3d profile/session slot | `match3d.rs` 调用方包裹 | 新草稿不回退 Rodin/GLB；部分连接错误按现有计费跳过规则处理 |
|
||||
| Match3D 图片 | APIMart/VectorEngine/OpenAI image helper | 下载、切图、透明化、校准后入库 | `LegacyAssetPrefix::Match3DAssets` | cover/background/item material sheet，音频 kind 另列 | match3d profile/session slot | `match3d.rs` 调用方包裹 | 新草稿不回退 Rodin/GLB；部分连接错误按现有计费跳过规则处理 |
|
||||
| Visual Novel 音频 | VectorEngine Suno/Vidu | 任务提交后按 task publish 下载音频 | 视觉小说/creation audio scope | `visual_novel_music`、`visual_novel_ambient_sound` | `visual_novel_scene` + scene id + `music`/`ambient_sound` | `vector_engine_audio_generation.rs` 调用方包裹 | 上游/下载失败显式错误，不混入图片 Adapter |
|
||||
| 通用音频 | VectorEngine Suno/Vidu | 同上 | creation audio scope | background_music/sound_effect 由调用方目标指定 | creation target entity/slot | 调用方包裹 | 不与 VN 场景语义混用 |
|
||||
| 视频 Opening CG | Ark/火山视频 + storyboard | 先生 storyboard，再图生视频，下载 remote video | Custom World 相关 prefix | `custom_world_opening_cg_storyboard`、`custom_world_opening_cg_video` | `custom_world_profile` + opening cg slots | `execute_billable_asset_operation_with_cost` 固定点数 | 配置缺失/超时显式错误，不应静默降级 |
|
||||
|
||||
@@ -1,82 +0,0 @@
|
||||
# 本地 SSH 服务器管理面板技术方案
|
||||
|
||||
日期：`2026-06-11`
|
||||
|
||||
## 背景
|
||||
|
||||
release / dev 等服务器的日常巡检已经有 `genarrative-health-patrol.timer`、`/readyz`、`/healthz`、SpacetimeDB `/v1/ping` 和 systemd 状态文件，但开发者本地仍需要在多个 SSH alias 之间切换命令。服务器管理面板用于把这些只读巡检和少量 systemd 服务操作收敛到一个本地桌面入口。
|
||||
|
||||
## 范围
|
||||
|
||||
- 使用 Rust `egui` / `eframe` 实现本地桌面面板，不接入线上 Web 后台，不暴露公网端口。
|
||||
- 从本机 `~/.ssh/config` 的 `Host` alias 发现服务器；只展示不含通配符的 alias。
|
||||
- 支持多个服务器，左侧服务器侧边栏可收起。
|
||||
- 主面板展示硬件状态、服务状态、HTTP 健康探测和生产健康巡检状态。
|
||||
- 支持对允许的 systemd unit 执行启动、关闭、重启。
|
||||
|
||||
## 命令入口
|
||||
|
||||
```bash
|
||||
npm run server-manager:panel
|
||||
```
|
||||
|
||||
等价于：
|
||||
|
||||
```bash
|
||||
cargo run -p server-manager-panel --manifest-path server-rs/Cargo.toml
|
||||
```
|
||||
|
||||
面板启动时会自动查找本机中文字体并注入 egui 字体集，优先使用 `Noto Sans CJK SC`，其次使用文泉驿 / Droid fallback。若某台开发机字体路径特殊，可用 `GENARRATIVE_SERVER_PANEL_CJK_FONT=/path/to/font.ttc|index` 指定；普通 `.ttf` 可省略 `|index`。
|
||||
|
||||
## SSH 约定
|
||||
|
||||
本地 `~/.ssh/config` 中需要存在类似：
|
||||
|
||||
```sshconfig
|
||||
Host dev
|
||||
HostName 10.2.0.10
|
||||
User genarrative
|
||||
|
||||
Host release
|
||||
HostName genarrative.world
|
||||
User genarrative
|
||||
```
|
||||
|
||||
面板通过 `ssh <alias> sh -s` 执行远端只读巡检脚本。服务操作使用：
|
||||
|
||||
```bash
|
||||
sudo -n systemctl <start|stop|restart> <unit>
|
||||
```
|
||||
|
||||
若 SSH 用户是 root，则直接执行 `systemctl`。非 root 用户需要提前配置只允许目标 unit 的无密码 sudo；否则面板会显示 sudo 权限错误，不会弹出交互密码输入。
|
||||
|
||||
## 健康检查内容
|
||||
|
||||
只读巡检覆盖：
|
||||
|
||||
- 主机名、内核、运行时长、CPU 核数 / 型号、load average。
|
||||
- 内存 / swap 使用情况。
|
||||
- `/`、`/var`、`/opt`、`/stdb`、`/data` 中存在路径的磁盘使用率。
|
||||
- `genarrative-api.service`、`spacetimedb.service`、`nginx.service`、`genarrative-health-patrol.timer`、`genarrative-database-backup.timer` 的 systemd 状态。
|
||||
- `http://127.0.0.1:8082/healthz`、`/readyz`、`http://127.0.0.1:3101/v1/ping` 和代表性公开接口。
|
||||
- `/var/lib/genarrative/health-patrol/status.json` 的最近巡检状态。
|
||||
- 若服务器安装了 `sensors`，附带温度 / 风扇等硬件传感器摘要。
|
||||
|
||||
## 服务操作安全边界
|
||||
|
||||
面板只允许 `start`、`stop`、`restart` 三种动作，并且 unit 名必须匹配安全字符集：
|
||||
|
||||
```text
|
||||
A-Z a-z 0-9 . _ - @ :
|
||||
```
|
||||
|
||||
服务操作会先出现确认弹窗，避免误点。第一版默认列出 Genarrative 生产相关 unit，并提供“其他 unit”输入框；该输入框仍只会执行 `systemctl` 的三种受控动作，不提供任意命令执行入口。
|
||||
|
||||
## 状态判定
|
||||
|
||||
- service / HTTP 探测失败：`CRITICAL`。
|
||||
- 磁盘使用率 `>= 95%`：`CRITICAL`，`>= 85%`：`WARNING`。
|
||||
- 内存使用率 `>= 95%`：`CRITICAL`，`>= 85%`：`WARNING`。
|
||||
- 生产健康巡检状态沿用 `OK / WARNING / CRITICAL`。
|
||||
|
||||
面板状态只是本地巡检视图，最终运维事实仍以服务器上的 systemd、journal、Nginx 日志、`production-health-patrol.mjs` 输出和现有部署文档为准。
|
||||
@@ -28,19 +28,17 @@
|
||||
| 形状 | 数量 | 单组单元数 | 解锁 |
|
||||
| --- | ---: | ---: | --- |
|
||||
| 1x2 | 23 | 2 | 第 1 关 |
|
||||
| 1x3 | 5 | 3 | 第 2 关 |
|
||||
| 2x2 | 4 | 4 | 第 3 关 |
|
||||
| 2x3 | 3 | 6 | 第 4 关 |
|
||||
| 1x3 | 5 | 3 | 第 1 关 |
|
||||
| 2x2 | 4 | 4 | 第 1 关 |
|
||||
| 2x3 | 3 | 6 | 第 1 关 |
|
||||
|
||||
流程：
|
||||
|
||||
```text
|
||||
卡牌素材主题 / 背景图画面描述 / 用户背景图 -> 4 张 sheet 坐标规划 -> gpt-image-2 生成素材工作表 -> 按 4x6 裁切 1x1 -> 合成最终 atlas -> atlas 与卡牌切片持久化 -> OSS / asset_object / bind -> session draft 回写
|
||||
主题词 / 场地底图主题词 / 用户底图 -> 4 张 sheet 坐标规划 -> gpt-image-2 生成素材工作表 -> 按 4x6 裁切 1x1 -> 合成最终 atlas -> atlas 与卡牌切片持久化 -> OSS / asset_object / bind -> session draft 回写
|
||||
```
|
||||
|
||||
背景图的 prompt 来源固定为：若用户填写 `boardBackgroundPrompt`，AI 生成背景图只读取该字段；若该字段为空，才回退读取 `themePrompt`。用户直接上传背景图资产时不再用主题词重写该资产，只执行平台资产持久化与换签。背景图在运行态不是整页氛围背景，而是玩家逐渐消除卡牌后露出的主题目标图；生成请求使用与中央棋盘一致的 1:1 正方形尺寸，prompt 必须强调探索、揭开全貌、追求完成目标、精致主题主视觉和强主题表现，不写“画面干净”或“适合作为卡牌棋盘底图”。
|
||||
|
||||
工作台 UI 对齐拼图创作流程：左上角保留返回按钮，下方展示大标题“拼消消创作”；工作台只收集游戏内容配置，包括卡牌素材主题和背景图配置。背景图配置通过同一个单图槽位表达“上传图片 / 填写画面描述”两种输入方式，槽位标题显示为“背景图”，描述输入显示为“画面描述”，工作台内容区不再套额外外层信息框。作品标题与简介属于发布元信息，不在工作台出现；前端创建草稿时可按主题派生内部占位标题，结果页点击发布时弹出发布前检查面板，先通过 `update-work-meta` 保存标题 / 简介，再调用发布接口。
|
||||
中央场地底图的 prompt 来源固定为：若用户填写 `boardBackgroundPrompt`，AI 生成底图只读取该字段；若该字段为空，才回退读取 `themePrompt`。用户直接上传底图资产时不再用主题词重写该资产，只执行平台资产持久化与换签。中央场地底图在运行态不是普通棋盘衬底，而是玩家逐渐消除卡牌后露出的主题目标图；生成请求使用与中央棋盘一致的 1:1 正方形尺寸，prompt 必须强调探索、揭开全貌、追求完成目标、精致主题主视觉和强主题表现，不写“画面干净”或“适合作为卡牌棋盘底图”。
|
||||
|
||||
### 素材工作表风险与切片验证
|
||||
|
||||
@@ -67,13 +65,13 @@
|
||||
|
||||
`module-puzzle-clear` 已固定以下规则：
|
||||
|
||||
- 关卡配置：4 关，棋盘均为 `6x6`；第 1 关目标 15、300 秒、仅 `1x2`；第 2 关目标 20、300 秒、解锁 `1x2/1x3`；第 3 关目标 30、420 秒、解锁 `1x2/1x3/2x2`；第 4 关目标 35、600 秒、解锁全部 `1x2/1x3/2x2/2x3`。
|
||||
- 关卡配置：单关 `6x6/35`，600 秒。
|
||||
- 图案组配比：`1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`。
|
||||
- 开局只放入本关目标消除数对应的全部卡牌；棋盘放不下的牌进入顶部准备区，牌不足棋盘格数时空格保留；开局仍保证至少一步可解。
|
||||
- 补牌按列重力下落；顶部没有新牌时空格留在场上并露出背景图；补牌后若场上仍有卡牌则保证至少一步可解。
|
||||
- 开局随机铺满并保证至少一步可解。
|
||||
- 补牌按列重力下落；补牌后仍保证至少一步可解。
|
||||
- 完整图案组消除并清空对应格。
|
||||
- 半锁定拼接组只由玩家主动交换 / 撞入打散，补牌不破坏。
|
||||
- 超时失败只作用于当前关，可重试；胜利条件永远是消除完本关全部卡牌，达到目标消除数且棋盘与顶部准备区都没有剩余卡牌后进入下一关，第 4 关全部卡牌消除后整局完成。
|
||||
- 超时失败只作用于当前单关，可重试；完成 35 次消除目标并清空棋盘后整局完成。
|
||||
|
||||
## API 命名空间
|
||||
|
||||
@@ -96,7 +94,7 @@ api-server 路由熔断使用 SpacetimeDB 创作入口配置 `puzzle-clear`，
|
||||
|
||||
正式 `published` run 记录开局、全局完成、当前关失败、耗时和消除统计。runtime action 返回的终态事件包括：
|
||||
|
||||
- `run-finished`：第 4 关完成并结束整局，结果 JSON 至少包含 `status`、`level`、`clears`、`clearDelta`、`elapsedMs`。
|
||||
- `run-finished`：第 1 关完成并结束整局，结果 JSON 至少包含 `status`、`level`、`clears`、`clearDelta`、`elapsedMs`。
|
||||
- `level-failed`：当前关超时失败，结果 JSON 至少包含 `status`、`level`、`clears`、`clearDelta`、`elapsedMs`。
|
||||
|
||||
草稿试玩只消费同一份 snapshot/action 结果做表现，不写正式统计。
|
||||
@@ -110,7 +108,7 @@ api-server 路由熔断使用 SpacetimeDB 创作入口配置 `puzzle-clear`，
|
||||
- `puzzle-clear-result` -> `/creation/puzzle-clear/result`
|
||||
- `puzzle-clear-runtime` -> `/runtime/puzzle-clear`
|
||||
|
||||
runtime 移动端优先，首屏结构为顶部倒计时 / 关卡铭牌、顶部列准备区、棋盘、失败 / 完成弹层。棋盘主网格、半锁定组覆盖层和消除 / 掉落覆盖层统一使用 1.5px 格间距。动画包括开场翻转、局部正确拼合高光、完整消除放大淡出、列补牌延迟下落和关卡完成后的下一关切换。消除和补牌动画只能作为当前后端 snapshot 的表现层覆盖；已有场上卡片因重力下沉后的最终格不得被旧消除坐标或掉落覆盖层隐藏，避免出现“下方空位但上方卡片未下落”的视觉假象；新补入卡牌应等完整消除淡出进入尾段后再播放下落反馈。列补牌下落的过渡层生命周期必须覆盖 `delay + duration + settle buffer`，并按下落距离延长动画时长，避免叠层在延迟后刚出现就被卸载；下落叠层不得带白色背景、白色边框或提亮滤镜，卡片图本身负责视觉主体，避免下滑时白闪。拖拽覆盖替换时，拖动卡由拖拽 ghost 落到目标格，被覆盖的目标卡才使用替换飞行层回到源空位；替换飞行层同样不得带白底、白边或白色外壳，避免目标卡在新位置先闪白再显示。
|
||||
runtime 移动端优先，首屏结构为顶部倒计时 / 单关铭牌、顶部列准备区、棋盘、失败 / 完成弹层。棋盘主网格、半锁定组覆盖层和消除 / 掉落覆盖层统一使用 1.5px 格间距。动画包括开场翻转、局部正确拼合高光、完整消除放大淡出和列补牌延迟下落，不再有下一关切换。消除和补牌动画只能作为当前后端 snapshot 的表现层覆盖；已有场上卡片因重力下沉后的最终格不得被旧消除坐标或掉落覆盖层隐藏，避免出现“下方空位但上方卡片未下落”的视觉假象；新补入卡牌应等完整消除淡出进入尾段后再播放下落反馈。
|
||||
|
||||
## 验证计划
|
||||
|
||||
|
||||
@@ -1,40 +0,0 @@
|
||||
# SpacetimeDB 连接池租约 Drop 兜底与取消安全
|
||||
|
||||
- 日期：2026-06-11
|
||||
- 关联故障：release 环境 api-server 周期性全量 `spacetime_stage="pool_acquire" elapsed_ms=45000` 超时，`/readyz` 503（`reason=spacetime_unhealthy, stage=pool_acquire`），重启后临时恢复。
|
||||
- 涉及代码：`server-rs/crates/spacetime-client/src/lib.rs`
|
||||
|
||||
## 故障根因
|
||||
|
||||
修复前的连接池存在两个叠加缺陷：
|
||||
|
||||
1. **租约没有 Drop 兜底**。`PooledConnectionLease` 只能通过显式 `release_connection` 归还。当 HTTP 请求方在等待 StDB 回包期间断开（前端超时、用户刷新、Nginx 截断），axum/hyper 会直接丢弃 handler future，租约被 Drop：permit 因 `OwnedSemaphorePermit` 自动归还，但槽位的 `in_use` 标记永远不会复位。
|
||||
2. **acquire 在槽位泄漏后永久空转**。后续请求拿到 permit 后进入 `loop { 扫描槽位; yield_now }`，找不到空闲槽位就无限自旋，且这段自旋不受 `procedure_timeout` 约束，自旋期间 permit 不归还。
|
||||
|
||||
叠加效果：StDB 一旦变慢（请求占用连接接近 45 秒），客户端取消请求的概率大增，每次取消泄漏一个槽位并连带吞掉一个 permit；泄漏数量达到 `pool_size`（release 为 8）后，所有业务请求与健康检查全部在 `pool_acquire` 阶段 45 秒超时，服务表现为"连不上 StDB"，只有重启能恢复。
|
||||
|
||||
## 本地复现
|
||||
|
||||
不需要真实 SpacetimeDB，单元测试即可复现机制（位于 `spacetime-client` tests 模块）：
|
||||
|
||||
- 修复前：将一个槽位置为 `in_use=true` 后调用 `acquire_connection_with_timeout(200ms)`，acquire 在 5 秒守护窗口内不返回（永久自旋），测试红。
|
||||
- `dropped_lease_releases_slot_and_permit`：模拟"请求被取消、租约未经 release 直接 Drop"，断言槽位与 permit 都被复位归还。
|
||||
- `acquire_times_out_at_pool_acquire_when_pool_is_busy`：池内 permit 全部被占用时，acquire 必须在超时窗口内返回 `PoolAcquire + Timeout`，不允许无限等待。
|
||||
|
||||
## 修复方案
|
||||
|
||||
1. `PooledConnectionSlot` 改为 `in_use: AtomicBool + connection: Mutex<Option<PooledConnection>>`，槽位占用标记不再依赖异步锁。
|
||||
2. `PooledConnectionLease` 持有 `Arc<SpacetimeConnectionPool>` 并实现 `Drop`：无论显式归还还是 future 被取消，统一在 Drop 中复位槽位、按 broken 状态决定连接是否回池，permit 随后自动归还。Drop 体先复位 `in_use` 再释放 permit（字段在 Drop 体之后析构），保证新请求拿到 permit 时必有空闲槽位。
|
||||
3. acquire 改为 CAS 抢占槽位：持有 permit 即保证并发持有者不超过 `pool_size`，扫描一轮必然命中空闲槽位，彻底删除自旋循环；建连失败直接返回错误，槽位由租约 Drop 复位。
|
||||
4. `release_connection` 退化为 `drop(lease)`，显式与隐式归还共用同一条兜底路径。
|
||||
|
||||
## 验收
|
||||
|
||||
- `cargo test -p spacetime-client --manifest-path server-rs/Cargo.toml --lib`（35 通过，含上述新测试）
|
||||
- `cargo test -p api-server --manifest-path server-rs/Cargo.toml readyz`（2 通过）
|
||||
- `cargo check -p api-server --manifest-path server-rs/Cargo.toml`
|
||||
|
||||
## 运维提示
|
||||
|
||||
- 此修复解决的是"取消导致的永久泄漏"。StDB 真慢时仍会出现成批 45 秒超时（连接被在途请求合法占用），那是容量/上游问题，应结合 `GENARRATIVE_SPACETIME_POOL_SIZE` 与 StDB 负载排查，不要再怀疑池泄漏。
|
||||
- 健康检查 `/readyz` 在池被在途请求占满时仍可能短暂 503（stage=pool_acquire），恢复后自动转好，无需重启。
|
||||
@@ -1,6 +1,6 @@
|
||||
# server-rs 与 SpacetimeDB 数据契约
|
||||
|
||||
更新时间：`2026-06-10`
|
||||
更新时间：`2026-05-15`
|
||||
|
||||
## 后端主线
|
||||
|
||||
@@ -16,13 +16,13 @@ server-rs + Axum + SpacetimeDB
|
||||
|
||||
`server-rs/Cargo.toml` 是 workspace 事实源。默认构建成员为 `crates/api-server`；第三方依赖版本和 workspace 内 crate path 统一放在 `[workspace.dependencies]`。
|
||||
|
||||
SpacetimeDB 版本口径：当前 Rust crate `spacetimedb`、`spacetimedb-sdk`、`spacetimedb-lib` 统一锁定 `2.4.1`；本地 `spacetime` CLI / standalone、生成的 `spacetime-client` bindings 和容器压测镜像也必须与 `2.4.1` 对齐，避免 BSATN / procedure result 反序列化错配。
|
||||
SpacetimeDB 版本口径：当前 Rust crate `spacetimedb`、`spacetimedb-sdk`、`spacetimedb-lib` 统一锁定 `2.3.0`；本地 `spacetime` CLI / standalone、生成的 `spacetime-client` bindings 和容器压测镜像也必须与 `2.3.0` 对齐，避免 BSATN / procedure result 反序列化错配。
|
||||
|
||||
当前主要 crate：
|
||||
|
||||
- HTTP 服务：`api-server`。
|
||||
- 领域模块：`module-ai`、`module-assets`、`module-auth`、`module-bark-battle`、`module-big-fish`、`module-combat`、`module-creative-agent`、`module-custom-world`、`module-inventory`、`module-match3d`、`module-npc`、`module-progression`、`module-puzzle`、`module-quest`、`module-runtime`、`module-runtime-item`、`module-runtime-story`、`module-square-hole`、`module-story`、`module-visual-novel`。
|
||||
- 平台副作用：`platform-agent`、`platform-auth`、`platform-image`、`platform-llm`、`platform-oss`、`platform-wechat`、`platform-speech`。
|
||||
- 平台副作用：`platform-agent`、`platform-auth`、`platform-image`、`platform-llm`、`platform-oss`、`platform-speech`。
|
||||
- 共享层：`shared-contracts`、`shared-kernel`、`shared-logging`。
|
||||
- SpacetimeDB：`spacetime-client`、`spacetime-module`。
|
||||
- 测试支撑：`tests-support`。
|
||||
@@ -35,7 +35,6 @@ SpacetimeDB 版本口径：当前 Rust crate `spacetimedb`、`spacetimedb-sdk`
|
||||
4. 后端访问 SpacetimeDB 必须经 `spacetime-client` facade。
|
||||
5. HTTP 鉴权、BFF 聚合、SSE、外部模型编排、OSS 上传和第三方回调在 `api-server`。
|
||||
6. 前端共享 DTO 通过 `shared-contracts` 和 `packages/shared` 对齐，不在页面内重新发明旧接口。
|
||||
7. 微信能力按两层收口：`server-rs/crates/platform-wechat` 承载微信协议 client、订阅消息 `stable_token` / `subscribeMessage.send`、微信支付 V3 / 虚拟支付消息推送的 HTTP header、签名、验签、解密、mock 响应和协议 payload 解析；`server-rs/crates/api-server/src/wechat.rs` 与 `wechat/*` 承载 Axum handler、AppConfig 到平台配置的映射、Genarrative 用户 / 订单 / 钱包 / SSE / 错误 envelope 编排。`platform-auth` 当前仍承载微信 OAuth / 小程序登录 provider 协议，`api-server::wechat::provider` 只作为组合根 adapter，不在业务 handler 内散落 provider 构造。
|
||||
|
||||
验证：
|
||||
|
||||
@@ -54,13 +53,12 @@ npm run check:server-rs-ddd
|
||||
路由树由 `server-rs/crates/api-server/src/app.rs` 统一构造。当前主要分组：
|
||||
|
||||
- 健康检查：`GET /healthz`。
|
||||
- 后台管理：`/admin/api/*`，包括登录、概览、HTTP debug、埋点、表查询、创作入口开关、作品互动配置、作品可见性、兑换码、邀请码、任务配置和充值商品配置。
|
||||
- 后台管理：`/admin/api/*`，包括登录、概览、HTTP debug、埋点、表查询、创作入口开关、作品可见性、兑换码、邀请码、任务配置和充值商品配置。
|
||||
- 认证与账号：`/api/auth/*`、`/api/profile/me`，包括短信、密码、微信、refresh session、多端会话和登出。
|
||||
- 个人中心：`/api/profile/*`，包括钱包流水、任务、领奖、充值、反馈、邀请和兑换等账号侧能力。
|
||||
- 平台基础能力：`/api/llm/*`、`/api/speech/volcengine/*`，只保留通用 LLM 和语音代理。
|
||||
- 资产基础能力：`/api/assets/direct-upload-tickets`、`/api/assets/sts-upload-credentials`、`/api/assets/objects/*`、`/api/assets/read-*`，负责直传、确认、绑定和读取。
|
||||
- 创作 / 游玩支撑能力：`/api/creation-entry/config`、`/api/ai/tasks*`、`/api/runtime/chat/*`、`/api/runtime/settings`、`/api/runtime/save/snapshot`、`/api/profile/browse-history`、`/api/profile/save-archives*`、`/api/profile/play-stats`、`/api/assets/history`、`/api/assets/character-visual/*`、`/api/assets/character-animation/*`、`/api/assets/character-workflow-cache*`、`/api/assets/hyper3d/*`、`/api/runtime/custom-world/asset-studio/*`。
|
||||
- 后台入口配置：`/admin/api/creation-entry/config`、`/admin/api/creation-entry/config/banners` 和 `/admin/api/creation-entry/config/interactions`。
|
||||
- 个人中心：`/api/profile/*`，包括钱包流水、任务、领奖、充值、反馈、邀请、兑换、存档、历史浏览和游玩统计。
|
||||
- LLM 与语音：`/api/llm/*`、`/api/speech/volcengine/*`。
|
||||
- 资产：`/api/assets/*`，包括直传票据、STS、对象确认、实体绑定、读签名、读 bytes、历史资产、角色图像/动画和 Hyper3D 代理。
|
||||
- 创作入口配置：`/api/creation-entry/config`，后台 `/admin/api/creation-entry/config` 和 `/admin/api/creation-entry/config/banners`。
|
||||
- 自定义世界 / RPG：`/api/runtime/custom-world*`、`/api/story/*`、`/api/runtime/chat/*`。
|
||||
- 拼图：`/api/runtime/puzzle/*`。
|
||||
- 抓大鹅 Match3D：`/api/creation/match3d/*`、`/api/runtime/match3d/*`。
|
||||
@@ -71,27 +69,15 @@ npm run check:server-rs-ddd
|
||||
- 跳一跳：`/api/creation/jump-hop/*`、`/api/runtime/jump-hop/*`。
|
||||
- 汪汪声浪：`/api/runtime/bark-battle/*`。
|
||||
- 儿童向创作：`/api/creation/edutainment/*`。
|
||||
- AI task：`/api/ai/tasks*`。
|
||||
|
||||
需要新增路由时，先确认玩法入口配置和 tracking 分类，不要绕过 `app.rs` 的统一中间件、鉴权和入口开关。涉及创作、生成、作品、公开详情、试玩、正式运行态、运行态库存、运行态设置 / 存档、游玩历史、存档归档、游玩统计、AI task、角色资产工坊或玩法生成支撑资产的路由，不再直接在 `app.rs` 逐玩法 `.merge(...)`，也不挂到 `modules/platform.rs`；必须先进入 `server-rs/crates/api-server/src/modules/play_flow.rs` 的统一玩法流程主干，再由主干注册表分发到各领域 HTTP Adapter 或支撑能力 handler。
|
||||
|
||||
### 创作 / 游玩统一流程主干
|
||||
|
||||
`modules/play_flow.rs` 是后端创作与游玩流程的统一入口。现有外部 URL、DTO、错误 envelope、鉴权方式、入口开关语义和 SpacetimeDB schema 默认不变，但路由组织必须遵循：
|
||||
|
||||
1. `app.rs` 只合并 `modules::play_flow::router(state)`，不直接合并 RPG、拼图、抓大鹅、跳一跳、敲木鱼、拼消消、汪汪声浪、视觉小说或儿童向创作等逐玩法模块。
|
||||
2. `play_flow` 统一注册每个玩法的 `playId`、领域模块 key、创作路由前缀和运行态路由前缀；后续新增玩法或迁移旧玩法时，先补这个注册表，再挂具体领域模块路由。
|
||||
3. 新建创作、首次生成和 Remix 成草稿等会产生新创作的入口开关匹配规则同样归 `play_flow` 管理；`creation_entry_config.rs` 只复用该规则执行 `open=false` 熔断，不再维护第二份路径判断。
|
||||
4. `play_flow` 在进入领域 handler 前先解析并挂载 `PlayFlowRequestContext`，统一标记请求处于 `Creation`、`Runtime`、`CreationEntryConfig`、`CreationSupport`、`RuntimeSupport`、`AiTask`、`PublicReadModel` 或 `RuntimeInventory` 阶段，并记录目标 `playId` / 领域模块 key；领域 handler 可以读取该上下文做后续收口，但不能绕过主干自建平行流程。
|
||||
5. `play_flow` 只做平台共性编排和领域 Adapter 组合，不下沉玩法规则；最后一步的草稿编译、资产生成、发布、运行态 start/action/finish、计分和排行榜仍交给对应 `module-*`、`spacetime-module` procedure 和玩法 HTTP handler 处理。
|
||||
6. 公开作品聚合、作品详情、运行态库存、运行态设置 / 存档、游玩历史、存档归档、游玩统计、历史素材、AI task、runtime chat、文档解析、角色资产工坊、角色图像 / 动画生成和 Hyper3D 代理属于跨玩法或玩法支撑流程，也从 `play_flow` 主干挂入；`modules/platform.rs` 只保留通用 LLM / 语音代理，不再承接创作 / 游玩支撑路由。
|
||||
7. 如果某个旧玩法仍使用历史 `/api/runtime/<play>/agent/*` 作为创作命名空间，只保留外部兼容路径；新增实现和文档仍按“统一主干 -> 领域 Adapter”的语义描述，不把历史路径当新架构模板。
|
||||
需要新增路由时，先确认玩法入口配置和 tracking 分类，不要绕过 `app.rs` 的统一中间件、鉴权和入口开关。
|
||||
|
||||
### 认证态用户与会话摘要下发口径
|
||||
|
||||
- `AuthUserPayload` / `AuthUser` 只保留前端当前会用到的身份与绑定展示字段：`id`、`publicUserCode`、`displayName`、`avatarUrl`、`phoneNumber`、`phoneNumberMasked`、`loginMethod`、`bindingStatus`、`wechatBound`、`wechatDisplayName`、`wechatAccount`。账号信息面板展示微信绑定时优先使用 `wechatDisplayName`；该字段只能来自微信平台 profile、历史已保存的微信身份资料，或小程序原生 `input type="nickname"` 提交的 `displayName`，不得用系统账号显示名或“微信旅人”这类假昵称兜底。小程序 `/api/auth/wechat/miniprogram-login` 与 `/api/auth/wechat/bind-phone` 可接收 `displayName`；`/api/auth/wechat/miniprogram-login` 额外返回 `created`，供小程序壳在快捷登录后判断是否需要补采集微信昵称。`jscode2session` 无法直接返回微信昵称或个人微信号，只能稳定拿到小程序维度 `openid`，后端以 `wechatAccount` 下发可区分的绑定账号标识，前端在缺少真实昵称时展示账号尾号。
|
||||
- `AuthSessionSummaryPayload` / `AuthSessionSummary` 只保留设备卡片与撤销需要的摘要字段：`sessionId`、`sessionIds`、`sessionCount`、`clientLabel`、`ipMasked`、`isCurrent`、`createdAt`、`lastSeenAt`、`expiresAt`。
|
||||
- 设备诊断信息（例如原始 `clientType` / `clientRuntime` / `clientPlatform` / `userAgent` / `miniProgramAppId` / `miniProgramEnv` / `deviceDisplayName`）不再默认下发到前端；若未来确需展示，优先单独加窄 DTO，而不是把账号 / 会话快照恢复为全量对象。
|
||||
- 多端登录语义以 `refresh_session` 为粒度：同一账号可保留多个 active session，普通登录不会撤销旧设备；`POST /api/auth/logout` 只撤销当前 refresh session，不提升 `token_version`；`POST /api/auth/logout-all`、改密、重置密码才吊销全端 session 并提升 `token_version`。鉴权中间件仍校验 Bearer `sid` 对应的 refresh session 是否 active，单独踢下线或当前设备退出可以让目标设备立即失效而不误伤其它设备。
|
||||
|
||||
## api-server 模块化演进规则
|
||||
|
||||
@@ -99,8 +85,8 @@ npm run check:server-rs-ddd
|
||||
|
||||
路由模块化规则：
|
||||
|
||||
1. 每个能力 Module 只暴露 `router(state) -> Router<AppState>`；平台创作 / 游玩相关 Module 和支撑能力由 `modules/play_flow.rs` 统一 `.merge(...)` 或在支撑 router 内挂载，其它账号、资产基础、后台和平台基础能力再由 `app.rs` 直接合并。
|
||||
2. `app.rs` 只保留全局 middleware、TraceLayer、request context、tracking middleware、入口开关和少量顶层 glue；不得重新恢复逐玩法 creation/runtime merge 列表。
|
||||
1. 每个能力 Module 只暴露 `router(state) -> Router<AppState>`，由 `app.rs` 统一 `.merge(...)`。
|
||||
2. `app.rs` 只保留全局 middleware、TraceLayer、request context、tracking middleware、入口开关和少量顶层 glue。
|
||||
3. 能力 Module 可在路由内部用 `FromRef<AppState>` 派生自己的 Feature State，例如 `PuzzleApiState`。全局 `AppState` 仍作为进程组合根、鉴权层和全局中间件状态，但业务 handler 优先只提取对应 Feature State，不直接暴露完整 `AppState`。
|
||||
4. Feature State 只暴露该能力实际需要的 facade / adapter / 配置快照；若必须复用仍要求 `AppState` 的横切 helper（例如计费、外部失败审计或通用 tracking），应通过 Feature State 的窄方法或显式 `root_state()` 过渡，并在后续继续收窄。
|
||||
5. 路由迁移和业务重构分阶段处理；先移动路由装配，再拆 handler 内部实现，再收窄 handler 可见状态。
|
||||
@@ -119,20 +105,15 @@ npm run check:server-rs-ddd
|
||||
- `server-rs/crates/api-server/src/puzzle/mappers.rs` 承接 SpacetimeDB record 到 shared-contracts DTO 的映射。
|
||||
- `server-rs/crates/api-server/src/puzzle/tags.rs` 保留拼图标签生成、拼图通用错误映射和 SSE helper。
|
||||
|
||||
拼图发布 / 待发布门槛必须同时要求首图、关卡画面、UI spritesheet 与关卡背景资产包完整；`module-puzzle::validate_publish_requirements` 与 `api-server::puzzle::tags::is_puzzle_session_snapshot_publish_ready` 使用同一资产语言，不得只凭 cover、标题、描述和标签把半成品标为 `publishReady` 或 `ready_to_publish`。
|
||||
|
||||
该拆分只改变 `api-server` 文件组织，不改变 `/api/runtime/puzzle/*` route、DTO、error envelope、SpacetimeDB schema、公开 gallery cache 语义或计费语义；后续继续细分时也必须先保持行为不变，再单独讨论领域规则下沉。
|
||||
|
||||
`/api/runtime/puzzle/runs*` 当前接受 `RuntimePrincipal`，可同时识别登录用户 Bearer 和 runtime guest token。推荐页嵌入运行态的正式开局、交换、拖拽、下一关、暂停、道具与排行榜请求，应由前端在登录态下继续携带账号 access token；匿名游客仅在确认为未登录时走 runtime guest token。不要再把拼图 runtime 当成只认普通 Bearer 的纯账号接口。
|
||||
|
||||
公开正式 runtime 的启动与局内同步动作统一接受 `RuntimePrincipal`，包括拼图、拼消消、跳一跳、敲木鱼、抓大鹅 Match3D、方洞挑战、视觉小说、大鱼吃小鱼和汪汪声浪。登录用户仍使用账号 Bearer；未登录推荐页或公开运行态使用 Runtime Guest Token，后端以 `principal.subject()` 作为本局 owner / player subject，并用 `WorkPlayTrackingDraft::runtime_principal(...)` 记录游玩。创作、个人作品、删除、发布、Remix、点赞等账号或所有权动作不得改成 runtime guest 鉴权。
|
||||
|
||||
抓大鹅 Match3D `api-server` 内部拆分：
|
||||
|
||||
- `server-rs/crates/api-server/src/modules/match3d.rs` 继续负责路由装配和 body limit；对外 handler 名称保持不变。
|
||||
- `server-rs/crates/api-server/src/match3d.rs` 只作为聚合入口，保留共享 import / 常量 / 内部类型、模块声明和 handler re-export。
|
||||
- `server-rs/crates/api-server/src/match3d/handlers.rs` 承接 Axum handler，负责 extract、鉴权上下文、调用 SpacetimeDB facade / 编排 helper，并返回 HTTP 响应。
|
||||
- `/api/runtime/match3d/works/{profile_id}/runs`、`/api/runtime/match3d/runs/{run_id}`、`/click`、`/stop`、`/restart` 与 `/time-up` 属于正式运行态局部请求，必须接受 `RuntimePrincipal`；登录用户使用账号 Bearer，推荐页匿名游客使用 runtime guest token，后端以 principal subject 作为本局 owner，不得退回只认普通 Bearer 的路由。
|
||||
- `server-rs/crates/api-server/src/match3d/draft.rs` 承接 Agent session、草稿编译、题材 / 难度 / 物品计划和草稿持久化编排。
|
||||
- `server-rs/crates/api-server/src/match3d/works.rs` 承接作品 CRUD、封面 / 背景 / 容器资产生成入口、发布 / Remix / 点赞 / 游玩记录和作品级 helper。
|
||||
- `server-rs/crates/api-server/src/match3d/item_assets.rs` 承接物品生成批次编排、append / replace / delete / sort / merge、计费外层和草稿素材映射；sheet prompt、绿幕 / 近白底透明化、切图和切片持久化复用 `generated_asset_sheets` 通用模块。
|
||||
@@ -185,20 +166,10 @@ npm run check:server-rs-ddd
|
||||
7. access JWT 只携带最小设备快照 `device.client_type`、`device.client_runtime`、`device.client_platform`。充值下单按该快照拦截渠道：小程序只允许 `wechat_mp`，手机微信内网页只允许 `wechat_h5`，桌面微信内网页只允许 `wechat_native`。
|
||||
8. 所有微信真实渠道都以微信支付通知或服务端查单确认 `SUCCESS` 为到账事实；小程序、H5 跳转和 Native 二维码返回都不能直接发放泥点或会员。
|
||||
|
||||
## 创作入口泥点扣费契约
|
||||
|
||||
1. `creation_entry_type_config.unified_creation_spec_json` 内的 `mudPointCost` 是玩法新建草稿初始生成的泥点成本真相源，同时供入口卡展示和前端余额前置校验使用；旧契约缺失时允许按代码默认成本兜底。
|
||||
2. `api-server` 执行拼图首图生成、抓大鹅完整草稿生成和汪汪声浪初始三图生成时，必须通过 `GET /api/creation-entry/config` 同源配置解析对应玩法成本后再调用钱包扣费 procedure，不得继续使用前端或后端硬编码常量作为实际扣费真相。
|
||||
3. 结果页单图重生成、发布、道具使用和其它独立资产操作仍按各自业务操作成本执行；不要把初始草稿成本误套到这些单次操作上。
|
||||
4. 资产操作的预扣费必须 fail-closed：钱包或 SpacetimeDB 预扣费不可达、超时或返回业务错误时，`api-server` 直接返回错误，不允许继续调用图片、音频、GLB 等外部生成 provider。
|
||||
5. 需要支持 HTTP retry 的计费 ledger id 必须包含当前请求的 `request_id`；前端 `fetchWithApiAuth` 同一次业务请求的静默刷新重试复用同一个 `x-request-id`，后端不得再使用 prompt 指纹或随机 asset id 作为扣费幂等键。
|
||||
6. 外部生成已预扣费但后续失败时必须先同步调用钱包退款；若 SpacetimeDB 暂不可用，退款请求写入 `wallet-refund-outbox` 本地文件并由后台 worker 重放。默认启用，配置项为 `GENARRATIVE_WALLET_REFUND_OUTBOX_ENABLED`、`GENARRATIVE_WALLET_REFUND_OUTBOX_DIR`、`GENARRATIVE_WALLET_REFUND_OUTBOX_BATCH_SIZE`、`GENARRATIVE_WALLET_REFUND_OUTBOX_FLUSH_INTERVAL_MS` 和 `GENARRATIVE_WALLET_REFUND_OUTBOX_MAX_BYTES`。outbox 文件按 refund ledger id 幂等落盘；成功重放后删除，坏文件隔离为 `corrupt-*`。
|
||||
7. 拼图首图后台生成的跨实例互斥锁必须落在 SpacetimeDB `puzzle_background_compile_task` 表，claim id 由 `task_id + request_id` 构成，释放时必须校验 claim id，避免旧后台任务释放新请求抢到的租约。
|
||||
|
||||
## 外部服务与资产
|
||||
|
||||
- LLM：通用 LLM 门面继续使用 `GENARRATIVE_LLM_*`；创意 Agent `gpt-5` Responses / Chat Completions 文本链路已于 2026-06 从 APIMart 迁移到 VectorEngine，使用 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible client，`api-server` 会把未带 `/v1` 的 VectorEngine base URL 规范化到 `/v1` 后请求 `/responses`。`APIMART_BASE_URL` / `APIMART_API_KEY` 只作为历史残留，不再作为创意 Agent gpt-5 客户端来源；后续排障时优先确认 VectorEngine `/v1/models`、`/v1/chat/completions` 和 `/v1/responses` 可用性。
|
||||
- 图片生成：VectorEngine `gpt-image-2` 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。实际外部生成运行记录统一落 `tracking_event`，`event_key = external_generation_run`，metadata 记录开始 / 结束时间、耗时、状态、成功标记、失败原因、provider task id 和结果摘要，不再写回过时的 `ai_task`。DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。VectorEngine `/v1/images/generations` 和 `/v1/images/edits` 上游 POST 使用 `libcurl` 发送；`reqwest` 只保留给参考图 URL 下载和响应中图片 URL 下载。`/v1/images/edits` 的 multipart 参考图必须作为 libcurl 文件上传 part 发送，字段名为 `image`，实现上使用 `Form::buffer(file_name, bytes)` 并设置 `Content-Type`；不能只用 `contents(...).filename(...)`，否则上游会把请求转码为缺少图片并返回 `image is required`。`request_send` 阶段的 curl timeout / connect error 按可重试传输错误处理，最多尝试 5 次，并使用指数退避加短抖动；排障时优先看 `attempt`、`max_attempts`、`retry_delay_ms`、`reference_image_bytes_total` 和 `request_params`，不要把 `SendRequest` 当成上游业务错误。
|
||||
- LLM：`GENARRATIVE_LLM_*`，创意 Agent 另用 `APIMART_BASE_URL` / `APIMART_API_KEY`。
|
||||
- 图片生成：VectorEngine `gpt-image-2` 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。实际外部生成运行记录统一落 `tracking_event`，`event_key = external_generation_run`，metadata 记录开始 / 结束时间、耗时、状态、成功标记、失败原因、provider task id 和结果摘要，不再写回过时的 `ai_task`。APIMart 只保留给创意 Agent `gpt-5` Responses 文本 / 多模态链路；DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。VectorEngine `/v1/images/generations` 和 `/v1/images/edits` 上游 POST 使用 `libcurl` 发送；`reqwest` 只保留给参考图 URL 下载和响应中图片 URL 下载。`/v1/images/edits` 的 multipart 参考图必须作为 libcurl 文件上传 part 发送，字段名为 `image`，实现上使用 `Form::buffer(file_name, bytes)` 并设置 `Content-Type`；不能只用 `contents(...).filename(...)`，否则上游会把请求转码为缺少图片并返回 `image is required`。`request_send` 阶段的 curl timeout / connect error 按可重试传输错误处理，最多尝试 5 次，并使用指数退避加短抖动；排障时优先看 `attempt`、`max_attempts`、`retry_delay_ms`、`reference_image_bytes_total` 和 `request_params`，不要把 `SendRequest` 当成上游业务错误。
|
||||
- Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端优先按透明 alpha 连通域从该 sheet 识别真实素材矩形并持久化 20 个物品、每个 5 个形态；识别数量不足时才回退 `10*10` 固定网格。通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。
|
||||
- Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。
|
||||
- Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。该容器参考图是后端生图协议输入，必须通过 `include_bytes!` 随 `api-server` 编译进二进制，避免 API 单独发布或运行目录缺少 `public/` 时生成失败。
|
||||
@@ -273,7 +244,7 @@ npm run check:server-rs-ddd
|
||||
- Rust 结构体：`AuthStoreSnapshot`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/auth/tables.rs`
|
||||
|
||||
认证恢复策略：`api-server` 启动时只从 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）投影恢复进程内认证工作集；运行中若 Bearer `sid` 或 refresh cookie 在本进程工作集内未命中，会先从 SpacetimeDB 正式认证表按需刷新一次认证工作集再复查，避免多实例或滚动重启时新登录设备只被签发它的进程认识。`auth_store_snapshot` 只保留行级快照备查，不再作为启动兜底来源。`module-auth` 只保留内存工作集和 JSON 导入 / 导出能力，不再写本地持久化文件；`auth-store.json` / `GENARRATIVE_AUTH_STORE_PATH` 不再是兼容恢复源，也不得在启动时回写覆盖 `auth_identity` / `user_account`。认证创建、登录会话、刷新、退出、改密、重置密码、绑定和资料变更等写操作必须在返回客户端前成功同步 SpacetimeDB 正式认证表；同步失败时接口返回错误，不允许把只存在于当前进程内存的账号或会话当成成功结果。新用户注册奖励、邀请码绑定和登录埋点必须排在认证同步成功之后，避免认证没落库时先写出钱包或邀请关系。若启动恢复阶段 SpacetimeDB 不可连接或超时，`api-server` 会按固定间隔持续重试认证工作集恢复，恢复成功后才开始监听 HTTP，避免一次短超时让进程永久停留在依赖不可用状态。
|
||||
认证恢复策略：`api-server` 启动时只从 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）投影恢复进程内认证工作集；`auth_store_snapshot` 只保留行级快照备查，不再作为启动兜底来源。`module-auth` 只保留内存工作集和 JSON 导入 / 导出能力，不再写本地持久化文件；`auth-store.json` / `GENARRATIVE_AUTH_STORE_PATH` 不再是兼容恢复源，也不得在启动时回写覆盖 `auth_identity` / `user_account`。认证创建、登录会话、刷新、退出、改密、重置密码、绑定和资料变更等写操作必须在返回客户端前成功同步 SpacetimeDB 正式认证表；同步失败时接口返回错误，不允许把只存在于当前进程内存的账号或会话当成成功结果。新用户注册奖励、邀请码绑定和登录埋点必须排在认证同步成功之后，避免认证没落库时先写出钱包或邀请关系。若启动恢复阶段 SpacetimeDB 不可连接或超时，`api-server` 进入依赖不可用模式并对请求返回 `503 SERVICE_UNAVAILABLE`，直到运维恢复 SpacetimeDB 并重启服务。
|
||||
|
||||
`auth_store_snapshot` 禁止再写单行 `snapshot_id = "default"` 聚合 JSON。认证同步入口收到 `module-auth` 整份快照后必须拆成行级记录写入同一张表，当前行键前缀包括：`meta/next_user_id`、`user/<user_id>`、`phone/<phone+user>`、`session/<session_id>`、`session_hash/<hash+session>`、`wechat/<provider_uid+user>`、`union/<union+user>`。SpacetimeDB 模块只保留 `import_auth_store_snapshot_json` 与 `export_auth_store_snapshot_from_tables` 两个认证快照过程；旧 `get_auth_store_snapshot`、`upsert_auth_store_snapshot`、`import_auth_store_snapshot` 兼容入口已删除。导入正式表时只按主键 upsert 本次快照包含的用户、身份和会话，避免过期快照把其他用户整表删除。
|
||||
|
||||
@@ -363,8 +334,8 @@ npm run check:server-rs-ddd
|
||||
|
||||
- Rust 结构体：`CreationEntryConfig`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs`
|
||||
- 字段：`config_id`、`start_title`、`start_description`、`start_idle_badge`、`start_busy_badge`、`modal_title`、`modal_description`、`updated_at`、`event_title`、`event_description`、`event_cover_image_src`、`event_prize_pool_mud_points`、`event_starts_at_text`、`event_ends_at_text`、`event_banners_json`、`public_work_interactions_json`。
|
||||
- 迁移兼容：旧迁移包缺少活动横幅字段时，由 `migration.rs` 写入 `None` / `58000` 默认值；旧库缺少 `event_banners_json` 时写入 `None`，运行态读取层再按 `module-runtime` 默认公告数组归一，不覆盖后台已保存配置，也不把旧结构化 `eventBanner` 升格为前端优先数组。旧库缺少 `public_work_interactions_json` 时写入 `None`，读取层按 `module-runtime` 默认作品互动矩阵补齐 `publicWorkInteractions`，不覆盖后台已保存开关。HTTP 响应同时返回 `eventBanners` 数组、旧 `eventBanner` 单条兼容字段和 `publicWorkInteractions` 互动矩阵；前端优先消费数组与矩阵。后台新公告配置主格式为 HTML 公告字符串数组或 `{title, htmlCode}` 对象数组，旧结构化 banner 字段仅保留兼容。默认公告背景和旧结构化默认 `coverImageSrc` 必须引用 `public/` 下真实存在的静态资源，当前为 `/creation-type-references/puzzle.webp`。
|
||||
- 字段：`config_id`、`start_title`、`start_description`、`start_idle_badge`、`start_busy_badge`、`modal_title`、`modal_description`、`updated_at`、`event_title`、`event_description`、`event_cover_image_src`、`event_prize_pool_mud_points`、`event_starts_at_text`、`event_ends_at_text`、`event_banners_json`。
|
||||
- 迁移兼容：旧迁移包缺少活动横幅字段时，由 `migration.rs` 写入 `None` / `58000` 默认值；旧库缺少 `event_banners_json` 时写入 `None`，运行态读取层再按 `module-runtime` 默认公告数组归一，不覆盖后台已保存配置，也不把旧结构化 `eventBanner` 升格为前端优先数组。HTTP 响应同时返回 `eventBanners` 数组和旧 `eventBanner` 单条兼容字段，前端优先消费数组；后台新配置主格式为 HTML 公告字符串数组或 `{title, htmlCode}` 对象数组，旧结构化 banner 字段仅保留兼容。默认公告背景和旧结构化默认 `coverImageSrc` 必须引用 `public/` 下真实存在的静态资源，当前为 `/creation-type-references/puzzle.webp`。
|
||||
|
||||
### `creation_entry_type_config`
|
||||
|
||||
@@ -443,7 +414,6 @@ npm run check:server-rs-ddd
|
||||
- Rust 结构体：`JumpHopLeaderboardEntryRow`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/jump_hop/tables.rs`
|
||||
- 说明：跳一跳作品维度排行榜 read model，每个 `profile_id + player_id` 只保留 1 条最佳记录；排序口径为成功跳跃次数降序、游戏时长升序、更新时间升序，草稿试玩不作为公开排行榜语义。
|
||||
- 展示契约：`player_id` 只作为后端去重和 `viewerBest` 匹配身份键，不得直接进入 HTTP/UI 展示字段；`/api/runtime/jump-hop/works/{profile_id}/leaderboard` 必须补齐 `displayName`，已登录玩家读取账号显示名，匿名游客展示“游客玩家”，失效账号展示“失效玩家”。
|
||||
|
||||
### `jump_hop_runtime_run`
|
||||
|
||||
@@ -644,12 +614,6 @@ npm run check:server-rs-ddd
|
||||
- Rust 结构体：`PuzzleAgentSessionRow`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
|
||||
|
||||
### `puzzle_background_compile_task`
|
||||
|
||||
- Rust 结构体：`PuzzleBackgroundCompileTaskRow`
|
||||
- 源码：`server-rs/crates/spacetime-module/src/puzzle.rs`
|
||||
- 说明：拼图首图后台生成的跨 api-server 实例互斥 claim 表，只保存活动任务租约，不表达最终生成结果；`task_id` 为主键，`claim_id` 用于释放时防止误删新租约，租约超时时间为 30 分钟。
|
||||
|
||||
### `puzzle_event`
|
||||
|
||||
- Rust 结构体：`PuzzleEvent`
|
||||
@@ -762,8 +726,8 @@ npm run check:server-rs-ddd
|
||||
|
||||
跨玩法公开作品列表 / 详情主读模型是 `public_work_gallery_entry` 与 `public_work_detail_entry`。拼图、自定义世界等旧玩法公开列表 HTTP 路由保留原响应 shape，由 BFF mapper 从统一 public cache 映射回当前 DTO；旧 `*_gallery_card_view` / `*_gallery_view` / `custom_world_gallery_entry` 继续作为 source view 和兼容缓存。各玩法的个人作品列表、详情、发布、点赞、游玩记录、Remix 和其它需要鉴权或写入副作用的路径继续走 procedure / reducer；不要为了公开列表性能把这些 owner-specific 或 mutation 语义混进 public view。
|
||||
|
||||
`GET /api/creation-entry/config`、入口熔断和公开作品互动熔断优先从订阅 cache 读取创作入口配置；cache 缺失时使用最近一次成功读取的内存快照，再兜底调用 `get_creation_entry_config` procedure 完成空库种子或旧库兼容。
|
||||
入口配置快照包含 start card、类型弹窗、公告位兼容字段、入口类型列表和 `publicWorkInteractions` 作品互动矩阵；入口类型列表新增 `category_id`、`category_label`、`category_sort_order` 后，后台 upsert、`shared-contracts`、`module-runtime` 和 `spacetime-client` binding 必须同步，旧迁移 JSON 通过 `migration.rs` 默认值兼容。作品互动矩阵是全局公开作品详情能力配置，不属于单个 `creation_entry_type_config`；后台通过 `/admin/api/creation-entry/config/interactions` 保存，前端据此隐藏或拦截已接入的点赞 / Remix 入口，api-server 同时对已接入后端动作执行 `public_work_interaction_disabled` 熔断。
|
||||
`GET /api/creation-entry/config` 和入口熔断优先从订阅 cache 读取创作入口配置；cache 缺失时使用最近一次成功读取的内存快照，再兜底调用 `get_creation_entry_config` procedure 完成空库种子或旧库兼容。
|
||||
入口配置快照包含 start card、类型弹窗、公告位兼容字段和入口类型列表；入口类型列表新增 `category_id`、`category_label`、`category_sort_order` 后，后台 upsert、`shared-contracts`、`module-runtime` 和 `spacetime-client` binding 必须同步，旧迁移 JSON 通过 `migration.rs` 默认值兼容。
|
||||
|
||||
RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；历史 `custom-world` 路由仍是 RPG 的工程域与运行态源类型。入口熔断把 `/api/runtime/custom-world*`、`/api/story/*` 和 `/api/runtime/chat/*` 统一映射到 `rpg`，不要新增平行 `airp` 路由或用 `airp` 接管当前文字冒险链路。
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# 本地开发验证与生产运维
|
||||
# 本地开发验证与生产运维
|
||||
|
||||
更新时间：`2026-06-09`
|
||||
更新时间：`2026-06-05`
|
||||
|
||||
## 标准开发流程
|
||||
|
||||
@@ -55,8 +55,6 @@ Linux 本机多用户并发开发时，`npm run dev` 和 `npm run dev:*` 单模
|
||||
|
||||
微信小程序虚拟支付使用 `WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_OFFER_ID`、`WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_APP_KEY`、`WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_SANDBOX_APP_KEY` 和 `WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_ENV` 配置。小程序充值统一走 `wechat_mp_virtual` / `wx.requestVirtualPayment`：泥点属于代币（`coin`），`buyQuantity` 按当前充值商品快照里的 `points_amount` 传；会员和后台新增道具类商品走 `short_series_goods`，`productId` 对应微信后台道具 ID。旧登录快照若缺 `session_key`，需要用户在小程序内重新登录后再支付；客户端成功回调不是最终到账，仍以后端通知或查询确认订单为准。详细口径见 `docs/【技术方案】微信虚拟支付接入-2026-05-26.md`。
|
||||
|
||||
微信小程序订阅消息生成结果通知使用 `WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_ENABLED`、`WECHAT_MINIPROGRAM_GENERATION_RESULT_TEMPLATE_ID` 和 `WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_STATE` 配置。当前模板为 `AI创作生成结果通知`；H5 在生成动作发起前先进入生成进度态并立即继续生成动作，同时非阻塞跳转到小程序原生订阅授权页尝试请求授权，用户接受、拒绝或返回都不能阻塞生成，且原生页不改写上一页 `webViewUrl`，避免返回后丢失 H5 当前进度页状态。后端只在玩法草稿生成成功或失败终态后用微信登录保存的 openid 调用 `subscribeMessage.send`，发送失败只打 warning，不影响生成主链路。模板 `thing1` 字段发送玩法模板名，例如 `拼图`、`敲木鱼`、`抓大鹅`；`number6` 字段发送本次生成结算后的实际泥点扣除，失败退款后固定为 `0`。模板 `time4` 字段固定发送北京时间 `YYYY-MM-DD HH:mm`，不要使用内部微秒时间戳、秒级时间戳或带时区后缀的 RFC3339 字符串，否则微信会返回 `argument invalid! data.time4.value invalid`。当前已接入拼图、敲木鱼、抓大鹅、跳一跳、方洞、视觉小说的草稿生成终态；分槽素材生成或发布动作不得直接复用生成结果通知，避免一次作品生成产生多条订阅消息。
|
||||
|
||||
如果本地 `GET /api/creation-entry/config` 返回 `No such procedure`，或 `api-server` 日志出现 `no such table: puzzle_gallery_card_view` / `no such table: wooden_fish_gallery_card_view` 这类公开 view 缺失，通常是 `.env.local` 指向的 SpacetimeDB 库还没有发布当前 `spacetime-module`，或当前 CLI 身份无权发布该库。debug 构建的 `api-server` 会临时使用后端默认入口配置兜底，避免创作作品架整块消失；正式修复仍应切换到拥有目标库权限的 SpacetimeDB 身份后重新运行 `npm run dev` 完成发布，或用 gitignored 的 `spacetime.local.json` 指向可发布的本地库。
|
||||
|
||||
本地排查 schema 漂移时，先用当前 dev server 显式查询目标库，例如：
|
||||
@@ -69,11 +67,11 @@ spacetime sql <database> "SELECT * FROM puzzle_gallery_card_view LIMIT 1" --serv
|
||||
|
||||
本地 `npm run dev:spacetime` 发布模块时必须显式忽略仓库根目录的 `spacetime.json`，由脚本固定追加 `--no-config` 并使用命令参数里传入的数据库名和 `--server http://127.0.0.1:3101`。否则 CLI 可能把发布目标改写到配置文件里的其他数据库，导致 `dev:spacetime` 启动后又因发布失败自动退出，浏览器随后会在 `ws://127.0.0.1:3101/v1/database/.../subscribe` 看到连接拒绝。
|
||||
|
||||
本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.4.1`。若版本错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value`，api-server 最终表现为敲木鱼等创作动作的 `SpacetimeDB procedure 调用超时`。排障时先运行 `spacetime --version`，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."`；需要切版本时执行 `spacetime version install <version> && spacetime version use <version>`，然后重新启动 `npm run dev:spacetime`。当前 `scripts/dev.mjs` 会在启动和复用本地 SpacetimeDB 前写入并校验 `dev-spacetime-tool-version`，避免把旧 standalone 继续带进新一轮创作。
|
||||
本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.3.0`。若版本错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value`，api-server 最终表现为敲木鱼等创作动作的 `SpacetimeDB procedure 调用超时`。排障时先运行 `spacetime --version`，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."`；需要切版本时执行 `spacetime version install <version> && spacetime version use <version>`，然后重新启动 `npm run dev:spacetime`。当前 `scripts/dev.mjs` 会在启动和复用本地 SpacetimeDB 前写入并校验 `dev-spacetime-tool-version`，避免把旧 standalone 继续带进新一轮创作。
|
||||
|
||||
本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查 RPG / 拼图 / 抓大鹅等 VectorEngine 生图链路时，确认 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git。VectorEngine `gpt-image-2` 图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`；`api-server` 只做配置、玩法编排、OSS / asset 持久化、计费和失败审计落库。开局 CG 故事板、首图、背景和图集都属于长耗时图片请求；后端默认会把 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 下限收口到 `1000000`，旧进程仍可能沿用重启前的短超时。若 VectorEngine 在 `send()` 阶段失败且日志显示 `SendRequest`，先看同一 `request_id` 的 provider 日志字段 `source`、`source_chain`、`source_chain_depth`，再查 `external_api_call_failure.metadata_json.errorSource`；当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。拼图关卡资产按 `level_scene -> ui_spritesheet -> level_background` 顺序生成，日志会带 `slot`、`asset_kind` 和 `elapsed_ms`。
|
||||
|
||||
VectorEngine 图片生成 / 编辑在 `request_send` 阶段出现 `timeout`、`connect`、libcurl 35 SSL connect reset、libcurl 56 receive error / `unexpected eof while reading`、recv failure 等临时传输错误，或在 `upstream_status` 阶段收到 408 / 429 / 5xx（例如 Nginx HTML `502 Bad Gateway`）时，`platform-image` 会对同一请求最多发送 5 次；multipart 图片编辑每次重试都会重新构造 form，避免复用已消费的 body。日志中 `VectorEngine 图片请求发送失败，准备重试` 或 `VectorEngine 图片上游状态可重试，准备重试` 表示本次失败已进入下一次尝试；最终仍失败时才会写入 `external_api_call_failure` 并返回 504 / 502。排查生产失败时应同时统计 retry 前的尝试日志和最终 audit，避免把一次用户请求内的多次发送误判成多个用户请求。
|
||||
VectorEngine 图片生成 / 编辑在 `request_send` 阶段出现 `timeout` 或 `connect` 错误时，`platform-image` 会对同一请求最多发送 3 次；multipart 图片编辑每次重试都会重新构造 form，避免复用已消费的 body。日志中 `VectorEngine 图片请求发送失败，准备重试` 表示本次失败已进入下一次尝试；最终仍失败时才会写入 `external_api_call_failure` 并返回 504。排查生产失败时应同时统计 retry 前的尝试日志和最终 audit，避免把一次用户请求内的多次发送误判成多个用户请求。
|
||||
|
||||
拼图入口直创的 `compile_puzzle_draft` 是长耗时链路：后端会先快速编译草稿并返回 `image_refining` / `generating` 快照，然后在 api-server 后台任务中完成首图、UI 资产、OSS 持久化、作品投影、计费退款和失败态回写。生产排查小程序 `Failed to fetch` 时，若 Nginx access log 里 action POST 是 `499`、`upstream_status=-`，说明客户端或 WebView 先断开；此时不应再把长 POST 是否返回作为生成成败依据，而应继续按实际 `session_id` 查后台任务日志、VectorEngine provider 日志、`external_api_call_failure` 和后续 GET 轮询结果。同一用户可能先轮询旧的 `puzzle-session-*`，随后 POST 新建实际生成 session；必须用 action POST 的 `request_id` 和 `/api/runtime/puzzle/agent/sessions/<session_id>/actions` 路径对齐真实失败请求，避免被前端显示的“来源草稿”误导。
|
||||
|
||||
@@ -96,7 +94,6 @@ npm run admin-web:typecheck
|
||||
```bash
|
||||
npm run check:encoding
|
||||
npm run check:spacetime-schema
|
||||
npm run check:production-ops
|
||||
npm run check:server-rs-ddd
|
||||
npm run lint:eslint
|
||||
npm run typecheck
|
||||
@@ -215,10 +212,10 @@ UI 相关修改要重点验证：
|
||||
数据库备份不放进 `spacetime-module` reducer / procedure：备份属于文件系统与 OSS 外部副作用，必须由运维脚本在 SpacetimeDB 宿主外执行。当前统一脚本为；生产 provision 还会安装 `genarrative-database-backup.timer`，每天 `03:20` 左右自动执行一次 OSS 冷备份：
|
||||
|
||||
```bash
|
||||
npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.service --restart-service-after genarrative-api.service
|
||||
npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.service
|
||||
```
|
||||
|
||||
脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service` 依赖 `spacetimedb.service`，生产定时冷备份还必须传入 `--restart-service-after genarrative-api.service`，确保备份后 API 随数据库一起恢复。`2026-06-10` release 故障就是现场 unit 漏掉该参数，`03:20` 冷备份停止 SpacetimeDB 后 API 被依赖关系一并停止，备份脚本只恢复了 SpacetimeDB，API 直到人工重启前都不可用；后续现场变更、provision 模板和 Jenkins 归档都必须通过 `npm run check:production-ops` 防止回退。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用后台 `node ... --upload-archive <tar.gz>` 上传同一份发布前备份，不等待上传完成。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
|
||||
脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用后台 `node ... --upload-archive <tar.gz>` 上传同一份发布前备份，不等待上传完成。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
|
||||
|
||||
生产环境变量模板在 `deploy/env/api-server.env.example`：
|
||||
|
||||
@@ -235,17 +232,6 @@ GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET=
|
||||
|
||||
`GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET` 为空时会回退 `ALIYUN_OSS_BUCKET`；AccessKey 默认复用 `ALIYUN_OSS_ACCESS_KEY_ID` / `ALIYUN_OSS_ACCESS_KEY_SECRET`，也可用 `GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID` / `GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET` 为备份 bucket 单独配置最小权限账号。`Genarrative-Server-Provision` 会创建 `/var/lib/genarrative/database-backups` 并归属 `genarrative:genarrative`，同时安装并启用 `genarrative-database-backup.timer`。手动检查定时器：`systemctl list-timers genarrative-database-backup.timer`；手动触发一次：`systemctl start genarrative-database-backup.service`。
|
||||
|
||||
冷备份后必须做一次只读验收，不要只看 `genarrative-database-backup.service` 是否成功退出：
|
||||
|
||||
```bash
|
||||
systemctl is-active spacetimedb.service genarrative-api.service nginx.service
|
||||
curl -fsS --max-time 5 http://127.0.0.1:3101/v1/ping
|
||||
curl -fsS --max-time 5 http://127.0.0.1:8082/healthz
|
||||
curl -fsS --max-time 5 http://127.0.0.1:8082/readyz
|
||||
curl -fsS --max-time 5 http://127.0.0.1/api/creation-entry/config >/dev/null
|
||||
curl -fsS --max-time 5 http://127.0.0.1/api/runtime/puzzle/gallery >/dev/null
|
||||
```
|
||||
|
||||
## 生产运维
|
||||
|
||||
生产部署当前口径：
|
||||
@@ -256,47 +242,18 @@ Nginx 负责站点和反向代理
|
||||
Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
|
||||
```
|
||||
|
||||
### 生产健康巡检
|
||||
|
||||
`Genarrative-Server-Provision` 会安装并启用 `genarrative-health-patrol.timer`，默认每 5 分钟运行一次 `genarrative-health-patrol.service`。巡检脚本随 API release 归档到 `/opt/genarrative/current/scripts/ops/production-health-patrol.mjs`，只读检查：
|
||||
|
||||
- `genarrative-api.service`、`spacetimedb.service`、`nginx.service` 是否 active。
|
||||
- API 直连 `/healthz`、`/readyz`。
|
||||
- SpacetimeDB 直连 `/v1/ping`。
|
||||
- 默认直连 API 端口检查 `/api/creation-entry/config`、`/api/runtime/puzzle/gallery`、`/api/runtime/custom-world-gallery`；如需走 Nginx / 公网域名，在 `/etc/genarrative/health-patrol.env` 配置 `GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL=https://<域名>`。
|
||||
- 最近 15 分钟 `genarrative-api.service`、`spacetimedb.service`、`nginx.service` 的 `err..alert` 日志。
|
||||
|
||||
巡检输出总状态 `OK / WARNING / CRITICAL`；只有 `CRITICAL` 默认让 systemd service 失败，`WARNING` 只写日志和状态文件，避免历史日志噪声把 timer 长期打成失败。最近一次结果写入 `/var/lib/genarrative/health-patrol/status.json`。手动执行：
|
||||
|
||||
```bash
|
||||
systemctl start genarrative-health-patrol.service
|
||||
systemctl status genarrative-health-patrol.service --no-pager
|
||||
journalctl -u genarrative-health-patrol.service -n 80 --no-pager
|
||||
cat /var/lib/genarrative/health-patrol/status.json
|
||||
```
|
||||
|
||||
如需接外部告警，可在 `/etc/genarrative/health-patrol.env` 配置 `GENARRATIVE_HEALTH_PATROL_WEBHOOK_URL`；脚本只会在 `WARNING` 或 `CRITICAL` 时向该 webhook 发送 JSON。未配置 webhook 时，告警来源是 systemd 失败状态、journal 和状态文件。
|
||||
|
||||
`Genarrative-Web-Build` 的主站构建失败若出现 Rollup 报错 `"xxx" is not exported by "src/services/publicWorkCode.ts"`，优先按前端公开作品号工具缺失处理，而不是排查 Jenkins 节点环境。修复时要让 `publicWorkCode.ts` 的 `build<Play>PublicWorkCode` 与 `isSame<Play>PublicWorkCode` 成对导出，并补 `src/services/publicWorkCode.test.ts` 覆盖对应玩法前缀；随后用 `npm run build:production-release -- --component web --name <临时名>` 复现 Jenkins web 构建路径。
|
||||
|
||||
`Genarrative-Web-Build` 会把 `build/<version>/web.tar.gz`、`web.tar.gz.sha256`、`release-manifest.json` 和 `scripts/deploy/production-web-deploy.sh` 直接归档为 Jenkins 构建产物；`Genarrative-Web-Deploy` 只通过 `copyArtifacts` 从指定上游构建复制这些产物和部署脚本，不再在目标机器 checkout Git，再执行随构建归档的 `scripts/deploy/production-web-deploy.sh`。Web 发布不再读取构建机本地缓存目录，也不再通过 release agent `rsync` 回构建机拉取大包；如果 deploy 找不到 `web.tar.gz`，应先检查上游 Web Build 是否按同一 `BUILD_VERSION` 成功归档产物。
|
||||
|
||||
`Genarrative-Api-Build` 的 Jenkins 归档产物必须包含 `build/<version>/api-server`、`api-server.sha256`、`release-manifest.json`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`scripts/deploy/production-api-deploy.sh`、`scripts/deploy/maintenance-on.sh` 和 `scripts/deploy/maintenance-off.sh`。`deploy/systemd/genarrative-database-backup.service` 从 `/opt/genarrative/current/scripts/database-backup-to-oss.mjs` 执行冷备份，`deploy/systemd/genarrative-health-patrol.service` 从 `/opt/genarrative/current/scripts/ops/production-health-patrol.mjs` 执行巡检；`Genarrative-Api-Deploy` 会从上游 API 构建产物复制部署脚本、备份脚本和巡检脚本，不再在目标机器 checkout Git。如果 API 发布后 current release 中缺少这些脚本，应先检查 `Genarrative-Api-Build` 的 `archiveArtifacts` 和 `Genarrative-Api-Deploy` 的 `copyArtifacts` 过滤器是否仍包含 `build/<version>/scripts/database-backup-to-oss.mjs` 与 `build/<version>/scripts/ops/production-health-patrol.mjs`，不要只在部署机工作区手工补文件。
|
||||
|
||||
`Genarrative-Stdb-Module-Build` 的 Jenkins 归档产物必须包含 `build/<version>/spacetime_module.wasm`、`spacetime_module.wasm.sha256`、`release-manifest.json`、`scripts/deploy/production-stdb-publish.sh`、`scripts/deploy/maintenance-on.sh`、`scripts/deploy/maintenance-off.sh` 和 `scripts/database-backup-to-oss.mjs`。`Genarrative-Stdb-Module-Publish` 只通过 `copyArtifacts` 复制这些产物和发布脚本，不再在目标机器 checkout Git；如果 publish 前备份脚本缺失，应先检查 Stdb Build 的归档列表和 Stdb Publish 的复制过滤器。
|
||||
`Genarrative-Web-Build` 会把 `build/<version>/web.tar.gz`、`web.tar.gz.sha256` 和 `release-manifest.json` 直接归档为 Jenkins 构建产物；`Genarrative-Web-Deploy` 只通过 `copyArtifacts` 从指定上游构建复制这些产物，再执行 `scripts/deploy/production-web-deploy.sh`。Web 发布不再读取构建机本地缓存目录，也不再通过 release agent `rsync` 回构建机拉取大包；如果 deploy 找不到 `web.tar.gz`，应先检查上游 Web Build 是否按同一 `BUILD_VERSION` 成功归档产物。
|
||||
|
||||
`Genarrative-Web-Build` 打包 `web.tar.gz` 前、`Genarrative-Web-Deploy` 解包后都会把 Web 静态目录规范为目录 `755`、文件 `644`。如果前端页面能打开但 public 图片、字体或音频返回 `403 Forbidden`，优先检查当前 `/srv/genarrative/web` 指向的 release 中对应文件权限是否被异常归档为 `600`，临时恢复可对该 release 的 `web` 目录执行目录 `755`、文件 `644` 的权限修正。
|
||||
|
||||
生产 Jenkins 的 `Pipeline script from SCM` 由 Jenkins controller 读取 Jenkinsfile。`Genarrative-Server-Provision` 是服务器初始化流水线，Job 配置里的 SCM URL 必须使用 controller 本机可访问的仓库路径或内网 Gitea 地址，不能使用 `https://git.genarrative.world/...`；否则日志一开始的 `Checking out git ... to read jenkins/Jenkinsfile.production-server-provision` 就会先从公网拉 Jenkinsfile。构建类流水线仍按各自 Jenkinsfile 的 checkout 口径执行；所有 `GitSCM checkout` 都必须保留单分支 refspec、`shallow=true`、`depth=1`、`noTags=true` 与 `honorRefspec=true`。API / Web / Stdb 发布类流水线不在目标机器 checkout Git，统一执行上游构建归档里的部署脚本，避免产物 commit 与部署脚本 commit 漂移。
|
||||
|
||||
dev 服务器上的 Gitea 内网入口固定为 `http://10.2.0.10/GenarrativeAI/Genarrative.git`，用于 release / dev 等内网 agent 直接拉取仓库，避免绕公网 `git.genarrative.world`。该入口由 dev Nginx `/etc/nginx/conf.d/gitea-internal.conf` 暴露，只允许 `10.2.0.0/16` 和本机访问；Gitea 进程自身仍只监听 `127.0.0.1:3000`，公网域名 `https://git.genarrative.world/` 继续走原有 TLS 反代。验证时从 release 执行 `git ls-remote http://10.2.0.10/GenarrativeAI/Genarrative.git HEAD`，应能直接返回 HEAD。
|
||||
|
||||
`scripts/jenkins-checkout-source.sh` 是生产 Jenkinsfile 内部二次确认源码的统一入口。构建流水线和服务器初始化流水线传入 `COMMIT_HASH` 时，脚本必须先保持 `depth=1` 浅拉，若上游 commit 已在浅历史内则直接校验并 checkout；只有浅历史无法证明 commit 属于目标分支时，才按 `GENARRATIVE_JENKINS_CHECKOUT_DEEPEN_STEPS`（默认 `50 200 1000 5000`）逐步加深，最后才尝试展开完整历史。`Genarrative-Api-Deploy`、`Genarrative-Web-Deploy` 和 `Genarrative-Stdb-Module-Publish` 仍保留上游构建传入的 `COMMIT_HASH` 作为通知和追溯字段，但不再用它在目标机器重新 checkout 部署脚本。
|
||||
生产 Jenkins 的 `Pipeline script from SCM` 由 Jenkins controller 读取 Jenkinsfile。`Genarrative-Server-Provision` 是服务器初始化流水线，Job 配置里的 SCM URL 必须使用 controller 本机可访问的仓库路径或内网 Gitea 地址，不能使用 `https://git.genarrative.world/...`；否则日志一开始的 `Checking out git ... to read jenkins/Jenkinsfile.production-server-provision` 就会先从公网拉 Jenkinsfile。其它构建 / 发布流水线仍按各自 Jenkinsfile 的 checkout 口径执行；所有 `GitSCM checkout` 都必须保留单分支 refspec、`shallow=true`、`depth=1`、`noTags=true` 与 `honorRefspec=true`。
|
||||
|
||||
|
||||
`Genarrative-Stdb-Module-Publish` 在 `Pipeline script from SCM` 阶段如果一开始就报 `No such DSL method 'pipeline'`，优先检查 `jenkins/Jenkinsfile.production-stdb-module-publish` 是否带 UTF-8 BOM。Jenkins Declarative Pipeline 的首个 token 必须是纯 `pipeline`；仓库中的 Jenkinsfile 应保存为 UTF-8 without BOM，只有临时写给 Windows PowerShell 5.1 `-File` 执行的 `.ps1` 才需要按对应 helper 转成带 BOM。验证时可检查文件前三字节不再是 `EF BB BF`，并运行 `validateDeclarativePipeline` 或重放该流水线。
|
||||
|
||||
`Genarrative-Stdb-Module-Build` 或 SpacetimeDB module 构建失败若出现 Rust `E0425 cannot find function migrate_*`，优先排查 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs` 等同文件内默认种子迁移 helper 是否在分支合并时只保留了调用、漏掉了函数定义。`Genarrative-Stdb-Module-Build` 现在运行在 `linux && genarrative-build` 节点上，Checkout 与 Build 都走 bash + cargo + sccache，不再依赖 Windows PowerShell 或 Git Bash；Stdb module 的 `CARGO_HOME`、`CARGO_TARGET_DIR` 和 `SCCACHE_DIR` 默认落在稳定缓存根 `~/caches/genarrative-jenkins/stdb-module` 下，可用 `GENARRATIVE_STDB_CACHE_ROOT` 覆盖，避免 `WORKSPACE@tmp` 被清理后无改动也触发近似冷构建。修复时不要直接删除迁移调用；应恢复只纠偏历史默认种子且不覆盖后台手动配置的 helper，并用 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 复现 Jenkins module 编译路径。
|
||||
`Genarrative-Stdb-Module-Build` 或 SpacetimeDB module 构建失败若出现 Rust `E0425 cannot find function migrate_*`，优先排查 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs` 等同文件内默认种子迁移 helper 是否在分支合并时只保留了调用、漏掉了函数定义。`Genarrative-Stdb-Module-Build` 现在运行在 `linux && genarrative-build` 节点上，Checkout 与 Build 都走 bash + cargo + sccache，不再依赖 Windows PowerShell 或 Git Bash。修复时不要直接删除迁移调用；应恢复只纠偏历史默认种子且不覆盖后台手动配置的 helper，并用 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 复现 Jenkins module 编译路径。
|
||||
|
||||
`Genarrative-Server-Provision` 只做服务器初始化，不再承担构建职责。流水线全程运行在目标服务器 agent：`DEPLOY_TARGET=development` 使用 `linux && genarrative-dev-deploy`，`DEPLOY_TARGET=release` 使用 `linux && genarrative-release-deploy`；`Prepare Provision Tools` 也在同一个目标 agent 工作区内准备 SpacetimeDB 与 `otelcol-contrib` 交付件，不再切到 `linux && genarrative-build`，也不再 stash 给后续阶段。`SOURCE_GIT_REMOTE_URL` 必须显式填写为目标 agent 可访问的本机路径、`file:///` 地址、localhost / 127.0.0.1、RFC1918 内网 HTTP Git 地址、单标签内网主机名或 `.local` / `.lan` / `.internal` 地址；这条流水线不配置公网 Git 备用地址，目标 agent 拉不到内网源就应直接失败。真实初始化会写入 `/etc` / systemd / Nginx、创建系统用户并修改服务，目标 dev / release agent 非 dry-run 时都必须具备 root 权限。
|
||||
|
||||
@@ -308,10 +265,9 @@ dev 服务器上的 Gitea 内网入口固定为 `http://10.2.0.10/GenarrativeAI/
|
||||
|
||||
- `api-server` 生产模板默认 `GENARRATIVE_API_LISTEN_BACKLOG=1024`、`GENARRATIVE_API_WORKER_THREADS=4`；本地未设置 worker threads 时继续使用 Tokio 默认值。
|
||||
- `GENARRATIVE_API_MAX_CONCURRENT_REQUESTS=512` 开启应用内 HTTP 并发背压；`GENARRATIVE_API_GALLERY_MAX_CONCURRENT_REQUESTS=320`、`GENARRATIVE_API_DETAIL_MAX_CONCURRENT_REQUESTS=64`、`GENARRATIVE_API_ADMIN_MAX_CONCURRENT_REQUESTS=16` 分别限制公开列表、公开详情和后台 API 热路径。超过许可时直接返回 `429 Too Many Requests` 和 `Retry-After: 1`，`/healthz` 与 `/readyz` 不受该限制。这些值不是 RPS 限速；如果压测中 429 上升但内存和 p95 收敛，说明背压正在保护进程。直连 `api-server` 的极高 RPS 压测若出现 `connection refused`，通常已经打到 TCP 监听 / accept 层，应同时检查 backlog、Nginx upstream keepalive 和前置限流。
|
||||
- `api-server` 正常运行时 `/healthz` 只返回进程存活状态，`/readyz` 会同时检查进程是否仍接收新流量和 SpacetimeDB 连接租约是否健康；收到 `SIGINT` / `SIGTERM` 后会先把 readiness 标记为不可用，再让 Axum 停止接新连接并等待已有 HTTP 请求排空。systemd 仍以 `KillSignal=SIGINT` 停服务，`TimeoutStopSec=90` 作为长请求排空上限。
|
||||
- SpacetimeDB 健康检查默认使用 `GENARRATIVE_SPACETIME_HEALTH_CHECK_TIMEOUT_SECONDS=2` 的短等待窗口，和业务 procedure 的 `GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS` 分开。`/readyz` 失败时 `details.spacetime.stage` 会标出当前卡住阶段：`pool_acquire`、`connect_build`、`connect_handshake`、`read_model_subscribe`、`procedure_result`、`reducer_result` 或 `read_cache`；`elapsedMs` / `timeoutMs` 用于确认是否命中健康检查窗口。业务请求日志也会写入 `operation_kind`、`operation_name`、`spacetime_stage` 和 `elapsed_ms`，后续 45 秒超时不再只靠 Nginx `request_time=45s` 推断。
|
||||
- `api-server` 正常运行时 `/healthz` 返回进程存活状态，`/readyz` 返回是否仍接收新流量；收到 `SIGINT` / `SIGTERM` 后会先把 readiness 标记为不可用，再让 Axum 停止接新连接并等待已有 HTTP 请求排空。systemd 仍以 `KillSignal=SIGINT` 停服务，`TimeoutStopSec=90` 作为长请求排空上限。
|
||||
- `genarrative-api.service` 设置 `LimitNOFILE=65535`、`TasksMax=2048`；上线后用 `systemctl show genarrative-api.service -p LimitNOFILE -p TasksMax -p TimeoutStopUSec` 和 `cat /proc/$(pidof api-server)/limits` 核对。
|
||||
- Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转工具包。`Prepare Provision Tools` 在目标 dev / release agent 工作区内先检查 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current`：版本已满足时直接复用目标机现有文件生成 `provision-tools/`，只有缺失或版本不匹配时才使用 `PROVISION_DOWNLOADS_DIR` 里的本地包或从配置的下载源准备 SpacetimeDB `2.4.1` / `otelcol-contrib 0.151.0`；如果目标服务器下载需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
|
||||
- Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转工具包。`Prepare Provision Tools` 在目标 dev / release agent 工作区内准备 `spacetime-x86_64-unknown-linux-gnu.tar.gz` 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz` 并生成 `provision-tools/`；如果目标服务器下载需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
|
||||
- 除 `Genarrative-Server-Provision` 外，`Genarrative-Stdb-Module-Build`、`Genarrative-Web-Build`、`Genarrative-Api-Build`、`Genarrative-*Deploy`、`Genarrative-Database-Import/Export`、`Genarrative-Full-Build-And-Deploy` 和 `Genarrative-Notify-Email` 的生产流水线现都以 Linux agent 为主，仍按各自 Jenkinsfile 的 checkout 口径执行。Server provision 不使用公网备用 Git 源。
|
||||
- `otelcol-contrib.service` 作为可选系统服务加入 provision，默认监听 `127.0.0.1:4317/4318` 并使用 `deploy/otelcol/genarrative-debug.yaml`。api-server 是否发送 OTLP 仍由 `GENARRATIVE_OTEL_ENABLED` 控制，服务 unit 见 `deploy/systemd/otelcol-contrib.service`。
|
||||
- Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；`limit_conn` 负责连接 / 并发保护，`limit_req` 负责入口 RPS 快拒绝。当前模板把公开 gallery list 单独放到 `genarrative_gallery_rps`，默认 `rate=5000r/s`、`burst=4096`、`limit_conn=320`；公开详情和普通 API 放到 `genarrative_api_rps`，后台 API 放到 `genarrative_admin_rps`。通用 `/api` location 设置 `client_max_body_size 64m` 是反代兜底，防止拼图入口页 / 新增关卡本地参考图 Data URL 或旧兼容请求在到达 `api-server` 前被默认 1 MiB 上限拦截；拼图本地参考图前后端统一限制 6MB，历史图片仍提交 `referenceImageAssetObjectId(s)`。若线上出现 `413 Request Entity Too Large` 且 access log 中 `request_time=0.000`、`upstream_status=-`，说明请求在 Nginx 层被拦截，先用 `nginx -T | grep client_max_body_size` 检查 release 模板是否已渲染并 reload，同时检查前端是否超出 6MB 或错误提交了未压缩大图。`limit_conn_status 429` 和 `limit_req_status 429` 必须在 HTTP 与 HTTPS server 中同时生效；若线上压测看到 `limiting connections by zone "genarrative_api_conn"` 却返回 503，优先检查 `nginx -T` 里 HTTPS server 是否缺少这些状态码，以及 `/api/runtime/puzzle/gallery` 是否误落到通用 `location ~ ^/api` 的 `limit_conn=64`。压测时看 `/var/log/nginx/genarrative.access.log` 中的 `request_time`、`upstream_connect_time`、`upstream_header_time`、`upstream_response_time`、`upstream_status`、`request_id`。
|
||||
@@ -344,7 +300,7 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日
|
||||
- api-server 会随 metrics 发送进程级指标：`process.memory.usage`、`process.memory.virtual`、`process.cpu.time`、`genarrative.process.cpu.usage_percent`、`process.thread.count`、`genarrative.process.memory.private`；Windows 额外发送 `process.windows.handle.count`，Linux 额外发送 `process.unix.file_descriptor.count`。这些指标只描述当前进程，不携带请求、用户或作品 label。
|
||||
- HTTP 运行态补充发送 `genarrative.http.server.response_bodies.in_flight` 与 `genarrative.http.server.request_permits.available`，后者带低基数 `pool=default|gallery|detail|admin` label，用于区分业务 handler / 背压 permit 是否仍被占用；拼图广场热点缓存补充发送 `genarrative.puzzle_gallery.cache.*` 指标，记录 fresh hit、stale hit、未命中、后台刷新开始 / 失败、重建耗时和预序列化 data JSON 字节数。
|
||||
- 外部 API 失败统一发送 OTLP 并落库。当前 VectorEngine `gpt-image-2` 图片生成 / 编辑失败由 `platform-image` provider 输出结构化日志字段，字段包括 provider、endpoint、failure_stage、status、source、source_chain、source_chain_depth、timeout、retryable、latency_ms、prompt_chars、reference_image_count、image_model、request_params 和 raw_excerpt；图片编辑请求参数日志还会带 reference_image_bytes_total，并在 request_params.referenceImages 中记录每个 multipart `image` part 的 fileName、mimeType 和 bytes，不记录 API key 或原始图片 bytes；`api-server` 再记录指标 `genarrative.external_api.failures{provider,failure_stage,status_class,retryable}`，并写入 `tracking_event`，`event_key = external_api_call_failure`、`module_key = external-api`、`scope_kind = module`、`scope_id = provider`。调用方能拿到身份上下文时，失败事件还会在行级 `user_id` / `owner_user_id` / `profile_id` 和 `metadata_json.userId` / `metadata_json.profileId` / `metadata_json.requestId` / `metadata_json.errorSource` 中记录触发者、草稿 / 作品作用域、请求标识和传输错误链。排障时先按 provider / failureStage 聚合，再下钻 userId / profileId，最后结合 request 日志、errorSource 和上游响应 excerpt 判断是限流、超时、解析失败还是未返回图片。
|
||||
- OSS 平台适配器也输出结构化日志，覆盖 `sign_post_object`、`sign_get_object_url`、`head_object` 和 `put_object`。排查资产签名、上传或确认失败时，先按 `provider=aliyun-oss` 与 `operation` 过滤，再看 `object_key` / `key_prefix`、`status`、`status_class`、`error_kind`、`content_length`、`content_type` 和 `elapsed_ms`；日志不得包含 AccessKey、policy、signature、Authorization header 或完整 signed URL。排查 generated 图片重复下载时，先确认前端输入是否为 `/generated-*` legacy path 或可归一化的 `https://*.oss-*.aliyuncs.com/generated-*`；正确链路应先调 `/api/assets/read-url`，再由浏览器请求 signed URL，且同一路径、同一 `refreshKey` 版本和未临近过期的 signed URL 应复用。新上传 generated 私有对象应带 `Cache-Control: public, max-age=31536000, immutable`；旧对象若只有 `ETag` / `Last-Modified`，浏览器会走 304 协商缓存而不是长期强缓存，可通过刷新 OSS 元数据或 CDN 配置补齐。
|
||||
- OSS 平台适配器也输出结构化日志，覆盖 `sign_post_object`、`sign_get_object_url`、`head_object` 和 `put_object`。排查资产签名、上传或确认失败时，先按 `provider=aliyun-oss` 与 `operation` 过滤，再看 `object_key` / `key_prefix`、`status`、`status_class`、`error_kind`、`content_length`、`content_type` 和 `elapsed_ms`；日志不得包含 AccessKey、policy、signature、Authorization header 或完整 signed URL。排查 generated 图片重复下载时，先确认前端输入是否为 `/generated-*` legacy path 或可归一化的 `https://*.oss-*.aliyuncs.com/generated-*`；正确链路应先调 `/api/assets/read-url`，再由浏览器请求 signed URL。新上传 generated 私有对象应带 `Cache-Control: public, max-age=31536000, immutable`；旧对象若只有 `ETag` / `Last-Modified`，浏览器会走 304 协商缓存而不是长期强缓存，可通过刷新 OSS 元数据或 CDN 配置补齐。
|
||||
- SpacetimeDB 观测分为两类：procedure / reducer 调用继续用 `genarrative.spacetime.procedure.*`，订阅本地 cache 读使用 `genarrative.spacetime.read.*`。`read=list_puzzle_gallery` 表示拼图广场当前从 `puzzle_gallery_card_view` 本地 cache 读取，不再每个 HTTP 请求调用 `list_puzzle_gallery` procedure。
|
||||
- 本地 Windows 直连压测的内存高水位要结合 K6 VU / 连接数解释。250 RPS 下过高 `PREALLOCATED_VUS` 可能让 300 个本地 Established 连接把 `api-server` private memory 瞬时推到 GB 级，且 `/healthz` 小响应也能复现；若压测结束后回落、`response_bodies.in_flight` 和背压 permit 未显示业务积压，应优先按连接 / 发送链路高水位处理，而不是判断为 SpacetimeDB 或 JSON 缓存泄漏。
|
||||
- Rider 的 Logs 面板只展示 log event 自身字段，不会自动展开父 span 的全部 attributes；请求完成日志会直接带 `request_id`、`http.request.method`、`http.route`、`url.scheme`、`url.path`、`http.response.status_code`、`status_class`、`latency_ms` 和 `slow_request`，完整链路继续到 Traces 面板按 trace/span 查看。
|
||||
@@ -357,9 +313,8 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日
|
||||
- `GENARRATIVE_SPACETIME_TOKEN`
|
||||
- `GENARRATIVE_DATABASE_BACKUP_*`
|
||||
- `GENARRATIVE_LLM_*`
|
||||
- `APIMART_*`
|
||||
- `VECTOR_ENGINE_*`
|
||||
- ~~`APIMART_*`~~（已弃用，LLM 文本调用统一迁移到 VectorEngine）
|
||||
- `APIMART_*`（历史残留，创意 Agent LLM 已迁移到 VectorEngine）
|
||||
- `HYPER3D_*`
|
||||
- `VOLCENGINE_SPEECH_*`
|
||||
- `DASHSCOPE_*`
|
||||
@@ -369,14 +324,6 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日
|
||||
|
||||
结构化创作 / RPG 的 Responses JSON 链路默认不打开 `web_search`；本地和生产如需联网增强，必须显式配置 `GENARRATIVE_RPG_LLM_WEB_SEARCH_ENABLED=true` 或 `GENARRATIVE_CREATION_AGENT_LLM_WEB_SEARCH_ENABLED=true`。如果上游未开通工具，Responses 可能先吐自然语言再返回 `ToolNotOpen`，这类报错应按工具不可用排查，不要先当成 JSON 解析 bug。
|
||||
|
||||
创意 Agent `gpt-5` 文本链路已从 APIMart 切到 VectorEngine：`api-server` 读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` 构造 OpenAI-compatible LLM client，并自动补齐 `/v1` 前缀用于 Responses 协议。排查或切换密钥后，可在本地运行：
|
||||
|
||||
```bash
|
||||
node scripts/test-ve-llm.mjs
|
||||
```
|
||||
|
||||
该脚本读取仓库根目录 `.env.secrets.local` 中的 `VECTOR_ENGINE_BASE_URL` 和 `VECTOR_ENGINE_API_KEY`，依次探测 `/v1/models`、`/v1/chat/completions`、`/v1/responses`、`gpt-5` Chat Completions 和基础 JSON 输出能力；脚本只输出 HTTP 状态、耗时、模型和截断摘要，不应打印密钥。若 `.env.secrets.local` 不存在，先补本地 secrets 文件再运行，不要把 secrets 提交进仓库。
|
||||
|
||||
### 手机验证码短信
|
||||
|
||||
手机验证码发送走阿里云普通短信 `SendSms`，验证码由 `module-auth` 在当前 `api-server` 进程内生成、哈希存储和校验，不再调用阿里云托管验证码的 `SendSmsVerifyCode` / `CheckSmsVerifyCode`。因此 `api-server` 重启后，已发送但未校验的验证码会失效。
|
||||
@@ -463,9 +410,7 @@ systemctl restart genarrative-api.service
|
||||
journalctl -u genarrative-api.service --since '30 seconds ago' --no-pager | grep -E 'tracking outbox|Permission denied|os error 13'
|
||||
```
|
||||
|
||||
`Genarrative-Server-Provision` 和 `Genarrative-Api-Deploy` 会在保留旧 `/etc/genarrative/api-server.env` 的前提下补齐缺失的 tracking outbox 运行态路径，并确保 `/var/lib/genarrative/tracking-outbox` 归属 `genarrative:genarrative`。用户认证真相源只允许在 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）恢复；不要再配置或依赖 `GENARRATIVE_AUTH_STORE_PATH` / `auth-store.json`，`module-auth` 也不再维护本地文件持久化；`auth_store_snapshot` 只保留行级记录，不再保存为单行 `default` 聚合快照，且旧 `get_auth_store_snapshot` / `upsert_auth_store_snapshot` / `import_auth_store_snapshot` 入口已经删除。如果 `api-server` 启动时连不上 SpacetimeDB，会持续重试启动恢复，直到认证工作集从 SpacetimeDB 正式表恢复成功后才开始监听 HTTP，以避免用空本地状态或旧快照覆盖认证表。
|
||||
|
||||
前端登录态恢复只把 `/api/auth/refresh` 的 `401` / `403` 当成权威失效信号；服务器重启窗口里的 `502` / `503` / `504`、浏览器 `Failed to fetch` 或 refresh 响应契约异常都必须保留已有本地 access token，不触发全局 auth 变化。refresh 成功响应以共享契约 `RefreshSessionResponse { token }` 为准，前端不要额外要求业务 `ok` 字段。排查“重启后用户都掉线”时，先区分前端是否被暂时不可用清掉本地 token，再检查 SpacetimeDB 正式认证表是否缺 `user_account` / `refresh_session` 数据。
|
||||
`Genarrative-Server-Provision` 和 `Genarrative-Api-Deploy` 会在保留旧 `/etc/genarrative/api-server.env` 的前提下补齐缺失的 tracking outbox 运行态路径，并确保 `/var/lib/genarrative/tracking-outbox` 归属 `genarrative:genarrative`。用户认证真相源只允许在 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）恢复；不要再配置或依赖 `GENARRATIVE_AUTH_STORE_PATH` / `auth-store.json`，`module-auth` 也不再维护本地文件持久化；`auth_store_snapshot` 只保留行级记录，不再保存为单行 `default` 聚合快照，且旧 `get_auth_store_snapshot` / `upsert_auth_store_snapshot` / `import_auth_store_snapshot` 入口已经删除。如果 `api-server` 启动时连不上 SpacetimeDB，会等待启动恢复，超时后继续监听但进入依赖不可用模式，所有请求统一返回 `503 SERVICE_UNAVAILABLE`，错误详情包含 `reason=spacetime_startup_unavailable`，以避免用空本地状态或旧快照覆盖认证表。
|
||||
|
||||
常用检查思路：
|
||||
|
||||
|
||||
@@ -17,9 +17,7 @@
|
||||
- 充值入口：`src/components/rpg-entry/RpgEntryHomeView.tsx`
|
||||
- 小程序支付承接页：`miniprogram/pages/wechat-pay/index.shared.js`
|
||||
- API 契约：`packages/shared/src/contracts/runtime.ts`、`server-rs/crates/shared-contracts/src/runtime.rs`
|
||||
- 后端下单与订单编排：`server-rs/crates/api-server/src/runtime_profile.rs`、`server-rs/crates/api-server/src/wechat/pay.rs`
|
||||
- 微信支付 / 虚拟支付协议适配：`server-rs/crates/platform-wechat/src/pay.rs`
|
||||
- 微信订阅消息协议适配：`server-rs/crates/platform-wechat/src/subscribe_message.rs`
|
||||
- 后端下单与签名：`server-rs/crates/api-server/src/runtime_profile.rs`
|
||||
- WebView 回流确认：`GET /api/profile/recharge/orders/{orderId}/wechat/events`、`POST /api/profile/recharge/orders/{orderId}/wechat/confirm`
|
||||
- 微信登录态保存：`server-rs/crates/platform-auth/src/lib.rs`、`server-rs/crates/module-auth/src/lib.rs`
|
||||
|
||||
@@ -35,9 +33,6 @@ WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_APP_KEY=<现网 AppKey>
|
||||
WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_SANDBOX_APP_KEY=<沙箱 AppKey，可选>
|
||||
WECHAT_MINIPROGRAM_MESSAGE_TOKEN=<微信消息推送 Token>
|
||||
WECHAT_MINIPROGRAM_MESSAGE_ENCODING_AES_KEY=<微信消息推送 EncodingAESKey>
|
||||
WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_ENABLED=true
|
||||
WECHAT_MINIPROGRAM_GENERATION_RESULT_TEMPLATE_ID=m5z7BkkBhJGbcH0cdDeHaeRU2tViDEguP38XdrRRCdU
|
||||
WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_STATE=formal
|
||||
WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_ENV=0
|
||||
```
|
||||
|
||||
@@ -74,5 +69,4 @@ npm run check:encoding
|
||||
- 沙箱或基础库失败会把微信返回的 `errCode` / `errMsg` 透传到前端失败弹窗，便于区分微信后台道具、沙箱 AppKey、签名和基础库能力问题。
|
||||
- Web 侧在拉起虚拟支付后会短时轮询 `wx_pay_result`，即使小程序 `web-view` 回写 hash 没触发浏览器 `hashchange`，也必须展示回写的微信错误内容。
|
||||
- WebView 返回但没有拿到 `wx_pay_result` 时，前端必须主动调用订单确认接口，并接入 `/api/profile/recharge/orders/{orderId}/wechat/events` 的 SSE 事件流作为服务端推送兜底；后端收到虚拟支付消息推送并入账后会发布订单更新，SSE 先推当前订单快照，再在订单结束时推 `done`。
|
||||
- 小程序订阅消息用于 AI 创作生成结果通知：H5 在生成动作发起前先把页面切到生成进度态并立即调用生成 action，同时非阻塞跳转到小程序原生订阅授权页尝试请求授权；授权接受、拒绝或页面返回都不得阻塞或取消生成。原生页不得改写上一页 `webViewUrl`，避免返回后丢失 H5 当前进度页状态。通知发送只允许发生在玩法草稿生成成功或失败终态之后，api-server 使用当前用户微信登录保存的 openid 调用微信 `subscribeMessage.send`。发送失败只记录 warning，不阻断作品生成。模板 `thing1` 发送玩法模板名，`number6` 发送本次生成结算后的实际泥点扣除，失败退款后固定为 `0`；模板 `time4` 字段必须是北京时间 `YYYY-MM-DD HH:mm`。`WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_STATE` 支持 `formal` / `trial` / `developer`，应与当前发布环境一致。
|
||||
- WebView 返回后，在订单状态拉取或 SSE 等待期间展示不可关闭遮罩“正在确认支付”，阻止用户离开或继续操作；只有确认到最终订单状态后才展示一次最终结果弹窗，不能先弹“正在支付/支付已提交”再二次弹成功。
|
||||
|
||||
@@ -1,38 +1,22 @@
|
||||
# 平台入口与玩法链路
|
||||
|
||||
更新时间：`2026-06-10`
|
||||
更新时间：`2026-06-06`
|
||||
|
||||
## 平台创作入口
|
||||
|
||||
创作入口配置事实源在 SpacetimeDB，通过 `GET /api/creation-entry/config` 下发；后台通过 `/admin/api/creation-entry/config` 管理入口开关，通过 `/admin/api/creation-entry/config/interactions` 管理公开作品点赞 / 改造能力矩阵。前端只在展示层派生可见卡片、入口状态和作品详情互动状态，`api-server` 路由熔断也使用同一份配置。不要恢复前端硬编码入口配置文件。
|
||||
创作入口配置事实源在 SpacetimeDB，通过 `GET /api/creation-entry/config` 下发；后台通过 `/admin/api/creation-entry/config` 管理。前端只在展示层派生可见卡片和入口状态，`api-server` 路由熔断也使用同一份配置。不要恢复前端硬编码入口配置文件。
|
||||
|
||||
当前点击底部加号进入的创作入口页承载后台公告位、创作入口页签和两列模板卡；页签中只有真实后端作品架摘要存在时才展示“最近创作”，其余为玩法模板分类。点击模板卡后直接进入对应玩法已有的入口创作表单 stage，不再经过空白占位页，也不把旧表单嵌进创作入口页；模板点击的占位 no-op、隐藏模板拦截、未知入口 no-op 和工作台启动目标统一由 `platformCreationLaunchModel.ts` 判定，壳层只执行启动前准备、错误提示和受保护动作。移动端创作入口页顶栏在 `陶泥儿` 品牌同一行显示真实账户泥点数，数据来自 `profileDashboard.walletBalance`，不得再把公告内容或活动奖池当作账号余额展示。创作入口页公告位数据优先读取 `GET /api/creation-entry/config` 的 `eventBanners` 数组，多条配置时前端自动轮播；旧 `eventBanner` 只保留字段回显与旧客户端兼容，不再作为前端公告数组的兜底来源。后台公告配置面向表单：每条公告包含标题和 HTML 内容，后台保存时序列化为后端 `eventBannersJson` 传输字段，由前端空权限沙箱 iframe 展示；旧结构化 banner 字段仅保留回显兼容，不再作为后台公告配置主格式；不得执行 JSX 或把后台代码直接注入 DOM。玩法列表不再套外部边框卡片，移动端需要压缩横向边距和两列间距；玩法卡统一按“上图、左上状态标签（仅非开放态显示）、封面右下显示 `creationTypes[].unifiedCreationSpec.mudPointCost` 经前端格式化后的泥点消耗、下方白底标题/描述”结构展示，旧契约缺少该字段时兜底 `10` 并由前端显示为 `10泥点数`，卡片高度保持紧凑但标题、描述和预估消耗点数都必须可见。创作入口页根容器不再使用 `platform-page-stage` 这类全局内容卡片壳，但继续保留 `platform-remap-surface` 作为主题和输入框样式命中钩子。创作入口页字号需要对齐平台普通 UI 档位：顶栏泥点组件、公告正文、分类 Tab 和玩法卡标题 / 副标题 / 消耗说明优先使用 `11px` 到 `14px`，不使用 `text-lg`、`text-xl` 或更大的展示级字号。草稿 Tab 继续承接作品架；底部加号入口页的“最近创作”只用 7 天内的真实后端作品架摘要判断是否展示，并从摘要里推导最近使用过的模板 ID，页面必须展示“仅显示最近7天内使用过的模板”提示，列表内容必须复用其它页签里的模板卡样式、文案和点击行为，不展示具体作品名称、摘要或生成状态，也不新增独立最近创作卡组件。RPG、RPG 之外的各玩法入口分别落到既有的 `agent-workspace`、`big-fish-agent-workspace`、`match3d-agent-workspace`、`square-hole-agent-workspace`、`jump-hop-workspace`、`wooden-fish-workspace`、`puzzle-agent-workspace`、`bark-battle-workspace`、`visual-novel-agent-workspace`、`baby-object-match-workspace`，这些入口继续承接各玩法自己的表单、草稿恢复和后续编排，不作为创作入口页内容。
|
||||
当前点击底部加号进入的创作入口页承载后台公告位、创作入口页签和两列模板卡；页签中只有真实后端作品架摘要存在时才展示“最近创作”，其余为玩法模板分类。点击模板卡后直接进入对应玩法已有的入口创作表单 stage，不再经过空白占位页，也不把旧表单嵌进创作入口页。移动端创作入口页顶栏在 `陶泥儿` 品牌同一行显示真实账户泥点数，数据来自 `profileDashboard.walletBalance`，不得再把公告内容或活动奖池当作账号余额展示。创作入口页公告位数据优先读取 `GET /api/creation-entry/config` 的 `eventBanners` 数组，多条配置时前端自动轮播；旧 `eventBanner` 只保留字段回显与旧客户端兼容，不再作为前端公告数组的兜底来源。后台公告配置面向表单：每条公告包含标题和 HTML 内容，后台保存时序列化为后端 `eventBannersJson` 传输字段，由前端空权限沙箱 iframe 展示；旧结构化 banner 字段仅保留回显兼容，不再作为后台公告配置主格式；不得执行 JSX 或把后台代码直接注入 DOM。玩法列表不再套外部边框卡片，移动端需要压缩横向边距和两列间距；玩法卡统一按“上图、左上状态标签（仅非开放态显示）、封面右下 `10-20泥点数`、下方白底标题/描述”结构展示，卡片高度保持紧凑但标题、描述和预估消耗点数都必须可见。创作入口页根容器不再使用 `platform-page-stage` 这类全局内容卡片壳，但继续保留 `platform-remap-surface` 作为主题和输入框样式命中钩子。创作入口页字号需要对齐平台普通 UI 档位：顶栏泥点组件、公告正文、分类 Tab 和玩法卡标题 / 副标题 / 消耗说明优先使用 `11px` 到 `14px`，不使用 `text-lg`、`text-xl` 或更大的展示级字号。草稿 Tab 继续承接作品架；底部加号入口页的“最近创作”只用 7 天内的真实后端作品架摘要判断是否展示，并从摘要里推导最近使用过的模板 ID，页面必须展示“仅显示最近7天内使用过的模板”提示，列表内容必须复用其它页签里的模板卡样式、文案和点击行为，不展示具体作品名称、摘要或生成状态，也不新增独立最近创作卡组件。RPG、RPG 之外的各玩法入口分别落到既有的 `agent-workspace`、`big-fish-agent-workspace`、`match3d-agent-workspace`、`square-hole-agent-workspace`、`jump-hop-workspace`、`wooden-fish-workspace`、`puzzle-agent-workspace`、`bark-battle-workspace`、`visual-novel-agent-workspace`、`baby-object-match-workspace`，这些入口继续承接各玩法自己的表单、草稿恢复和后续编排，不作为创作入口页内容。
|
||||
|
||||
旧库或旧迁移包没有 `event_banners_json` 时，后端读取层必须把 `eventBanners` 归一到 `module-runtime` 默认公告数组，不能把旧结构化 `eventBanner` 当成前端优先数组下发。默认公告引用的背景图必须指向 `public/` 下真实存在的站内静态资源，当前默认使用 `/creation-type-references/puzzle.webp`，避免创作入口顶部 banner 出现失效图片。
|
||||
|
||||
创作页和草稿页顶栏右上角的泥点余额胶囊是补足泥点入口：如果当前运行环境开启充值入口，点击后直接打开账户充值弹窗；否则直接打开运营兑换码弹窗。该入口不再跳到账户面板或泥点账单，头像 / 设置等账号入口继续保留各自语义。
|
||||
|
||||
创作恢复参数只保留 `sessionId`、`profileId`、`draftId`、`workId` 这四个私有 query。它们只允许在同一条创作链路的结果页、生成页、工作台之间保留；切到首页、公开作品详情、runtime 或另一条玩法链路时必须清掉。平台入口刷新直达时，路径到玩法恢复目标、四个 query 归一化、生成页标记、大鱼吃小鱼 workId 兜底、作品 / 草稿身份匹配和跳一跳 / 敲木鱼恢复阶段落点统一由 `platformCreationUrlStateModel.ts` 解析，壳层只执行读取作品、恢复草稿和切换阶段等副作用。生成页等待时间统一以生成状态里的 `startedAtMs` 为准；创建该状态时优先使用后端 session 下发的时间戳，作品摘要里的 `updatedAt` 仍只用于排序与摘要展示，不作为前端自行推导业务状态的真相。
|
||||
创作恢复参数只保留 `sessionId`、`profileId`、`draftId`、`workId` 这四个私有 query。它们只允许在同一条创作链路的结果页、生成页、工作台之间保留；切到首页、公开作品详情、runtime 或另一条玩法链路时必须清掉。生成页等待时间统一以生成状态里的 `startedAtMs` 为准；创建该状态时优先使用后端 session 下发的时间戳，作品摘要里的 `updatedAt` 仍只用于排序与摘要展示，不作为前端自行推导业务状态的真相。
|
||||
|
||||
生成页进度 tick 是否启动统一由 `platformGenerationProgressTickModel.ts` 判定：各小游戏生成页只在当前 stage 与对应生成状态匹配、状态存在且 phase 非 `ready` / `failed` 时 tick；视觉小说继续使用 `startedAtMs` 与轻量 phase 判定，不强行转成小游戏生成状态。平台壳只保留 `Date.now()`、`setInterval` 和 cleanup 副作用，不在壳层重复维护 stage 到 state 的三元链。
|
||||
统一创作入口覆盖当前可进入创作链路的已有模板：`rpg`、`big-fish`、`puzzle`、`match3d`、`jump-hop`、`wooden-fish`、`square-hole`、`bark-battle`、`visual-novel`、`baby-object-match` 和 `creative-agent`；`airp` 仍是未开放占位，不作为当前统一创作链路目标。拼图、抓大鹅、跳一跳和敲木鱼在前端继续经过 `UnifiedCreationWorkspace` 和 `UnifiedGenerationPage`：`UnifiedCreationWorkspace` 作为平台壳依赖的统一创作编排层，再内部调用 `src/components/unified-creation/workspaces/` 下的 `PuzzleCreationWorkspace`、`Match3DCreationWorkspace`、`JumpHopCreationWorkspace` 和 `WoodenFishCreationWorkspace`。其它已有模板由平台壳用 `UnifiedCreationPage` 包住既有工作台，复用统一标题栏、返回入口、页面级纵向滚动和隐藏字段契约，同时保留各玩法自己的表单、草稿恢复和后续编排。创作页字段清单和表头由后端在 `GET /api/creation-entry/config` 的 `creationTypes[].unifiedCreationSpec` 下发，前端仅在该扩展位缺失时回退到本地默认 spec；字段类型只保留 `text`、`select`、`image`、`audio`。统一创作页表头按 `unifiedCreationSpec.title` 契约内容原样显示，读取和保存时不再用入口名称自动覆盖；需要改表头时应直接修改后台契约 JSON 的 `title` 字段。`UnifiedCreationPage` 不在 UI 中额外展示字段说明 chip，也不在右上角显示内部 `playId`、模板 ID 或工作台阶段名；竖屏移动端必须能从标题、表单一路滑到提交按钮。统一创作页根容器必须保留平台浅色背景并让内容区占满剩余高度，移动端软键盘打开或视口被小程序宿主压缩时，短表单也不得露出浏览器 / 宿主黑底。各玩法工作台负责渲染真实输入控件、上传、历史素材、校验和提交，但返回按钮只保留在统一页头，工作台内部不再重复渲染。暗色创作进度卡片位于 `platform-remap-surface` 内时，必须用组件专属 class 覆盖浅色主题 remap，确保白字、浅色边框和进度条底色不会被全局规则改成深色；不要只依赖通用 `text-white*` 类。敲木鱼的音效和功德词条面板不得放进独立内部滚动容器，移动端应跟随页面自然滚动展开。生成页统一展示阶段、当前步骤、总进度、错误和重试动作。
|
||||
|
||||
拼图 runtime 刷新恢复、跳一跳生成中草稿打开和敲木鱼生成中 / detail 草稿恢复所需的 session / work DTO 映射统一由 `platformMiniGameSessionMappingModel.ts` 构造。平台壳只负责读取后端、写入本地 state、写 URL 和切换 stage；不得在壳层重新手写 sessionId 优先级、pending draft 空素材默认值或拼图稳定 ID 映射。
|
||||
|
||||
平台小游戏生成状态的恢复、失败 / 完成收尾、展示 rebase、拼图后端进度合并和 ready / generating 判定统一由 `platformMiniGameDraftGenerationStateModel.ts` 处理。平台壳只决定何时调用并写入对应 React state，不得在壳层重新维护 `MiniGameDraftGenerationState` 的 phase 阈值、`finishedAtMs` 清理或拼图进度 metadata 合并规则。
|
||||
|
||||
拼图 / 抓大鹅草稿恢复和提交所需的表单 payload、拼图编译 action、pending metadata 与拼图 form-only 草稿判定统一由 `platformMiniGameDraftPayloadModel.ts` 构造。平台壳不得重新手写拼图描述字段优先级、formDraft 回退、form-only 空草稿判定、Match3D config / draft / anchorPack 优先级、数字解析或 pending 标题摘要派生规则。
|
||||
|
||||
拼图生成完成后刷新恢复的草稿归一化与可恢复完成态判定统一由 `platformPuzzleDraftRecoveryModel.ts` 处理。恢复链路只有在首图、关卡画面、UI spritesheet 与关卡背景资产包完整时才可把 draft 和首关状态抬为 `ready`；只有 cover 或候选图的半成品不得直接进入结果页完成态。
|
||||
|
||||
后端拼图发布 / 待发布门槛同样必须要求首图、关卡画面、UI spritesheet 与关卡背景资产包完整：`module-puzzle` preview blockers 与 `api-server` session stage 判定不得只凭 cover、标题、描述和标签把半成品标为 `publishReady` 或 `ready_to_publish`。
|
||||
|
||||
平台入口个人钱包本地 delta 由 `platformProfileWalletDeltaModel.ts` 判定：余额归一、本地扣点 / 返还后的 dashboard 乐观更新，以及服务端 dashboard 刷新后的 delta 对账不得散落在平台壳层；壳层只负责 API、React ref 和 state 写入。
|
||||
|
||||
RPG Agent 结果页发布门禁展示由 `platformRpgAgentResultPreviewModel.ts` 判定：平台壳不得重新手写 `CustomWorldProfile` 顶层、`creatorIntent`、`anchorContent`、章节蓝图与首幕 acts 的结构探测，也不得在壳层内联 result preview source label 映射；壳层只负责 session/profile 编排和结果页 props 传递。
|
||||
|
||||
统一创作入口覆盖当前可进入创作链路的已有模板：`rpg`、`big-fish`、`puzzle`、`match3d`、`jump-hop`、`wooden-fish`、`square-hole`、`bark-battle`、`visual-novel`、`baby-object-match` 和 `creative-agent`；`airp` 仍是未开放占位，不作为当前统一创作链路目标。拼图、抓大鹅、跳一跳和敲木鱼在前端继续经过 `UnifiedCreationWorkspace` 和 `UnifiedGenerationPage`：`UnifiedCreationWorkspace` 作为平台壳依赖的统一创作编排层，再内部调用 `src/components/unified-creation/workspaces/` 下的 `PuzzleCreationWorkspace`、`Match3DCreationWorkspace`、`JumpHopCreationWorkspace` 和 `WoodenFishCreationWorkspace`。其它已有模板由平台壳用 `UnifiedCreationPage` 包住既有工作台，复用统一标题栏、返回入口、页面级纵向滚动和隐藏字段契约，同时保留各玩法自己的表单、草稿恢复和后续编排。创作页字段清单、表头和入口卡泥点消耗数量由后端在 `GET /api/creation-entry/config` 的 `creationTypes[].unifiedCreationSpec` 下发，前端仅在该扩展位缺失时回退到本地默认 spec；字段类型只保留 `text`、`select`、`image`、`audio`。统一创作页表头按 `unifiedCreationSpec.title` 契约内容原样显示，入口卡泥点消耗按 `unifiedCreationSpec.mudPointCost` 由前端格式化为 `X泥点数`，读取和保存时不再用入口名称或前端固定文案自动覆盖；需要改表头或入口卡消耗数量时应在后台契约结构卡片点击修改，并通过弹窗表单编辑 `title` 或 `mudPointCost` 字段，不再要求直接编辑 JSON。`workspaceStage`、`generationStage` 和 `resultStage` 属于内部阶段标识，后台弹窗不展示也不允许编辑；保存时沿用已有契约值，新增契约时按 `playId` 的前端固定阶段映射自动带出。`UnifiedCreationPage` 不在 UI 中额外展示字段说明 chip，也不在右上角显示内部 `playId`、模板 ID 或工作台阶段名；竖屏移动端必须能从标题、表单一路滑到提交按钮。统一创作页根容器必须保留平台浅色背景并让内容区占满剩余高度，移动端软键盘打开或视口被小程序宿主压缩时，短表单也不得露出浏览器 / 宿主黑底；H5 根节点在 `data-mobile-keyboard-open=true` 时必须把 `html` / `body` / `#root` 背景切到当前平台浅色底，但不得再用 `.platform-viewport-shell` 全局 `transform` 二次上推页面；小程序 `web-view` 页面原生宿主也必须使用浅色背景，不能沿用全局黑色 page 背景。各玩法工作台负责渲染真实输入控件、上传、历史素材、校验和提交，但返回按钮只保留在统一页头，工作台内部不再重复渲染。暗色创作进度卡片位于 `platform-remap-surface` 内时，必须用组件专属 class 覆盖浅色主题 remap，确保白字、浅色边框和进度条底色不会被全局规则改成深色；不要只依赖通用 `text-white*` 类。敲木鱼的音效和功德词条面板不得放进独立内部滚动容器，移动端应跟随页面自然滚动展开。生成页统一展示阶段、当前步骤、总进度、错误和重试动作。
|
||||
|
||||
创作表单提交前的泥点余额前置校验只允许用独立弹窗提示失败原因，不得把用户退回创作入口或玩法模板列表，也不得清空当前表单状态。当前适用拼图、抓大鹅和汪汪声浪等会在前端提交前校验泥点的生成入口；校验成本必须读取同一份 `creationTypes[].unifiedCreationSpec.mudPointCost`，不能回到前端常量。余额不足、余额读取失败都应停留在当前工作台，由用户关闭提示后继续编辑或自行补足泥点。
|
||||
创作表单提交前的泥点余额前置校验只允许用独立弹窗提示失败原因，不得把用户退回创作入口或玩法模板列表，也不得清空当前表单状态。当前适用拼图、抓大鹅和汪汪声浪等会在前端提交前校验泥点的生成入口；余额不足、余额读取失败都应停留在当前工作台，由用户关闭提示后继续编辑或自行补足泥点。
|
||||
|
||||
平台入口、生成页、结果页、作品详情、作品架和运行态的跨流程错误统一收口到 `PlatformErrorDialog`。弹窗必须带明确错误来源，例如某个草稿、某次生成、作品详情或某个游玩实例，并提供复制按钮复制“错误来源 + 错误内容”。页面内不再重复渲染裸错误 banner；表单校验、发布确认弹窗里的局部业务错误可以保留在原弹窗内。生成任务在用户离开生成页后异步失败时，也必须通过同一弹窗通知用户，并把失败消息写入该 session 的草稿 notice，供草稿页和失败重试页恢复使用。
|
||||
|
||||
@@ -40,9 +24,7 @@ RPG Agent 结果页发布门禁展示由 `platformRpgAgentResultPreviewModel.ts`
|
||||
|
||||
入口配置中的 `open=false` 表示关闭新建创作入口，不表示下架已有草稿、私有作品或公开作品。api-server 的入口熔断只允许拦截新建创作、新建草稿、首次生成入口和 Remix 成草稿等会产生新创作的请求；公开广场列表、公开详情、点赞、已发布作品启动、运行态过程请求、存档 / 浏览记录和已有作品回读不能因为创作入口关闭而返回 `creation_entry_disabled`。平台首页如果遇到旧服务端返回的 `creation_entry_disabled`，只能降级为空列表或隐藏入口，不弹平台级错误弹窗。
|
||||
|
||||
公开作品点赞 / 改造是否开放不跟随入口 `open` 字段，而是读取 `GET /api/creation-entry/config` 的 `publicWorkInteractions`。后台可以按 `sourceType` 分别关闭点赞或改造并维护关闭提示；前端只据此关闭已接入的作品详情动作，尚未接入后端动作的玩法仍按实际能力矩阵返回不可用提示。api-server 对已接入的 RPG、自定义世界兼容路径、大鱼吃小鱼和拼图点赞 / 改造接口做同源熔断，关闭时返回 `public_work_interaction_disabled`，但公开列表、公开详情、已发布作品启动和运行态过程请求不受影响。
|
||||
|
||||
创作入口页的关闭态卡片必须有明显差异：卡片禁用点击，展示后台配置的关闭态 badge 或 `暂未开放`，不再显示泥点消耗这类可创建成本提示；开放态卡片仍不显示普通 `可创建 / 可创作` badge。
|
||||
创作入口页的关闭态卡片必须有明显差异：卡片禁用点击，展示后台配置的关闭态 badge 或 `暂未开放`，不再显示 `10-20泥点数` 这类可创建成本提示；开放态卡片仍不显示普通 `可创建 / 可创作` badge。
|
||||
|
||||
`PlatformEntryFlowShellImpl.tsx` 仍是平台入口编排壳，后续维护时应优先把独立 UI 片段、公开作品映射、草稿生成 notice 和运行态状态 helper 拆到 `src/components/platform-entry/PlatformEntryFlowShellImpl/` 或同目录紧邻 helper 文件。拆分只允许改变文件组织，不改变入口配置事实源、默认导出、props、页面阶段、UI 文案或现有交互；其中拼图首访 onboarding 已拆为 `PlatformEntryFlowShellImpl/PuzzleOnboardingView.tsx`。
|
||||
|
||||
@@ -58,8 +40,6 @@ RPG Agent 结果页发布门禁展示由 `platformRpgAgentResultPreviewModel.ts`
|
||||
创作入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态
|
||||
```
|
||||
|
||||
后端链路也按同一条平台主干组织：所有创作、生成、作品回读、发布、试玩、正式 runtime、公开详情、作品架、运行态设置 / 存档、游玩历史、存档归档、游玩统计、历史素材、AI task、runtime chat、文档解析、角色资产工坊和玩法生成支撑资产相关 HTTP 路由，先注册到 `server-rs/crates/api-server/src/modules/play_flow.rs`，由主干在进入领域 handler 前统一解析 `PlayFlowRequestContext`，再在最后一步分发给对应领域模块或支撑能力 handler 处理。`app.rs` 不再逐玩法挂载创作 / 运行态路由，`modules/platform.rs` 只保留通用 LLM / 语音代理；新增玩法、补齐旧玩法或迁移旧路径时，必须先补 `play_flow` 的 `playId`、领域模块 key、创作路由前缀、运行态路由前缀和入口开关匹配规则，再补具体 handler。领域规则、胜负裁决、计分、发布状态、资产完整性和排行榜仍留在各自 `module-*` 与 SpacetimeDB procedure 中，不把平台主干写成某个玩法的新业务真相。
|
||||
|
||||
默认工作台只提交结构化表单、图片槽位和配置 payload，不默认增加聊天输入区、流式消息区或轻输入 Agent。确需偏离该模式时，必须先在 PRD 和本文档写明例外原因、影响范围和回退方式，再进入编码。
|
||||
|
||||
单图资产编辑统一通过 `CreativeImageInputPanel` 承载上传、AI 重绘、参考图、历史图、主图预览和删除确认；新玩法页面不得重复手写这些交互。主图已有图片时，默认点击图片打开全屏预览，上传 / 更换收口到右下角 `ImagePlus` 图标按钮；无图时仍允许点击空图卡上传。调用方只能通过 `canUploadMainImage`、`canUseImageHistory` 等受控参数开关上传和历史入口，不得用复制组件或样式遮挡改行为。系列素材图集生成统一走“批量规划 -> sheet 生图 -> 后端切图 -> 透明化 -> OSS 持久化 -> 状态回写 -> 局部重生成”流程，玩法只提供 `sheetSpec`、`slotSpecs`、提示词和字段映射，不把任一玩法专属素材 DTO 当作平台通用模型。
|
||||
@@ -72,7 +52,7 @@ RPG Agent 结果页发布门禁展示由 `platformRpgAgentResultPreviewModel.ts`
|
||||
|
||||
1. 草稿页作品卡对齐发现页列表卡风格：左侧信息，右侧封面图，移动端单列，桌面两到三列。
|
||||
2. 草稿页顶部 `全部 / 草稿 / 已发布` 筛选与发现页 `推荐 / 今日 / 分类 / 排行` 频道标签复用同一选中 / 未选中视觉，即 `platform-mobile-home-channel` 与 `platform-mobile-home-channel--active`，不再使用旧 `platform-tab` 胶囊样式。
|
||||
3. 草稿页与底部导航的未读提示点统一使用平台暖棕色点和暖棕光晕，不再使用红点或红色 glow；草稿 Tab 作品架卡片无论草稿 / 已发布都不外露作者信息；已发布作品卡右上角直接显示带底色的分享 icon，并统一唤起发布分享弹窗 `PublishShareModal`，不在卡片内部单独复制分享文案。删除等破坏性动作在作品卡上也要直接开放统一 `actions.delete` 入口，左滑、长按和键盘左箭头仅作为打开同一操作层的辅助交互；所有玩法草稿和已发布列表项都必须通过该统一接口接入删除确认、删除中状态和列表刷新，不允许只给拼图保留专属滑动删除分支。
|
||||
3. 草稿页与底部导航的未读提示点统一使用平台暖棕色点和暖棕光晕，不再使用红点或红色 glow；草稿 Tab 作品架卡片无论草稿 / 已发布都不外露作者信息；已发布作品卡右上角直接显示无边框分享 icon。删除等破坏性动作在作品卡上也要直接开放统一 `actions.delete` 入口，左滑、长按和键盘左箭头仅作为打开同一操作层的辅助交互；所有玩法草稿和已发布列表项都必须通过该统一接口接入删除确认、删除中状态和列表刷新，不允许只给拼图保留专属滑动删除分支。
|
||||
4. 生成中作品在整卡上加等待遮罩，但不移除作品基础信息。
|
||||
5. 生成中状态不能只存在前端内存 notice。后端作品摘要必须下发可恢复的 `generationStatus`；前端刷新或退出产品后，作品架优先用摘要状态恢复等待遮罩，本轮内存 notice 只作为即时反馈。
|
||||
6. 点击 `generationStatus=generating` 的草稿卡必须恢复对应玩法的生成进度页，不能进入空白结果页或普通工作区；恢复生成页的 `startedAtMs` 优先使用后端 session 的 `updatedAt`，没有 session 时再使用作品摘要 `updatedAt`，不得因重新进入页面从 0 秒重新计时。
|
||||
@@ -81,15 +61,14 @@ RPG Agent 结果页发布门禁展示由 `platformRpgAgentResultPreviewModel.ts`
|
||||
9. 私有 generated 图片必须通过 `ResolvedAssetImage` / `/api/assets/read-url` 换签读取。
|
||||
10. 敲木鱼作品架读取当前用户作品列表时走 `GET /api/creation/wooden-fish/works`；发布成功后平台壳必须同时刷新作品架与公开广场，避免作品刚发布时仍停留在旧列表。
|
||||
11. 移动端草稿页整体禁止长按选择文字，避免误触系统选区；输入框、文本域和可编辑区域仍必须保留文本选择能力。
|
||||
12. 作品架删除确认的纯规则统一由 `platformCreationWorkDeleteFlow.ts` 解析，输出确认框 `id/title/detail` 与删除成功后清理的草稿 notice keys；平台壳只接回该模型执行删除 API、刷新列表、清错误和跳转。Jump Hop、Wooden Fish、Bark Battle 虽在作品架 action 层有预留删除入口，但未补齐删除 API 前不得传入删除 handler 或开放按钮。
|
||||
|
||||
发现页 / 推荐页公开作品卡的作者行只显示可读公开昵称；不得把手机号掩码、账号生成的脱敏手机号、`SY-*` 陶泥号或作品号拼接进卡片作者名。陶泥号搜索、作品号复制和完整作品身份只在搜索、详情页或明确的复制入口展示，避免卡片列表暴露账号标识。推荐页运行态、标题和作者信息必须使用同一套公开作品 key 选中当前条目；新增或补齐公开玩法类型时复用 `buildPlatformPublicGalleryCardKey(...)`，避免运行内容已切换但标题 / 作者仍退回第一条作品。
|
||||
|
||||
平台公开搜索的分流顺序、per-play 公开码匹配、公开可见性过滤和详情卡 DTO 映射统一由 `platformPublicCodeSearchModel.ts` 判定：`user_` / `user-` 内部用户 ID 只查用户 ID；`PZ`、`BF`、`JH`、`WF`、`BO`、`M3`、`SH`、`VN`、`BB` 前缀分别直达对应玩法公开作品；`M3D-*` 作为抓大鹅旧前缀继续匹配；`CW` 与 1-8 位纯数字先查 RPG 公开作品再回退陶泥号；普通关键词和 `SY` 陶泥号保持先查陶泥号、再查 RPG 作品、再查汪汪声浪作品、最后陶泥号兜底的既有顺序。平台壳只按计划执行网络读取、详情打开、Bark Battle runtime 特例和缺失作品归航，不在壳层重复维护前缀布尔链、`isSame*PublicWorkCode` 或 DTO 映射。
|
||||
移动端底部导航的创作按钮在登录前后必须保持同一个图片化创作图标，不因登录态切换成加号。
|
||||
|
||||
个人“玩过作品”面板点击作品时，玩法别名、`worldKey` 前缀兜底、RPG 公开详情 payload 和大鱼吃小鱼缺 gallery 命中时的 fallback work 统一由 `platformPlayedWorkOpenModel.ts` 判定。平台壳只负责关闭面板、调用对应公开详情打开函数、刷新大鱼 gallery、优先使用真实 gallery 命中项和写入错误提示；不要在壳层重新维护 `worldType` / `worldKey` 分支链。
|
||||
发现 Tab、创作 Tab 与草稿 Tab 的页面根内容区不再套 `platform-page-stage` 外层全局卡片壳，让列表、筛选和玩法卡获得更宽的横向空间；推荐页和我的页仍按各自页面设计保留原有全局卡片口径。移动端“我的”页仍按顶部头像 / 昵称 / 陶泥号、会员横幅、三张统计卡、每日任务、五项常用功能宫格、通用设置入口和法律信息组织，不保留旧的底部“填邀请码”次级入口；主题设置、账号与安全只放在通用设置弹窗下一级，不在外层单独占行；常用功能当前只展示四项常驻入口时必须按四列铺满整行，不保留五列网格导致左对齐空位；每日任务卡必须读取 `/api/profile/tasks` 的当前任务摘要并在领取后同步刷新卡片进度，外层卡片不展示“去完成”等行动按钮。字号必须维持平台普通 UI 档位，不能因为窄屏把卡片标题、功能 label 或法律信息撑成展示级字号；最后一屏内容必须能在底部 dock 上方完整滚动露出，不得被固定底部导航遮挡。
|
||||
|
||||
发现 Tab、创作 Tab 与草稿 Tab 的页面根内容区不再套 `platform-page-stage` 外层全局卡片壳，让列表、筛选和玩法卡获得更宽的横向空间；推荐页和我的页仍按各自页面设计保留原有全局卡片口径。移动端“我的”页仍按顶部头像 / 昵称 / 陶泥号、会员横幅、三张统计卡、每日任务、五项常用功能宫格、设置入口和法律信息组织，不保留旧的底部“填邀请码”次级入口；常用功能当前只展示四项常驻入口时必须按四列铺满整行，不保留五列网格导致左对齐空位；每日任务卡必须读取 `/api/profile/tasks` 的当前任务摘要并在领取后同步刷新卡片进度。字号必须维持平台普通 UI 档位，不能因为窄屏把卡片标题、功能 label 或法律信息撑成展示级字号；最后一屏内容必须能在底部 dock 上方完整滚动露出，不得被固定底部导航遮挡。
|
||||
平台应用隐藏浏览器根节点 `html` / `body` / `#root` 和平台页面级滚动容器的最外层滚动条可见轨道；弹窗、列表、运行态侧栏等内部滚动容器继续使用原有滚动条样式或显式 `.scrollbar-hide` 控制。
|
||||
|
||||
## RPG / 自定义世界
|
||||
|
||||
@@ -131,7 +110,6 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
|
||||
|
||||
- 图像输入复用 `CreativeImageInputPanel`。
|
||||
- 结果页每关画面编辑复用 `CreativeImageInputPanel`；入口页和关卡画面只共享受控 UI 模块，不共享数据源、状态、action 或存储位置：入口页继续写 `formDraft` 与草稿编译 payload，关卡画面写 `levels[].pictureReference/pictureDescription` 并触发 `generate_puzzle_images`。结果页删除独立“素材配置”Tab，不再提供单独 UI 背景生成入口。通用图片面板的展示图和 AI 重绘参考图能力必须分开控制：结果页正式关卡图只作为预览图，不因存在正式图自动暴露 AI 重绘开关；只有本地上传、历史选择或已保存 `pictureReference` 可作为重绘参考图时，才显示 AI 重绘开关并把状态带入 `generate_puzzle_images`。用户在本次编辑中上传或选择历史图后，该图优先占据主图卡片，可删除、切换 AI 重绘，也可关闭 AI 重绘直用；仅有正式图预览时，画面描述框仍可上传多张参考图。关卡详情弹窗应使用加宽面板，关卡名称、画面图和画面描述合并在同一个纵向列表中，名称输入和画面编辑模块外层不再包独立 `platform-subpanel`；画面图卡仍必须保留稳定最小高度，避免弹窗内 `flex-1` 布局坍缩后只剩标题、描述输入和操作按钮。
|
||||
- 历史图片选择弹窗只展示缩略图与生成时间，不展示从对象路径或文件名解析出的图片名称；选中历史图后内部兜底文案统一使用“历史素材”。
|
||||
- 支持画面描述生图、多参考图生图、上传或历史生成主图后 AI 重绘、上传或历史生成主图后不重绘；主链要求浏览器先经 `/api/assets/direct-upload-tickets` 直传 OSS 并确认 `asset_object`，创作 action 只提交 `referenceImageAssetObjectId(s)`，由后端校验 owner / bucket / kind / MIME / size 后签发 OSS 只读 URL 并下载为 VectorEngine `/v1/images/edits` 的 multipart `image` part。本地上传 Data URL 与历史 `/generated-*` 图片路径仅保留为旧草稿、旧入口或未迁移客户端的兼容输入；关闭 AI 重绘时，后端统一解析为首关或当前关卡正式图后再持久化，不调用第一段拼图首图生成。
|
||||
- 草稿生成会先持久化 `generationStatus=generating` 的作品摘要，生成完成并回写关卡拼图画面、关卡画面参考图、UI spritesheet 和关卡背景图后再变为 `ready`；当前不自动生成背景音乐。生成页步骤推进必须跟随后端 session `progressPercent` 的真实里程碑：`88` 表示草稿编译完成并进入出图步骤，`94` 表示生成图已保存并进入 UI / 背景步骤，`96` 表示正式图与 UI 背景已确认并进入写入步骤，最终 action 成功或发布才进入完成态；每个步骤内部可以按实际等待时间使用假进度平滑推进。`88/94/96` 只负责切换当前步骤，不作为总进度地板；总进度按已完成步骤权重加当前步骤内假进度推导，非完成态最多停在 `98%`。任一同步 action 回包到达时立即以真实完成/失败结果冻结进度。
|
||||
- 作品架拼图草稿的“生成中”遮罩只表示初始草稿还没有可查看结果；只要作品摘要、首关封面或任一关卡候选图已经可用，后续 UI 背景重生成和追加关卡生图都必须作为结果页局部生成态处理，不能阻止打开草稿结果页。生成失败后，同一浏览器会话内的失败 notice 必须覆盖后端可能仍短暂返回的 `generationStatus=generating` 摘要，作品架保留对应草稿卡但不再显示“生成中”，点击后回到失败 / 重试状态。
|
||||
@@ -146,18 +124,18 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
|
||||
- 拼图试玩和正式运行态刷新恢复不复用创作私有 query。进入 `/runtime/puzzle` 时必须写入 `runtimeProfileId`、草稿 `runtimeSessionId`、可选 `runtimeLevelId`、公开作品 `work` 和 `mode=draft|published`；进入运行态的导航顺序必须先切到 `/runtime/puzzle`，再写这些 runtime query，避免被阶段导航清掉后刷新停在“正在进入拼图关卡”。
|
||||
- 结果页生成关卡图时若关卡名为空，前端必须传 `shouldAutoNameLevel=true`，后端复用首关命名契约先按画面描述生成关卡名，再在图片生成后用视觉命名结果精修，并把生成名和 UI 背景提示词随本次关卡快照写回。
|
||||
- 拼图运行态背景优先读取当前关卡 `levelBackgroundImageSrc/levelBackgroundImageObjectKey`，旧数据才兼容 `uiBackgroundImageSrc/uiBackgroundImageObjectKey`；本地试玩、直达指定关卡和正式 `next-level` 推进时，目标关卡缺关卡背景时必须继承同作品首个可用关卡背景，仍缺失时才沿用当前运行态快照背景或默认 UI。运行态按钮视觉优先读取当前关卡 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`，先按透明 alpha 自动边界检测识别 spritesheet 中的独立按钮展示矩形，再按原图位置从左到右、从上到下映射到返回、设置、下一关、提示、原图、冻结；同一组件还要按较高 alpha 阈值派生紧致点击热区，透明留白和柔边低 alpha 区域尽量不响应点击。检测失败时回退旧固定六格裁切，缺失时才用现有图标按钮兜底。有 spritesheet 时，返回、设置和下一关的点击容器只提供透明点击区，不再叠加默认白色圆形底、胶囊主按钮底或额外文字；下一关按钮在通关弹窗和底部入口中都直接使用 spritesheet 裁切出的 next 素材作为按钮本体。底部提示、原图、冻结三枚素材按检测矩形的原始宽高比显示，不能强行拉伸成正圆或铺满整列。底部道具区不再使用连片胶囊背景，提示、原图、冻结三个按钮均匀分布；运行态只展示按钮素材本身，不额外叠加“提示 / 原图 / 冻结”文字。
|
||||
- 推荐页本身不是登录门禁入口，未登录用户点击底部或侧边栏的推荐 Tab 应直接进入嵌入运行态，不主动打开登录弹窗。推荐页嵌入运行态必须按真实身份分流：已登录用户或本地已有 access token 时，正式 runtime 启动与后续局内动作继续走账号 Bearer；只有确认为匿名访客时才申请并透传 runtime guest token。平台壳统一通过 `buildRecommendRuntimeRequestOptions(...)` 为各玩法的 start / checkpoint / finish / input / drop / click / restart / time-up / leaderboard / next-level 等动作生成局部 request options，不允许每个玩法各写一套匿名分支。后端 `/api/runtime/*` 正式运行态写请求统一接受 `RuntimePrincipal`，可识别账号用户和匿名 runtime guest；推荐卡片的后台读写请求仍使用 local auth impact，避免单卡 401 清空整站登录态。创作、个人作品、删除、发布、Remix 等账号或所有权动作仍保持普通用户鉴权。
|
||||
- 推荐页作品队列只能通过 `buildPlatformRecommendFeedEntries(...)` 生成，首页卡片窗口、桌面推荐格、嵌入 runtime 自动启动和上一条 / 下一条切换都必须消费同一队列。不得在首页和 `PlatformEntryFlowShellImpl` 内分别按“最新列表顺序”和“评分推荐顺序”各算一套相邻作品，否则连续切换会出现视觉上跳过作品或回跳。
|
||||
- 推荐页作品信息区的分享按钮统一唤起发布分享弹窗 `PublishShareModal`，不在推荐卡内部单独拼接分享文案或只做剪贴板复制反馈；拼图推荐作品的 H5 分享链接继续沿用 `/gallery/puzzle/detail?work=...`，其它统一公开作品默认走 `/works/detail?work=...`。微信小程序 WebView 内复制动作必须改为小程序 `pages/web-view/index` 路径并补齐 `targetPath=/works/detail` 与 `work` 参数。推荐页当前 active 作品必须通过 `wx.miniProgram.postMessage` 同步给原生 `web-view` 页，让右上角系统“转发给朋友”和“分享到朋友圈”也使用当前作品参数生成小程序短链背后的 path。微信小程序 WebView 内的推荐页运行态需要启用分享快照安全区，把游戏画面等比缩放并保持在页面中部，避免用户直接点击小程序自带“分享到聊天”时只截到游戏画面局部。
|
||||
- 推荐页本身不是登录门禁入口，平台首页默认落点也是推荐页；未登录用户点击底部或侧边栏的推荐 Tab 应直接进入嵌入运行态，不主动打开登录弹窗。推荐页嵌入运行态必须按真实身份分流：已登录用户或本地已有 access token 时，启动拼图和后续排行榜 / 下一关等正式请求继续走账号 Bearer；只有确认为匿名访客时才申请并透传 runtime guest token。`/api/runtime/puzzle/runs*` 后端统一接受 `RuntimePrincipal`，可识别账号用户和匿名 runtime guest；推荐卡片的后台读写请求仍使用 local auth impact，避免单卡 401 清空整站登录态。创作、个人作品、删除、发布、Remix 等账号或所有权动作仍保持普通用户鉴权。
|
||||
- 拼图运行态棋盘不叠加分块蒙版、描边、阴影、选中底色或合并块 SVG 轮廓；拼图片本体需要裁切为圆角形状，单块使用独立圆角裁切，合并块使用 SVG 原生 `clipPath` 裁切整体外轮廓，外凸角和内凹角分别计算半径，内凹角半径要比外凸角更明显以避免手机 WebView 中看起来仍是直角。原图道具只在用户主动确认后打开独立原图查看层，不在当前拼图棋盘上叠加原图。
|
||||
- 拼图运行态拖拽必须完全跟随手指或鼠标位置，`pointermove` 期间即时写入可见拼块的 transform，不依赖等待后端回包、React 重渲染或下一帧动画队列；进入拖动后不展示拼块选中态或“已选择”提示，松手后再提交目标格同步规则真相。
|
||||
- 拼图运行态的提示、设置等点击弹层跟随当前运行态主色主题，使用普通圆角主题面板，不复用像素九宫格素材框。
|
||||
- 拼图运行态壳层自身要补齐 `platform-ui-shell` / `platform-theme` / `platform-theme--light|dark`，不能依赖外层平台壳来提供主题变量；`/puzzle` 直达页和平台内嵌页都必须渲染同一套主题语义类。
|
||||
- 拼图运行态顶部关卡信息采用游戏化铭牌样式：橘棕横向关卡名牌承载 `第 N 关` 和关卡名，左侧固定使用 `media/logo-runtime-hud.webp` 卡通形象小图；倒计时作为下挂米白小牌独立显示，紧贴铭牌但不遮挡棋盘。该样式只改变运行态 HUD 视觉，不改变计时、暂停、失败同步或关卡推进规则。
|
||||
- 拼图运行态顶部关卡信息采用游戏化铭牌样式：橘棕横向关卡名牌承载 `第 N 关` 和关卡名，左侧固定使用 `media/logo.png` 卡通形象；倒计时作为下挂米白小牌独立显示，紧贴铭牌但不遮挡棋盘。该样式只改变运行态 HUD 视觉，不改变计时、暂停、失败同步或关卡推进规则。
|
||||
- 拼图运行态进行中关卡的 `elapsedMs` 仍是结算字段，设置面板的“当前用时”必须按 `startedAtMs`、暂停累计和冻结累计实时派生；不要直接把进行中的 `currentLevel.elapsedMs` 当作展示值。
|
||||
- 推荐页嵌入拼图运行态时，通关结算弹层必须挂到页面级 fixed 浮层，不能留在推荐卡片视觉区内的 absolute 覆盖层；推荐页滑动卡片和运行态视口都使用 `overflow: hidden`，半屏内容区会裁剪排行榜、下一关按钮和相似作品卡。
|
||||
- 推荐页嵌入拼图运行态时，“下一关”应优先切到相似作品；如果当前推荐候选为空，才回退到同作品下一关，避免匿名推荐流在多关卡作品上持续停留在同一作品内。下一关请求 pending 期间必须保留当前 `PuzzleRuntimeShell` 和棋盘，不得把推荐卡整体切回 `加载中...` 占位态；局部同步状态由拼图运行态自己的 busy 表现承接。后端返回的新关卡属于其它作品时，前端必须同步 `selectedPuzzleDetail`、推荐页 `puzzleGalleryEntries` 缓存和 `activeRecommendEntryKey`，让底部作品信息、分享 / 点赞 / 改造和下一次“下一个”基准都指向新作品。
|
||||
- 推荐页嵌入拼图运行态时，通关结算弹层必须挂到页面级 fixed 浮层，不能留在推荐卡片视觉区内的 absolute 覆盖层；推荐页滑动卡片和运行态视口都使用 `overflow: hidden`，半屏内容区会裁剪排行榜和下一关按钮。
|
||||
- 推荐页嵌入拼图运行态时，“下一关”必须走推荐页统一相邻作品切换流程，不得由拼图 runtime 自己传递 `preferSimilarWork` 或私自把当前 run handoff 到其它拼图作品。点击后应与推荐页底部“下一个”使用同一套 `activeRecommendEntryKey` / 推荐队列切换和新作品启动语义，推荐卡标题、分享 / 点赞 / 改造基准都由统一推荐切换结果决定。切换发起前仍必须保留当前 `PuzzleRuntimeShell` 和棋盘，不得把推荐卡整体切回 `加载中...` 占位态；后续局部同步状态由推荐页启动新作品的统一 busy 表现承接。
|
||||
- 推荐页作品信息区的分享按钮统一唤起发布分享弹窗 `PublishShareModal`，不在推荐卡内部单独拼接分享文案或只做剪贴板复制反馈；拼图推荐作品的分享链接继续沿用 `/gallery/puzzle/detail?work=...`，其它统一公开作品默认走 `/works/detail?work=...`。
|
||||
- 推荐页里的拼图作品如果从运行态进入“改造”结果页，返回平台后要清掉推荐嵌入态的 `activeRecommendEntryKey` / `activeRecommendRuntimeKind` / `isStartingRecommendEntry`，再重新按推荐页自动启动逻辑进入作品，不能复用已经被清空的旧 `puzzleRun`。
|
||||
- 推荐页作品点赞必须按前端全局公开作品 `sourceType` 联合类型明确分流；暂未接入点赞后端的玩法直接报“该作品类型暂不支持点赞”，不能显示开放兜底文案，也不能落入 RPG / custom-world 默认点赞路径。特别是 `WF-*` 敲木鱼作品不得调用 `/api/runtime/custom-world-gallery/.../like`。前端全局创作类型 / 公开作品类型定义以 `packages/shared/src/contracts/playTypes.ts` 为准，新增玩法必须先补类型再补推荐页、详情页、分类页和公开互动分支。
|
||||
- 拼图运行态允许前端低延迟交互表现，但通关、排行榜、奖励和作品状态仍以后端确认为准。
|
||||
|
||||
## 跳一跳
|
||||
@@ -176,31 +154,29 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
|
||||
|
||||
1. 创作端只保留主题输入，作品标题、简介、标签和地块提示词由系统派生；
|
||||
2. v1 不再单独生成角色图片，运行态固定使用抠除白底后的陶泥儿 logo 透明 PNG 作为玩家角色；
|
||||
3. 地板贴图只调用一次 image2，输出一张 `1024x1536` 竖版、`3列*6行`、单一纯洋红 `#FF00FF` key 安全缝 / 外圈背景的立方体主题物体 UV 展开图集；image2 要生成 18 个完整 `1x1x1` 立方体主题物体包装，每个大单元格内部固定为 `4列*3行` UV 网：第 1 行第 2 列为 `top`，第 2 行依次为 `left / front / right / back`，第 3 行第 2 列为 `bottom`，其它 UV 空位保持纯洋红。每个大单元格的六个面必须属于同一个方块化主题物体，top/front/right/back/left/bottom 之间的果皮、切面、籽点、条纹、果柄、叶片等身份特征要连续一致，不能把同一张纹理重复六次，也不能六面各画互不相关的小图标。水果主题应生成 18 种可一眼辨认的方块水果 UV，例如方块苹果、方块香蕉、方块橙子、方块西瓜、方块草莓、方块葡萄、方块奇异果、方块菠萝、方块柠檬、方块桃子、方块梨、方块蓝莓、方块芒果、方块椰子、方块火龙果、方块樱桃、方块哈密瓜、方块石榴；苹果需要果柄叶片跨 top/front，香蕉需要剥皮条带跨 front/right，橙子需要放射切面跨 top/front，西瓜需要红瓤黑籽和绿皮条纹在各面连续。禁止文字、UI、底座、托盘、圆台、地板垫层、落地投影、接触阴影、方形阴影、洋红描边、紫色底边、粉色脏边、彩色光晕、发光边、透明背景、留白、自然圆形水果、自然长条香蕉、孤立水果照片、小型贴纸、纯果皮材质、纯果肉纹理、纯叶脉纹理和无法分辨具体物体的抽象纹理；真实透视、极小倒角、侧壁厚度和阴影统一由运行态 Three.js 标准 `1x1x1` 等比立方体生成。后端只把洋红 key 作为图集安全边界处理，先按 3x6 大单元格切出 18 个方块，再按每格 4x3 UV 网切出 108 张 `256x256` 不透明面贴图，不再运行透明化抠图、最大 alpha 连通主体保留或透明安全边补白；若裁切后仍残留极少洋红 key 色，会转成不透明材质底色。前端和后端默认 `tilePrompt` 都必须使用“立方体主题物体 UV 展开包装图集 / cube object UV unwrap atlas”的口径，不再提交“正面30度主题物体 / 平台素材 / 跳台 / 地块成品 / 地砖 / 材质贴片 / 平铺纹理”等会把模型拉回 2D 地块、平台或单纯材质的词，后端生成前也会清洗旧草稿遗留的这些词；当主题或地块提示词命中宝可梦 / 神奇宝贝 / 口袋妖怪 / Pokemon / Pikachu / 精灵球等宝可梦相关词时，仅生图请求侧改写为“原创幻想萌宠冒险道具 / 彩色冒险能量球 / 黄色闪电萌宠符号”，用户草稿标题和主题展示不改；
|
||||
3. 地块只调用一次 image2，输出一张 `5行*5列`、`1:1`、单一纯洋红 `#FF00FF` key 背景的主题地块图集；跳一跳地块常包含草地、花、雪、白石和云朵，后端透明化必须使用跳一跳专用洋红 key，不启用近白底扣除，也不清理非边缘连通的 key 色像素，避免把绿色或白色主体误扣；后处理必须对边缘连通 key 色做容差清理、去彩边 defringe 和底部残影清理，主体图不得自带洋红阴影、紫色底边、粉色脏边、彩色光晕或发光底边，运行态阴影统一由 DOM 绘制；地块造型提示词要求以主题物体本身外轮廓为准，允许苹果近似圆形、香蕉近似长条或长方形、西瓜近似扇形等自然差异，只统一单格规格、安全留白、正面30度视角和 2D/2.5D 手绘风格包装；所有地块素材必须保持统一正面30度视角，相机位于物体正前方略高位置、镜头向下约30度，必须看到清晰正面、侧壁、下沿、明显自身厚度和少量上表面，主体正面或侧壁可见面积必须接近或大于顶面面积，顶面只能作为辅助可见面；水果主题需要明确要求橙瓣看到橙皮正面外侧和果肉厚度、椰子看到壳的正面侧壁和切口厚度、浆果不能只是从上往下看的圆形球顶；避免生成纯俯视、正上方俯拍、鸟瞰地图块、平铺俯拍、圆形顶视图或扁平图标；主题物体本身必须是唯一可落脚体，只能用自身切面、边缘厚度、花瓣层或果皮边表现承重，禁止在主题物体下方额外垫石台、土墩、木板、圆台、托盘、岛屿底座或通用地板；前端和后端默认 `tilePrompt` 都必须使用“正面30度视角主题物体图集，物体本身作为跳跃落点”的口径，不再提交“平台素材 / 跳台 / 地块 / 地砖”等会把模型拉回通用平台造型的词，后端生成前也会清洗旧草稿遗留的这些词；当主题或地块提示词命中宝可梦 / 神奇宝贝 / 口袋妖怪 / Pokemon / Pikachu / 精灵球等宝可梦相关词时，仅生图请求侧改写为“原创幻想萌宠冒险道具 / 彩色冒险能量球 / 黄色闪电萌宠符号”，用户草稿标题和主题展示不改；
|
||||
4. 背景底图同样由 image2 生成，复用现有 `coverComposite` / `coverImageSrc` 作为运行态背景读写字段，OSS 槽位固定为 `background/image.png`；提示词必须严格以用户主题关键词为背景主题，结构以左右两侧氛围为主，中央纵轴 1/2 区域保持少元素、简洁、可读且有纵深感，两侧允许更强立体层次和行进感；背景只作为底图，禁止生成跳板、地块、落脚物、角色、UI、返回按钮、文字、路径箭头或海报排版；左上角返回按钮不允许画进背景，而是单独生成 `backButtonAsset` 透明 PNG，OSS 槽位固定为 `back-button/image.png`，提示词要求标准圆形、主题色材质包装、居中左箭头、纯绿色 key 背景，后端去绿后写入作品 profile；
|
||||
5. 后端按从上到下、从左到右均匀切分为 `tile-01` 到 `tile-18`，每个方块再持久化 `tile-XX-top/front/right/back/left/bottom` 六个独立 slot/path，不能按重复的 `tileType` 复用槽位；`tileAssets[].faceAssets` 保存六面贴图，历史兼容字段 `imageSrc/imageObjectKey/assetObjectId` 写 top 面作为旧单贴图 fallback，运行态对旧作品没有 `faceAssets` 时仍可把单张贴图应用到立方体所有面；
|
||||
5. 后端按从上到下、从左到右均匀切分为 `tile-01` 到 `tile-25` 的透明 PNG，每个切片必须使用唯一 slot/path 持久化，不能按重复的 `tileType` 复用槽位；
|
||||
6. 结果页只展示陶泥儿 logo 透明角色预览、地块池预览和首屏 3 地块预览；不再提供旧角色图生成槽；移动端结果页必须由结果页根容器承接纵向滚动并保留底部安全区，确保素材预览较长时仍能下滑到返回编辑、试玩和发布按钮；
|
||||
7. 前端跳一跳创作 client 的创建会话与执行生成动作请求都必须使用 20 分钟等待窗口，避免背景底图、返回按钮去绿、地板贴图图集切片和 OSS 写入仍在后端执行时被共创会话默认 15 秒超时中断。
|
||||
|
||||
待解决问题（风险程度：高）：跳一跳创作链路目前仍是一次 HTTP 请求内串行生成背景底图、返回按钮、地板贴图图集、切片和 OSS 写入；VectorEngine image2 单步 timeout/connect 失败会在后端最多重试 5 次，而前端只有 20 分钟总等待窗口。若某次背景底图生成接近或超过 18 分钟，前端会先报“请求超时，请稍后重试”，但后端可能继续跑完并在数分钟后写入草稿；同时因为背景、返回按钮和图集等中间资产未按阶段落库，同一 session 超时后重试会重新从背景图开始生成，存在重复生图、重复计费、用户误以为失败、作品架状态短时间不一致的风险。后续应将跳一跳生成改为后端任务化 / 可轮询真实阶段进度，并在每个素材阶段成功后写入可恢复状态；同时收口后端全局生成 deadline、前端等待策略和失败态回写，确保超时、重试和最终成功不会互相打架。
|
||||
7. 前端跳一跳创作 client 的创建会话与执行生成动作请求都必须使用 20 分钟等待窗口，避免背景底图、地块图集、切片、抠图和 OSS 写入仍在后端执行时被共创会话默认 15 秒超时中断。
|
||||
|
||||
生成页“当前跳一跳信息”只展示实际参与创作提示词的主题、地块提示词等用户可理解信息；`stylePreset` 等未参与当前 image2 提示词组装的内部风格枚举不得作为兜底内容展示，避免把 `minimal-blocks`、`paper-toy` 等工程值暴露给创作者。
|
||||
|
||||
运行态规则真相必须沉到 `module-jump-hop`，前端只做长按蓄力、角色位移、投影和落地反馈。失败、成功跳跃次数、游戏时长冻结、运行态快照和发布作品状态以后端为准。v1 不保留公开 combo / perfect / 通关语义，旧 `score` 兼容映射为成功跳跃次数。公开列表应走 `jump_hop_gallery_card_view` 订阅缓存，不要每次 HTTP 请求调用 procedure 组装全量列表。
|
||||
运行态规则真相必须沉到 `module-jump-hop`，前端只做拖拽蓄力、角色位移、投影和落地反馈。失败、成功跳跃次数、游戏时长冻结、运行态快照和发布作品状态以后端为准。v1 不保留公开 combo / perfect / 通关语义，旧 `score` 兼容映射为成功跳跃次数。公开列表应走 `jump_hop_gallery_card_view` 订阅缓存，不要每次 HTTP 请求调用 procedure 组装全量列表。
|
||||
|
||||
每屏只展示 3 个地块：当前地块、目标地块和下一预览地块。平台流按同一 seed 无限生成，前端不得自行生成正式路径。运行态 HUD 顶部只保留返回按钮和成功跳跃次数，不展示计时器或右上角重开按钮；生成背景和游戏舞台必须覆盖整个运行态视口，HUD 直接绝对定位压在背景上，不再用外层白底、居中窄栏、卡片边框或游戏区域圆角裁切背景。返回按钮固定在左上角安全区，交互热区固定为移动端 `56px`、桌面约 `62px`，不显示“返回”文字，并通过顶部锚点微调与得分标题牌保持协调；运行态优先使用独立 `backButtonAsset` 透明 PNG 作为真实可点击按钮图，旧作品缺失该字段时才使用同尺寸 CSS 主题色圆形按钮兜底。上方成功跳跃次数 UI 复用拼图模板顶部 HUD 结构：`puzzle-runtime-header-card` 内包含陶泥儿 IP logo、居中的“得分”标题牌，以及下挂 `puzzle-runtime-timer-card / puzzle-runtime-timer` 居中数字卡；数字卡展示成功跳跃次数而不是倒计时。游玩中不显示左下角“进行中”状态，也不在屏幕底部常驻排行榜。排行榜按作品维度展示玩家 ID、成功跳跃次数和游戏时长；每位玩家只保留 1 条最佳记录，排序固定为 `成功跳跃次数 desc -> 游戏时长 asc -> 更新时间 asc`，并只在失败结算弹窗内展示，弹窗保留重开和返回动作。
|
||||
|
||||
运行态渲染分层固定为：舞台底层 `.jump-hop-runtime__scene-backdrop` 优先使用 `coverComposite` / `coverImageSrc` 中的 image2 背景底图，图片读取继续走平台资产换签，没有背景时才回退到内置渐变；Three.js 平台层复用同一份标准 `1x1x1` 等比极小倒角立方体几何体，只按单一 side 等比缩放当前 / 目标 / 预览地块，并把 `tileAssets[]` 的生成切片作为主题身份方块包装贴图加载到立方体表面；单块地板保持正轴向摆放，不做 Y 轴偏航或 Z 轴歪斜旋转；`tileAssets[].faceAssets` 存在时，Three.js 材质刷新签名必须纳入 top/front/right/back/left/bottom 六面 texture URL，任一面异步换签或 blob URL 变化都要重建平台材质，不能只监听旧单图 `imageSrc` 或基础 render key；运行态采用约 `1.3x` 近距相机、45° 下压视角和更紧凑的可见地板间距，当前脚下地块基准位于屏幕中线略下方，目标和预览地块向上展开，侧壁、倒角、透视和软椭圆阴影均由 Three.js 统一表现；Three.js 相机和 DOM 角色层必须保持屏幕 X 轴同向，不得通过反向 `camera.up` 或镜像 wrapper 把平台层左右翻转，否则会出现地块显示在右侧但蓄力与飞行动画朝左侧的反向错觉；DOM 地块图片层只作为资产换签、预加载、WebGL 不可用和测试环境 fallback，Three.js 平台层 ready 后必须隐藏 DOM 地块图片和 DOM 阴影，避免露出旧原型方块或双层闪现；推进期存在旧地块退出保留时，Three 平台层必须继续承接 3D 地块渲染，旧地块只跟随后续相机推进逐步离屏，不播放独立飞走动画，超过屏幕后自然销毁；图片读取继续走平台资产换签，并以 `assetObjectId` 作为刷新键避免重生成后沿用旧签名或旧图片缓存。DOM 角色层固定使用 `public/branding/jump-hop-taonier-character.png` 陶泥儿 logo 透明 PNG 并保持在 Three.js 平台层之上。长按蓄力、计时刷新和角色位置变化只能更新 refs 或 DOM 状态，不得销毁重建透明画布、背景、平台贴图预加载层或 DOM 角色层，否则会造成背景、地块和角色层频闪。
|
||||
运行态渲染分层固定为：舞台底层 `.jump-hop-runtime__scene-backdrop` 优先使用 `coverComposite` / `coverImageSrc` 中的 image2 背景底图，图片读取继续走平台资产换签，没有背景时才回退到内置渐变；DOM 平台层直接使用 `tileAssets[]` 的生成切片图片显示地块，图片读取继续走平台资产换签，并以 `assetObjectId` 作为刷新键避免重生成后沿用旧签名或旧图片缓存；每个地块下方的统一软椭圆阴影来自运行态 DOM 的 `.jump-hop-runtime__platform-shadow`，不是 image2 地块切片的必需内容，调整阴影优先改运行态 CSS；有真实地块图片 URL 时不得在加载空档显示 fallback 原型地块，下一屏预览地块必须在进入相机视野前隐藏预加载；DOM 角色层固定使用 `public/branding/jump-hop-taonier-character.png` 陶泥儿 logo 透明 PNG 并保持最高层级；Three.js 透明画布仅作为后续扩展层。拖拽蓄力、计时刷新和角色位置变化只能更新 refs 或 DOM 状态，不得销毁重建透明画布、背景或平台图片层，否则会造成背景、地块和角色层频闪。
|
||||
|
||||
跳一跳当前长按蓄力手感统一采用 `chargeToDistanceRatio=0.004`，用于把长按时长换算成世界跳跃距离；如果历史路径仍保存其它系数，`start_run` 会在开局归一化到新系数。用户按住画面开始蓄力，松手立即起跳；前端必须提交 `dragDistance` 以及换算到后端世界坐标的 `dragVectorX/dragVectorY`，后端正式裁决用该方向向量计算真实落点，只有旧客户端缺失方向、方向非有限数或向量长度过小时，才 fallback 到当前地块中心指向下一块地块中心。成功判定使用下一块地块可见顶面 footprint：后端以该地块 `width/height` 的收缩矩形模拟 45° 视角下的可见顶面，当前命中区约为宽度 72% 和高度 52%，落点进入该视觉顶面则成功，未进入则失败；旧 `landingRadius/perfectRadius` 只保留兼容读写，不再作为当前命中真相。蓄力中角色只做垂直压缩，不沿目标方向拉伸；蓄力反馈可显示朝向当前目标方向的轻量引导，但不显示落点辅助点、投影圈或其它命中提示。松手后运行态必须立即生成 `visualJump`，用当前角色位置作为起点、前端预测真实落点作为终点，播放约 `560ms` 的角色飞行动画：视觉预测必须使用当前显示窗口的 current/next 地块作为方向来源，即使后端最新 run 已提前返回，也不能拿新 run 目标配旧窗口角色导致下一跳反向；角色沿本次提交方向弹向预测真实落点，成功也不得强制吸附回目标地块中心。若后端新 run 晚于飞行动画返回，角色必须停在预测真实落点等待；新 run 到达后应优先用 `lastJump.landedX/landedY` 映射出的真实落点显示角色，再把显示态切到后端最新 run，并用约 `1440ms` 的相机层推进过渡承接新窗口，避免先飞过很远再瞬间拉回地块造成闪现。推进时地块 DOM 层和 DOM 角色层统一包在同一个 camera layer 下移动，旧当前地块只随相机推进保留在屏幕后方，不单独执行向上 / 向下飞走动画；玩家继续向前跳时，旧地块继续被新的相机推进带离视口，超过离屏阈值后自然销毁，新预览地块从上方露出，禁止用 p1/p2 各自 `top/left` 过渡造成角色和地块不同步。相机层推进必须同时使用 X/Y 偏移，从旧真实落点位置斜向滑到新当前地块聚焦位置，不得先横向瞬切到居中再纵向滑动。地块允许保留当前 / 目标 / 预览的深度尺寸差异，但该差异必须通过固定基准宽高上的 `transform: scale(...)` 缓动呈现，并与相机推进使用同一 `1440ms` 节奏；不要直接修改宽高造成瞬切，也不要再给当前态额外叠 CSS scale。相机推进期间角色自身必须禁用 `left/top` transition，只允许父级 camera layer 负责位移，否则角色局部坐标切换和相机推进会叠加，表现为落地后又从屏幕外闪回。
|
||||
跳一跳当前拖拽手感统一采用 `chargeToDistanceRatio=0.008`，用于把同等跳跃距离所需拖拽距离缩短到旧 `0.004` 的一半；如果历史路径仍保存旧系数，`start_run` 会在开局归一化到新系数。拖拽中只显示弹弓拉线，不显示落点辅助点、投影圈或其它命中提示。松手后运行态必须立即生成 `visualJump`，用当前角色位置作为起点、前端预测落点作为终点，播放约 `560ms` 的角色飞行动画：蓄力时角色沿拖拽方向明显拉长，角色弹向预测落点，落地后向反方向回弹两次；动画路径不得等待后端新 run。若后端新 run 晚于飞行动画返回，角色必须停在预测落点等待，直到新 run 到达后再把显示态切到后端最新 run，并用约 `1440ms` 的相机层推进过渡承接新窗口。推进时地块 DOM 层和 DOM 角色层统一包在同一个 camera layer 下移动，旧当前地块自然离开视野，新预览地块从上方露出，禁止用 p1/p2 各自 `top/left` 过渡造成角色和地块不同步。相机层推进必须同时使用 X/Y 偏移，从旧目标地块位置斜向滑到新当前地块聚焦位置，不得先横向瞬切到居中再纵向滑动。地块允许保留当前 / 目标 / 预览的深度尺寸差异，但该差异必须通过固定基准宽高上的 `transform: scale(...)` 缓动呈现，并与相机推进使用同一 `1440ms` 节奏；不要直接修改宽高造成瞬切，也不要再给当前态额外叠 CSS scale。相机推进期间角色自身必须禁用 `left/top` transition，只允许父级 camera layer 负责位移，否则角色局部坐标切换和相机推进会叠加，表现为落地后又从屏幕外闪回。
|
||||
|
||||
平台首页推荐、精选、最新、公开详情、搜索、已玩作品和公开试玩统一按 `sourceType='jump-hop'` 与 `JH-*` 公开作品号识别跳一跳作品；从公开详情或推荐流启动运行态时，若卡片摘要不足以携带地板贴图图集和路径配置，必须先补读完整 work profile 再传入运行态。`/runtime/jump-hop?work=JH-*` 这类正式深链必须先通过公开作品号回读 gallery detail，再以 profileId 启动 published run；直接打开没有 `work` 参数的 `/runtime/jump-hop` 时不能停留在空运行态或“正在加载内容”，应回到平台首页。平台壳层必须同步注册 `jump-hop-workspace`、`jump-hop-generating`、`jump-hop-result`、`jump-hop-runtime`、`jump-hop-gallery-detail` 阶段，并在 `appPageRoutes.ts` 映射 `/creation/jump-hop`、`/creation/jump-hop/generating`、`/creation/jump-hop/result`、`/gallery/jump-hop/detail`、`/runtime/jump-hop`，同时持有 session、work、run、gallery、busy/error 与生成进度状态，避免只合入渲染分支但遗漏状态源或分享路径导致 typecheck 失败、刷新回首页。
|
||||
平台首页推荐、精选、最新、公开详情、搜索、已玩作品和公开试玩统一按 `sourceType='jump-hop'` 与 `JH-*` 公开作品号识别跳一跳作品；从公开详情或推荐流启动运行态时，若卡片摘要不足以携带地块图集和路径配置，必须先补读完整 work profile 再传入运行态。平台壳层必须同步注册 `jump-hop-workspace`、`jump-hop-generating`、`jump-hop-result`、`jump-hop-runtime`、`jump-hop-gallery-detail` 阶段，并在 `appPageRoutes.ts` 映射 `/creation/jump-hop/workspace`、`/creation/jump-hop/generating`、`/creation/jump-hop/result`、`/gallery/jump-hop/detail`、`/runtime/jump-hop`，同时持有 session、work、run、gallery、busy/error 与生成进度状态，避免只合入渲染分支但遗漏状态源或分享路径导致 typecheck 失败、刷新回首页。
|
||||
|
||||
跳一跳作品架走创作中心的统一作品列表：前端通过 `/api/creation/jump-hop/works` 拉取作品摘要，草稿态会与 pending notice 合并后显示在作品架里，已发布作品点击后会先按 profileId 读取完整详情再进入详情或运行态。生成中作品仍以后端摘要里的 `generationStatus` 为准，刷新后应能恢复等待遮罩，不能只依赖内存 notice。
|
||||
跳一跳作品架走创作中心的统一作品列表：前端通过 `/api/creation/jump-hop/works` 拉取作品摘要，草稿态会与 pending notice 合并后显示在作品架里，已完成但未发布草稿点击后必须通过私有创作接口 `GET /api/creation/jump-hop/works/{profile_id}` 读取完整详情并进入创作结果页；已发布作品点击后才通过公开运行态接口 `GET /api/runtime/jump-hop/works/{profile_id}` 读取完整详情再进入公开详情或运行态，该公开接口保持 published-only 校验。生成中作品仍以后端摘要里的 `generationStatus` 为准，刷新后应能恢复等待遮罩，不能只依赖内存 notice。
|
||||
|
||||
跳一跳作品架删除入口必须走 `/api/creation/jump-hop/works/{profile_id}`，并通过 SpacetimeDB 同步删除 work profile、源 session、运行态 run 与事件，再刷新作品架和公开广场；不得只做前端本地隐藏。
|
||||
|
||||
推荐页匿名游玩不再限定为跳一跳。移动端一级 `推荐` Tab 是内嵌运行态刷卡流，会自动选择推荐作品并启动对应玩法；桌面端首页不启动这套移动推荐运行态，而是渲染桌面发现壳，展示 `今日游戏`、`推荐`、`作品分类` 等桌面内容。推荐页候选顺序由前端轻量推荐算法 `platformRecommendation.ts` 统一生成：先按公开作品 key 去重，再使用公开读模型已有的精选来源、近 7 日游玩、点赞、改造、总游玩、发布时间新鲜度、封面和标签完整度做确定性评分，最后优先交错不同玩法类型；只要还有其它玩法候选，就不要连续推荐同一玩法，只有候选池已没有其它玩法时才允许同玩法相邻。该算法不得新增前端业务真相或绕过公开作品 read model。断点事实统一走 `platformEntryResponsive.ts` 的 `usePlatformDesktopLayout()`，平台壳和首页视图必须共用同一个判断，避免桌面发现页与移动推荐页同时挂载、重复触发请求或启动运行态。移动端推荐页拿到推荐作品列表后必须预加载每个作品的卡片封面、主封面和玩法兜底封面；启动或切换作品时先展示当前带玩法标签和标题的作品卡面遮罩，嵌入 runtime 在卡面下层加载，不得再从卡面闪切到另一层单独纯封面图。作品切换提交后，当前 runtime 遮罩接手已在屏幕上的卡面时必须瞬时贴合，不允许再执行“卡面到同一卡面”的淡入或重绘过渡；推荐页 runtime 必须通过统一 `ready` 门控等待对应运行态 run / profile、lazy runtime 组件和 runtime DOM 内图片资源都准备好，且必须持续观察后续新增图片、内联 `background-image` 和换签中的资源标记，不能只在首次挂载时扫描主图或封面；`ready` 返回 `true` 后才由外层放开游戏画面并只让卡面遮罩渐隐。遮罩层级必须高于并隔离下层 runtime，防止运行态 HUD、canvas 或高 `z-index` 子层穿透到封面上；ready 前不展示“加载中”文案，但封面内必须保留无文案加载动效或进度条，避免用户误以为卡片损坏，也不得把未准备好的运行态直接暴露给用户。切换推荐作品时，如果上一条作品的启动请求、退出收口或目标玩法 busy 状态尚未结束，应继续显示当前作品卡面遮罩并等待下一轮自动启动；只有目标作品启动明确失败时，才显示“作品暂时无法进入，请稍后再试。”这类失败态。推荐页内拼图通关后的同 run 相似作品推进不视为推荐作品切换，不能重新显示启动封面；如果需要跨公开作品进入下一关，则必须走推荐页统一切卡入口，不能复用拼图 runtime 的跨作品 handoff，也不能直接把当前 run 改写到另一个作品，`activeRecommendEntryKey` 只能由推荐页统一选择下一作品后更新。推荐页嵌入运行态启动时按真实身份分流：已登录用户或本地已有 access token 时继续使用账号 Bearer，但请求选项必须是 local auth impact，避免单卡 401 清空整站登录态；只有确认为匿名访客时才申请短期 Runtime Guest Token，并只把它作为局部请求头传给运行态客户端，不写入全局登录态、不触发 refresh，也不把匿名流量伪装成普通用户。当前覆盖矩阵为：跳一跳、视觉小说、抓大鹅 Match3D、方洞挑战、拼图、敲木鱼、大鱼吃小鱼、汪汪声浪。每个模板的启动请求、推荐页内后续运行态动作以及需要上报的 play/finish/leaderboard/next-level 类请求，都必须继续按该身份分流；公开读取入口仍可匿名读取，创作、个人作品、删除、发布、Remix 等账号/所有权动作仍保持普通用户鉴权。推荐 runtime 的 `none` / `background` / `runtime-guest` 请求计划和拼图 `default` / `isolated` runtime auth mode 由 `platformRecommendRuntimeAuthModel.ts` 统一判定，平台壳只负责读取 token、申请 Runtime Guest Token 和传递 request options。推荐 runtime 自动启动只由 `platformPublicGalleryFlow.ts` 输出 `noop` / `clear` / `start(entry)` 决策，平台壳只执行清空 state 或启动指定作品。
|
||||
推荐页匿名游玩不再限定为跳一跳。移动端一级 `推荐` Tab 是内嵌运行态刷卡流，会自动选择推荐作品并启动对应玩法；桌面端首页不启动这套移动推荐运行态，而是渲染桌面发现壳，展示 `今日游戏`、`推荐`、`作品分类` 等桌面内容。推荐页候选顺序由前端轻量推荐算法 `platformRecommendation.ts` 统一生成：先按公开作品 key 去重，再使用公开读模型已有的精选来源、近 7 日游玩、点赞、改造、总游玩、发布时间新鲜度、封面和标签完整度做确定性评分，最后优先交错不同玩法类型；只要还有其它玩法候选，就不要连续推荐同一玩法，只有候选池已没有其它玩法时才允许同玩法相邻。该算法不得新增前端业务真相或绕过公开作品 read model。断点事实统一走 `platformEntryResponsive.ts` 的 `usePlatformDesktopLayout()`，平台壳和首页视图必须共用同一个判断，避免桌面发现页与移动推荐页同时挂载、重复触发请求或启动运行态。移动端推荐页启动或切换作品时先展示当前作品封面，嵌入 runtime 在封面下层加载；只有对应运行态 run / profile 已准备且 lazy runtime 组件完成挂载后，封面才渐隐，不在中途展示“加载中”文案。推荐页内拼图通关后的“下一关”属于推荐页统一切卡入口，不能复用拼图 runtime 的跨作品 handoff，也不能直接把当前 run 改写到另一个作品；`activeRecommendEntryKey` 只能由推荐页统一选择下一作品后更新。推荐页嵌入运行态启动时按真实身份分流：已登录用户或本地已有 access token 时继续使用账号 Bearer，但请求选项必须是 local auth impact，避免单卡 401 清空整站登录态；只有确认为匿名访客时才申请短期 Runtime Guest Token，并只把它作为局部请求头传给运行态客户端，不写入全局登录态、不触发 refresh，也不把匿名流量伪装成普通用户。当前覆盖矩阵为：跳一跳、视觉小说、抓大鹅 Match3D、方洞挑战、拼图、敲木鱼、大鱼吃小鱼、汪汪声浪。每个模板的启动请求、推荐页内后续运行态动作以及需要上报的 play/finish/leaderboard/next-level 类请求，都必须继续按该身份分流；公开读取入口仍可匿名读取，创作、个人作品、删除、发布、Remix 等账号/所有权动作仍保持普通用户鉴权。
|
||||
|
||||
## 敲木鱼
|
||||
|
||||
@@ -237,20 +213,20 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
|
||||
创作入口 -> 轻表单工作台 -> 生成过程页 -> 结果页 -> 试玩 -> 发布 -> 统一作品详情 -> 正式运行态
|
||||
```
|
||||
|
||||
工作台字段固定为卡牌素材主题 `themePrompt`、背景图画面描述 `boardBackgroundPrompt`、背景图槽位和是否 AI 生成背景图；作品标题与简介不在工作台填写，发布前检查环节保存为作品信息后再发布。背景图必须复用 `CreativeImageInputPanel`，支持上传、历史图和 AI 重绘；工作台界面用同一槽位表达“上传图片 / 填写画面描述”两种输入方式，槽位标题显示为“背景图”，描述输入显示为“画面描述”，内容区不再套额外外层信息框。若用户填写 `boardBackgroundPrompt`，AI 生成背景图只读取该字段，字段为空时才回退读取 `themePrompt`；用户上传背景图时不再用主题词重写该资产。背景图的实际语义是玩家逐步消除清空棋盘后露出的主题目标图，生成尺寸必须与中央棋盘一致，按 1:1 正方形出图；prompt 必须强绑定主题、画面精致、强表现力并一眼体现主题，不再要求“画面干净”或“适合作为卡牌棋盘底图”。运行态必须把背景图作为棋盘内部静态底图使用，不能降级成整页氛围背景；卡牌消除后产生的空位和拖拽源位应露出该棋盘底图。卡面背面背景 v1 使用默认占位图，不作为创作者配置项。规则参数不开放编辑：4 关棋盘均为 `6x6`；第 1 关目标 15、5 分钟、仅 `1x2`，第 2 关目标 20、5 分钟、解锁 `1x2/1x3`，第 3 关目标 30、7 分钟、解锁 `1x2/1x3/2x2`，第 4 关目标 35、10 分钟、解锁 `1x2/1x3/2x2/2x3`；防死局发牌和半锁定规则均由后端规则集固定。
|
||||
工作台字段固定为作品标题、简介、主题词、场地底图主题词 `boardBackgroundPrompt`、中央场地底图槽位、是否 AI 生成底图。中央场地底图必须复用 `CreativeImageInputPanel`，支持上传、历史图和 AI 重绘；若用户填写 `boardBackgroundPrompt`，AI 生成底图只读取该字段，字段为空时才回退读取 `themePrompt`；用户上传底图时不再用主题词重写该资产。中央场地底图的字段名保留平台口径，但实际语义是玩家逐步消除清空棋盘后露出的主题目标图，生成尺寸必须与中央棋盘一致，按 1:1 正方形出图；prompt 必须强绑定主题、画面精致、强表现力并一眼体现主题，不再要求“画面干净”或“适合作为卡牌棋盘底图”。运行态必须把中央场地底图作为棋盘内部静态底图使用，不能降级成整页氛围背景；卡牌消除后产生的空位和拖拽源位应露出该棋盘底图。卡面背面背景 v1 使用默认占位图，不作为创作者配置项。规则参数不开放编辑：单关 `6x6`、每局 10 分钟、35 次目标消除、形状解锁、防死局发牌和半锁定规则均由后端规则集固定。
|
||||
|
||||
素材生成使用拼消消专用编排，但必须复用 `platform-image`、VectorEngine `gpt-image-2`、OSS、`asset_object`、换签和失败审计。素材目标是 4 张 `1024x1536` 竖版工作表，每张后台按 `4 列 x 6 行` 裁切，每格 `256x256`；服务端从工作表切出总计 95 个 1x1 卡牌碎片，再合成一张 `10x10 / 2560x2560` 最终 atlas。复合图案组总数固定为 35，形状配比固定为 `1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`。服务端先预排每个复合图案组的 sheet 布局、最终 atlas 坐标和形状，再按坐标切成 1x1 卡牌碎片作为运行态素材；sheet 生图 prompt 只能要求复合图案组可按后台 4x6 均等切成 1x1 方形小份，不能让模型在小图案上绘制切分线、边框、网格线、编号或裁切参考线。4 关复用同一套 atlas，根据关卡解锁形状和目标数选择可用图案组；同关内复合图案不重复。草稿编译和发布都必须使用 api-server 已持久化的真实 atlas / card assets，拒绝缺失、空对象键或 `placeholder` 占位素材，不允许 `spacetime-client` 或 SpacetimeDB 侧合成临时素材绕过平台图片底座。
|
||||
素材生成使用拼消消专用编排，但必须复用 `platform-image`、VectorEngine `gpt-image-2`、OSS、`asset_object`、换签和失败审计。素材目标是 4 张 `1024x1536` 竖版工作表，每张后台按 `4 列 x 6 行` 裁切，每格 `256x256`；服务端从工作表切出总计 95 个 1x1 卡牌碎片，再合成一张 `10x10 / 2560x2560` 最终 atlas。复合图案组总数固定为 35，形状配比固定为 `1x2=23`、`1x3=5`、`2x2=4`、`2x3=3`。服务端先预排每个复合图案组的 sheet 布局、最终 atlas 坐标和形状，再按坐标切成 1x1 卡牌碎片作为运行态素材；sheet 生图 prompt 只能要求复合图案组可按后台 4x6 均等切成 1x1 方形小份，不能让模型在小图案上绘制切分线、边框、网格线、编号或裁切参考线。当前只有单关，同关内复合图案不重复。草稿编译和发布都必须使用 api-server 已持久化的真实 atlas / card assets，拒绝缺失、空对象键或 `placeholder` 占位素材，不允许 `spacetime-client` 或 SpacetimeDB 侧合成临时素材绕过平台图片底座。
|
||||
|
||||
运行态规则：
|
||||
|
||||
1. 4 关棋盘均固定为 `6x6`。
|
||||
2. 第 1 / 2 / 3 / 4 关目标分别为 `15 / 20 / 30 / 35` 次消除，限时分别为 `5 / 5 / 7 / 10` 分钟；超时只判当前关失败，可重试当前关。
|
||||
3. 第 1 关仅出现 `1x2`；第 2 关出现 `1x2`、`1x3`；第 3 关出现 `1x2`、`1x3`、`2x2`；第 4 关出现 `1x2`、`1x3`、`2x2`、`2x3`。
|
||||
4. 开局只放入本关目标消除数对应的全部卡牌，棋盘放不下的牌进入顶部准备区，牌不足棋盘格数时空格保留；开局仍保证至少一步可解。
|
||||
5. 顶部卡牌准备区按纵列补位，某列有空格时该列卡牌从顶部下落；顶部没有新牌时空格留在场上并露出背景图。胜利条件永远是消除完本关全部卡牌，达到目标消除数且棋盘与顶部准备区都没有剩余卡牌后才进入下一关。
|
||||
1. 单关固定为 `6x6 / 35次消除`。
|
||||
2. 每局固定 10 分钟；超时只判当前关失败，可重试当前关。
|
||||
3. 当前关直接出现 `1x2`、`1x3`、`2x2` 和 `2x3`。
|
||||
4. 开局棋盘随机铺满并保证至少一步可解；补牌后也必须由后端保证至少一步可解。
|
||||
5. 顶部卡牌准备区按纵列补位，某列有空格时该列卡牌从顶部下落。
|
||||
6. 非 2 格消除时，补牌不得破坏已完成局部；只有玩家主动交换或撞入才允许打散半锁定拼接组。
|
||||
7. 正式 runtime 只消费后端 snapshot 与 action 结果；前端负责开局翻转、拖拽、掉落、消除和弹层动画。
|
||||
拖拽手感必须对齐拼图模板：开局小卡片只翻转一次，交换落位不得重新翻牌；按住后可见卡片立即跟随鼠标或手指，源位置即时留出空槽；放下时被替换卡片要快速飞向对应空位；已完成局部拼接组要以连续整体呈现并可作为整组拖起。半锁定局部拼接组按同组卡牌“素材坐标相邻且棋盘格相邻”的连通块识别，`1x3`、`2x2`、`2x3` 的转角或多行局部拼合也必须整体写入同一个 `lockedGroupId`，不能只锁住线性排序后相邻的一段。拖拽浮层必须挂到页面级 `document.body` portal，避免平台壳层 transform 让 `position: fixed` 和 `clientX/clientY` 坐标系错位；整组拖起期间活动组只能由 portal ghost 展示卡图，棋盘格子层标记为拖拽源位并保持透明空槽，锁定组覆盖层不得继续渲染正在拖的组。整组拖拽落点必须先以前端当前 board snapshot 校验整组平移后的所有格子仍在棋盘内，越界时只回弹不提交 `swap`；后端仍保留最终规则裁决。
|
||||
拖拽手感必须对齐拼图模板：开局小卡片只翻转一次，交换落位不得重新翻牌；按住后可见卡片立即跟随鼠标或手指，源位置即时留出空槽；放下时被替换卡片要快速飞向对应空位；已完成局部拼接组要以连续整体呈现并可作为整组拖起。拖拽浮层必须挂到页面级 `document.body` portal，避免平台壳层 transform 让 `position: fixed` 和 `clientX/clientY` 坐标系错位。
|
||||
8. 正式 `published` run 的终态事件使用 `run-finished` 和 `level-failed`，事件结果 JSON 至少包含 `status`、`level`、`clears`、`clearDelta` 和 `elapsedMs`，供基础统计与排障回读。
|
||||
|
||||
新增阶段为 `puzzle-clear-workspace`、`puzzle-clear-generating`、`puzzle-clear-result` 和 `puzzle-clear-runtime`；路由为 `/creation/puzzle-clear`、`/creation/puzzle-clear/generating`、`/creation/puzzle-clear/result` 与 `/runtime/puzzle-clear`。API 命名空间为 `/api/creation/puzzle-clear/*` 与 `/api/runtime/puzzle-clear/*`。验证命令见 `docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md` 与 `docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`。
|
||||
@@ -277,7 +253,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
|
||||
|
||||
当前素材生成流水线：
|
||||
|
||||
1. 点击生成前弹出泥点确认，草稿初始生成成本来自后台入口契约 `creationTypes[].unifiedCreationSpec.mudPointCost`；抓大鹅完整草稿生成按该值一次性预扣，汪汪声浪初始三张图按该值分摊到三次素材请求，结果页单图重新生成仍按单图资产操作计费。
|
||||
1. 点击生成前弹出泥点确认，草稿生成固定消耗 `10` 泥点。
|
||||
2. 先写入可恢复草稿 profile，再执行文本计划、关卡整图生成、三张派生图生成、OSS 上传和素材解析；作品摘要在背景、UI spritesheet 或物品 spritesheet 未完整时下发 `generationStatus=generating`，完整后下发 `ready`，草稿完成条件不包含 `backgroundMusic`。
|
||||
3. 首次调用 VectorEngine `gpt-image-2`，无参考图，竖屏 `9:16`，生成完整抓大鹅关卡画面并持久化到 `generatedBackgroundAsset.levelSceneImageSrc/levelSceneImageObjectKey`。提示词必须包含用户主题描述、顶部返回 / 标题倒计时 / 设置按钮、中间与主题匹配且贴横向边缘的容器，以及底部“移出 / 凑齐 / 打乱”三个道具按钮。
|
||||
4. 关卡整图完成后并发发起三次 `gpt-image-2` 编辑请求，三者都以关卡整图作为参考图：`1K`、`1:1` 的 UI spritesheet 写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`；`1K`、`9:16` 的背景图写入 `imageSrc/imageObjectKey`；`2K`、`1:1` 的物品 spritesheet 写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。
|
||||
@@ -306,7 +282,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
|
||||
- 难度只决定本局加载的物品种类数量：轻松 3、标准 9、进阶 15、硬核 20。硬核仍保留 21 次消除和 63 件总物品，运行态按 20 种素材循环复用，不要求生成第 21 种素材。
|
||||
- 运行态启动前要预加载 `generatedItemAssets[].imageViews[]`、顶层 `generatedBackgroundAsset`、物品挂载 `backgroundAsset` 中的背景、UI spritesheet 和物品 spritesheet；首次生成自动试玩、结果页手动试玩、推荐流和公开详情启动都必须传入提升后的 profile。卡片摘要缺图集字段时，进入运行态前必须补读 work detail。补读后的 profile 也要再次提升 `generatedItemAssets[].backgroundAsset`，确保背景和图集字段传给 `Match3DRuntimeShell`。
|
||||
- 背景图作为运行态全屏背景，图内已经保留容器；旧 `containerImage*` 只作为历史透明容器兼容字段。若 `containerImage*` 与 `uiSpritesheetImage*` 同源，运行态不得把 UI spritesheet 当中心容器图叠到棋盘上。
|
||||
- 抓大鹅运行态 HUD 需贴近拼图顶部信息条的视觉口径：左上只保留透明返回按钮；右上不再暴露设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板和同造型，并在牌面左侧挂上 `media/logo-runtime-hud.webp` 产品 logo 小图；下方备选栏和道具图标只保留内容与交互边界，不再显示灰白半透底板；中央容器图层视觉可隐藏，但棋盘命中边界仍保留。
|
||||
- 抓大鹅运行态 HUD 需贴近拼图顶部信息条的视觉口径：左上只保留透明返回按钮；右上不再暴露设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板和同造型，并在牌面左侧挂上 `media/logo.png` 产品 logo；下方备选栏和道具图标只保留内容与交互边界，不再显示灰白半透底板；中央容器图层视觉可隐藏，但棋盘命中边界仍保留。
|
||||
- generated 私有图换签未完成时，局内物品先隐藏等待，不得短暂显示默认积木；同一批资源在重启 run 时保留已解析签名 URL，只有资源源列表变化或换签失败后才允许进入兜底视觉。
|
||||
- `itemSize` 只缩放生成 2D 图片本体：`大`、`中`、`小` 均按相对尺寸缩放，其中 `大` 也比原始图片略小，`中` 和 `小` 进一步缩小；不改变后端下发的布局半径、点击半径或三消规则。
|
||||
- 物品进入底部物品栏时按同类型插入：如果物品栏已有同类物品，新物品插到该类型最后一个物品后面，后续物品整体后移；没有同类时追加到当前末尾。达到三件同类时，在飞入物品栏动画结束后，左侧和右侧同类物品向中间合成，三件一起消失，播放合成音效，不展示星星图标，后面的物品再向前补位。该动效只是前端表现层，后端和本地试玩仍负责权威插入、指定点击类型清除与补位后的槽位快照。
|
||||
@@ -363,8 +339,8 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
|
||||
- 结果页：围绕三图槽位展示错误态与已生成结果，只保留单槽重试、重新生成和上传，不再提供一次生成按钮、音频配置入口或排名配置；生成回写 `partial_failed` 时作品架不再显示整卡“生成中”遮罩，由结果页槽位错误承接失败。
|
||||
- 手动上传：结果页通过平台资产直传 `/api/assets/direct-upload-tickets` 与 `/api/assets/objects/confirm` 写入私有资产，再把返回的历史 generated 路径写回草稿配置。
|
||||
- 发布：结果页确认后必须携带草稿返回的同一个 `workId` 和结果页最终 `publishedSnapshot` 调用 `POST /api/creation/bark-battle/works/publish`；SpacetimeDB 发布态的 `config_json` 必须使用该最终快照，works summary 若拿到 `publishedSnapshotJson` 也优先使用最终快照映射封面三图。发布成功后先进入统一作品详情页，再由详情页进入正式 runtime；缺少 `workId` 的旧草稿状态需要重新生成草稿。
|
||||
- 作品架：Bark Battle 草稿 / 已发布列表优先读取后端 `/works`，但创建、生成完成、保存或发布后的本地摘要必须在后端 read model 尚未回读到同 `workId` 前继续保留；创作中心作品架同时接入 pending shelf 兜底，避免 ready 且三图齐全的草稿在刷新窗口期从“我的草稿 / 已发布”中消失。草稿三图完整性、`pending_assets` / `partial_failed` / `ready` 生成状态归一和作品摘要合并规则统一由 `barkBattleWorkCache.ts` 承接，平台壳只执行读取、刷新与 React state 副作用。
|
||||
- 试玩与正式 runtime：草稿试玩使用 `runtimeMode=draft` 和 mock 输入，不写正式 run；正式 runtime 使用 `runtimeMode=published`，进入运行态后直接申请真实麦克风权限，授权成功后立刻进入倒计时，启动对局时调用 `POST /api/runtime/bark-battle/works/{workId}/runs` 登记 start run，并以返回的 `runtimeConfig` 作为本局前端规则参数；结算时调用 `POST /api/runtime/bark-battle/runs/{runId}/finish` 写入基础统计派生指标；对局会在能量条推到任一侧边界时提前结算并弹出独立结算弹窗，运行态内固定提供返回按钮。发布快照拼装、发布回包缺图时沿用草稿图，以及草稿 / 已发布作品进入前端 runtime 前的 `BarkBattlePublishedConfig` 映射也统一由 `barkBattleWorkCache.ts` 提供，缺失 `publishedAt` 时仍按 `updatedAt` 兜底。
|
||||
- 作品架：Bark Battle 草稿 / 已发布列表优先读取后端 `/works`，但创建、生成完成、保存或发布后的本地摘要必须在后端 read model 尚未回读到同 `workId` 前继续保留；创作中心作品架同时接入 pending shelf 兜底，避免 ready 且三图齐全的草稿在刷新窗口期从“我的草稿 / 已发布”中消失。
|
||||
- 试玩与正式 runtime：草稿试玩使用 `runtimeMode=draft` 和 mock 输入，不写正式 run；正式 runtime 使用 `runtimeMode=published`，进入运行态后直接申请真实麦克风权限，授权成功后立刻进入倒计时，启动对局时调用 `POST /api/runtime/bark-battle/works/{workId}/runs` 登记 start run，并以返回的 `runtimeConfig` 作为本局前端规则参数；结算时调用 `POST /api/runtime/bark-battle/runs/{runId}/finish` 写入基础统计派生指标；对局会在能量条推到任一侧边界时提前结算并弹出独立结算弹窗，运行态内固定提供返回按钮。
|
||||
|
||||
支持的创作者可替换内容：
|
||||
|
||||
|
||||
@@ -50,8 +50,6 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台。当
|
||||
7. 小程序 `web-view` 页必须启用好友分享与朋友圈分享，分享目标固定回到 `pages/web-view/index`，不把 H5 当前 URL 作为不受控启动参数传回小程序页。
|
||||
8. 小程序 `web-view` 外壳运行时通过 `wx.getAccountInfoSync().miniProgram.envVersion` 自动识别版本：线上版 `release` 使用 `www.genarrative.world`，体验版 `trial` 与开发版 `develop` 使用 `dev.genarrative.world`；传给后端的 `x-mini-program-env` 分别为 `release`、`trial`、`dev`。
|
||||
9. 账号信息面板只展示 `账号信息` 标题；绑定手机号和绑定微信以紧凑模块展示当前绑定状态，已绑定手机号展示完整手机号，已绑定微信优先展示微信平台实际返回并由后端保存的 `wechatDisplayName`。小程序 `jscode2session` 不能直接返回微信昵称或个人微信号，只能稳定拿到当前小程序维度的 `openid`，并在满足微信开放平台条件时拿到 `unionid`；小程序昵称来自快捷登录后按需展示的原生 `input type="nickname"` 提交的 `displayName`。后端下发 `wechatAccount` 作为绑定账号标识，前端在没有真实昵称时展示微信账号尾号，不展示裸“已绑定”。换绑入口放在对应模块右上角，退出登录和退出全部设备固定放在面板内容最底部。
|
||||
10. H5 登录态从未登录变为已登录，或从已登录变为未登录后，必须刷新当前页面一次，确保推荐运行态、作品架、个人缓存和私有 query 都按新身份重新初始化；普通 access token 续期、账号资料更新和同一登录态内的设置变化不得触发整页刷新。
|
||||
11. 同一账号允许多端同时在线。新增登录和单设备退出只影响对应 refresh session，不得提升账号级 `tokenVersion` 让其它设备的 access token 失效；只有“退出全部设备”、修改密码、重置密码等明确安全动作才吊销全端 refresh session 并提升 `tokenVersion`。
|
||||
|
||||
## 账户与充值
|
||||
|
||||
@@ -97,7 +95,7 @@ server-rs + Axum + SpacetimeDB
|
||||
3. 点击按钮弹出独立面板时，必须弹出 dialog / drawer / modal，不要在当前面板下方展开内容。
|
||||
4. 优先复用现有系统、页面、组件和弹层，不因一次需求新建平行系统。
|
||||
5. 游戏式页面要防止文字、按钮、HUD、底部 dock、输入法和画布互相遮挡。
|
||||
6. 平台根壳已处理移动端输入法聚焦：输入法弹出时保持画布稳定高度，只记录键盘状态、隐藏底部 dock 并补齐浅色暴露背景，不再全局上移平台壳；业务组件不要重复注册全局键盘适配。
|
||||
6. 平台根壳已处理移动端输入法聚焦：输入法弹出时保持画布稳定高度，用偏移聚焦输入框，业务组件不要重复注册全局键盘适配。
|
||||
7. 主站入口已锁定移动端页面级缩放；单个游戏页面不要再重复实现整页缩放锁定。
|
||||
8. 图像输入通用 UI 统一走 `src/components/common/CreativeImageInputPanel.tsx`。外层页面持有业务状态，组件只承担上传卡、预览、参考图缩略图、AI 重绘开关、错误展示和提交按钮。
|
||||
9. 发现页 `分类` 子频道的筛选必须打开独立 dialog / drawer / modal，至少支持玩法类型过滤与排序切换；筛选结果为空时显示空状态，不把筛选内容展开在当前列表下方。
|
||||
|
||||
@@ -104,7 +104,7 @@ pipeline {
|
||||
|
||||
stage('Archive') {
|
||||
steps {
|
||||
archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/api-server,build/${env.EFFECTIVE_BUILD_VERSION}/api-server.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${env.EFFECTIVE_BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,scripts/deploy/production-api-deploy.sh,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh", fingerprint: true
|
||||
archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/api-server,build/${env.EFFECTIVE_BUILD_VERSION}/api-server.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json", fingerprint: true
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -7,11 +7,16 @@ pipeline {
|
||||
buildDiscarder(logRotator(numToKeepStr: '20', artifactNumToKeepStr: '20'))
|
||||
}
|
||||
|
||||
environment {
|
||||
GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
|
||||
GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
|
||||
}
|
||||
|
||||
parameters {
|
||||
choice(name: 'DEPLOY_TARGET', choices: ['development', 'release'], description: '逻辑部署目标；development 使用当前 Linux 开发/构建/开发部署 agent')
|
||||
booleanParam(name: 'CONFIRM_RELEASE_DEPLOY_AGENT', defaultValue: false, description: '确认 release 目标已有独立 release 部署 agent；当前 Linux 开发/构建/开发部署 agent 不可冒充 release 部署机')
|
||||
string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '上游构建源码分支')
|
||||
string(name: 'COMMIT_HASH', defaultValue: '', description: '上游构建源码 commit')
|
||||
string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '部署脚本来源分支')
|
||||
string(name: 'COMMIT_HASH', defaultValue: '', description: '部署脚本来源 commit；上游触发时传实际构建 commit')
|
||||
string(name: 'NOTIFICATION_EMAILS', defaultValue: '', description: '本次运行追加通知邮箱；会与 Jenkins Secret Text 凭据 genarrative-notification-emails 合并发送')
|
||||
string(name: 'BUILD_VERSION', defaultValue: '', description: '待发布版本号')
|
||||
string(name: 'BUILD_JOB_NAME', defaultValue: 'Genarrative-Api-Build', description: 'API 构建流水线作业名')
|
||||
@@ -57,6 +62,53 @@ pipeline {
|
||||
}
|
||||
}
|
||||
|
||||
stage('Checkout Deploy Scripts') {
|
||||
agent {
|
||||
label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-dev-deploy' : 'linux && genarrative-release-deploy'}"
|
||||
}
|
||||
steps {
|
||||
script {
|
||||
def checkoutFromRemote = { String remoteUrl ->
|
||||
checkout([
|
||||
$class: 'GitSCM',
|
||||
branches: [[name: "*/${params.SOURCE_BRANCH}"]],
|
||||
doGenerateSubmoduleConfigurations: false,
|
||||
extensions: [
|
||||
[$class: 'CleanBeforeCheckout'],
|
||||
[$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
|
||||
],
|
||||
userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
|
||||
])
|
||||
}
|
||||
try {
|
||||
checkoutFromRemote(env.GIT_REMOTE_URL)
|
||||
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
|
||||
} catch (error) {
|
||||
echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
|
||||
checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
|
||||
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
|
||||
}
|
||||
}
|
||||
script {
|
||||
if (params.COMMIT_HASH?.trim()) {
|
||||
echo "API 发布脚本 checkout 将忽略上游构建 commit=${params.COMMIT_HASH}，改用 ${params.SOURCE_BRANCH ?: 'master'} 最新提交，避免发布阶段回退到旧部署脚本。构建产物仍由 BUILD_NUMBER_TO_DEPLOY 决定。"
|
||||
}
|
||||
}
|
||||
sh '''
|
||||
bash -lc '
|
||||
set -euo pipefail
|
||||
chmod +x scripts/jenkins-checkout-source.sh
|
||||
SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
|
||||
COMMIT_HASH="" \
|
||||
GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
|
||||
GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
|
||||
SOURCE_COMMIT_FILE=".jenkins-source-commit" \
|
||||
scripts/jenkins-checkout-source.sh
|
||||
'
|
||||
'''
|
||||
}
|
||||
}
|
||||
|
||||
stage('Fetch Artifact') {
|
||||
agent {
|
||||
label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-dev-deploy' : 'linux && genarrative-release-deploy'}"
|
||||
@@ -65,7 +117,7 @@ pipeline {
|
||||
copyArtifacts(
|
||||
projectName: params.BUILD_JOB_NAME,
|
||||
selector: specific(params.BUILD_NUMBER_TO_DEPLOY),
|
||||
filter: "build/${params.BUILD_VERSION}/api-server,build/${params.BUILD_VERSION}/api-server.sha256,build/${params.BUILD_VERSION}/release-manifest.json,build/${params.BUILD_VERSION}/scripts/database-backup-to-oss.mjs,build/${params.BUILD_VERSION}/scripts/ops/production-health-patrol.mjs,scripts/deploy/production-api-deploy.sh,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh",
|
||||
filter: "build/${params.BUILD_VERSION}/api-server,build/${params.BUILD_VERSION}/api-server.sha256,build/${params.BUILD_VERSION}/release-manifest.json",
|
||||
target: '.',
|
||||
fingerprintArtifacts: true
|
||||
)
|
||||
|
||||
@@ -21,7 +21,7 @@ pipeline {
|
||||
string(name: 'PROVISION_DOWNLOADS_DIR', defaultValue: 'provision-tool-downloads', description: '目标服务器工作区内暂存 SpacetimeDB/otelcol 安装包的相对目录')
|
||||
string(name: 'PROVISION_TOOLS_DIR', defaultValue: 'provision-tools', description: '目标机工作区内由已下载安装包生成的工具包目录')
|
||||
string(name: 'PROVISION_DOWNLOAD_PROXY', defaultValue: '', description: '可选，目标服务器下载 SpacetimeDB 和 otelcol-contrib 时使用的代理地址，例如 http://127.0.0.1:7890；留空不设置代理')
|
||||
string(name: 'SPACETIME_DOWNLOAD_ROOT', defaultValue: 'https://github.com/clockworklabs/SpacetimeDB/releases/download/v2.4.1', description: '目标服务器使用的 SpacetimeDB Linux release tarball 根地址；默认固定到项目锁定版本')
|
||||
string(name: 'SPACETIME_DOWNLOAD_ROOT', defaultValue: 'https://github.com/clockworklabs/SpacetimeDB/releases/latest/download', description: '目标服务器使用的 SpacetimeDB Linux release tarball 根地址')
|
||||
string(name: 'SPACETIME_TARGET_HOST', defaultValue: 'x86_64-unknown-linux-gnu', description: 'SpacetimeDB 预编译包 host triple，development/release Linux amd64 使用默认值')
|
||||
string(name: 'SPACETIME_ROOT', defaultValue: '/stdb', description: 'SpacetimeDB root-dir')
|
||||
string(name: 'RELEASE_ROOT', defaultValue: '/opt/genarrative/releases', description: 'release 根目录')
|
||||
@@ -162,9 +162,8 @@ BASH
|
||||
OTELCOL_VERSION="${OTELCOL_VERSION:-0.151.0}" \
|
||||
PREPARE_OTELCOL="${ENABLE_OTELCOL:-true}" \
|
||||
PROVISION_DOWNLOAD_PROXY="${PROVISION_DOWNLOAD_PROXY:-}" \
|
||||
SPACETIME_DOWNLOAD_ROOT="${SPACETIME_DOWNLOAD_ROOT:-https://github.com/clockworklabs/SpacetimeDB/releases/download/v2.4.1}" \
|
||||
SPACETIME_DOWNLOAD_ROOT="${SPACETIME_DOWNLOAD_ROOT:-https://github.com/clockworklabs/SpacetimeDB/releases/latest/download}" \
|
||||
SPACETIME_TARGET_HOST="${SPACETIME_TARGET_HOST:-x86_64-unknown-linux-gnu}" \
|
||||
SPACETIME_ROOT="${SPACETIME_ROOT:-/stdb}" \
|
||||
scripts/prepare-server-provision-tools.sh
|
||||
'
|
||||
'''
|
||||
|
||||
@@ -12,7 +12,6 @@ pipeline {
|
||||
environment {
|
||||
GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
|
||||
GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
|
||||
GENARRATIVE_STDB_CACHE_ROOT = 'caches/genarrative-jenkins/stdb-module'
|
||||
CARGO_INCREMENTAL = '0'
|
||||
RUSTC_WRAPPER = 'sccache'
|
||||
SCCACHE_CACHE_SIZE = '30G'
|
||||
@@ -82,15 +81,12 @@ pipeline {
|
||||
sh '''
|
||||
bash -lc '
|
||||
set -euo pipefail
|
||||
stdb_cache_root="${GENARRATIVE_STDB_CACHE_ROOT:-caches/genarrative-jenkins/stdb-module}"
|
||||
if [[ "${stdb_cache_root}" != /* ]]; then
|
||||
stdb_cache_root="${HOME:?HOME 不能为空}/${stdb_cache_root}"
|
||||
fi
|
||||
export CARGO_HOME="${stdb_cache_root}/cargo-home"
|
||||
export CARGO_TARGET_DIR="${stdb_cache_root}/cargo-target/prod-release"
|
||||
workspace_tmp="${WORKSPACE_TMP:-${WORKSPACE}@tmp}"
|
||||
export CARGO_HOME="${workspace_tmp}/cargo-home"
|
||||
export CARGO_TARGET_DIR="${workspace_tmp}/cargo-target/prod-release"
|
||||
export CARGO_INCREMENTAL=0
|
||||
export RUSTC_WRAPPER=sccache
|
||||
export SCCACHE_DIR="${stdb_cache_root}/sccache"
|
||||
export SCCACHE_DIR="${workspace_tmp}/sccache-stdb-module"
|
||||
export SCCACHE_CACHE_SIZE=30G
|
||||
mkdir -p "${CARGO_HOME}" "${CARGO_TARGET_DIR}" "${SCCACHE_DIR}"
|
||||
chmod +x scripts/jenkins-prepare-cargo-env.sh
|
||||
@@ -119,7 +115,7 @@ pipeline {
|
||||
|
||||
stage('Archive') {
|
||||
steps {
|
||||
archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/spacetime_module.wasm,build/${env.EFFECTIVE_BUILD_VERSION}/spacetime_module.wasm.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,scripts/deploy/production-stdb-publish.sh,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh,scripts/database-backup-to-oss.mjs", fingerprint: true
|
||||
archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/spacetime_module.wasm,build/${env.EFFECTIVE_BUILD_VERSION}/spacetime_module.wasm.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json", fingerprint: true
|
||||
archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/migration-bootstrap-secret.txt", fingerprint: false
|
||||
}
|
||||
}
|
||||
|
||||
@@ -7,11 +7,16 @@ pipeline {
|
||||
buildDiscarder(logRotator(numToKeepStr: '20', artifactNumToKeepStr: '20'))
|
||||
}
|
||||
|
||||
environment {
|
||||
GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
|
||||
GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
|
||||
}
|
||||
|
||||
parameters {
|
||||
choice(name: 'DEPLOY_TARGET', choices: ['development', 'release'], description: '逻辑部署目标；development 使用当前 Linux 开发/构建/开发部署 agent')
|
||||
booleanParam(name: 'CONFIRM_RELEASE_DEPLOY_AGENT', defaultValue: false, description: '确认 release 目标已有独立 release 部署 agent；当前 Linux 开发/构建/开发部署 agent 不可冒充 release 部署机')
|
||||
string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '上游构建源码分支')
|
||||
string(name: 'COMMIT_HASH', defaultValue: '', description: '上游构建源码 commit')
|
||||
string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '部署脚本来源分支')
|
||||
string(name: 'COMMIT_HASH', defaultValue: '', description: '部署脚本来源 commit；上游触发时传实际构建 commit')
|
||||
string(name: 'NOTIFICATION_EMAILS', defaultValue: '', description: '本次运行追加通知邮箱；会与 Jenkins Secret Text 凭据 genarrative-notification-emails 合并发送')
|
||||
string(name: 'BUILD_VERSION', defaultValue: '', description: '待发布版本号')
|
||||
string(name: 'BUILD_JOB_NAME', defaultValue: 'Genarrative-Stdb-Module-Build', description: 'Stdb module 构建流水线作业名')
|
||||
@@ -70,6 +75,48 @@ pipeline {
|
||||
}
|
||||
}
|
||||
|
||||
stage('Checkout Publish Scripts') {
|
||||
agent {
|
||||
label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-dev-deploy' : 'linux && genarrative-release-deploy'}"
|
||||
}
|
||||
steps {
|
||||
script {
|
||||
def checkoutFromRemote = { String remoteUrl ->
|
||||
checkout([
|
||||
$class: 'GitSCM',
|
||||
branches: [[name: "*/${params.SOURCE_BRANCH}"]],
|
||||
doGenerateSubmoduleConfigurations: false,
|
||||
extensions: [
|
||||
[$class: 'CleanBeforeCheckout'],
|
||||
[$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
|
||||
],
|
||||
userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
|
||||
])
|
||||
}
|
||||
try {
|
||||
checkoutFromRemote(env.GIT_REMOTE_URL)
|
||||
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
|
||||
} catch (error) {
|
||||
echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
|
||||
checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
|
||||
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
|
||||
}
|
||||
}
|
||||
sh '''
|
||||
bash -lc '
|
||||
set -euo pipefail
|
||||
chmod +x scripts/jenkins-checkout-source.sh
|
||||
SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
|
||||
COMMIT_HASH="${COMMIT_HASH:-}" \
|
||||
GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
|
||||
GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
|
||||
SOURCE_COMMIT_FILE=".jenkins-source-commit" \
|
||||
scripts/jenkins-checkout-source.sh
|
||||
'
|
||||
'''
|
||||
}
|
||||
}
|
||||
|
||||
stage('Fetch Artifact') {
|
||||
agent {
|
||||
label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-dev-deploy' : 'linux && genarrative-release-deploy'}"
|
||||
@@ -78,7 +125,7 @@ pipeline {
|
||||
copyArtifacts(
|
||||
projectName: params.BUILD_JOB_NAME,
|
||||
selector: specific(params.BUILD_NUMBER_TO_DEPLOY),
|
||||
filter: "build/${params.BUILD_VERSION}/spacetime_module.wasm,build/${params.BUILD_VERSION}/spacetime_module.wasm.sha256,build/${params.BUILD_VERSION}/release-manifest.json,scripts/deploy/production-stdb-publish.sh,scripts/deploy/maintenance-on.sh,scripts/deploy/maintenance-off.sh,scripts/database-backup-to-oss.mjs",
|
||||
filter: "build/${params.BUILD_VERSION}/spacetime_module.wasm,build/${params.BUILD_VERSION}/spacetime_module.wasm.sha256,build/${params.BUILD_VERSION}/release-manifest.json",
|
||||
target: '.',
|
||||
fingerprintArtifacts: true
|
||||
)
|
||||
|
||||
@@ -89,7 +89,7 @@ pipeline {
|
||||
|
||||
stage('Archive') {
|
||||
steps {
|
||||
archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/web.tar.gz,build/${env.EFFECTIVE_BUILD_VERSION}/web.tar.gz.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json,scripts/deploy/production-web-deploy.sh", fingerprint: true
|
||||
archiveArtifacts artifacts: "build/${env.EFFECTIVE_BUILD_VERSION}/web.tar.gz,build/${env.EFFECTIVE_BUILD_VERSION}/web.tar.gz.sha256,build/${env.EFFECTIVE_BUILD_VERSION}/release-manifest.json", fingerprint: true
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -7,11 +7,16 @@ pipeline {
|
||||
buildDiscarder(logRotator(numToKeepStr: '20', artifactNumToKeepStr: '20'))
|
||||
}
|
||||
|
||||
environment {
|
||||
GIT_REMOTE_URL = 'http://127.0.0.1:3000/GenarrativeAI/Genarrative.git'
|
||||
GIT_REMOTE_FALLBACK_URL = 'https://git.genarrative.world/GenarrativeAI/Genarrative.git'
|
||||
}
|
||||
|
||||
parameters {
|
||||
choice(name: 'DEPLOY_TARGET', choices: ['development', 'release'], description: '逻辑部署目标；development 使用当前 Linux 开发/构建/开发部署 agent')
|
||||
booleanParam(name: 'CONFIRM_RELEASE_DEPLOY_AGENT', defaultValue: false, description: '确认 release 目标已有独立 release 部署 agent；当前 Linux 开发/构建/开发部署 agent 不可冒充 release 部署机')
|
||||
string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '上游构建源码分支')
|
||||
string(name: 'COMMIT_HASH', defaultValue: '', description: '上游构建源码 commit')
|
||||
string(name: 'SOURCE_BRANCH', defaultValue: 'master', description: '部署脚本来源分支')
|
||||
string(name: 'COMMIT_HASH', defaultValue: '', description: '部署脚本来源 commit；上游触发时传实际构建 commit')
|
||||
string(name: 'NOTIFICATION_EMAILS', defaultValue: '', description: '本次运行追加通知邮箱；会与 Jenkins Secret Text 凭据 genarrative-notification-emails 合并发送')
|
||||
string(name: 'BUILD_VERSION', defaultValue: '', description: '待发布版本号')
|
||||
string(name: 'BUILD_JOB_NAME', defaultValue: 'Genarrative-Web-Build', description: 'Web 构建流水线作业名')
|
||||
@@ -44,6 +49,48 @@ pipeline {
|
||||
}
|
||||
}
|
||||
|
||||
stage('Checkout Deploy Scripts') {
|
||||
agent {
|
||||
label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-dev-deploy' : 'linux && genarrative-release-deploy'}"
|
||||
}
|
||||
steps {
|
||||
script {
|
||||
def checkoutFromRemote = { String remoteUrl ->
|
||||
checkout([
|
||||
$class: 'GitSCM',
|
||||
branches: [[name: "*/${params.SOURCE_BRANCH}"]],
|
||||
doGenerateSubmoduleConfigurations: false,
|
||||
extensions: [
|
||||
[$class: 'CleanBeforeCheckout'],
|
||||
[$class: 'CloneOption', shallow: true, depth: 1, noTags: true, timeout: 30, honorRefspec: true],
|
||||
],
|
||||
userRemoteConfigs: [[url: remoteUrl, refspec: "+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}"]],
|
||||
])
|
||||
}
|
||||
try {
|
||||
checkoutFromRemote(env.GIT_REMOTE_URL)
|
||||
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_URL
|
||||
} catch (error) {
|
||||
echo "Git 主地址拉取失败: ${env.GIT_REMOTE_URL}，改用备用地址: ${env.GIT_REMOTE_FALLBACK_URL}"
|
||||
checkoutFromRemote(env.GIT_REMOTE_FALLBACK_URL)
|
||||
env.EFFECTIVE_GIT_REMOTE_URL = env.GIT_REMOTE_FALLBACK_URL
|
||||
}
|
||||
}
|
||||
sh '''
|
||||
bash -lc '
|
||||
set -euo pipefail
|
||||
chmod +x scripts/jenkins-checkout-source.sh
|
||||
SOURCE_BRANCH="${SOURCE_BRANCH:-master}" \
|
||||
COMMIT_HASH="${COMMIT_HASH:-}" \
|
||||
GIT_REMOTE_URL="${EFFECTIVE_GIT_REMOTE_URL:-${GIT_REMOTE_URL}}" \
|
||||
GIT_REMOTE_FALLBACK_URL="${GIT_REMOTE_FALLBACK_URL:-}" \
|
||||
SOURCE_COMMIT_FILE=".jenkins-source-commit" \
|
||||
scripts/jenkins-checkout-source.sh
|
||||
'
|
||||
'''
|
||||
}
|
||||
}
|
||||
|
||||
stage('Fetch Artifact') {
|
||||
agent {
|
||||
label "${params.DEPLOY_TARGET == 'development' ? 'linux && genarrative-dev-deploy' : 'linux && genarrative-release-deploy'}"
|
||||
@@ -52,7 +99,7 @@ pipeline {
|
||||
copyArtifacts(
|
||||
projectName: params.BUILD_JOB_NAME,
|
||||
selector: specific(params.BUILD_NUMBER_TO_DEPLOY),
|
||||
filter: "build/${params.BUILD_VERSION}/web.tar.gz,build/${params.BUILD_VERSION}/web.tar.gz.sha256,build/${params.BUILD_VERSION}/release-manifest.json,scripts/deploy/production-web-deploy.sh",
|
||||
filter: "build/${params.BUILD_VERSION}/web.tar.gz,build/${params.BUILD_VERSION}/web.tar.gz.sha256,build/${params.BUILD_VERSION}/release-manifest.json",
|
||||
target: '.',
|
||||
fingerprintArtifacts: true
|
||||
)
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 6.4 KiB |
@@ -1,10 +1,5 @@
|
||||
{
|
||||
"pages": [
|
||||
"pages/web-view/index",
|
||||
"pages/share-grid/index",
|
||||
"pages/wechat-pay/index",
|
||||
"pages/subscribe-message/index"
|
||||
],
|
||||
"pages": ["pages/web-view/index", "pages/wechat-pay/index"],
|
||||
"window": {
|
||||
"navigationBarTitleText": "陶泥儿",
|
||||
"navigationBarBackgroundColor": "#0b0f14",
|
||||
|
||||
@@ -15,10 +15,6 @@ const MINI_PROGRAM_APP_ID = 'wx3da23ea14ca66b65';
|
||||
// 中文注释：仅作为运行时环境识别失败时的兜底；正常情况下由 wx.getAccountInfoSync 自动判断。
|
||||
const MINI_PROGRAM_ENV = 'release';
|
||||
|
||||
// 中文注释：AI 创作生成结果订阅消息模板，需与微信公众平台后台的模板 ID 保持一致。
|
||||
const GENERATION_RESULT_SUBSCRIBE_TEMPLATE_ID =
|
||||
'm5z7BkkBhJGbcH0cdDeHaeRU2tViDEguP38XdrRRCdU';
|
||||
|
||||
// 中文注释：给 H5 加一个来源标记，便于后续前端或后端识别这是微信小程序 web-view 宿主。
|
||||
const WEB_VIEW_SOURCE_QUERY = {
|
||||
clientType: 'mini_program',
|
||||
@@ -29,7 +25,6 @@ module.exports = {
|
||||
API_BASE_URL,
|
||||
DEV_API_BASE_URL,
|
||||
DEV_WEB_VIEW_ENTRY_URL,
|
||||
GENERATION_RESULT_SUBSCRIBE_TEMPLATE_ID,
|
||||
MINI_PROGRAM_APP_ID,
|
||||
MINI_PROGRAM_ENV,
|
||||
WEB_VIEW_ENTRY_URL,
|
||||
|
||||
@@ -1,206 +0,0 @@
|
||||
/* global Page, wx */
|
||||
/* eslint-disable no-console */
|
||||
|
||||
const {
|
||||
buildShareGridTileFileName,
|
||||
buildShareGridTilePlan,
|
||||
normalizeShareGridQuery,
|
||||
} = require('./index.shared');
|
||||
|
||||
function downloadImage(imageUrl) {
|
||||
return new Promise((resolve, reject) => {
|
||||
wx.downloadFile({
|
||||
url: imageUrl,
|
||||
success(response) {
|
||||
if (response.statusCode >= 200 && response.statusCode < 300) {
|
||||
resolve(response.tempFilePath);
|
||||
return;
|
||||
}
|
||||
reject(new Error(`封面下载失败：${response.statusCode}`));
|
||||
},
|
||||
fail(error) {
|
||||
reject(new Error(error.errMsg || '封面下载失败'));
|
||||
},
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
function getImageInfo(src) {
|
||||
return new Promise((resolve, reject) => {
|
||||
wx.getImageInfo({
|
||||
src,
|
||||
success: resolve,
|
||||
fail(error) {
|
||||
reject(new Error(error.errMsg || '读取封面失败'));
|
||||
},
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
function getCanvasNode(page) {
|
||||
return new Promise((resolve, reject) => {
|
||||
wx.createSelectorQuery()
|
||||
.in(page)
|
||||
.select('#share-grid-canvas')
|
||||
.fields({ node: true, size: true })
|
||||
.exec((results) => {
|
||||
const canvas = results && results[0] && results[0].node;
|
||||
if (canvas) {
|
||||
resolve(canvas);
|
||||
return;
|
||||
}
|
||||
reject(new Error('切图画布初始化失败'));
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
function canvasToTempFilePath(canvas, width, height) {
|
||||
return new Promise((resolve, reject) => {
|
||||
wx.canvasToTempFilePath({
|
||||
canvas,
|
||||
width,
|
||||
height,
|
||||
destWidth: width,
|
||||
destHeight: height,
|
||||
fileType: 'png',
|
||||
success(response) {
|
||||
resolve(response.tempFilePath);
|
||||
},
|
||||
fail(error) {
|
||||
reject(new Error(error.errMsg || '导出切图失败'));
|
||||
},
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
function saveImageToAlbum(filePath) {
|
||||
return new Promise((resolve, reject) => {
|
||||
wx.saveImageToPhotosAlbum({
|
||||
filePath,
|
||||
success() {
|
||||
resolve();
|
||||
},
|
||||
fail(error) {
|
||||
reject(new Error(error.errMsg || '保存到相册失败'));
|
||||
},
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
function copyTempFileWithName(tempFilePath, fileName) {
|
||||
const fileSystem = wx.getFileSystemManager && wx.getFileSystemManager();
|
||||
const userDataPath = wx.env && wx.env.USER_DATA_PATH;
|
||||
if (!fileSystem || !userDataPath || typeof fileSystem.copyFile !== 'function') {
|
||||
return Promise.resolve(tempFilePath);
|
||||
}
|
||||
|
||||
const targetPath = `${userDataPath}/${fileName}`;
|
||||
return new Promise((resolve) => {
|
||||
fileSystem.copyFile({
|
||||
srcPath: tempFilePath,
|
||||
destPath: targetPath,
|
||||
success() {
|
||||
resolve(targetPath);
|
||||
},
|
||||
fail() {
|
||||
resolve(tempFilePath);
|
||||
},
|
||||
});
|
||||
});
|
||||
}
|
||||
|
||||
async function saveGridTiles(page, params, localImagePath, imageInfo) {
|
||||
const canvas = await getCanvasNode(page);
|
||||
const context = canvas.getContext('2d');
|
||||
const image = canvas.createImage();
|
||||
await new Promise((resolve, reject) => {
|
||||
image.onload = resolve;
|
||||
image.onerror = () => reject(new Error('封面绘制失败'));
|
||||
image.src = localImagePath;
|
||||
});
|
||||
|
||||
const plan = buildShareGridTilePlan(imageInfo.width, imageInfo.height);
|
||||
for (const tile of plan) {
|
||||
canvas.width = tile.sourceWidth;
|
||||
canvas.height = tile.sourceHeight;
|
||||
context.clearRect(0, 0, tile.sourceWidth, tile.sourceHeight);
|
||||
context.drawImage(
|
||||
image,
|
||||
tile.sourceX,
|
||||
tile.sourceY,
|
||||
tile.sourceWidth,
|
||||
tile.sourceHeight,
|
||||
0,
|
||||
0,
|
||||
tile.sourceWidth,
|
||||
tile.sourceHeight,
|
||||
);
|
||||
|
||||
const tempFilePath = await canvasToTempFilePath(
|
||||
canvas,
|
||||
tile.sourceWidth,
|
||||
tile.sourceHeight,
|
||||
);
|
||||
const namedFilePath = await copyTempFileWithName(
|
||||
tempFilePath,
|
||||
buildShareGridTileFileName(params, tile.index),
|
||||
);
|
||||
await saveImageToAlbum(namedFilePath);
|
||||
page.setData({
|
||||
savedCount: tile.index + 1,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
Page({
|
||||
data: {
|
||||
errorMessage: '',
|
||||
loading: true,
|
||||
savedCount: 0,
|
||||
title: '九宫切图',
|
||||
},
|
||||
|
||||
async onLoad(query = {}) {
|
||||
const params = normalizeShareGridQuery(query);
|
||||
this._shareGridParams = params;
|
||||
this.setData({
|
||||
errorMessage: '',
|
||||
loading: true,
|
||||
savedCount: 0,
|
||||
title: params.title,
|
||||
});
|
||||
|
||||
if (!params.imageUrl) {
|
||||
this.setData({
|
||||
errorMessage: '缺少封面图。',
|
||||
loading: false,
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
try {
|
||||
const localImagePath = await downloadImage(params.imageUrl);
|
||||
const imageInfo = await getImageInfo(localImagePath);
|
||||
await saveGridTiles(this, params, localImagePath, imageInfo);
|
||||
this.setData({
|
||||
loading: false,
|
||||
savedCount: 9,
|
||||
});
|
||||
wx.showToast({
|
||||
title: '已保存',
|
||||
icon: 'success',
|
||||
});
|
||||
} catch (error) {
|
||||
console.error('[share-grid] save failed', error);
|
||||
this.setData({
|
||||
errorMessage:
|
||||
error && error.message ? error.message : '九宫切图保存失败。',
|
||||
loading: false,
|
||||
});
|
||||
}
|
||||
},
|
||||
|
||||
handleBack() {
|
||||
wx.navigateBack();
|
||||
},
|
||||
});
|
||||
@@ -1,3 +0,0 @@
|
||||
{
|
||||
"navigationBarTitleText": "九宫切图"
|
||||
}
|
||||
@@ -1,62 +0,0 @@
|
||||
const GRID_SIZE = 3;
|
||||
const TILE_COUNT = GRID_SIZE * GRID_SIZE;
|
||||
|
||||
function normalizeQueryValue(value) {
|
||||
return String(value || '').trim();
|
||||
}
|
||||
|
||||
function sanitizeFileNamePart(value) {
|
||||
const normalized = normalizeQueryValue(value)
|
||||
.replace(/[\\/:*?"<>|]/g, '')
|
||||
.replace(/\s+/g, '-')
|
||||
.slice(0, 32);
|
||||
return normalized || 'taonier';
|
||||
}
|
||||
|
||||
function buildShareGridTileFileName(params, tileIndex) {
|
||||
const safeTitle = sanitizeFileNamePart(params.title || params.publicWorkCode);
|
||||
const safeCode = sanitizeFileNamePart(params.publicWorkCode || 'share');
|
||||
const order = String(tileIndex + 1).padStart(2, '0');
|
||||
return `${safeTitle}-${safeCode}-${order}.png`;
|
||||
}
|
||||
|
||||
function normalizeShareGridQuery(query) {
|
||||
return {
|
||||
imageUrl: normalizeQueryValue(query && query.imageUrl),
|
||||
title: normalizeQueryValue(query && query.title) || '我的作品',
|
||||
publicWorkCode: normalizeQueryValue(query && query.publicWorkCode),
|
||||
};
|
||||
}
|
||||
|
||||
function buildShareGridTilePlan(imageWidth, imageHeight) {
|
||||
const tileWidth = Math.floor(imageWidth / GRID_SIZE);
|
||||
const tileHeight = Math.floor(imageHeight / GRID_SIZE);
|
||||
const plan = [];
|
||||
|
||||
for (let row = 0; row < GRID_SIZE; row += 1) {
|
||||
for (let col = 0; col < GRID_SIZE; col += 1) {
|
||||
const index = row * GRID_SIZE + col;
|
||||
const sourceX = col * tileWidth;
|
||||
const sourceY = row * tileHeight;
|
||||
plan.push({
|
||||
index,
|
||||
row,
|
||||
col,
|
||||
sourceX,
|
||||
sourceY,
|
||||
sourceWidth: col === GRID_SIZE - 1 ? imageWidth - sourceX : tileWidth,
|
||||
sourceHeight: row === GRID_SIZE - 1 ? imageHeight - sourceY : tileHeight,
|
||||
});
|
||||
}
|
||||
}
|
||||
|
||||
return plan;
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
GRID_SIZE,
|
||||
TILE_COUNT,
|
||||
buildShareGridTileFileName,
|
||||
buildShareGridTilePlan,
|
||||
normalizeShareGridQuery,
|
||||
};
|
||||
@@ -1,67 +0,0 @@
|
||||
import { describe, expect, test } from 'vitest';
|
||||
|
||||
import shareGridBridge from './index.shared.js';
|
||||
|
||||
const {
|
||||
buildShareGridTileFileName,
|
||||
buildShareGridTilePlan,
|
||||
normalizeShareGridQuery,
|
||||
} = shareGridBridge;
|
||||
|
||||
describe('share-grid mini program bridge', () => {
|
||||
test('normalizes query values and keeps a fallback title', () => {
|
||||
expect(
|
||||
normalizeShareGridQuery({
|
||||
imageUrl: ' https://web.test/cover.png ',
|
||||
publicWorkCode: ' PZ-0001 ',
|
||||
}),
|
||||
).toEqual({
|
||||
imageUrl: 'https://web.test/cover.png',
|
||||
title: '我的作品',
|
||||
publicWorkCode: 'PZ-0001',
|
||||
});
|
||||
});
|
||||
|
||||
test('names tiles by title, public code and left-to-right order', () => {
|
||||
const params = {
|
||||
title: '星港:拼图',
|
||||
publicWorkCode: 'PZ-0001',
|
||||
};
|
||||
|
||||
expect(buildShareGridTileFileName(params, 0)).toBe(
|
||||
'星港拼图-PZ-0001-01.png',
|
||||
);
|
||||
expect(buildShareGridTileFileName(params, 8)).toBe(
|
||||
'星港拼图-PZ-0001-09.png',
|
||||
);
|
||||
});
|
||||
|
||||
test('builds a 3x3 crop plan in reading order', () => {
|
||||
const plan = buildShareGridTilePlan(900, 600);
|
||||
|
||||
expect(plan).toHaveLength(9);
|
||||
expect(plan[0]).toMatchObject({
|
||||
index: 0,
|
||||
row: 0,
|
||||
col: 0,
|
||||
sourceX: 0,
|
||||
sourceY: 0,
|
||||
sourceWidth: 300,
|
||||
sourceHeight: 200,
|
||||
});
|
||||
expect(plan[4]).toMatchObject({
|
||||
index: 4,
|
||||
row: 1,
|
||||
col: 1,
|
||||
sourceX: 300,
|
||||
sourceY: 200,
|
||||
});
|
||||
expect(plan[8]).toMatchObject({
|
||||
index: 8,
|
||||
row: 2,
|
||||
col: 2,
|
||||
sourceX: 600,
|
||||
sourceY: 400,
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -1,20 +0,0 @@
|
||||
<view class="share-grid-page">
|
||||
<view class="share-grid-card">
|
||||
<view class="share-grid-title">{{title}}</view>
|
||||
<view wx:if="{{loading}}" class="share-grid-text">
|
||||
正在保存 {{savedCount}}/9
|
||||
</view>
|
||||
<view wx:elif="{{errorMessage}}" class="share-grid-text share-grid-text--danger">
|
||||
{{errorMessage}}
|
||||
</view>
|
||||
<view wx:else class="share-grid-text">已保存 9/9</view>
|
||||
<button class="share-grid-button" bindtap="handleBack">
|
||||
返回
|
||||
</button>
|
||||
</view>
|
||||
<canvas
|
||||
id="share-grid-canvas"
|
||||
type="2d"
|
||||
class="share-grid-canvas"
|
||||
></canvas>
|
||||
</view>
|
||||
@@ -1,60 +0,0 @@
|
||||
page {
|
||||
background: #fffdf9;
|
||||
}
|
||||
|
||||
.share-grid-page {
|
||||
min-height: 100vh;
|
||||
box-sizing: border-box;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
padding: 48rpx;
|
||||
background: #fffdf9;
|
||||
}
|
||||
|
||||
.share-grid-card {
|
||||
width: 100%;
|
||||
max-width: 560rpx;
|
||||
box-sizing: border-box;
|
||||
border: 1rpx solid rgba(127, 85, 57, 0.18);
|
||||
border-radius: 16rpx;
|
||||
background: rgba(255, 255, 255, 0.92);
|
||||
padding: 36rpx;
|
||||
box-shadow: 0 24rpx 68rpx rgba(127, 85, 57, 0.12);
|
||||
}
|
||||
|
||||
.share-grid-title {
|
||||
color: #332820;
|
||||
font-size: 34rpx;
|
||||
font-weight: 700;
|
||||
line-height: 1.35;
|
||||
}
|
||||
|
||||
.share-grid-text {
|
||||
margin-top: 18rpx;
|
||||
color: rgba(51, 40, 32, 0.68);
|
||||
font-size: 26rpx;
|
||||
line-height: 1.55;
|
||||
}
|
||||
|
||||
.share-grid-text--danger {
|
||||
color: #b84a3d;
|
||||
}
|
||||
|
||||
.share-grid-button {
|
||||
margin-top: 28rpx;
|
||||
width: 100%;
|
||||
border-radius: 8rpx;
|
||||
background: #7f5539;
|
||||
color: #fffdf9;
|
||||
font-size: 28rpx;
|
||||
line-height: 2.6;
|
||||
}
|
||||
|
||||
.share-grid-canvas {
|
||||
position: fixed;
|
||||
left: -9999px;
|
||||
top: -9999px;
|
||||
width: 1px;
|
||||
height: 1px;
|
||||
}
|
||||
@@ -1,10 +0,0 @@
|
||||
/* global Page */
|
||||
|
||||
const { GENERATION_RESULT_SUBSCRIBE_TEMPLATE_ID } = require('../../config');
|
||||
const { createSubscribeMessagePage } = require('./index.shared');
|
||||
|
||||
Page(
|
||||
createSubscribeMessagePage(null, {
|
||||
templateId: GENERATION_RESULT_SUBSCRIBE_TEMPLATE_ID,
|
||||
}),
|
||||
);
|
||||
@@ -1,3 +0,0 @@
|
||||
{
|
||||
"navigationBarTitleText": "生成通知"
|
||||
}
|
||||
@@ -1,128 +0,0 @@
|
||||
/* global wx */
|
||||
|
||||
const SUBSCRIBE_RESULT_STORAGE_KEY = 'genarrative:wechat-subscribe-result';
|
||||
|
||||
function appendSubscribeResult(url, result) {
|
||||
const hashIndex = String(url || '').indexOf('#');
|
||||
const baseUrl =
|
||||
hashIndex >= 0 ? String(url).slice(0, hashIndex) : String(url || '');
|
||||
const rawHash = hashIndex >= 0 ? String(url).slice(hashIndex + 1) : '';
|
||||
const nextHash = rawHash
|
||||
.split('&')
|
||||
.filter((part) => part && !part.startsWith('wx_subscribe_result='))
|
||||
.concat(`wx_subscribe_result=${encodeURIComponent(result)}`)
|
||||
.join('&');
|
||||
return `${baseUrl}#${nextHash}`;
|
||||
}
|
||||
|
||||
function buildSubscribeResultValue(requestId, status, reason) {
|
||||
const segments = [requestId, status];
|
||||
if (reason) {
|
||||
segments.push(encodeURIComponent(reason));
|
||||
}
|
||||
return segments.join(':');
|
||||
}
|
||||
|
||||
function notifyPreviousWebView(requestId, status, reason) {
|
||||
const result = buildSubscribeResultValue(requestId, status, reason);
|
||||
wx.setStorageSync(SUBSCRIBE_RESULT_STORAGE_KEY, result);
|
||||
}
|
||||
|
||||
function resolveSubscribeStatus(result, templateId) {
|
||||
return result && result[templateId] === 'accept'
|
||||
? 'success'
|
||||
: 'skip';
|
||||
}
|
||||
|
||||
function createSubscribeMessagePage(pageContext, options = {}) {
|
||||
const templateId = String(options.templateId || '').trim();
|
||||
const notifyPageResult = (methodThis, status, reason) => {
|
||||
const page = pageContext ?? methodThis;
|
||||
const requestId = page.requestId || '';
|
||||
if (!requestId || page.hasNotifiedSubscribeResult) {
|
||||
return;
|
||||
}
|
||||
page.hasNotifiedSubscribeResult = true;
|
||||
notifyPreviousWebView(requestId, status, reason);
|
||||
};
|
||||
|
||||
return {
|
||||
data: {
|
||||
title: '接收生成结果通知',
|
||||
errorMessage: '',
|
||||
requesting: false,
|
||||
},
|
||||
|
||||
onLoad(query) {
|
||||
const page = pageContext ?? this;
|
||||
page.requestId = String(query.requestId || '');
|
||||
page.hasNotifiedSubscribeResult = false;
|
||||
},
|
||||
|
||||
notifyResult(status, reason) {
|
||||
notifyPageResult(this, status, reason);
|
||||
},
|
||||
|
||||
requestSubscribe() {
|
||||
const page = pageContext ?? this;
|
||||
const requestId = page.requestId || '';
|
||||
if (!requestId) {
|
||||
page.setData({
|
||||
errorMessage: '缺少订阅请求参数。',
|
||||
});
|
||||
return;
|
||||
}
|
||||
if (!templateId) {
|
||||
notifyPageResult(this, 'skip', 'missing_template_id');
|
||||
wx.navigateBack();
|
||||
return;
|
||||
}
|
||||
if (typeof wx.requestSubscribeMessage !== 'function') {
|
||||
notifyPageResult(this, 'skip', 'unsupported');
|
||||
wx.navigateBack();
|
||||
return;
|
||||
}
|
||||
|
||||
page.setData({
|
||||
requesting: true,
|
||||
errorMessage: '',
|
||||
});
|
||||
wx.requestSubscribeMessage({
|
||||
tmplIds: [templateId],
|
||||
success(result) {
|
||||
notifyPageResult(
|
||||
page,
|
||||
resolveSubscribeStatus(result, templateId),
|
||||
'',
|
||||
);
|
||||
wx.navigateBack();
|
||||
},
|
||||
fail(error) {
|
||||
notifyPageResult(
|
||||
page,
|
||||
'skip',
|
||||
error && error.errMsg ? error.errMsg : 'failed',
|
||||
);
|
||||
wx.navigateBack();
|
||||
},
|
||||
});
|
||||
},
|
||||
|
||||
handleSkip() {
|
||||
notifyPageResult(this, 'skip', 'user_skip');
|
||||
wx.navigateBack();
|
||||
},
|
||||
|
||||
onUnload() {
|
||||
notifyPageResult(this, 'skip', 'page_unload');
|
||||
},
|
||||
};
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
SUBSCRIBE_RESULT_STORAGE_KEY,
|
||||
appendSubscribeResult,
|
||||
buildSubscribeResultValue,
|
||||
createSubscribeMessagePage,
|
||||
resolveSubscribeStatus,
|
||||
};
|
||||
@@ -1,93 +0,0 @@
|
||||
import { beforeEach, describe, expect, test, vi } from 'vitest';
|
||||
|
||||
import subscribeMessageBridge from './index.shared.js';
|
||||
|
||||
const TEST_TEMPLATE_ID = 'm5z7BkkBhJGbcH0cdDeHaeRU2tViDEguP38XdrRRCdU';
|
||||
|
||||
const {
|
||||
SUBSCRIBE_RESULT_STORAGE_KEY,
|
||||
appendSubscribeResult,
|
||||
buildSubscribeResultValue,
|
||||
createSubscribeMessagePage,
|
||||
} = subscribeMessageBridge;
|
||||
|
||||
describe('subscribe-message mini program bridge', () => {
|
||||
beforeEach(() => {
|
||||
globalThis.wx = {
|
||||
requestSubscribeMessage: vi.fn(),
|
||||
setStorageSync: vi.fn(),
|
||||
navigateBack: vi.fn(),
|
||||
};
|
||||
globalThis.getCurrentPages = vi.fn(() => []);
|
||||
});
|
||||
|
||||
test('requests subscribe message and stores result before returning', () => {
|
||||
const previousPage = {
|
||||
data: { webViewUrl: 'https://web.test/#tab=create' },
|
||||
setData: vi.fn(),
|
||||
};
|
||||
globalThis.getCurrentPages = vi.fn(() => [previousPage, {}]);
|
||||
globalThis.wx.requestSubscribeMessage.mockImplementationOnce((options) => {
|
||||
options.success?.({
|
||||
m5z7BkkBhJGbcH0cdDeHaeRU2tViDEguP38XdrRRCdU: 'accept',
|
||||
});
|
||||
});
|
||||
const page = createSubscribeMessagePage(
|
||||
{
|
||||
setData: vi.fn(),
|
||||
},
|
||||
{ templateId: TEST_TEMPLATE_ID },
|
||||
);
|
||||
page.onLoad({ requestId: 'request-1' });
|
||||
|
||||
page.requestSubscribe();
|
||||
|
||||
expect(globalThis.wx.requestSubscribeMessage).toHaveBeenCalledWith({
|
||||
tmplIds: [TEST_TEMPLATE_ID],
|
||||
success: expect.any(Function),
|
||||
fail: expect.any(Function),
|
||||
});
|
||||
expect(globalThis.wx.setStorageSync).toHaveBeenCalledWith(
|
||||
SUBSCRIBE_RESULT_STORAGE_KEY,
|
||||
'request-1:success',
|
||||
);
|
||||
expect(previousPage.setData).not.toHaveBeenCalled();
|
||||
expect(globalThis.wx.navigateBack).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
test('skip action notifies previous web-view', () => {
|
||||
const previousPage = {
|
||||
data: { webViewUrl: 'https://web.test/' },
|
||||
setData: vi.fn(),
|
||||
};
|
||||
globalThis.getCurrentPages = vi.fn(() => [previousPage, {}]);
|
||||
const page = createSubscribeMessagePage(
|
||||
{
|
||||
setData: vi.fn(),
|
||||
},
|
||||
{ templateId: TEST_TEMPLATE_ID },
|
||||
);
|
||||
page.onLoad({ requestId: 'request-skip' });
|
||||
|
||||
page.handleSkip();
|
||||
|
||||
expect(globalThis.wx.setStorageSync).toHaveBeenCalledWith(
|
||||
SUBSCRIBE_RESULT_STORAGE_KEY,
|
||||
'request-skip:skip:user_skip',
|
||||
);
|
||||
expect(previousPage.setData).not.toHaveBeenCalled();
|
||||
expect(globalThis.wx.navigateBack).toHaveBeenCalled();
|
||||
});
|
||||
|
||||
test('appendSubscribeResult replaces stale subscribe hash', () => {
|
||||
expect(
|
||||
appendSubscribeResult(
|
||||
'https://web.test/#old=1&wx_subscribe_result=old',
|
||||
'req:skip',
|
||||
),
|
||||
).toBe('https://web.test/#old=1&wx_subscribe_result=req%3Askip');
|
||||
expect(buildSubscribeResultValue('req-1', 'skip', 'user_cancel')).toBe(
|
||||
'req-1:skip:user_cancel',
|
||||
);
|
||||
});
|
||||
});
|
||||
@@ -1,19 +0,0 @@
|
||||
<view class="subscribe-screen">
|
||||
<view class="subscribe-card">
|
||||
<view class="subscribe-title">{{title}}</view>
|
||||
<view wx:if="{{errorMessage}}" class="subscribe-text subscribe-text--danger">
|
||||
{{errorMessage}}
|
||||
</view>
|
||||
<button
|
||||
class="primary-button"
|
||||
loading="{{requesting}}"
|
||||
disabled="{{requesting}}"
|
||||
bindtap="requestSubscribe"
|
||||
>
|
||||
继续并接收通知
|
||||
</button>
|
||||
<button class="ghost-button" disabled="{{requesting}}" bindtap="handleSkip">
|
||||
仅继续生成
|
||||
</button>
|
||||
</view>
|
||||
</view>
|
||||
@@ -1,58 +0,0 @@
|
||||
.subscribe-screen {
|
||||
min-height: 100vh;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
padding: 48rpx;
|
||||
background: #0b0f14;
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
.subscribe-card {
|
||||
width: 100%;
|
||||
max-width: 560rpx;
|
||||
padding: 36rpx;
|
||||
border: 1rpx solid rgba(255, 255, 255, 0.14);
|
||||
border-radius: 12rpx;
|
||||
background: rgba(255, 255, 255, 0.06);
|
||||
box-sizing: border-box;
|
||||
}
|
||||
|
||||
.subscribe-title {
|
||||
font-size: 34rpx;
|
||||
font-weight: 600;
|
||||
line-height: 1.35;
|
||||
color: #f5f7fb;
|
||||
}
|
||||
|
||||
.subscribe-text {
|
||||
margin-top: 16rpx;
|
||||
font-size: 26rpx;
|
||||
line-height: 1.55;
|
||||
color: rgba(245, 247, 251, 0.72);
|
||||
}
|
||||
|
||||
.subscribe-text--danger {
|
||||
color: #ffb4a9;
|
||||
}
|
||||
|
||||
.primary-button,
|
||||
.ghost-button {
|
||||
margin-top: 28rpx;
|
||||
width: 100%;
|
||||
border-radius: 8rpx;
|
||||
font-size: 26rpx;
|
||||
line-height: 2.6;
|
||||
}
|
||||
|
||||
.primary-button {
|
||||
background: #f5f7fb;
|
||||
color: #0b0f14;
|
||||
}
|
||||
|
||||
.ghost-button {
|
||||
margin-top: 20rpx;
|
||||
border: 1rpx solid rgba(255, 255, 255, 0.24);
|
||||
background: transparent;
|
||||
color: rgba(245, 247, 251, 0.86);
|
||||
}
|
||||
@@ -10,13 +10,6 @@ const {
|
||||
WEB_VIEW_ENTRY_URL,
|
||||
WEB_VIEW_SOURCE_QUERY,
|
||||
} = require('../../config');
|
||||
const {
|
||||
appendHashParams,
|
||||
buildWebViewSharePath,
|
||||
buildWebViewShareTimelineQuery,
|
||||
resolveShareTargetFromWebViewMessage,
|
||||
resolveWebViewUrlFromRuntimeConfig,
|
||||
} = require('./index.shared');
|
||||
|
||||
const MINI_PROGRAM_CLIENT_TYPE = 'mini_program';
|
||||
const MINI_PROGRAM_CLIENT_RUNTIME = 'wechat_mini_program';
|
||||
@@ -26,6 +19,7 @@ const AUTH_RESULT_STORAGE_KEY = 'genarrative:mini-program-auth-result';
|
||||
const AUTH_ACTION_LOGIN = 'login';
|
||||
const PAY_RESULT_RECHECK_DELAY_MS = 120;
|
||||
const WEB_VIEW_SHARE_TITLE = '陶泥儿';
|
||||
const WEB_VIEW_SHARE_PATH = '/pages/web-view/index';
|
||||
|
||||
function showWebViewShareMenu() {
|
||||
if (typeof wx.showShareMenu !== 'function') {
|
||||
@@ -38,25 +32,17 @@ function showWebViewShareMenu() {
|
||||
});
|
||||
}
|
||||
|
||||
function resolveNativeShareQuery(page) {
|
||||
return (
|
||||
(page && page._currentShareTarget) ||
|
||||
(page && page._lastLaunchQuery) ||
|
||||
{}
|
||||
);
|
||||
}
|
||||
|
||||
function buildWebViewShareAppMessage(query = {}) {
|
||||
function buildWebViewShareAppMessage() {
|
||||
return {
|
||||
title: WEB_VIEW_SHARE_TITLE,
|
||||
path: buildWebViewSharePath(query),
|
||||
path: WEB_VIEW_SHARE_PATH,
|
||||
};
|
||||
}
|
||||
|
||||
function buildWebViewShareTimeline(query = {}) {
|
||||
function buildWebViewShareTimeline() {
|
||||
return {
|
||||
title: WEB_VIEW_SHARE_TITLE,
|
||||
query: buildWebViewShareTimelineQuery(query),
|
||||
query: '',
|
||||
};
|
||||
}
|
||||
|
||||
@@ -73,6 +59,50 @@ function isConfiguredApiBaseUrl(value) {
|
||||
return /^https:\/\/[^/]+/i.test(String(value || '').trim());
|
||||
}
|
||||
|
||||
function appendQuery(url, query) {
|
||||
const pairs = Object.keys(query)
|
||||
.filter((key) => query[key])
|
||||
.map(
|
||||
(key) =>
|
||||
`${encodeURIComponent(key)}=${encodeURIComponent(String(query[key]))}`,
|
||||
);
|
||||
|
||||
if (pairs.length === 0) {
|
||||
return url;
|
||||
}
|
||||
|
||||
return `${url}${url.includes('?') ? '&' : '?'}${pairs.join('&')}`;
|
||||
}
|
||||
|
||||
function appendHashParams(url, params) {
|
||||
const nextKeys = new Set(Object.keys(params).filter((key) => params[key]));
|
||||
const pairs = Object.keys(params)
|
||||
.filter((key) => params[key])
|
||||
.map(
|
||||
(key) =>
|
||||
`${encodeURIComponent(key)}=${encodeURIComponent(String(params[key]))}`,
|
||||
);
|
||||
if (pairs.length === 0) {
|
||||
return url;
|
||||
}
|
||||
|
||||
const hashIndex = url.indexOf('#');
|
||||
const baseUrl = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
|
||||
const rawHash = hashIndex >= 0 ? url.slice(hashIndex + 1) : '';
|
||||
const keptHashParts = rawHash.split('&').filter((part) => {
|
||||
if (!part) {
|
||||
return false;
|
||||
}
|
||||
const [rawKey = ''] = part.split('=');
|
||||
try {
|
||||
return !nextKeys.has(decodeURIComponent(rawKey));
|
||||
} catch (_error) {
|
||||
return !nextKeys.has(rawKey);
|
||||
}
|
||||
});
|
||||
return `${baseUrl}#${keptHashParts.concat(pairs).join('&')}`;
|
||||
}
|
||||
|
||||
function parseBooleanQueryFlag(value) {
|
||||
return value === true || value === '1' || value === 'true' || value === 'yes';
|
||||
}
|
||||
@@ -203,16 +233,22 @@ function shouldReturnToPreviousPage(query) {
|
||||
return String((query && query.returnTo) || '').trim() === 'previous';
|
||||
}
|
||||
|
||||
function resolveWebViewUrl(authResult, launchQuery = {}) {
|
||||
function resolveWebViewUrl(authResult) {
|
||||
const runtimeConfig = resolveMiniProgramRuntimeConfig();
|
||||
const entryUrl = String(runtimeConfig.webViewEntryUrl || '').trim();
|
||||
if (!isConfiguredEntryUrl(entryUrl)) {
|
||||
return '';
|
||||
}
|
||||
|
||||
return resolveWebViewUrlFromRuntimeConfig(authResult, launchQuery, {
|
||||
...runtimeConfig,
|
||||
webViewEntryUrl: String(runtimeConfig.webViewEntryUrl || '').trim(),
|
||||
const sourcedUrl = appendQuery(entryUrl, runtimeConfig.sourceQuery);
|
||||
if (!authResult || !authResult.token) {
|
||||
return sourcedUrl;
|
||||
}
|
||||
|
||||
return appendHashParams(sourcedUrl, {
|
||||
auth_provider: 'wechat',
|
||||
auth_token: authResult.token,
|
||||
auth_binding_status: authResult.bindingStatus,
|
||||
});
|
||||
}
|
||||
|
||||
@@ -431,7 +467,7 @@ Page({
|
||||
loading: false,
|
||||
phoneBindingRequired: false,
|
||||
returnToPreviousPage: false,
|
||||
webViewUrl: resolveWebViewUrl(null, query),
|
||||
webViewUrl: resolveWebViewUrl(null),
|
||||
});
|
||||
return;
|
||||
}
|
||||
@@ -536,7 +572,7 @@ Page({
|
||||
nicknameRequired: false,
|
||||
phoneBindingRequired: false,
|
||||
returnToPreviousPage,
|
||||
webViewUrl: resolveWebViewUrl(authResult, this._lastLaunchQuery || {}),
|
||||
webViewUrl: resolveWebViewUrl(authResult),
|
||||
});
|
||||
} catch (error) {
|
||||
this.setData({
|
||||
@@ -564,7 +600,7 @@ Page({
|
||||
loading: false,
|
||||
nicknameRequired: false,
|
||||
phoneBindingRequired: false,
|
||||
webViewUrl: resolveWebViewUrl(authResult, this._lastLaunchQuery || {}),
|
||||
webViewUrl: resolveWebViewUrl(authResult),
|
||||
});
|
||||
}
|
||||
|
||||
@@ -638,10 +674,7 @@ Page({
|
||||
loading: false,
|
||||
nicknameRequired: false,
|
||||
phoneBindingRequired: false,
|
||||
webViewUrl: resolveWebViewUrl(
|
||||
nextAuthResult,
|
||||
this._lastLaunchQuery || {},
|
||||
),
|
||||
webViewUrl: resolveWebViewUrl(nextAuthResult),
|
||||
});
|
||||
} catch (error) {
|
||||
this.setData({
|
||||
@@ -679,19 +712,15 @@ Page({
|
||||
},
|
||||
|
||||
handleWebViewMessage(event) {
|
||||
const shareTarget = resolveShareTargetFromWebViewMessage(event.detail);
|
||||
if (shareTarget) {
|
||||
this._currentShareTarget = shareTarget;
|
||||
}
|
||||
// 中文注释：支付和订阅消息都由独立 native 页面承接，web-view 消息只保留调试输出。
|
||||
// 中文注释：支付由独立 native 页面承接，web-view 消息只保留调试输出。
|
||||
console.info('[web-view] message', event.detail);
|
||||
},
|
||||
|
||||
onShareAppMessage() {
|
||||
return buildWebViewShareAppMessage(resolveNativeShareQuery(this));
|
||||
return buildWebViewShareAppMessage();
|
||||
},
|
||||
|
||||
onShareTimeline() {
|
||||
return buildWebViewShareTimeline(resolveNativeShareQuery(this));
|
||||
return buildWebViewShareTimeline();
|
||||
},
|
||||
});
|
||||
|
||||
@@ -1,188 +0,0 @@
|
||||
const ALLOWED_TARGET_PATHS = new Set(['/works/detail']);
|
||||
const SHARE_TARGET_MESSAGE_TYPE = 'genarrative:share-target';
|
||||
const WEB_VIEW_SHARE_PATH = '/pages/web-view/index';
|
||||
|
||||
function trimTrailingSlash(value) {
|
||||
return String(value || '').trim().replace(/\/+$/u, '');
|
||||
}
|
||||
|
||||
function appendQuery(url, query) {
|
||||
const rawUrl = String(url || '');
|
||||
const pairs = Object.keys(query)
|
||||
.filter((key) => query[key])
|
||||
.map(
|
||||
(key) =>
|
||||
`${encodeURIComponent(key)}=${encodeURIComponent(String(query[key]))}`,
|
||||
);
|
||||
|
||||
if (pairs.length === 0) {
|
||||
return rawUrl;
|
||||
}
|
||||
|
||||
const hashIndex = rawUrl.indexOf('#');
|
||||
const baseUrl = hashIndex >= 0 ? rawUrl.slice(0, hashIndex) : rawUrl;
|
||||
const hash = hashIndex >= 0 ? rawUrl.slice(hashIndex) : '';
|
||||
return `${baseUrl}${baseUrl.includes('?') ? '&' : '?'}${pairs.join('&')}${hash}`;
|
||||
}
|
||||
|
||||
function appendHashParams(url, params) {
|
||||
const nextKeys = new Set(Object.keys(params).filter((key) => params[key]));
|
||||
const pairs = Object.keys(params)
|
||||
.filter((key) => params[key])
|
||||
.map(
|
||||
(key) =>
|
||||
`${encodeURIComponent(key)}=${encodeURIComponent(String(params[key]))}`,
|
||||
);
|
||||
if (pairs.length === 0) {
|
||||
return url;
|
||||
}
|
||||
|
||||
const hashIndex = url.indexOf('#');
|
||||
const baseUrl = hashIndex >= 0 ? url.slice(0, hashIndex) : url;
|
||||
const rawHash = hashIndex >= 0 ? url.slice(hashIndex + 1) : '';
|
||||
const keptHashParts = rawHash.split('&').filter((part) => {
|
||||
if (!part) {
|
||||
return false;
|
||||
}
|
||||
const [rawKey = ''] = part.split('=');
|
||||
try {
|
||||
return !nextKeys.has(decodeURIComponent(rawKey));
|
||||
} catch (_error) {
|
||||
return !nextKeys.has(rawKey);
|
||||
}
|
||||
});
|
||||
return `${baseUrl}#${keptHashParts.concat(pairs).join('&')}`;
|
||||
}
|
||||
|
||||
function normalizeTargetPath(value) {
|
||||
const trimmed = String(value || '').trim();
|
||||
if (!trimmed.startsWith('/')) {
|
||||
return '';
|
||||
}
|
||||
|
||||
const normalized = trimmed.replace(/\/+$/u, '') || '/';
|
||||
return ALLOWED_TARGET_PATHS.has(normalized) ? normalized : '';
|
||||
}
|
||||
|
||||
function resolveLaunchTargetQuery(query) {
|
||||
const targetPath = normalizeTargetPath(query && query.targetPath);
|
||||
const work = String((query && query.work) || '').trim();
|
||||
if (!targetPath || !work) {
|
||||
return {};
|
||||
}
|
||||
|
||||
return {
|
||||
targetPath,
|
||||
work,
|
||||
};
|
||||
}
|
||||
|
||||
function buildWebViewSharePath(query = {}, basePath = WEB_VIEW_SHARE_PATH) {
|
||||
const launchTarget = resolveLaunchTargetQuery(query);
|
||||
if (!launchTarget.targetPath) {
|
||||
return basePath;
|
||||
}
|
||||
|
||||
return appendQuery(basePath, {
|
||||
targetPath: launchTarget.targetPath,
|
||||
work: launchTarget.work,
|
||||
});
|
||||
}
|
||||
|
||||
function buildWebViewShareTimelineQuery(query = {}) {
|
||||
const launchTarget = resolveLaunchTargetQuery(query);
|
||||
if (!launchTarget.targetPath) {
|
||||
return '';
|
||||
}
|
||||
|
||||
return new URLSearchParams({
|
||||
targetPath: launchTarget.targetPath,
|
||||
work: launchTarget.work,
|
||||
}).toString();
|
||||
}
|
||||
|
||||
function normalizeShareTargetMessageData(value) {
|
||||
const message = value && value.data ? value.data : value;
|
||||
if (!message || message.type !== SHARE_TARGET_MESSAGE_TYPE) {
|
||||
return null;
|
||||
}
|
||||
|
||||
const payload = message.payload || {};
|
||||
const launchTarget = resolveLaunchTargetQuery(payload);
|
||||
if (!launchTarget.targetPath) {
|
||||
return null;
|
||||
}
|
||||
|
||||
return {
|
||||
...launchTarget,
|
||||
title: String(payload.title || '').trim(),
|
||||
};
|
||||
}
|
||||
|
||||
function resolveShareTargetFromWebViewMessage(detail) {
|
||||
const dataList = detail && Array.isArray(detail.data) ? detail.data : [];
|
||||
for (let index = dataList.length - 1; index >= 0; index -= 1) {
|
||||
const target = normalizeShareTargetMessageData(dataList[index]);
|
||||
if (target) {
|
||||
return target;
|
||||
}
|
||||
}
|
||||
|
||||
return normalizeShareTargetMessageData(detail);
|
||||
}
|
||||
|
||||
function appendLaunchTargetToEntryUrl(entryUrl, query) {
|
||||
const launchTarget = resolveLaunchTargetQuery(query);
|
||||
if (!launchTarget.targetPath) {
|
||||
return entryUrl;
|
||||
}
|
||||
|
||||
const rawEntryUrl = String(entryUrl || '').trim();
|
||||
const hashIndex = rawEntryUrl.indexOf('#');
|
||||
const entryWithoutHash =
|
||||
hashIndex >= 0 ? rawEntryUrl.slice(0, hashIndex) : rawEntryUrl;
|
||||
const hash = hashIndex >= 0 ? rawEntryUrl.slice(hashIndex) : '';
|
||||
const queryIndex = entryWithoutHash.indexOf('?');
|
||||
const entryBase =
|
||||
queryIndex >= 0 ? entryWithoutHash.slice(0, queryIndex) : entryWithoutHash;
|
||||
const entrySearch =
|
||||
queryIndex >= 0 ? entryWithoutHash.slice(queryIndex) : '';
|
||||
const targetUrl = `${trimTrailingSlash(entryBase)}${launchTarget.targetPath}${entrySearch}${hash}`;
|
||||
|
||||
return appendQuery(targetUrl, {
|
||||
work: launchTarget.work,
|
||||
});
|
||||
}
|
||||
|
||||
function resolveWebViewUrlFromRuntimeConfig(
|
||||
authResult,
|
||||
launchQuery = {},
|
||||
runtimeConfig = {},
|
||||
) {
|
||||
const entryUrl = appendLaunchTargetToEntryUrl(
|
||||
String(runtimeConfig.webViewEntryUrl || '').trim(),
|
||||
launchQuery,
|
||||
);
|
||||
const sourcedUrl = appendQuery(entryUrl, runtimeConfig.sourceQuery || {});
|
||||
if (!authResult || !authResult.token) {
|
||||
return sourcedUrl;
|
||||
}
|
||||
|
||||
return appendHashParams(sourcedUrl, {
|
||||
auth_provider: 'wechat',
|
||||
auth_token: authResult.token,
|
||||
auth_binding_status: authResult.bindingStatus,
|
||||
});
|
||||
}
|
||||
|
||||
module.exports = {
|
||||
appendHashParams,
|
||||
appendLaunchTargetToEntryUrl,
|
||||
appendQuery,
|
||||
buildWebViewSharePath,
|
||||
buildWebViewShareTimelineQuery,
|
||||
normalizeTargetPath,
|
||||
resolveShareTargetFromWebViewMessage,
|
||||
resolveLaunchTargetQuery,
|
||||
resolveWebViewUrlFromRuntimeConfig,
|
||||
};
|
||||
@@ -1,32 +0,0 @@
|
||||
import fs from 'node:fs';
|
||||
import path from 'node:path';
|
||||
|
||||
import { describe, expect, test } from 'vitest';
|
||||
|
||||
const PAGE_DIR = path.resolve(
|
||||
process.cwd(),
|
||||
'miniprogram/pages/web-view',
|
||||
);
|
||||
|
||||
function readPageFile(fileName) {
|
||||
return fs.readFileSync(path.join(PAGE_DIR, fileName), 'utf8');
|
||||
}
|
||||
|
||||
describe('mini program web-view page background', () => {
|
||||
test('keeps the native web-view host light when the mobile keyboard exposes it', () => {
|
||||
const wxml = readPageFile('index.wxml');
|
||||
const wxss = readPageFile('index.wxss');
|
||||
|
||||
expect(wxml).toContain('class="web-view-host"');
|
||||
expect(wxml).not.toContain('class="web-view-page"');
|
||||
expect(wxss).toContain('page');
|
||||
expect(wxss).toContain('.web-view-host');
|
||||
expect(wxss).toContain('background: #fffdf9;');
|
||||
|
||||
const webViewHostBlock = wxss.slice(
|
||||
wxss.indexOf('.web-view-host'),
|
||||
wxss.indexOf('.setup-screen'),
|
||||
);
|
||||
expect(webViewHostBlock).not.toContain('#0b0f14');
|
||||
});
|
||||
});
|
||||
@@ -1,110 +0,0 @@
|
||||
import { describe, expect, test } from 'vitest';
|
||||
|
||||
import webViewBridge from './index.shared.js';
|
||||
|
||||
const {
|
||||
appendLaunchTargetToEntryUrl,
|
||||
buildWebViewSharePath,
|
||||
buildWebViewShareTimelineQuery,
|
||||
resolveShareTargetFromWebViewMessage,
|
||||
resolveWebViewUrlFromRuntimeConfig,
|
||||
} = webViewBridge;
|
||||
|
||||
const runtimeConfig = {
|
||||
sourceQuery: {
|
||||
clientType: 'mini_program',
|
||||
clientRuntime: 'wechat_mini_program',
|
||||
},
|
||||
webViewEntryUrl: 'https://www.genarrative.world',
|
||||
};
|
||||
|
||||
describe('mini program web-view launch target', () => {
|
||||
test('opens the H5 public work detail when launch query carries work params', () => {
|
||||
expect(
|
||||
appendLaunchTargetToEntryUrl('https://www.genarrative.world?foo=bar', {
|
||||
targetPath: '/works/detail',
|
||||
work: 'BB-12345678',
|
||||
}),
|
||||
).toBe(
|
||||
'https://www.genarrative.world/works/detail?foo=bar&work=BB-12345678',
|
||||
);
|
||||
|
||||
const webViewUrl = resolveWebViewUrlFromRuntimeConfig(
|
||||
null,
|
||||
{
|
||||
targetPath: '/works/detail',
|
||||
work: 'BB-12345678',
|
||||
},
|
||||
runtimeConfig,
|
||||
);
|
||||
const url = new URL(webViewUrl);
|
||||
expect(url.pathname).toBe('/works/detail');
|
||||
expect(url.searchParams.get('work')).toBe('BB-12345678');
|
||||
expect(url.searchParams.get('clientRuntime')).toBe('wechat_mini_program');
|
||||
});
|
||||
|
||||
test('ignores unsupported launch target paths', () => {
|
||||
const webViewUrl = resolveWebViewUrlFromRuntimeConfig(
|
||||
null,
|
||||
{
|
||||
targetPath: '/admin',
|
||||
work: 'BB-12345678',
|
||||
},
|
||||
runtimeConfig,
|
||||
);
|
||||
const url = new URL(webViewUrl);
|
||||
expect(url.pathname).toBe('/');
|
||||
expect(url.searchParams.get('work')).toBeNull();
|
||||
});
|
||||
|
||||
test('keeps public work params in native mini program share paths', () => {
|
||||
const sharePath = buildWebViewSharePath({
|
||||
targetPath: '/works/detail',
|
||||
work: 'BB-12345678',
|
||||
});
|
||||
const url = new URL(sharePath, 'https://mini.test');
|
||||
|
||||
expect(url.pathname).toBe('/pages/web-view/index');
|
||||
expect(url.searchParams.get('targetPath')).toBe('/works/detail');
|
||||
expect(url.searchParams.get('work')).toBe('BB-12345678');
|
||||
expect(
|
||||
buildWebViewShareTimelineQuery({
|
||||
targetPath: '/works/detail',
|
||||
work: 'BB-12345678',
|
||||
}),
|
||||
).toBe('targetPath=%2Fworks%2Fdetail&work=BB-12345678');
|
||||
});
|
||||
|
||||
test('reads the latest H5 recommended work share target from web-view messages', () => {
|
||||
expect(
|
||||
resolveShareTargetFromWebViewMessage({
|
||||
data: [
|
||||
{
|
||||
data: {
|
||||
type: 'genarrative:share-target',
|
||||
payload: {
|
||||
targetPath: '/works/detail',
|
||||
work: 'PZ-0001',
|
||||
title: '旧作品',
|
||||
},
|
||||
},
|
||||
},
|
||||
{
|
||||
data: {
|
||||
type: 'genarrative:share-target',
|
||||
payload: {
|
||||
targetPath: '/works/detail',
|
||||
work: 'BB-12345678',
|
||||
title: '汪汪声浪',
|
||||
},
|
||||
},
|
||||
},
|
||||
],
|
||||
}),
|
||||
).toEqual({
|
||||
targetPath: '/works/detail',
|
||||
work: 'BB-12345678',
|
||||
title: '汪汪声浪',
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -1,7 +1,6 @@
|
||||
<block wx:if="{{webViewUrl}}">
|
||||
<web-view
|
||||
id="genarrative-web-view"
|
||||
class="web-view-host"
|
||||
src="{{webViewUrl}}"
|
||||
bindload="handleWebViewLoad"
|
||||
binderror="handleWebViewError"
|
||||
|
||||
@@ -1,14 +1,3 @@
|
||||
page {
|
||||
background: #fffdf9;
|
||||
}
|
||||
|
||||
.web-view-host {
|
||||
display: block;
|
||||
width: 100%;
|
||||
min-height: 100vh;
|
||||
background: #fffdf9;
|
||||
}
|
||||
|
||||
.setup-screen {
|
||||
min-height: 100vh;
|
||||
display: flex;
|
||||
|
||||
@@ -9,7 +9,6 @@
|
||||
"dev:api-server": "node scripts/dev.mjs api-server",
|
||||
"dev:web": "node scripts/dev.mjs web",
|
||||
"dev:admin-web": "node scripts/dev.mjs admin-web",
|
||||
"server-manager:panel": "cargo run -p server-manager-panel --manifest-path server-rs/Cargo.toml",
|
||||
"dev:spacetime:logs": "node scripts/run-bash-script.mjs scripts/spacetime-logs-local.sh",
|
||||
"otel:debug": "node scripts/run-otelcol.mjs debug",
|
||||
"otel:rider": "node scripts/run-otelcol.mjs rider",
|
||||
@@ -28,7 +27,6 @@
|
||||
"clean": "node -e \"require('fs').rmSync('dist', { recursive: true, force: true })\"",
|
||||
"check:encoding": "node scripts/check-encoding.mjs",
|
||||
"check:spacetime-schema": "node scripts/check-spacetime-schema-guard.mjs",
|
||||
"check:production-ops": "node scripts/check-production-ops-guardrails.mjs",
|
||||
"assets:child-motion-demo": "node scripts/generate-child-motion-demo-assets.mjs",
|
||||
"assets:match3d-style-references": "node scripts/generate-match3d-style-references.mjs",
|
||||
"check:visual-novel-vn11": "node scripts/check-visual-novel-vn11-negative-scan.mjs",
|
||||
@@ -39,7 +37,7 @@
|
||||
"lint:guardrails": "npm run lint:eslint",
|
||||
"typecheck": "tsc -p tsconfig.typecheck-guardrails.json --noEmit",
|
||||
"typecheck:guardrails": "npm run typecheck",
|
||||
"lint": "npm run check:encoding && npm run check:spacetime-schema && npm run check:production-ops && npm run lint:eslint && npm run typecheck",
|
||||
"lint": "npm run check:encoding && npm run check:spacetime-schema && npm run lint:eslint && npm run typecheck",
|
||||
"lint:fix": "eslint . --ext .ts,.tsx,.js,.mjs,.cjs --fix && prettier --write .",
|
||||
"format": "prettier --write .",
|
||||
"format:check": "prettier --check .",
|
||||
|
||||
@@ -156,7 +156,8 @@ export type AuthPhoneChangeResponse = {
|
||||
};
|
||||
|
||||
export type AuthRefreshResponse = {
|
||||
token: string;
|
||||
ok: true;
|
||||
token?: string;
|
||||
};
|
||||
|
||||
export type AuthSessionSummary = {
|
||||
|
||||
@@ -61,7 +61,6 @@ export interface BarkBattleWorkPublishRequest {
|
||||
export interface BarkBattleImageAssetGenerateRequest {
|
||||
slot: BarkBattleAssetSlot;
|
||||
draftId?: string | null;
|
||||
billingPurpose?: 'initial_draft_generation' | null;
|
||||
config: BarkBattleConfigEditorPayload;
|
||||
}
|
||||
|
||||
|
||||
@@ -96,37 +96,6 @@ export interface JumpHopTileAsset {
|
||||
visualHeight: number;
|
||||
topSurfaceRadius: number;
|
||||
landingRadius: number;
|
||||
faceAssets?: JumpHopTileFaceAssets | null;
|
||||
}
|
||||
|
||||
export type JumpHopTileFaceKey =
|
||||
| 'top'
|
||||
| 'front'
|
||||
| 'right'
|
||||
| 'back'
|
||||
| 'left'
|
||||
| 'bottom';
|
||||
|
||||
export interface JumpHopTileFaceAsset {
|
||||
face: JumpHopTileFaceKey;
|
||||
assetId: string;
|
||||
imageSrc: string;
|
||||
imageObjectKey: string;
|
||||
assetObjectId: string;
|
||||
generationProvider: string;
|
||||
prompt: string;
|
||||
width: number;
|
||||
height: number;
|
||||
sourceAtlasCell: string;
|
||||
}
|
||||
|
||||
export interface JumpHopTileFaceAssets {
|
||||
top: JumpHopTileFaceAsset;
|
||||
front: JumpHopTileFaceAsset;
|
||||
right: JumpHopTileFaceAsset;
|
||||
back: JumpHopTileFaceAsset;
|
||||
left: JumpHopTileFaceAsset;
|
||||
bottom: JumpHopTileFaceAsset;
|
||||
}
|
||||
|
||||
export interface JumpHopScoring {
|
||||
@@ -325,7 +294,6 @@ export interface JumpHopJumpResponse {
|
||||
export interface JumpHopLeaderboardEntry {
|
||||
rank: number;
|
||||
playerId: string;
|
||||
displayName: string;
|
||||
successfulJumpCount: number;
|
||||
durationMs: number;
|
||||
updatedAt: string;
|
||||
|
||||
@@ -445,7 +445,7 @@ if [[ "${BUILD_SPACETIME}" -eq 1 ]]; then
|
||||
write_migration_bootstrap_secret_file
|
||||
fi
|
||||
|
||||
mkdir -p "${TARGET_DIR}/scripts" "${TARGET_DIR}/scripts/ops" "${TARGET_DIR}/deploy"
|
||||
mkdir -p "${TARGET_DIR}/scripts" "${TARGET_DIR}/deploy"
|
||||
cp "${SCRIPT_DIR}/deploy/maintenance-on.sh" "${TARGET_DIR}/scripts/maintenance-on.sh"
|
||||
cp "${SCRIPT_DIR}/deploy/maintenance-off.sh" "${TARGET_DIR}/scripts/maintenance-off.sh"
|
||||
cp "${SCRIPT_DIR}/deploy/maintenance-status.sh" "${TARGET_DIR}/scripts/maintenance-status.sh"
|
||||
@@ -466,7 +466,6 @@ copy_required_file "${SCRIPT_DIR}/spacetime-migration-common.mjs" "${TARGET_DIR}
|
||||
copy_required_file "${SCRIPT_DIR}/spacetime-authorize-migration-operator.mjs" "${TARGET_DIR}/scripts/spacetime-authorize-migration-operator.mjs" "数据库迁移授权脚本"
|
||||
copy_required_file "${SCRIPT_DIR}/spacetime-revoke-migration-operator.mjs" "${TARGET_DIR}/scripts/spacetime-revoke-migration-operator.mjs" "数据库迁移撤权脚本"
|
||||
copy_required_file "${SCRIPT_DIR}/database-backup-to-oss.mjs" "${TARGET_DIR}/scripts/database-backup-to-oss.mjs" "数据库 OSS 备份脚本"
|
||||
copy_required_file "${SCRIPT_DIR}/ops/production-health-patrol.mjs" "${TARGET_DIR}/scripts/ops/production-health-patrol.mjs" "生产健康巡检脚本"
|
||||
|
||||
copy_required_dir "${REPO_ROOT}/deploy/systemd" "${TARGET_DIR}/deploy/systemd" "systemd 配置"
|
||||
copy_required_dir "${REPO_ROOT}/deploy/nginx" "${TARGET_DIR}/deploy/nginx" "Nginx 配置"
|
||||
@@ -486,7 +485,7 @@ cat >"${TARGET_DIR}/README.md" <<EOF
|
||||
- \`migration-bootstrap-secret.txt\`：构建 \`spacetime_module.wasm\` 时注入的迁移引导密钥，仅用于创建首个迁移操作员；请作为敏感文件保存到 Jenkins Secret Text，授权完成后不要长期留在公开归档中。
|
||||
- \`*.sha256\`：发布产物 checksum，用于部署前校验。
|
||||
- \`release-manifest.json\`：发布版本、源码 commit 与产物清单。
|
||||
- \`scripts/\`：维护模式脚本、数据库导入导出脚本、数据库 OSS 备份脚本、生产健康巡检脚本、迁移授权脚本和 Jenkins inbound agent systemd 安装脚本。
|
||||
- \`scripts/\`：维护模式脚本、数据库导入导出脚本、数据库 OSS 备份脚本、迁移授权脚本和 Jenkins inbound agent systemd 安装脚本。
|
||||
- \`deploy/\`：systemd、Nginx 和生产环境变量示例；\`deploy/nginx/genarrative-dev-http.conf\` 仅供无域名开发服初始化使用。
|
||||
|
||||
## 生产部署口径
|
||||
|
||||
@@ -1,64 +0,0 @@
|
||||
#!/usr/bin/env node
|
||||
|
||||
import {readFileSync} from 'node:fs';
|
||||
|
||||
const checks = [
|
||||
{
|
||||
file: 'deploy/systemd/genarrative-database-backup.service',
|
||||
includes: '--restart-service-after genarrative-api.service',
|
||||
reason: '生产冷备份恢复 SpacetimeDB 后必须显式拉起依赖它的 API 服务。',
|
||||
},
|
||||
{
|
||||
file: 'deploy/systemd/genarrative-health-patrol.service',
|
||||
includes: 'scripts/ops/production-health-patrol.mjs',
|
||||
reason: '健康巡检 systemd service 必须调用随 API release 发布的巡检脚本。',
|
||||
},
|
||||
{
|
||||
file: 'deploy/systemd/genarrative-health-patrol.timer',
|
||||
includes: 'genarrative-health-patrol.service',
|
||||
reason: '健康巡检 timer 必须绑定巡检 service。',
|
||||
},
|
||||
{
|
||||
file: 'scripts/jenkins-server-provision.sh',
|
||||
includes: 'genarrative-health-patrol.timer',
|
||||
reason: 'Server-Provision 必须安装并启用健康巡检 timer。',
|
||||
},
|
||||
{
|
||||
file: 'scripts/build-production-release.sh',
|
||||
includes: 'production-health-patrol.mjs',
|
||||
reason: '生产 API release 必须携带健康巡检脚本。',
|
||||
},
|
||||
{
|
||||
file: 'scripts/deploy/production-api-deploy.sh',
|
||||
includes: 'production-health-patrol.mjs',
|
||||
reason: 'API deploy 必须把健康巡检脚本复制到 current release。',
|
||||
},
|
||||
{
|
||||
file: 'jenkins/Jenkinsfile.production-api-build',
|
||||
includes: 'scripts/ops/production-health-patrol.mjs',
|
||||
reason: 'API Build 归档必须包含健康巡检脚本。',
|
||||
},
|
||||
{
|
||||
file: 'jenkins/Jenkinsfile.production-api-deploy',
|
||||
includes: 'scripts/ops/production-health-patrol.mjs',
|
||||
reason: 'API Deploy 复制上游产物时必须包含健康巡检脚本。',
|
||||
},
|
||||
];
|
||||
|
||||
let failed = false;
|
||||
|
||||
for (const check of checks) {
|
||||
const content = readFileSync(check.file, 'utf8');
|
||||
if (!content.includes(check.includes)) {
|
||||
failed = true;
|
||||
console.error(
|
||||
`[check:production-ops] ${check.file} 缺少 ${check.includes}。${check.reason}`,
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
if (failed) {
|
||||
process.exit(1);
|
||||
}
|
||||
|
||||
console.log('[check:production-ops] OK');
|
||||
@@ -1,86 +0,0 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
REPO_ROOT="$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd)"
|
||||
TMP_ROOT="$(mktemp -d)"
|
||||
trap 'rm -rf "${TMP_ROOT}"' EXIT
|
||||
|
||||
WORK_DIR="${TMP_ROOT}/workspace"
|
||||
FAKE_BIN_DIR="${TMP_ROOT}/fake-bin"
|
||||
TARGET_BIN_DIR="${TMP_ROOT}/target-bin"
|
||||
SPACETIME_ROOT_DIR="${TMP_ROOT}/stdb"
|
||||
OUTPUT_LOG="${TMP_ROOT}/prepare.log"
|
||||
|
||||
mkdir -p \
|
||||
"${WORK_DIR}" \
|
||||
"${FAKE_BIN_DIR}" \
|
||||
"${TARGET_BIN_DIR}" \
|
||||
"${SPACETIME_ROOT_DIR}/bin/current"
|
||||
|
||||
cat >"${FAKE_BIN_DIR}/curl" <<'EOF'
|
||||
#!/usr/bin/env bash
|
||||
echo "curl should not be called when target tools are already ready" >&2
|
||||
exit 97
|
||||
EOF
|
||||
cat >"${FAKE_BIN_DIR}/wget" <<'EOF'
|
||||
#!/usr/bin/env bash
|
||||
echo "wget should not be called when target tools are already ready" >&2
|
||||
exit 97
|
||||
EOF
|
||||
chmod +x "${FAKE_BIN_DIR}/curl" "${FAKE_BIN_DIR}/wget"
|
||||
|
||||
cat >"${TARGET_BIN_DIR}/otelcol-contrib" <<'EOF'
|
||||
#!/usr/bin/env bash
|
||||
echo "otelcol-contrib version 0.151.0"
|
||||
EOF
|
||||
chmod +x "${TARGET_BIN_DIR}/otelcol-contrib"
|
||||
|
||||
cat >"${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-cli" <<'EOF'
|
||||
#!/usr/bin/env bash
|
||||
echo "spacetimedb-cli 2.4.1"
|
||||
EOF
|
||||
cat >"${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-standalone" <<'EOF'
|
||||
#!/usr/bin/env bash
|
||||
echo "spacetimedb-standalone 2.4.1"
|
||||
EOF
|
||||
chmod +x \
|
||||
"${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-cli" \
|
||||
"${SPACETIME_ROOT_DIR}/bin/current/spacetimedb-standalone"
|
||||
|
||||
if ! (
|
||||
cd "${WORK_DIR}"
|
||||
PATH="${FAKE_BIN_DIR}:${PATH}" \
|
||||
WORKSPACE="${WORK_DIR}" \
|
||||
PROVISION_TOOLS_DIR="provision-tools" \
|
||||
PROVISION_DOWNLOADS_DIR="downloads" \
|
||||
PROVISION_TOOLS_TMP_PARENT="${WORK_DIR}/.tmp/server-provision-tools" \
|
||||
PROVISION_REQUIRE_LOCAL_DOWNLOADS="true" \
|
||||
OTELCOL_TARGET_BIN="${TARGET_BIN_DIR}/otelcol-contrib" \
|
||||
OTELCOL_VERSION="0.151.0" \
|
||||
SPACETIME_ROOT="${SPACETIME_ROOT_DIR}" \
|
||||
SPACETIME_EXPECTED_VERSION="2.4.1" \
|
||||
"${REPO_ROOT}/scripts/prepare-server-provision-tools.sh" \
|
||||
>"${OUTPUT_LOG}" 2>&1
|
||||
); then
|
||||
echo "[check-server-provision-tools] prepare-server-provision-tools.sh 执行失败。" >&2
|
||||
cat "${OUTPUT_LOG}" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
grep -q "复用目标机已有 otelcol-contrib" "${OUTPUT_LOG}"
|
||||
grep -q "复用目标机已有 SpacetimeDB 安装" "${OUTPUT_LOG}"
|
||||
grep -q "otelcol-contrib 0.151.0 target existing" "${WORK_DIR}/provision-tools/MANIFEST.txt"
|
||||
grep -q "spacetime target existing" "${WORK_DIR}/provision-tools/MANIFEST.txt"
|
||||
|
||||
test -x "${WORK_DIR}/provision-tools/otelcol-contrib"
|
||||
test -x "${WORK_DIR}/provision-tools/spacetime/spacetime"
|
||||
test -x "${WORK_DIR}/provision-tools/spacetime/bin/current/spacetimedb-cli"
|
||||
test -x "${WORK_DIR}/provision-tools/spacetime/bin/current/spacetimedb-standalone"
|
||||
|
||||
if grep -q "下载 " "${OUTPUT_LOG}"; then
|
||||
echo "[check-server-provision-tools] 已有目标机工具时不应进入下载分支。" >&2
|
||||
cat "${OUTPUT_LOG}" >&2
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "[check-server-provision-tools] OK"
|
||||
@@ -20,7 +20,7 @@ const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
|
||||
function usage() {
|
||||
console.log(`用法:
|
||||
npm run database:backup:oss -- [--data-dir <path>] [--work-dir <path>] [--bucket <bucket>] [--object-prefix <prefix>] [--keep-local]
|
||||
node scripts/database-backup-to-oss.mjs [--stop-service spacetimedb.service] [--restart-service-after genarrative-api.service] [--defer-upload]
|
||||
node scripts/database-backup-to-oss.mjs [--stop-service spacetimedb.service] [--defer-upload]
|
||||
node scripts/database-backup-to-oss.mjs --upload-archive <path>
|
||||
|
||||
说明:
|
||||
@@ -100,7 +100,6 @@ function parseArgs(argv) {
|
||||
envFiles: [],
|
||||
keepLocal: false,
|
||||
stopService: '',
|
||||
restartServicesAfter: [],
|
||||
database: '',
|
||||
dryRun: false,
|
||||
deferUpload: false,
|
||||
@@ -160,9 +159,6 @@ function parseArgs(argv) {
|
||||
case '--stop-service':
|
||||
options.stopService = readValue();
|
||||
break;
|
||||
case '--restart-service-after':
|
||||
options.restartServicesAfter.push(readValue());
|
||||
break;
|
||||
case '--keep-local':
|
||||
options.keepLocal = true;
|
||||
break;
|
||||
@@ -270,16 +266,6 @@ function startServiceIfNeeded(serviceName, wasStopped) {
|
||||
runCommand('systemctl', ['start', serviceName], {stdio: 'inherit'});
|
||||
}
|
||||
|
||||
function restartServicesAfterBackup(serviceNames) {
|
||||
for (const serviceName of serviceNames) {
|
||||
if (!serviceName) {
|
||||
continue;
|
||||
}
|
||||
console.log(`[database-backup] 冷备份后重启依赖服务: ${serviceName}`);
|
||||
runCommand('systemctl', ['restart', serviceName], {stdio: 'inherit'});
|
||||
}
|
||||
}
|
||||
|
||||
function createArchive({dataDir, workDir, fileName}) {
|
||||
if (!existsSync(dataDir)) {
|
||||
throw new Error(`数据库数据目录不存在: ${dataDir}`);
|
||||
@@ -524,13 +510,6 @@ async function main() {
|
||||
} finally {
|
||||
startServiceIfNeeded(args.stopService || firstNonEmpty(env.GENARRATIVE_DATABASE_BACKUP_STOP_SERVICE), serviceStopped);
|
||||
}
|
||||
restartServicesAfterBackup([
|
||||
...String(env.GENARRATIVE_DATABASE_BACKUP_RESTART_SERVICE_AFTER ?? '')
|
||||
.split(',')
|
||||
.map((value) => value.trim())
|
||||
.filter(Boolean),
|
||||
...args.restartServicesAfter,
|
||||
]);
|
||||
|
||||
const manifestPath = `${archivePath}.manifest.json`;
|
||||
writeManifest({
|
||||
|
||||
@@ -332,34 +332,13 @@ mkdir -p "${RELEASE_DIR}"
|
||||
cp "${SOURCE_DIR}/api-server" "${RELEASE_DIR}/api-server"
|
||||
chmod +x "${RELEASE_DIR}/api-server"
|
||||
|
||||
BACKUP_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/database-backup-to-oss.mjs"
|
||||
WORKSPACE_BACKUP_SCRIPT_SOURCE="$(cd "${SCRIPT_DIR}/../.." && pwd)/scripts/database-backup-to-oss.mjs"
|
||||
HEALTH_PATROL_SCRIPT_SOURCE="${SOURCE_DIR}/scripts/ops/production-health-patrol.mjs"
|
||||
WORKSPACE_HEALTH_PATROL_SCRIPT_SOURCE="$(cd "${SCRIPT_DIR}/../.." && pwd)/scripts/ops/production-health-patrol.mjs"
|
||||
mkdir -p "${RELEASE_DIR}/scripts" "${RELEASE_DIR}/scripts/ops"
|
||||
if [[ ! -f "${BACKUP_SCRIPT_SOURCE}" ]]; then
|
||||
if [[ -f "${WORKSPACE_BACKUP_SCRIPT_SOURCE}" ]]; then
|
||||
echo "[production-api-deploy] 发布产物缺少 scripts/database-backup-to-oss.mjs，回退使用部署工作区脚本；请重新触发包含该脚本的 API 构建。" >&2
|
||||
BACKUP_SCRIPT_SOURCE="${WORKSPACE_BACKUP_SCRIPT_SOURCE}"
|
||||
else
|
||||
echo "[production-api-deploy] 缺少数据库备份脚本: ${SOURCE_DIR}/scripts/database-backup-to-oss.mjs" >&2
|
||||
exit 1
|
||||
fi
|
||||
fi
|
||||
cp "${BACKUP_SCRIPT_SOURCE}" "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
|
||||
chmod 0644 "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
|
||||
if [[ ! -f "${HEALTH_PATROL_SCRIPT_SOURCE}" ]]; then
|
||||
if [[ -f "${WORKSPACE_HEALTH_PATROL_SCRIPT_SOURCE}" ]]; then
|
||||
echo "[production-api-deploy] 发布产物缺少 scripts/ops/production-health-patrol.mjs，回退使用部署工作区脚本；请重新触发包含该脚本的 API 构建。" >&2
|
||||
HEALTH_PATROL_SCRIPT_SOURCE="${WORKSPACE_HEALTH_PATROL_SCRIPT_SOURCE}"
|
||||
else
|
||||
echo "[production-api-deploy] 未找到生产健康巡检脚本，跳过复制；genarrative-health-patrol.service 会因脚本缺失而跳过执行。" >&2
|
||||
HEALTH_PATROL_SCRIPT_SOURCE=""
|
||||
fi
|
||||
fi
|
||||
if [[ -n "${HEALTH_PATROL_SCRIPT_SOURCE}" ]]; then
|
||||
cp "${HEALTH_PATROL_SCRIPT_SOURCE}" "${RELEASE_DIR}/scripts/ops/production-health-patrol.mjs"
|
||||
chmod 0644 "${RELEASE_DIR}/scripts/ops/production-health-patrol.mjs"
|
||||
SCRIPT_SOURCE_DIR="$(cd "${SCRIPT_DIR}/../.." && pwd)/scripts"
|
||||
mkdir -p "${RELEASE_DIR}/scripts"
|
||||
if [[ -f "${SCRIPT_SOURCE_DIR}/database-backup-to-oss.mjs" ]]; then
|
||||
cp "${SCRIPT_SOURCE_DIR}/database-backup-to-oss.mjs" "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
|
||||
chmod 0644 "${RELEASE_DIR}/scripts/database-backup-to-oss.mjs"
|
||||
else
|
||||
echo "[production-api-deploy] 未找到数据库备份脚本，release 目录不会包含 scripts/database-backup-to-oss.mjs" >&2
|
||||
fi
|
||||
|
||||
if [[ -f "${SOURCE_DIR}/release-manifest.json" ]]; then
|
||||
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user