# 决策记录

> 用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。

## 记录格式

```md
## YYYY-MM-DD 决策标题

- 背景：为什么需要这个决策
- 决策：最终决定是什么
- 影响范围：涉及哪些模块/文档/流程
- 验证方式：如何确认决策仍有效
- 关联文档：相关 PRD、技术文档、提交或 Issue
```

---

## 2026-06-19 外部 OpenAPI 与 API Key 管理走 server-rs 正式链路

- 背景：外部调用方需要稳定调用图片画布项目创建、画布布局保存和编辑器美术生图能力，同时需要可撤销的开发者凭据，不能依赖前端临时状态或人工分发密钥。
- 决策：外部 API 固定放在 `/api/external/v1` 命名空间，v1 暴露项目创建 / 读取、默认画布保存、编辑器美术生图和 `/api/external/v1/openapi.json`。API Key 管理走登录态 `/api/profile/api-keys`，外部调用使用 `Authorization: Bearer tnr_sk_xxx`；后端只保存 `key_hash` 和 `key_prefix`，明文只在创建响应返回一次。外部 API 鉴权、项目 / 画布 / 素材写回全部经 `api-server -> spacetime-client -> spacetime-module`，生成图片成功后同时写入账号级 `editor_asset`，带 `projectId` 时写入 `editor_project_resource`。
- 影响范围：`server-rs/crates/api-server/src/external_*`、`server-rs/crates/api-server/src/modules/external_api.rs`、`server-rs/crates/spacetime-module/src/external_api_key_storage.rs`、`server-rs/crates/spacetime-client/src/external_api_key.rs`、`docs/openapi/genarrative-external-v1.openapi.json` 和后端数据契约文档。
- 验证方式：`cargo test -p api-server external_api --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server external_editor_api --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、`npm run check:encoding`、`git diff --check`。
- 关联文档：`docs/【后端架构】外部OpenAPI与APIKey接入方案-2026-06-19.md`。

## 2026-06-19 图片画布素材生成元数据上移到资源和素材

- 背景：角色、图标、UI 设计图、视频和音频等生成结果会在图片信息页展示用户可见输入快照；此前这些 `assetKind/generationInputs` 主要保存在画布 layer JSON 中，素材进入账号级素材库后跨项目复用和刷新恢复都依赖画布布局，不符合素材库作为账号级事实源的边界。
- 决策：普通图层的新保存不再把 `assetKind/generationInputs` 写入 `editor_canvas.layers_json`。`editor_project_resource` 保存项目画布资源快照的 `asset_kind/generation_inputs_json`，`editor_asset` 保存账号级素材的同名元数据；图片 / 图标 / UI 提取等生成 BFF 在请求携带 `projectId` / `assetFolderId` 时由后端创建新 resource / asset 并把快照回传前端，前端只用回包更新画布图层和素材栏，不再把同一生成结果二次调用保存接口。前端加载时优先从 resource / asset 恢复素材类别和生成输入快照，旧 layout 中的同名字段只作为历史兼容兜底。生成器对象本身仍作为 `itemType="generation-dialog"` 保存在画布布局中。
- 影响范围：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`server-rs/crates/spacetime-client/src/mapper/editor_project.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`src/services/image-editor/editorProjectClient.ts`、图片画布 hydrate / serialize / project persistence / asset library 代码和后端数据契约文档。
- 验证方式：运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`，并按需补充 `cargo check -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`。
- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-06-19 图片画布生成按钮价格统一绑定模型定价配置

- 背景：图片画布的生成图片、生成视频、生成规范、生成角色、生成素材、生成 UI、宣发素材、快速编辑、重绘和音频生成入口都在按钮内显示泥点；如果按钮文案、前端提交和后端校验各自写固定数值，后续调整模型价格会出现展示价、提交价和扣费价不一致。
- 决策：所有画板生成按钮价格必须从 `src/components/image-editor/ImageCanvasGenerationModel.ts` 的模型定价配置函数计算；需要提交 `priceMudPoints` 的视频、角色动画、图标素材、音效和背景音乐也使用同一函数。后端用 `server-rs/crates/api-server/src/editor_generation_config.rs` 的同名语义配置重新计算并校验 / 扣费。当前正式模型均已覆盖定价；画板 UI 统一显示 `nanobanana2`，它代表上游真实模型 `gemini-3.1-flash-image-preview`，历史输入或旧布局中的 `nano-banana` 必须归一到该真实模型 ID 后再提交和计费。
- 影响范围：图片画布生成类面板、生成提交模型、编辑器图片 / 视频 / 音频 BFF、`editor_generation_config` 和 Lovart 生成类面板文档。
- 验证方式：运行 `npm run test -- src/components/image-editor/ImageCanvasGenerationModel.test.ts src/components/image-editor/ImageCanvasQuickEditPanelView.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx`，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。

## 2026-06-18 图片画布 UI 设计图提取素材保留图集

- 背景：UI 设计图需要从成图中继续抽取可复用独立素材；原图标素材生成只把拆分后的图标放入画布，spritesheet 原图没有保留，后续追溯和二次切图不方便。
- 决策：`assetKind="ui-design"` 图层浮动工具栏新增 `提取素材`，固定调用 `/api/editor/ui-designs/assets/extractions`，后端固定 `gpt-image-2` 和提示词 `提取画面中的所有独立并整理成spritesheet`，返回结构复用图标 spritesheet 响应。图标生成与 UI 提取都必须把 spritesheet 图集作为 `assetKind="icon-spritesheet"` 图层放到画布，再放拆分后的 `assetKind="icon"` 素材。
- 影响范围：图片画布浮动工具栏、编辑器图片生成 BFF、`platform-image` 图集连通域拆分、画布图层类型和编辑器文档。
- 验证方式：运行图片画布工具栏 / 图集落层 / 生成提交相关前端测试，`cargo test -p platform-image generated_asset_sheets --manifest-path server-rs/Cargo.toml`，以及 `cargo test -p api-server editor_ui_design_asset_extraction_prompt_is_fixed --manifest-path server-rs/Cargo.toml`。
- 关联文档：`docs/【编辑器】画板UI设计图生成入口设计-2026-06-17.md`、`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`。

## 2026-06-18 `/creation` 独立为陶泥儿创作工具主页

- 背景：图片画布项目已经成为独立项目资产，旧“创作”站内 Tab 和一级“草稿”入口不能清晰表达桌面端创作工具主页与项目管理入口。
- 决策：桌面端新增独立 `/creation` 创作工具主页；顶级“创作”入口跳转 `/creation`，原“草稿”入口替换为“项目”并跳转 `/project`。移动端隐藏“创作”和“项目”入口，但不拦截直接 URL。页面文案统一使用“陶泥儿”，外部品牌只作为设计参考，不进入用户可见 UI、测试名、产品文案或验收口径。`陶泥儿精选` 是用户素材瀑布流，不展示玩法入口列表；创作入口事实源继续来自 `/api/creation-entry/config`，项目入口通过 `createEditorProject` 和 `/editor/canvas?projectid=xxx` 链路进入画布。
- 影响范围：平台入口导航、`SelectionStage` 路由、`/creation` 首页、`/project` 项目入口、`/editor/canvas` 项目打开链路、“我的”页快捷入口和创作入口相关测试。
- 验证方式：`/creation` 解析为创作主页，`/creation/<play>` 仍进入对应玩法工作台；桌面导航显示“创作 / 项目”且不显示“草稿”；移动端底部不显示“创作 / 项目”；页面不出现外站品牌或 `Discord` 字样；新建项目进入 `/editor/canvas?projectid=xxx`。
- 关联文档：`docs/【玩法创作】创作主页与项目入口改版计划-2026-06-18.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-06-18 图片画布 Seedance 2.0 参考媒体提交边界

- 背景：`/editor/canvas` 生成视频需要严格对齐火山 Seedance 2.0 多模态参考输入；参考视频若继续走 Base64 / `data:video` 会超过请求体并被上游拒绝，参考音频单独输入和非 Seedance 模型携带参考字段也会违反文档契约。
- 决策：仅 `seedance2.0-fast` / `seedance2.0` 可提交参考图片、参考视频、参考音频；图片 0~9、视频 0~3、音频 0~3，音频必须搭配图片或视频。参考视频只能提交公网 URL、`asset://` 或画板资源 `objectKey`，禁止 `data:video/*`；视频 / 音频上传先走 OSS 直传和 asset_object confirm，前端保存 signed URL 预览但提交优先 `objectKey`，后端统一重新签名给 Ark。Ark body 按 `image_url` / `video_url` / `audio_url` + `reference_*` role 构造，并显式发送 `generate_audio:false`。
- 影响范围：图片画布生成视频面板、参考媒体上传工作流、`editorReferenceUploadClient`、`ImageCanvasGenerationSubmissionModel`、`shared-contracts`、`api-server` 编辑器视频 BFF、Lovart 生成类面板文档。
- 验证方式：运行 `npx vitest run src/components/image-editor/useImageCanvasUploadWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/services/image-editor/editorReferenceUploadClient.test.ts --reporter verbose`、`cargo test -p api-server editor_video --manifest-path server-rs/Cargo.toml`、`cargo test -p shared-contracts editor_video_request_supports_seedance_multimodal_references --manifest-path server-rs/Cargo.toml`，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、火山 Seedance 2.0 任务创建文档。

## 2026-06-18 图片画布生成音乐入口作为音频图层接入

- 背景：图片画布底部生成工具需要补齐游戏音效和游戏背景音乐生成，既要复用现有 Lovart 式画布生成器快照、占位避让和持久化，又不能把音频能力并入图片素材库或视觉小说专用音频开关。
- 决策：`/editor/canvas` 新增底部 `生成音乐` 入口，点击后先弹出“生成游戏音效 / 生成游戏背景音乐”选项框，再分别创建 `audio-sound-effect` 或 `audio-background-music` 生成器；生成结果作为 `mediaType="audio"` 的画布音频卡保存，`assetKind` 分别为 `sound-effect` / `background-music`。音效请求字段固定映射 Vidu `prompt/model/duration`，模型固定 `audio1.0`、时长严格 `2-10` 秒；背景音乐请求字段固定映射 `gpt_description_prompt` 且 `make_instrumental=true`。
- 影响范围：图片画布生成工作流、前端 editorProjectClient、`shared-contracts`、`platform-audio`、`api-server` 编辑器音频 BFF、图片画布技术方案和音乐生成入口设计文档。
- 验证方式：运行编辑器生成入口 / 提交 / 音频图层相关前端测试，`platform-audio` 请求体测试，`shared-contracts` editor audio 序列化测试，`api-server` editor audio 归一化测试，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 关联文档：`docs/【编辑器】画板音乐生成入口设计-2026-06-18.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。

## 2026-06-17 图片画布生成占位统一避让落点

- 背景：图片画布的普通图片、规范、角色、图标、视频和 UI 设计图生成入口都会先在画布中新建“即将生成”的占位图；若各入口直接使用当前视口中心，容易压住已有图片或已有生成占位，Lovart 式连续创作体验不稳定。
- 决策：所有会新建画布生成占位的入口统一经过 `ImageCanvasGenerationPlacementModel` 计算落点。模型以当前视口世界中心为目标，避让所有未隐藏画布图层和 active / inactive generation dialog placeholder，按 32px 画布世界坐标间距外扩阻挡矩形，选择距离当前屏幕中心对应画板位置最近且不重叠的位置。选定后立即调用 `centerViewportOnPlacement(...)`，保持当前缩放比例不变，只平移画布 viewport，让屏幕中心移动到新占位中心。
- 影响范围：`/editor/canvas` 图片画布生成入口、`useImageCanvasGenerationWorkflow`、`ImageCanvasGenerationPlacementModel`、图片画布技术方案和 Lovart 生成类面板文档。
- 验证方式：运行 `npm run test -- src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`，并执行 `npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`。

## 2026-06-13 Pingora 低端口直连只通过显式 systemd drop-in 启用

- 背景：`genarrative-pingora-gateway.service` 默认以 `genarrative` 非 root 用户运行，shadow 阶段只监听本机高端口；如果正式评估让 Pingora 直接绑定公网 `80/443`，需要低端口绑定能力，但不能让 Server-Provision 或默认 service 自动改变接流边界。
- 决策：主 systemd service 保持 shadow 口径，不携带 `CAP_NET_BIND_SERVICE`。仓库提供 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf` 作为人工启用 drop-in 模板，Server-Provision 只安装到 `/etc/genarrative/pingora/genarrative-pingora-gateway-direct-entry.conf` 备查和手动覆盖；正式切换窗口从 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 执行时默认读取 current release 随包的 `/opt/genarrative/current/deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`，不依赖 `/etc` 参考模板、Jenkins 工作区或源码 checkout。直连切换前先用 `npm run plan:pingora-direct-cutover -- --require-direct ...` 生成 JSON runbook，逐条审阅 Host 与回退巡检入口确认、current release preflight、启用前基础门禁、direct enable dry-run、direct enable apply（通过命令证据脚本归档 stdout / stderr / 退出码）、切换后 health patrol 切到 `pingora-direct`、启用后 health patrol env 直连复核、启用后 `--require-direct` 复核、rollback dry-run、rollback apply（通过命令证据脚本归档 stdout / stderr / 退出码）、回退后 health patrol 切回 `nginx` 并恢复切换前 public base URL / Host、回退后 health patrol env Nginx 模式复核；启用前基础门禁不带 `--require-direct`，因为 systemd drop-in 尚未生效，启用后复核必须带 `--require-direct`。正式切换 runbook 中 `--direct-redirect-host`、`--rollback-nginx-smoke-host` 和 `--direct-host` 必须使用同一 hostname，只允许端口不同，避免 redirect 和回退 smoke 分别验证到不同入口；还必须显式传 `--rollback-health-patrol-public-base-url <切换前Nginx巡检入口>`，切换前 Nginx 巡检需要 Host 覆盖时再传 `--rollback-health-patrol-public-host <切换前Host>`，确认步骤会展示回退后要恢复的 public base URL / Host，避免回退 runbook 覆盖现场原有巡检入口。若需把回退后 Pingora shadow 探针复核纳入 runbook，追加 `--rollback-pingora-shadow-probe-url` / `--rollback-pingora-shadow-probe-token`，JSON 输出会隐藏 token 原文并把参数传给 rollback dry-run / apply。只有切换窗口通过 `pingora-direct-enable.sh --apply --preflight-env-file /etc/genarrative/pingora-gateway.env --preflight-check-cert-readable --preflight-check-service-env-file --preflight-check-service-user-cert-readable --preflight-check-service-binary-executable --preflight-check-ports-free --direct-https-base-url https://127.0.0.1 --direct-http-base-url http://127.0.0.1 --direct-host <域名> --direct-redirect-host <域名或host:port> --direct-spacetime-database <库名>` 先跑 current release 自审，确认发布包自包含、`pingora-gateway` 可执行且 systemd `ExecStart` 指向随包网关，失败时不安装 drop-in；随后跑 direct preflight，确认当前执行用户和 `genarrative-pingora-gateway.service` 的 `User=` 服务用户都可读取证书链 / 私钥，确认 service 模板与 `systemctl cat` 最终配置读取的 `EnvironmentFile=` 都包含本次 `/etc/genarrative/pingora-gateway.env`，并确认 service `ExecStart=` 指向的 current release `pingora-gateway` 存在且可执行，再安装到 `/etc/systemd/system/genarrative-pingora-gateway.service.d/direct-entry.conf`、执行 `systemctl daemon-reload`、重启 Pingora，并用 `systemctl cat` 核验 `AmbientCapabilities=CAP_NET_BIND_SERVICE`、`CapabilityBoundingSet=CAP_NET_BIND_SERVICE` 和 `EnvironmentFile=/etc/genarrative/pingora-gateway.env` 已生效、用 `systemctl is-active` 确认服务 active、用 direct live smoke 验证 HTTPS / HTTP redirect / ACME / WSS 101 后，才视为授予低端口能力成功。启用前还必须显式配置 TLS / redirect env 和真实证书，并确认 current release 已落盘可执行 `pingora-gateway`、Nginx 或其它进程已释放 `80/443`；启用后仍必须跑 release readiness 门禁；验证失败时统一执行 `pingora-direct-rollback.sh --apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'` 回到 shadow / Nginx 入口，回退脚本会先运行 `nginx -t`，通过后移除 direct-entry drop-in、重启 Pingora，再用 `systemctl cat` 确认两条低端口 capability 均已从最终 unit 配置中移除，用 `systemctl show ... ExecStart` 确认最终 service 仍指向随包主 service 模板中的 current release `pingora-gateway`，并 reload Nginx、确认 Nginx service 仍为 `active`，最后用 curl smoke URL 证明 Nginx 入口真实可访问；回退 smoke URL/body 必须来自切换前真实 Nginx 入口，不要继续用固定 `http://127.0.0.1/healthz` 与 `"ok":true`。回退脚本 `--apply` 必须同时带 `--reload-nginx` 和 `--nginx-smoke-url`，避免只撤掉 Pingora 低端口能力却没有证明 Nginx 已重新接流；本机打 `127.0.0.1`、`localhost` 或 `::1` 时，`--apply` 必须带 `--nginx-smoke-host <域名>`，且该值只能是 host 或 `host:port`，避免命中默认 vhost。回退后必须复核 health patrol env 已切回 `nginx` 且 public base URL / Host 恢复为切换前记录值；如果 env 已预先修正，rollback 脚本可追加 `--health-patrol-env-file /etc/genarrative/health-patrol.env --health-patrol-expected-public-base-url <切换前Nginx巡检入口> --health-patrol-require-empty-public-host` 自动执行这项复核，切换前 Nginx 巡检需要 Host 覆盖时把最后一项换成 `--health-patrol-expected-public-host <切换前Host>`。若需证明 Pingora 仍以 shadow 高端口存活，可追加 `--pingora-shadow-probe-url http://127.0.0.1:18081/__genarrative_pingora/healthz --pingora-shadow-probe-token <token>`，脚本会隐藏 token 并要求响应包含 `gateway=pingora-shadow`。
- 决策补充：health patrol env 的直连/回退切换不再靠人工编辑三行变量；正式 runbook 使用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --apply`，只更新 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE`、`GENARRATIVE_HEALTH_PATROL_PUBLIC_BASE_URL`、`GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST` 并立即调用随包 `check-production-health-patrol-env.mjs` 复核。Pingora direct 使用本机 public base URL 时脚本必须带 `--public-host <域名>`；回退到 Nginx 时根据切换前记录传 `--clear-public-host` 或 `--public-host <切换前Host>`。生产巡检、health patrol env 复核和 env 切换脚本读取的布尔 env 必须严格解析，非法值直接失败，不得静默按 false 继续；env 复核脚本的 `--env-file` 与 env 切换脚本的 `--env-file` / `--check-script` 必须是绝对路径且不能是文件系统根目录，也不能包含换行或 NUL；env 切换脚本写入的 public base URL / Host 同样不能包含换行或 NUL。Node 22 已内置 `--env-file` 启动参数，凡是用 Node 启动项目脚本且要把业务 `--env-file` 传给脚本时，必须写成 `node -- <script> --env-file ...`；systemd / shell / release readiness runbook 中的这类 Node 调用都必须保留 `--` 分隔符。
- 写入语义补充：`pingora-health-patrol-env-switch.mjs --apply` 必须先对权限固定为 `0600` 的临时目标 env 运行随包 env 复核脚本，复核通过后才按真实 `/etc/genarrative/health-patrol.env` 原权限和 owner/group 原子替换；复核失败时不得写入真实 env，避免切换窗口留下半坏巡检配置。`--apply` 时 `--env-file` 必须直接指向真实普通文件，不能是符号链接；若现场 env 是链接，先确认真实目标路径后再传给脚本，避免替换链接本身或写入非预期目标。
- 顺序补充：正式 runbook 中 health patrol 的 Nginx 回退 env 必须在 `rollback apply` 前预置，随后 `pingora-direct-rollback.sh --apply` 会用 `--health-patrol-expected-public-base-url` 和 `--health-patrol-expected-public-host` / `--health-patrol-require-empty-public-host` 在 Nginx smoke 后复核该 env；最后仍保留独立的回退后 health patrol env 复核步骤。
- 顺序补充：正式 runbook 中 Pingora 自身 env 的 shadow 回退也必须在 `rollback apply` 前预置。真实直连会把 `/etc/genarrative/pingora-gateway.env` 提升为 `0.0.0.0:80/443` direct 配置；回退脚本移除 `CAP_NET_BIND_SERVICE` 后会重启 Pingora，如果 env 仍保留低端口监听，服务可能按预期失败而不是回到 shadow。因此 rollback apply 前必须用 current release 随包 `node -- /opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --apply --env-file /etc/genarrative/pingora-gateway.env` 先确认 `GENARRATIVE_PINGORA_GATEWAY_LISTEN=127.0.0.1:18081`，并清空 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`、`GENARRATIVE_PINGORA_GATEWAY_TLS_CERT_FILE` 和 `GENARRATIVE_PINGORA_GATEWAY_TLS_KEY_FILE`，避免保留证书路径但无 TLS listener 的半直连 env。
- 安全补充：直连公网地址时 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR` 必须保持 `false`；只有 Pingora 前方仍有会清洗 `X-Forwarded-For` 的受控代理且监听为 loopback / 受控入口时，才允许配合 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true` 使用转发 IP 作为接流保护 client key。目标机 direct preflight 必须在公网监听加 `TRUST_X_FORWARDED_FOR=true` 时失败，且这两个 gateway env 布尔值也必须严格解析，非法值直接失败，避免公网用户伪造限流 key 或拼写错误被当成 false。
- 发布补充：`npm run check:production-api-release` 继续验证 API release 自包含和显式 include 的假二进制布局；`npm run check:pingora-production-release-build` 必须额外走真实 `cargo build -p pingora-gateway --release --target x86_64-unknown-linux-gnu`，并用假 `api-server` 验证 `--include-pingora-gateway` 发布包包含可执行 `pingora-gateway`、`pingora-gateway.sha256` 和 manifest 登记。`check:pingora-release-readiness` 默认纳入该真实构建 smoke，避免正式切换前只验证发布包布局而没有验证 Pingora release 二进制可构建。
- 发布安全补充：API release 和 deploy 动态烟测必须复核 `deploy/pingora/pingora-gateway.env.example` 随包后的生产安全默认值，至少包括 `COMPRESSION_ALGORITHMS=gzip`、`TRUST_X_FORWARDED_FOR=false`、`TRUSTED_FRONT_PROXY_CONFIRMED=false`、`PROTECTION_ENABLED=true` 和空 `PROBE_TOKEN`；这些值漂移时应在构建 / 部署门禁中失败，而不是等切换窗口人工审查。
- 自审补充：正式直连 runbook 的 current release 自审不只看文件存在和可执行；还必须复核 `api-server.sha256` / `pingora-gateway.sha256` 与当前文件匹配，并读取 `release-manifest.api-server.json` 或 `release-manifest.json` 确认 `component_type=api-server` 且 manifest 已登记 `pingora-gateway` 与 `pingora-gateway.sha256`。checksum 或 manifest 漂移属于 `CRITICAL`，应先修发布包或 deploy 复制链路，再继续切换。
- 证据补充：current release 自审、状态快照和证据包脚本的显式 `--timeout-ms`，以及 `GENARRATIVE_PINGORA_CURRENT_RELEASE_TIMEOUT_MS` / `GENARRATIVE_PINGORA_CUTOVER_SNAPSHOT_TIMEOUT_MS` 必须是正整数；这些脚本读取的布尔 env 只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值。非法值直接失败，不得静默回退默认超时或 false。自审、状态快照和证据包的 `--release-root` 都不能是文件系统根目录，状态快照的 `--health-patrol-env-file` / `--pingora-env-file` 以及证据包所有显式路径参数也不能是文件系统根目录；状态快照自身还必须拒绝带换行或 NUL 的 release/env 路径，并在执行 systemctl、current release 自审、health patrol env 复核或生产巡检子命令前复核子命令参数；证据包在执行状态快照或 direct live 子命令前还必须拒绝任何带换行或 NUL 字符的子命令参数，避免污染后的结构化 `args[]` 先进入 manifest / command 证据再等最终总审计兜底；`--output-root` 及其已存在上级路径不能是符号链接，已存在的 `--output-root` 必须是真实目录；路径异常时必须在执行状态快照前失败，避免把切换证据写入非预期软链目标。
- current release 自审安全补充：`pingora-current-release-audit.mjs` 的 `--release-root` 和 `--systemd-service` 不能包含换行或 NUL 字符；启用 `--systemd-show` 时，脚本必须在执行 `systemctl show` 前复核子命令可执行文件和所有参数不含换行或 NUL，避免污染参数进入只读自审命令。
- direct preflight 安全补充：`check-pingora-direct-preflight.mjs` 的 `--env-file`、`--systemd-service`、服务用户和 env 中的 listen / cert / key 值不能包含换行或 NUL 字符；执行 `systemctl cat` 或 `sudo -u <serviceUser> test -r <file>` 前必须复核子命令可执行文件和所有参数不含换行或 NUL，避免污染参数进入目标机直连预检命令。
- API 代理头补充：Pingora 直连接管前必须证明上游 `api-server` 收到的代理头仍对齐 Nginx。网关透传 `Host`，写入 `X-Forwarded-Host`、配置化的 `X-Forwarded-Proto`、TCP 对端 IP 作为 `X-Real-IP`，并把 TCP 对端 IP 追加到 `X-Forwarded-For`；`GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR` 只影响接流保护 client key，不改变上游归因头。`npm run check:pingora-gateway-smoke` 必须用 mock 上游回显并断言这些头，避免直连后回调 URL、鉴权来源或日志归因漂移。
- 静态缓存补充：Pingora 直连静态响应必须同时保留 `Cache-Control` 分档和浏览器协商缓存能力。HTML / SPA fallback 默认 `no-cache`，Vite 指纹资源默认 `public, max-age=31536000, immutable`，其它静态资源和 ACME 默认 `no-cache`；所有静态文件响应写入弱 `ETag` 与 `Last-Modified`，并对 `GET` / `HEAD` 的 `If-None-Match`、`If-Modified-Since` 返回 `304`。`npm run check:pingora-gateway-smoke` 必须覆盖静态 `HEAD`、ETag 304 和 Last-Modified 304，避免直连后旧浏览器缓存体验或 HTML 入口刷新语义漂移。
- 静态 Range 补充：Pingora 直连静态响应必须声明 `Accept-Ranges: bytes`，支持单段 `Range: bytes=` 返回 `206 + Content-Range`，越界范围返回 `416 + Content-Range: bytes */<len>`，`HEAD + Range` 只返回头且保留正确 `Content-Length`。多段 range 暂按完整文件返回，不引入 multipart 响应；条件请求优先于 Range，命中时仍返回 `304`；`If-Range` 日期匹配时继续返回 `206`，日期旧于文件或弱 ETag 校验器时回完整 `200`；`206` / `304` / `416` 不做 gzip 压缩，避免局部内容语义漂移。`npm run check:pingora-gateway-smoke` 必须覆盖 206、suffix range、416、HEAD range、If-Range 匹配和 If-Range 回完整文件。
- 静态方法补充：Pingora 静态路由只允许 `GET` / `HEAD` 读取；非读取方法命中静态候选时返回 `405` 并写入 `Allow: GET, HEAD`，缺失文件仍返回 `404`。`npm run check:pingora-gateway-smoke` 必须覆盖该行为，避免直连后错误客户端把静态入口当作可写接口。
- direct live 静态资产补充：`check-pingora-direct-live.mjs` 在 HTTPS 根路径返回 `200` 且 HTML 中发现 `/assets/` 或 `/admin/assets/` 引用时，必须额外请求该静态资源，校验 `Cache-Control`、`ETag`、`Last-Modified`、`Accept-Ranges: bytes`，再用 `HEAD` 验证头响应，用 `If-None-Match` / `If-Modified-Since` 验证 `304` 协商缓存，用 `Range: bytes=0-0` 验证 `206 + Content-Range` 且不压缩，并把这些 request_id 都纳入 `direct-access-log` method/path/status 对账；如果首页引用 Vite 指纹资源，还必须额外验证 `Cache-Control: public, max-age=31536000, immutable`，并把指纹资源 GET / HEAD / 304 / Range request_id 纳入同一 access log method/path/status 对账。静态 GET / HEAD / 304 / Range 的 `direct-live.json` 结果必须写入白名单 `headers`，只保留 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding`，让证据包复盘时能直接确认缓存分档、校验器和 Range 语义；API / WSS 检查不落原始响应头。证据包 `manifest.summary.directLiveStaticHeaders` 必须把普通静态和 Vite 指纹静态的缓存头、校验头、Range `Content-Range` 与 304 状态提升出来；如果 direct live 已输出静态资产结果但摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 或 Last-Modified 304 证据，整包记为 `CRITICAL`。维护模式、非 HTML 或首页没有构建资产引用时该项允许标记为 skipped。这样直连切换证据不只覆盖 API / WSS / redirect，也覆盖当前发布包前端静态资源可读、协商缓存和旧 tab chunk 长缓存口径。
- 快照补充：状态快照必须把 `--pingora-env-file` 与 `systemctl cat genarrative-pingora-gateway.service` 的 `EnvironmentFile=` 精确匹配，支持 `EnvironmentFile=-/path` 和一行多个文件，但不能用路径前缀误判；未包含本次 pingora env 时 `systemd.pingoraUnit.environmentFileMatchesPingoraEnvFile=false` 并标记 `CRITICAL`，避免证据包读取一份 env 而真实 Pingora 服务读取另一份 env。
- 快照补充：状态快照支持 `--expected-pingora-env-mode shadow|direct`。正式 cutover runbook 的 `post-enable` 证据包必须传 `--expected-pingora-env-mode direct`，`post-rollback` 证据包必须传 `--expected-pingora-env-mode shadow`；若 active env 姿态与期望不一致，证据包应标记 `CRITICAL`，不能只依赖 health patrol gateway mode 或 systemd drop-in 判断切流状态。
- 证据验真补充：`scripts/ops/pingora-cutover-evidence-verify.mjs` 只接受 `schemaVersion=1` 的 manifest，并把 `manifest.files` 视为闭集，证据目录中除 `manifest.json` 和 manifest 已登记文件外，任何未登记普通文件、目录或符号链接都默认失败；`--allow-extra-files` 只用于人工排障显式放行，正式切换归档不使用。正式 runbook 的五个即时验真步骤都必须追加 `--require-summary-ok`，让 `pre-cutover`、`enable-apply`、`post-enable`、`rollback-apply`、`post-rollback` 证据在生成后立即要求 `manifest.summary.status=OK`；缺少 summary 或状态非 OK 时先修现场状态或重采证据，不等最终总审计才发现。
- 正式 runbook 安全补充：`--warn-only`、`--allow-extra-files` 和 `--allow-extra-root-entries` 只允许在 runbook 外作为人工排障命令使用；`plan:pingora-direct-cutover` 生成的正式切换计划不得携带这些放行参数。需要使用放行参数时，先修现场状态、证据目录或重新归档，不能把人工排障口径带入正式切换计划。
- 证据根目录补充：`scripts/ops/pingora-cutover-evidence-audit.mjs` 默认把证据根目录也视为闭集，只允许带 `manifest.json` 的证据目录；根目录普通文件、无 manifest 子目录和符号链接都会失败。`--allow-extra-root-entries` 只用于人工排障显式放行，正式切换归档不使用。
- 证据总审计补充：三阶段 `pre-cutover` / `post-enable` / `post-rollback` 证据包分别验真，且 `enable-apply` / `rollback-apply` 命令证据生成后，正式 runbook 还必须执行 current release 随包 `scripts/ops/pingora-cutover-evidence-audit.mjs --evidence-root <证据根目录> --require-phase pre-cutover --require-phase post-enable --require-phase post-rollback --require-phase-direct-live-access-log post-enable --require-phase-direct-live-static-headers post-enable --require-command enable-apply:pingora-direct-enable-apply --require-command post-enable:pingora-health-patrol-direct-env-switch --require-command rollback-prep:pingora-gateway-shadow-env-switch --require-command rollback-prep:pingora-health-patrol-nginx-env-switch --require-command rollback-apply:pingora-direct-rollback-apply --require-command-executable enable-apply:pingora-direct-enable-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh --require-command-executable post-enable:pingora-health-patrol-direct-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-prep:pingora-gateway-shadow-env-switch:/opt/genarrative/current/scripts/deploy/pingora-gateway-env-shadow-switch.mjs --require-command-executable rollback-prep:pingora-health-patrol-nginx-env-switch:/opt/genarrative/current/scripts/deploy/pingora-health-patrol-env-switch.mjs --require-command-executable rollback-apply:pingora-direct-rollback-apply:/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh --require-command-arg enable-apply:pingora-direct-enable-apply:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:--apply --require-command-arg post-enable:pingora-health-patrol-direct-env-switch:pingora-direct --require-command-arg rollback-prep:pingora-gateway-shadow-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:--apply --require-command-arg rollback-prep:pingora-health-patrol-nginx-env-switch:nginx --require-command-arg rollback-apply:pingora-direct-rollback-apply:--apply --require-cutover-run-id <本次cutoverRunId> --timeline-max-span-ms 86400000`。runbook 会自动生成或接受显式 `--cutover-run-id <id>`，并把同一 `manifest.cutoverRunId` 写入三阶段证据包、五条真实切换命令证据和最终总审计；该脚本只读扫描证据根目录，按 `manifest.phase` 选择每个阶段最新证据目录、按 `manifest.phase + manifest.commandName` 选择真实切换命令证据，并复用随包 verifier 验真；所有候选 manifest 必须是 `schemaVersion=1`，最新证据选择和时间线证明只接受合法且规范的 UTC 毫秒 `manifest.generatedAt`，命令记录 `startedAt` / `finishedAt` 也必须使用 `new Date().toISOString()` 形式；缺失、非法或省略毫秒 / 本地时区格式时直接失败，不能用目录 mtime 兜底；`post-enable` 阶段还必须带可判定的 `manifest.summary.directLiveAccessLog` 与 `manifest.summary.directLiveStaticHeaders`，否则总审计失败，避免旧启用后证据包缺少 request_id 对账、静态缓存、校验器、Range 或 304 复盘入口；缺阶段、缺命令证据、最新证据损坏、阶段 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.status` 非 `OK`、命令 `manifest.summary.exitCode` 非 `0`、命令证据缺少或漂移 `manifest.expectedExecutable` / `manifest.command.executable` / 独立 `command-record.json` executable、命令证据缺少必需 `--apply` 参数、`manifest.command` 与 `command-record.json` 关键字段不一致、命令 stdout / stderr 引用与 `manifest.files` 不一致、命令 args / command 漂移、命令记录时间线不合法、标准八段证据任一条目审计状态非 `OK`、标准八段证据 `manifest.generatedAt` 顺序不满足 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback`、标准八段证据跨度超过默认 24 小时、要求 `--require-cutover-run-id` 时任一阶段或命令缺少同一 `manifest.cutoverRunId`、证据根目录或 verifier 路径不安全、证据 verifier / 总审计入口路径或 manifest 登记文件名含换行 / NUL、证据根目录内出现坏 manifest / 符号链接时都应失败。确需更长维护窗口时，通过 release readiness runbook 参数 `--cutover-evidence-timeline-max-span-ms <ms>` 显式放宽，并让最终总审计 JSON 留下 `requiredCutoverRunId`、`requiredCommandExecutables`、`requiredCommandArgs`、`timeline.maxSpanMs` / `timeline.spanMs`。
- 证据总审计补充：最终审计 JSON 的 `summary` 是值班人员优先入口；`summary.status` 给出 `OK` / `CRITICAL`，`summary.failedItems[]` 聚合根目录、阶段、命令和时间线失败，`summary.directLiveEvidence[]` 聚合 `post-enable` 的 access log 与静态头要求、ok 状态、短 reason 和摘要。现场先看 summary 定位，再展开 `phases[]`、`commands[]`、`timeline` 深挖。
- 证据总审计补充：证据包会把状态快照里的 Pingora env 监听摘要提升到 `manifest.summary.pingoraEnvShadow`，包含 `listen`、`tlsListen`、`httpRedirectListen`、`tlsCertFile`、`tlsKeyFile`、`mode`、`shadowReady` 和 `ok`。正式 runbook 的最终总审计必须追加 `--require-phase-pingora-env-shadow post-rollback`，要求 `post-rollback` 证明 `listen=127.0.0.1:18081`、`mode=shadow`、`shadowReady=true`，且 TLS / HTTP redirect 低端口监听和证书路径均为空；最终审计 JSON 的 `summary.pingoraEnvShadowEvidence[]` 会聚合该要求、ok 状态、短 reason 和摘要，避免回退后 active env 仍残留 direct 低端口配置或 cert/key 半直连配置。
- 文档门禁补充：Pingora 技术文档里的最终证据根目录总审计命令示例也必须包含 enable apply、health patrol direct env switch、Pingora gateway shadow env switch、health patrol nginx env switch 和 rollback apply 五条 `--require-command-executable`，`npm run check:pingora-release-readiness-plan` 会读取文档并阻断示例落后于真实 runbook 的情况；`npm run check:production-api-release` 还必须动态生成 API release，检查发布包 README 和随包 `scripts/check-pingora-release-readiness.mjs --dry-run-cutover` 输出的最终总审计步骤也保留这五条 current release 脚本身份要求。
- 证据总审计补充：同一阶段或同一命令的最新 `manifest.generatedAt` 必须唯一。若多个候选共享最新时间戳，`pingora-cutover-evidence-audit.mjs` 必须输出 `AMBIGUOUS_LATEST` 并列出重复目录，不能按目录名排序打平；处理方式是重新归档该阶段 / 命令证据，或把旧证据移出正式证据根目录后再审计。
- 证据总审计补充：标准八段时间线只要任一阶段或命令证据声明了 `manifest.cutoverRunId`，八段就必须全部声明同一个值；顺序固定为 `pre-cutover -> enable-apply -> post-enable:pingora-health-patrol-direct-env-switch -> post-enable -> rollback-prep:pingora-gateway-shadow-env-switch -> rollback-prep:pingora-health-patrol-nginx-env-switch -> rollback-apply -> post-rollback`。缺字段或混入其它批次时，即使没有显式传 `--require-cutover-run-id`，总审计也必须失败，避免人工临时审计把不同切换批次拼成一条时间线。任何证据 manifest 只要显式写入 `cutoverRunId` 字段，就必须是安全非空 ID，不能用空字符串伪装成缺省字段。
- 证据总审计输出补充：标准八段时间线失败时，`timeline.failedCount` 按具体失败项累计，`timeline.failureBreakdown` 分别记录 `nonOkItems`、`missingGeneratedAt`、`cutoverRunIdMismatch`、`outOfOrder` 和 `spanExceeded`，用于把多个失败证据或多个时间线问题拆成可操作排障项。
- 命令证据身份补充：正式 runbook 的 `enable-apply` / `rollback-apply` 命令证据必须传 `--expected-executable <current release 随包脚本绝对路径>` 和 `--require-arg --apply`，分别绑定 `/opt/genarrative/current/scripts/deploy/pingora-direct-enable.sh` 和 `/opt/genarrative/current/scripts/deploy/pingora-direct-rollback.sh`，并在执行前要求真实命令参数包含 `--apply`。命令证据脚本会在创建正式命令证据前拒绝真实命令与预期脚本不一致、缺少必需 apply 参数，或任一真实命令参数包含换行 / NUL 字符，并把 `expectedExecutable` 写入 manifest / command-record；最终证据根目录总审计再用 `--require-command-executable` 复核 `manifest.expectedExecutable`、`manifest.command.executable` 与独立 `command-record.json` executable，并用 `--require-command-arg ...:--apply` 复核 `manifest.command.args` 与独立 `command-record.json.args` 都包含 `--apply`，同时拒绝 args 数组中任何带换行或 NUL 字符的结构化参数。总审计传入的 `--require-command-executable` executable 段也必须是安全绝对路径，不能是文件系统根目录，也不能包含换行或 NUL 字符，且会写入 `requiredCommandExecutables` 供复盘。总审计还会要求顶层 `manifest.commandName` 与内嵌 `manifest.command.name` 只要存在就各自是安全非空命令名，且两者同时存在时必须一致，并比较 `manifest.command` 与 `command-record.json` 的 schemaVersion / phase / name / cutoverRunId / exitCode / signal / startedAt / finishedAt / durationMs / stdoutPath / stderrPath / args / command / cwd / error 等关键字段；两份命令记录的 `schemaVersion` 都必须是 `1`，stdoutPath / stderrPath 还必须分别与 `manifest.files.stdout.path` / `manifest.files.stderr.path` 指向同一份归档文件，args 与 command 用于证明真实 apply 参数未被替换成 dry-run 或其它动作；命令记录时间必须满足 `finishedAt >= startedAt`、`durationMs == finishedAt - startedAt`，且 `manifest.generatedAt` 不能早于命令 `finishedAt`；这些参数会隐式要求对应命令证据存在；`commandName` 只用于审计分类，不能替代真实脚本身份和真实 apply 参数校验。
- 命令证据字段补充：`manifest.expectedExecutable` 和 `manifest.command.expectedExecutable` 只要出现，就必须是安全绝对路径；空字符串、相对路径、文件系统根目录或包含换行 / NUL 的值必须按坏 manifest 失败，不能用 `||` 等兜底逻辑把坏字段吞掉。命令证据生成端的 `--expected-executable` 同样必须在执行真实命令前拒绝相对路径、文件系统根目录和带换行 / NUL 的路径。
- 命令证据身份补充：只要命令证据声明了 `expectedExecutable`，`manifest.command.executable` 和独立 `command-record.json.executable` 就必须同时是同一个安全绝对路径；即使人工总审计漏传 `--require-command-executable`，真实 executable 与 expectedExecutable 漂移也必须失败。
- 命令证据字段补充：正式命令证据必须在 `manifest.command.executable` 和 `command-record.json.executable` 中同时记录真实可执行文件绝对路径；只保留可读 `command` 字符串、缺少结构化 executable 或 executable 不是绝对路径，都必须失败。
- 命令证据生成补充：`pingora-cutover-command-evidence.mjs` 的 `-- <command>` 必须直接传真实命令绝对路径，不能传 PATH 裸命令名；生成端会在执行前拒绝非绝对路径，避免写出最终总审计天然会拒绝的 command-record。
- 路径安全补充：切换窗口覆盖 `pingora-direct-enable.sh` 的 `--preflight-script`、`--direct-live-script`、`--current-release-audit-script`、`--template-path`、`--service-unit-path`、`--dropin-path` 或 env 文件路径时必须使用绝对路径，且不能指向文件系统根目录，避免 current release、Jenkins 工作区和现场 cwd 混用；`--apply` 必须在安装 direct-entry drop-in 前确认 current release 自审、direct preflight 和 direct live smoke 脚本都真实存在，任一脚本缺失时直接失败且不改 systemd。启用脚本还必须在 current release 自审、preflight、drop-in 写入和 systemctl 前拒绝 service、路径、URL、Host、probe token、access log、数据库名、tail 行数和 timeout 参数中的换行或 NUL 字符，并在安装前拒绝符号链接形式的 drop-in 目录或 drop-in 目标文件、拒绝已存在但不是普通文件的目标，避免把低端口 capability 写入非预期 systemd 位置。`pingora-direct-rollback.sh --apply` 也必须在 `nginx -t`、删除 drop-in、reload Nginx 或 health patrol / shadow probe 复核前拒绝 service、路径、Nginx smoke URL / Host / 响应片段、health patrol 复核参数、shadow probe URL / token 和二进制 override 中的换行或 NUL 字符，并拒绝 service unit、drop-in、health patrol env、复核脚本和路径形式二进制 override 指向文件系统根目录，再拒绝符号链接形式的 drop-in 目录或目标文件、拒绝已存在但不是普通文件的目标，避免回退窗口误删或误判非预期 systemd 位置。`pingora-direct-rollback.sh` 覆盖 `--nginx-binary` 或 `--curl-binary` 时允许裸命令名走 `PATH`，但只要值包含路径分隔符就必须是绝对路径，避免回退窗口从 cwd 运行相对二进制；`--nginx-smoke-url` 必须是 `http(s)` URL，非法值在移除 drop-in 前失败。
- 直连日志证据补充：Pingora 直连接管不能只看 HTTPS / HTTP redirect / ACME / WSS 响应成功；`pingora-direct-enable.sh --apply` 和 release readiness `--require-direct` 必须显式提供 `--direct-pingora-access-log /var/log/genarrative/pingora-gateway.access.log`。direct live smoke 会给每个请求生成 `X-Request-Id`，再反查 Pingora access log 尾部记录，缺少对应 `request_id`、方法、路径或状态漂移都应阻断启用后复核。启用脚本 apply 后必须以 `--json` 运行 direct live 并解析 stdout 中的 `direct-access-log` 结构化结果；缺少该结果、`matchedCount != checked`、`missingCount != 0` 或 `mismatchCount != 0` 都让启用失败，避免 direct live 子进程退出 0 但 access log 证据缺失时误判切换成功。正式 runbook 的启用后证据包必须额外传 `--run-direct-live`，把 `direct-live.json`、stdout / stderr、命令记录、direct-access-log 检查结果和静态响应头白名单证据写入同一证据目录，不能只依赖启用脚本或 release readiness 的终端输出；`direct-live.json` 中的 `direct-access-log` 必须保留 `scannedLineCount`、`matchedCount`、`missing[]`、`mismatches[]` 以及每个 `request_id` 的预期 / 实际 method、path 与 status，静态资源检查还必须保留 `cache-control`、`etag`、`last-modified`、`accept-ranges`、`content-range`、`content-length` 和 `content-encoding` 白名单头，避免复盘时只看到 count 或终端 stderr。证据包还必须把 `directLiveAccessLog` 和 `directLiveStaticHeaders` 摘要提升到 `manifest.summary`，让值班人员先从 manifest 快速看到普通静态 / 指纹静态的 `Cache-Control`、`ETag`、`Last-Modified`、`Content-Length`、Range `Content-Range` 与 304 状态证据；缺少 `direct-access-log` 结构化结果、缺少可判定的静态头摘要，或静态头摘要缺少缓存头、校验头、Range `206 + Content-Range`、ETag 304 / Last-Modified 304 证据时整包记为 `CRITICAL`。若 snapshot 或 direct live stdout 无法解析，证据包必须保留 `snapshot-parse-error.txt` 或 `direct-live-parse-error.txt`，并在 manifest / 最终 stdout 中索引错误文件。`deploy/env/pingora-direct-live.env.example` 必须保留 `GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG` 和 `GENARRATIVE_PINGORA_DIRECT_ACCESS_LOG_SINCE_LINES`，让目标机和 CI 使用同一口径。
- 影响范围：`deploy/systemd/genarrative-pingora-gateway.service`、`deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`、`deploy/env/`、`scripts/deploy/pingora-direct-enable.sh`、`scripts/deploy/pingora-direct-rollback.sh`、`scripts/deploy/pingora-health-patrol-env-switch.mjs`、`scripts/jenkins-server-provision.sh`、API release / Jenkins 归档链路、生产运维护栏、Pingora 试点文档、Nginx README 和生产护栏。
- 验证方式：`npm run check:production-ops` 确认主 service 仍是 shadow、drop-in 具备最小 capability、Provision 只安装人工启用模板且 release 携带启用 / 回退脚本，并确认 enable 脚本默认模板路径指向 `deploy/systemd/genarrative-pingora-gateway-direct-entry.conf`、`plan:pingora-direct-cutover` 入口存在；`npm run check:pingora-direct-enable` 和 `npm run check:pingora-direct-rollback` 确认脚本默认 dry-run 不修改 drop-in、会打印命令、release layout 默认读取随包 direct-entry 模板、拒绝相对路径、非法 Nginx smoke URL、路径形式的二进制 override、enable / rollback 控制字符参数、符号链接 drop-in 目录 / 目标以及非普通 drop-in 目标，enable current release 自审失败、direct preflight 脚本缺失或 direct live smoke 脚本缺失时不会安装 drop-in，direct live 退出 0 但缺少 `direct-access-log` JSON 证据时启用失败，rollback drop-in 路径异常或控制字符参数时不会继续执行 `nginx -t` 或删除真实目标，enable `--apply` 缺少 `--preflight-env-file`、`--preflight-check-cert-readable`、`--preflight-check-service-env-file`、`--preflight-check-service-user-cert-readable`、`--preflight-check-service-binary-executable`、`--preflight-check-ports-free`、`--direct-https-base-url`、`--direct-http-base-url`、`--direct-host`、`--direct-redirect-host`、`--direct-pingora-access-log` 或 `--direct-spacetime-database` 会失败，rollback `--apply` 缺少 `--reload-nginx` 或 `--nginx-smoke-url` 会失败，且启用 / 回退后都会核验 systemd 最终配置和 `ExecStart` 指向 current release；`npm run check:pingora-cutover-status-snapshot` 必须覆盖 `systemctl cat` 读取另一份 Pingora env 时快照标记 `CRITICAL`；`npm run check:pingora-release-readiness-plan` 必须覆盖 `--dry-run-cutover` runbook、Host 一致性确认、redirect Host / rollback smoke Host 漂移负例、缺少 `--require-direct` 的负例、缺少 `--rollback-health-patrol-public-base-url` 的负例、enable / rollback apply 步骤和回退后 health patrol env Nginx 模式复核；enable 必须确认 Pingora active 并执行 direct live smoke，direct live 失败或 access log 结构化证据缺失时整次启用失败；rollback 必须先跑 `nginx -t`，失败时不能先删除 drop-in，重启后必须确认 `ExecStart` 没有漂到旧 release，reload 后必须确认 Nginx active 并执行 smoke URL，curl 失败时整次回退失败；可选 health patrol env 复核必须拒绝 `pingora-direct` 残留或 public base URL / Host 漂移；可选 shadow probe 复核必须拒绝 URL / token 缺任一项、非法 URL 或非 `pingora-shadow` 响应；`npm run check:pingora-release-readiness` 默认会串起 direct-entry 静态预检、启用 / 回退 dry-run 与生产护栏；切换窗口先运行 `npm run check:pingora-direct-preflight -- --env-file /etc/genarrative/pingora-gateway.env --require-live-env --systemd-cat --check-cert-readable --check-service-env-file --check-service-user-cert-readable --check-service-binary-executable --check-ports-free`，再运行 release readiness `--require-direct`；验证失败时先 dry-run 回退脚本，再用 `--apply --reload-nginx --nginx-smoke-url https://<域名>/ --nginx-smoke-expect-body '<!doctype html>'` 执行，并确认回退脚本未报告 capability 残留、ExecStart 漂移、Nginx 非 active 或 smoke 失败，最后用 `node -- /opt/genarrative/current/scripts/check-production-health-patrol-env.mjs ...` 运行 health patrol env nginx 模式复核。
- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。

## 2026-06-13 Pingora direct live 必须覆盖 WSS subscribe

- 背景：Pingora 已具备显式 TLS / HTTP redirect 直连入口，但 SpacetimeDB 前端订阅依赖 `/v1/database/<db>/subscribe` 的 WebSocket 长连接；只检查 HTTPS 普通请求无法证明直连入口能替代 Nginx 的 WebSocket 透传。
- 决策：`check-pingora-direct-live.mjs` 默认先通过 TLS ALPN 确认 HTTPS 可协商 `h2`，再对 `wss://<direct>/v1/database/<database>/subscribe` 发起握手，并使用 SpacetimeDB SDK 2.4.1 默认子协议 `v2.bsatn.spacetimedb`；成功 101 时必须保留该子协议和 `X-Genarrative-Gateway: pingora-shadow`。release readiness `--require-direct` 会自动要求 WSS subscribe 返回 101，并强制要求 `--direct-http-base-url` / `GENARRATIVE_PINGORA_DIRECT_HTTP_BASE_URL`、`--direct-host` / `GENARRATIVE_PINGORA_DIRECT_HOST`、`--direct-redirect-host` / `GENARRATIVE_PINGORA_DIRECT_REDIRECT_HOST`、`--direct-pingora-access-log` / `GENARRATIVE_PINGORA_DIRECT_PINGORA_ACCESS_LOG`、`--direct-preflight-systemd` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_SYSTEMD_CAT=true`、`--direct-preflight-check-cert-readable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_CERT_READABLE=true`、`--direct-preflight-check-service-env-file` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_ENV_FILE=true`、`--direct-preflight-check-service-user-cert-readable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_USER_CERT_READABLE=true`、`--direct-preflight-check-service-binary-executable` / `GENARRATIVE_PINGORA_DIRECT_PREFLIGHT_CHECK_SERVICE_BINARY_EXECUTABLE=true` 和 `--direct-spacetime-database` / `GENARRATIVE_PINGORA_DIRECT_SPACETIME_DATABASE` 和 `--direct-health-patrol-env-file` / `GENARRATIVE_PINGORA_DIRECT_HEALTH_PATROL_ENV_FILE`，确保 HTTP/2 ALPN、HTTP 301、ACME challenge、正式域名 Host/SNI、redirect Location host、Pingora access log 的 request_id 落盘、systemd drop-in 生效、service EnvironmentFile 一致性、当前用户证书可读性、服务用户证书可读性、current release 二进制可执行性、health patrol direct 模式和目标库 WSS subscribe 都进入直连硬门禁；单独运行 direct live smoke 时可用 `--require-wss-upgrade` 强制同一口径。本机 `--host <域名>` 验证正式证书时，该 host 同时用于 HTTP Host 和 TLS SNI，`--redirect-host <域名或host:port>` 则用于校验 HTTP redirect `Location`。`--skip-wss` 只允许单独 direct live 临时排障；release readiness `--require-direct` 会直接拒绝。
- 影响范围：`scripts/check-pingora-direct-live.mjs`、`scripts/check-pingora-gateway-smoke.mjs`、`scripts/check-pingora-release-readiness.mjs`、`deploy/env/pingora-direct-live.env.example`、生产运维护栏、Pingora 试点文档和 Nginx README。
- 验证方式：`node --check scripts/check-pingora-direct-live.mjs scripts/check-pingora-release-readiness.mjs scripts/check-pingora-release-readiness-plan.mjs`、`npm run check:pingora-gateway-smoke`、`npm run check:pingora-release-readiness-plan`、`npm run check:production-ops`、`npm run check:pingora-release-readiness`。
- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。

## 2026-06-13 Pingora 直连入口先做显式配置能力

- 背景：Pingora shadow 已覆盖 Nginx handoff、gzip、timeout 和接流保护；继续接近正式版时需要验证是否具备不经 Nginx 的 HTTPS 入口能力，但不能让默认 shadow 部署误绑定公网 `80/443`。
- 决策：`pingora-gateway` 默认仍只监听 `GENARRATIVE_PINGORA_GATEWAY_LISTEN`；只有显式配置 `GENARRATIVE_PINGORA_GATEWAY_TLS_LISTEN`、`TLS_CERT_FILE`、`TLS_KEY_FILE` 时才额外挂载 Rustls HTTPS listener。只有在 TLS 入口已配置时才允许配置 `GENARRATIVE_PINGORA_GATEWAY_HTTP_REDIRECT_LISTEN`，该 HTTP listener 除 ACME challenge 外统一 301 到 HTTPS。证书申请和续期仍由 Certbot / 外部自动化承担，Pingora 只读取现有证书文件。目标机直连入口验收使用 `npm run check:pingora-direct-live` 或 release readiness 的 `--require-direct`，默认 shadow / Nginx canary 门禁不强制直连。
- 影响范围：`server-rs/crates/pingora-gateway`、`deploy/pingora/pingora-gateway.env.example`、`scripts/check-pingora-gateway-smoke.mjs`、`scripts/check-pingora-direct-live.mjs`、生产运维护栏、Pingora 试点文档和 Nginx README。
- 验证方式：`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`、`npm run check:pingora-gateway-smoke`、`npm run check:production-ops`、`npm run check:pingora-release-readiness`。
- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。

## 2026-06-13 Pingora shadow 网关显式承接上游 timeout

- 背景：Pingora shadow 已覆盖路由、接流保护、gzip 和 canary handoff，但上游连接 / 读 / 写 timeout 若继续依赖框架默认值，正式 canary 时可能和 Nginx 的 `proxy_read_timeout` / `proxy_send_timeout` 口径漂移。
- 决策：`pingora-gateway` 在 `HttpPeer` 上显式设置 timeout：连接默认 `3000ms`，没有 Nginx 显式长超时的代理路由读取默认 `60s`，通用 `/api`、公开列表 / 详情和 SpacetimeDB subscribe 读取默认 `3600s`，写上游默认 `3600s`。读 / 写 / 连接超时统一映射为 JSON `504 GATEWAY_UPSTREAM_TIMEOUT`。所有 `GENARRATIVE_PINGORA_GATEWAY_UPSTREAM_*TIMEOUT*` 配置必须大于 `0`。
- 影响范围：`server-rs/crates/pingora-gateway`、`deploy/pingora/pingora-gateway.env.example`、`scripts/check-pingora-gateway-smoke.mjs`、生产运维护栏、Pingora 试点文档和 Nginx README。
- 验证方式：`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`、`npm run check:pingora-gateway-smoke`、`npm run check:production-ops`、`npm run check:pingora-release-readiness`。
- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。

## 2026-06-13 Pingora shadow 网关先补齐 gzip parity

- 背景：Pingora 影子网关已经覆盖核心路由、接流保护和 Nginx handoff smoke，但旧口径仍把 gzip 和 Brotli 一起列为未承接能力，正式切换前需要先补齐 Nginx 当前已启用的 gzip 行为，同时避免未验收算法被 Pingora 默认行为隐式打开。
- 决策：`pingora-gateway` 默认启用 Pingora response compression，`GENARRATIVE_PINGORA_GATEWAY_COMPRESSION_ALGORITHMS=gzip`、`GENARRATIVE_PINGORA_GATEWAY_GZIP_ENABLED=true`、`GENARRATIVE_PINGORA_GATEWAY_GZIP_LEVEL=5`、`GENARRATIVE_PINGORA_GATEWAY_GZIP_MIN_LENGTH_BYTES=1024` 对齐 Nginx `gzip_comp_level 5` / `gzip_min_length 1024`；进入 compression 模块前把 `Accept-Encoding` 收敛成 gzip allowlist，避免未验收的 `br` / `zstd` 被隐式打开，并避免小响应被额外压缩。smoke 还必须覆盖图片资源不压缩，保持 Nginx `gzip_types` 边界。`GZIP_LEVEL` 必须在 `0..=9`，`GZIP_MIN_LENGTH_BYTES` 必须大于 `0`，越界启动失败；`COMPRESSION_ALGORITHMS` 当前只允许 `gzip`。Pingora 正式化口径固定为 gzip-only；Brotli 不进入当前 Pingora 直连门禁，仍由 Nginx / 前置代理能力探测承担。
- 影响范围：`server-rs/crates/pingora-gateway`、`deploy/pingora/pingora-gateway.env.example`、`scripts/check-pingora-gateway-smoke.mjs`、生产运维护栏、Pingora 试点文档和 Nginx 压缩文档。
- 验证方式：`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`、`npm run check:pingora-gateway-smoke`、`npm run check:production-ops`、`npm run check:pingora-release-readiness`。
- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。

## 2026-06-13 Pingora canary handoff 先本机容器复现再目标机 live 验证

- 背景：Pingora 影子网关已覆盖核心 Nginx 路由 parity，但只靠静态 snippet 检查和目标机手工 live canary，无法在本机 / CI 中复现真实 Nginx -> Pingora handoff 链路。
- 决策：新增 `npm run check:pingora-canary-docker` 作为正式切换前的本机容器验收：脚本启动 Docker Nginx、真实 `pingora-gateway`、mock `api-server` 和 mock SpacetimeDB，渲染同一份 `deploy/nginx/snippets/genarrative-pingora-canary.conf` 后复用 live canary 断言。Docker Nginx 必须写入生产同口径 access log，并在 live smoke 后复用 `scripts/check-pingora-canary-access-log-parity.mjs` 按同一 `request_id` 对账 canary healthz、代表性 API、SpacetimeDB identity 和静态资源路径，避免本机 / CI 只验证 handoff 响应头。默认 Docker 或镜像缺失时跳过，CI / 目标 agent 用 `node scripts/check-pingora-canary-docker.mjs --require-docker --pull` 强制执行；目标机人工 include 后仍必须跑 `npm run check:pingora-canary-live`。同时新增 `npm run check:pingora-release-readiness` 作为正式切换聚合门禁，默认适合本机提交前检查；切换窗口必须用 `--require-docker --pull-docker --require-nginx --require-live` 强制 Docker handoff、目标机 `nginx -t` 和 live canary 全部通过，且 `--require-live` 必须显式提供 `--live-host`，避免只打到 Nginx 默认 vhost。
- 真实路径补充：前缀 canary 通过后、Pingora direct 直连前，使用 `deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 做真实路径 canary。该 snippet 必须作为独立本机 `server` include 到 Nginx `http` 上下文，默认监听 `127.0.0.1:18083` 并写独立 `genarrative-pingora-realpath-canary.access.log`，不能 include 到生产 `443` server 内覆盖正式 location。`check-pingora-canary-live.mjs --realpath` 和 `check-pingora-canary-access-log-parity.mjs --realpath` 负责验证真实 `/api`、`/v1`、`/assets` 路径；release readiness 默认执行 `check:pingora-realpath-canary-toggle`，验证 realpath canary 启停脚本 dry-run、apply、失败回滚和 disable 恢复逻辑，目标机 runtime-only 用 `--require-realpath-live` 把已启用真实路径 canary 纳入门禁。
- 影响范围：`scripts/check-pingora-canary-docker.mjs`、`scripts/check-pingora-release-readiness.mjs`、`package.json`、生产运维护栏、Nginx README、Pingora 试点文档和生产运维文档。
- 验证方式：`node --check scripts/check-pingora-canary-docker.mjs scripts/check-pingora-release-readiness.mjs scripts/check-pingora-release-readiness-plan.mjs scripts/check-pingora-realpath-canary-toggle.mjs`、`npm run check:pingora-realpath-canary-toggle`、`npm run check:pingora-canary-docker`、`npm run check:pingora-release-readiness`、`npm run check:nginx-pingora-canary`、`npm run check:production-ops`；有 Docker 镜像或允许拉取时追加 `node scripts/check-pingora-canary-docker.mjs --require-docker --pull`，目标机切换窗口追加 `node scripts/check-pingora-release-readiness.mjs --require-docker --pull-docker --require-nginx --require-live --live-base-url http://127.0.0.1 --live-host <域名>`。
- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/nginx/README.md`。
## 2026-06-15 SpacetimeDB 本地 skills 只保留 CLI / Concepts / Rust

- 背景：本仓库的 SpacetimeDB 接入已固定为 `server-rs + Axum + SpacetimeDB`，本地 skill 需要从上游 SpacetimeDB `skills/` 更新到 2.5 口径，同时避免继续维护当前项目不使用的 TypeScript server/client、C# 和 Unity 专用 skill。
- 决策：`.codex/skills/` 下只保留 `spacetimedb-cli`、`spacetimedb-concepts`、`spacetimedb-rust` 三个本地 SpacetimeDB skill；删除 `spacetimedb-typescript`、`spacetimedb-csharp`、`spacetimedb-unity`。前端 / Node 侧如需处理 SpacetimeDB 订阅或绑定，按当前生成绑定、项目代码和官方文档核对，不再依赖仓库内单独 TypeScript skill。
- 影响范围：`AGENTS.md` 的 SpacetimeDB skill 清单、`.codex/skills/` 本地 skill 维护范围、后续 SpacetimeDB 设计 / CLI / Rust module 开发协作口径。
- 验证方式：用上游 `clockworklabs/SpacetimeDB@master` 的 `skills/` 目录对照，运行本地 skill 校验、删除引用扫描、`git diff --check -- .codex/skills AGENTS.md .hermes/shared-memory/decision-log.md` 和 `npm run check:encoding`。
- 关联文档：`AGENTS.md`、`.codex/skills/spacetimedb-cli/SKILL.md`、`.codex/skills/spacetimedb-concepts/SKILL.md`、`.codex/skills/spacetimedb-rust/SKILL.md`。

## 2026-06-13 图片大图预览统一为黑底全屏查看器

- 背景：`CreativeImageInputPanel` 的参考图 / 主图预览曾使用白底 `UnifiedModal` 工具弹窗，移动端会透出原页面背景，且不能全屏查看、缩放或拖拽细节。
- 决策：纯图片大图预览统一使用 `src/components/common/PlatformImagePreviewModal.tsx`。该组件底层复用 `UnifiedModal` 的 dialog / portal / Escape 语义，但视觉上固定为黑底全屏查看器；图片按视口 contain 初始完整展示，缩放范围固定 `1x-4x`，拖拽位移按缩放后的图片边界夹取，避免露出背景。裁剪、选择、编辑等工具语义仍继续使用白底工具弹窗，不并入图片查看器。
- 影响范围：`CreativeImageInputPanel` 的参考图预览、主图预览，以及后续 common 级图片查看场景。
- 验证方式：`npm run test -- src/components/common/PlatformImagePreviewModal.test.tsx src/components/common/CreativeImageInputPanel.test.tsx`、`npm run typecheck`、`npm run check:encoding`。
- 关联文档：`docs/README.md`、`docs/technical/【前端架构】PlatformUiKit弹窗组件收口计划-2026-06-08.md`。

## 2026-06-13 外部生成队列概览归属“我的”页签

- 背景：外部生成 worker 队列从单个生成页等待信息扩展为当前账号级别的后台排队 / 生成概览；继续放在生成页 / 进度页会把账号级队列与当前玩法业务进度混在一起。
- 决策：移动端用户可见的外部生成队列概览统一放在一级 `我的` 页签；生成页 / 进度页只展示当前玩法的阶段、步骤、总进度、错误和重试动作。队列概览只读取 BFF `GET /api/runtime/external-generation/queue-overview` 与当前前端已知单 job 状态作为等待补充，不替代玩法 session/detail 的 ready / failed 回读。
- 影响范围：平台入口壳层轮询条件、`RpgEntryHomeView` 我的页卡片、共用生成页 `CustomWorldGenerationView` / `UnifiedGenerationPage`、外部生成 worker 技术文档和本地开发验证文档。
- 验证方式：生成页不出现“生成队列”区域；登录用户进入“我的”页且队列有 pending/running 或当前 job 为 queued/running/failed 时显示队列卡；退出登录或切换账号时不保留旧账号队列概览。前端验证运行 `npm run test -- src/components/platform-entry/PlatformEntryFlowShellImpl.test.ts src/components/unified-creation/UnifiedGenerationPage.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`、`npm run check:encoding`。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。

## 2026-06-13 `/editor/agent` AI Web 工程编辑器采用静态沙箱预览 MVP

- 背景：`/editor/agent` 需要承载浏览器内类似 IDE 的 AI Web 工程编辑和实时预览能力，但 AI 生成工程的构建和运行不能进入 Genarrative 主站 JS 上下文、当前仓库源码目录或 api-server 进程。
- 决策：第一版采用“平台编辑器壳 `/editor/agent` + api-server 控制面 + 独立 `web-project-runner` worker + 独立 preview origin”的四层结构。MVP 只支持固定 React / Vite / TypeScript 静态模板、虚拟文件系统、结构化 AI patch、平台固定构建命令、独立 runner 静态构建和独立域 iframe 预览；明确不做 HMR、终端 shell、后端服务、任意端口代理、任意 npm 安装、AI 自定义 shell script 或主站同源预览。
- 影响范围：`/editor/agent` 前端入口、api-server Web project 控制面、Web project runtime job、runner 部署、preview gateway、artifact store、安全验收和后续作品化发布链路。
- 验证方式：Phase 0 必须先完成技术方案、威胁模型和验收清单；Phase 1 只能在路径校验、runner 资源限制、网络隔离、preview token、iframe/CSP、失败保留上一版预览和刷新恢复验收口径明确后进入编码。
- 关联文档：`docs/technical/【技术方案】浏览器内AIWeb工程沙箱预览方案-2026-06-13.md`、`docs/technical/【安全模型】AIWeb工程Runner与预览隔离威胁模型-2026-06-13.md`、`docs/technical/【测试用例】AIWeb工程静态预览MVP验收清单-2026-06-13.md`。

## 2026-06-12 外部生成 worker 扩展到跳一跳、拼消消和敲木鱼

- 背景：外部图片生成已从 HTTP 长请求迁到 `external_generation_job` 队列；跳一跳、拼消消和敲木鱼继续扩展时需要统一 job 粒度、前端等待展示和本地 / 生产验证口径。
- 决策：队列 BFF 暴露用户可见队列概览 `GET /api/runtime/external-generation/queue-overview` 和单 job 状态 `GET /api/runtime/external-generation/jobs/{jobId}`；首版固定“单动作单 job”，不拆提示词 / 生图 / 切图 / 持久化等阶段 job。进入队列的范围为跳一跳 `compile-draft` / `regenerate-tiles`、拼消消 `compile-draft` / `regenerate-atlas`、敲木鱼 `compile-draft` / `regenerate-hit-object` 图片资产动作；非外部图片生成动作继续 inline。
- 影响范围：外部生成 worker Module、api-server BFF、生成页等待展示、跳一跳 / 拼消消 / 敲木鱼创作与结果页生成动作、本地和生产验证文档。
- 验证方式：本地 `npm run dev` 默认保留 inline 开发体验；验证 worker 队列、等待展示、lease 或扩缩容时显式使用 `GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 并启动 worker，或运行 `npm run container:worker-smoke -- smoke`。部署后确认 `/healthz`、`/readyz`、队列概览 BFF、单 job 状态和对应玩法 session/detail 状态都能收敛。
- 关联文档：`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 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` 包含该普通请求头。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`server-rs/crates/platform-oss/README.md`。

## 2026-06-06 小程序微信绑定展示使用原生昵称组件

- 背景：账号信息面板需要显示“绑定的是哪个微信号”。微信小程序登录 `jscode2session` 不返回昵称或个人微信号，但小程序提供 `input type="nickname"` 原生昵称填写 / 选择能力，可在登录前收集微信昵称用于展示。
- 决策：小程序登录页先展示原生 `input type="nickname"`，将昵称作为 `displayName` 随 `/api/auth/wechat/miniprogram-login` 提交；若还需要绑定手机号，再随 `/api/auth/wechat/bind-phone` 一并提交。`wechatDisplayName` 只能来自微信平台 profile、历史已保存的微信身份资料或小程序原生昵称组件，不能用系统账号显示名或“微信旅人”兜底。小程序侧拿不到昵称时，前端使用后端下发的 `wechatAccount`（openid / provider_uid）尾号展示，避免只显示裸“已绑定”。
- 影响范围：`platform-auth` 小程序登录 profile、`module-auth` 微信身份持久化、`api-server` 小程序登录 / 绑定响应、账号信息面板、项目基线和后端契约文档。
- 验证方式：`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 拼消消收敛为单关 6x6 与 4-sheet 素材策略

- 背景：最初 4 关 / 135 次消除 / 单张大 atlas 方案生图数量和空间一致性成本过高，真实 image2 结果容易被布局提示词诱导成带文字、边框或编号的说明图，不适合运行态 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`。

## 2026-05-30 拼消消按独立玩法公开闭环接入

- 背景：拼消消以拼图交换手感为基础，但核心规则从“拼完整单图过关”变为“拼成多个复合图案组后逐个消除”，同时需要顶部补牌、防死局、半锁定局部拼接组和正式统计，不能继续复用拼图运行态规则本体。
- 决策：`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。
- 补充约束：拼消消结果页草稿试玩使用前端本地 `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；当前 OpenSSL 3.2 独立运行时自举会安装 `build-essential` 等最小工具，这是满足 api-server/libcurl 运行时符号的受控例外，不代表 provision 承担 api-server 构建职责。非 dry-run 仍要求目标 dev / release agent 具备 root 权限，因为 provision 会写 systemd、Nginx、`/etc` 和系统用户。Job 的 `Pipeline script from SCM` 与 Jenkinsfile 参数 `SOURCE_GIT_REMOTE_URL` 都必须使用本机路径或目标 agent 可访问的内网 Git 源，不允许公网 Git fallback。
- 追加决策（2026-06-10）：`Prepare Provision Tools` 必须先读取目标机现状，再准备需要的文件。目标机 `/usr/local/bin/otelcol-contrib` 版本匹配 `OTELCOL_VERSION` 时直接复用；`${SPACETIME_ROOT}/bin/current/spacetimedb-cli` 和 `spacetimedb-standalone` 存在且 CLI 版本匹配 `SPACETIME_EXPECTED_VERSION` 或 `SPACETIME_DOWNLOAD_ROOT` 中的版本时，直接复用当前安装生成 `provision-tools/`。只有目标机缺失、不可执行或版本不匹配时，才消费 `PROVISION_DOWNLOADS_DIR` 中的本地包或进入下载分支。
- 影响范围：`jenkins/Jenkinsfile.production-server-provision`、`scripts/jenkins-server-provision.sh`、生产运维文档、Server-Provision 排障口径。
- 验证方式：Jenkins 日志中 Server-Provision 的 `Prepare`、`Checkout Provision Files`、`Prepare Provision Tools` 和 `Provision Server` 都在目标 dev / release agent 上执行；日志不出现 `Running on Jenkins`、`linux && genarrative-build`、`stash 'server-provision-tools'`、`Git 主地址拉取失败...改用备用地址`、`https://git.genarrative.world/GenarrativeAI/Genarrative.git` 或构建依赖 / sccache 安装步骤；`bash -n scripts/jenkins-server-provision.sh` 和编码检查通过。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-06-05 api-server 重启先摘流再排空并持久化 outbox

- 背景：生产部署重启 api-server 时，如果只用 `/healthz` 判断存活并直接停止进程，运行中的 HTTP 请求和本地 tracking outbox active 文件都可能被中断，容易造成用户请求失败或内存/本地缓冲数据延迟丢失。
- 决策：`/healthz` 只表示进程存活，发布和生产接流检查统一使用 `/readyz`。api-server 收到 `SIGINT` / `SIGTERM` 后先把 readiness 标记为不可用，再交给 Axum graceful shutdown 排空已有 HTTP 请求；退出前在 `GENARRATIVE_API_SHUTDOWN_OUTBOX_FLUSH_TIMEOUT_MS` 窗口内封存 active tracking outbox 并尽力 flush sealed 文件，失败或超时则保留本地文件给下次启动重试。systemd 停机窗口统一放到 `TimeoutStopSec=90`。
- 影响范围：`server-rs/crates/api-server`、`deploy/systemd/genarrative-api.service`、生产 API deploy 脚本、Jenkins API deploy 参数、Nginx 公网健康检查暴露策略、开发运维文档。
- 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml readyz_reports_readiness_and_draining_state`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml shutdown_flush_seals_active_file_for_later_retry`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、部署脚本 `bash -n` 与 `/readyz` 本机 smoke。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-06-05 OSS 平台适配器输出结构化日志

- 背景：AI 生成资产、浏览器直传签名、私有读签名和对象确认都依赖 OSS；如果 OSS 侧只有错误字符串，排查资产写入 / 确认失败时很难按操作、对象、状态码和耗时下钻。
- 决策：`server-rs/crates/platform-oss` 统一为 `sign_post_object`、`sign_get_object_url`、`head_object` 和 `put_object` 输出结构化日志。日志固定携带 `provider=aliyun-oss`、`operation`、`bucket`、`endpoint`、`object_key` / `key_prefix`、`access`、`content_type`、`content_length`、`status`、`status_class`、`error_kind` 和 `elapsed_ms` 等排障字段；禁止输出 AccessKey、policy、signature、Authorization header 或完整 signed URL。
- 影响范围：`server-rs/crates/platform-oss`、`api-server` 资产签名 / 上传 / 确认链路、OTLP logs、本地 `logs/api-server/` 与运维排障文档。
- 验证方式：`cargo test -p platform-oss --manifest-path server-rs/Cargo.toml`；真实联调时按 `provider=aliyun-oss` 与 `operation` 过滤日志，确认只出现对象定位和状态字段，不出现签名材料。
- 关联文档：`server-rs/crates/platform-oss/README.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-06-05 跳一跳返回按钮改为独立主题资产

- 背景：跳一跳运行态曾把左上角返回按钮视觉锚点写进背景 image2 prompt，导致返回按钮像静态背景元素，不能替代真实可点击按钮。
- 决策：跳一跳背景 prompt 禁止生成任何 UI 或左上角图标；返回按钮由 `backButtonAsset` 单独生成 1:1 纯绿 key 图，后端去绿后作为透明 PNG 持久化到作品 profile，运行态左上角真实按钮优先渲染该资产。顶部得分 HUD 复用拼图模板结构，包含陶泥儿 IP logo、标题牌和下挂数字卡。
- 影响范围：`packages/shared/src/contracts/jumpHop.ts`、`shared-contracts`、`spacetime-module` / `spacetime-client` bindings、`api-server` 跳一跳生成链路、`JumpHopRuntimeShell`、玩法链路文档和后端数据契约文档。
- 验证方式：`npm run spacetime:generate`、`cargo test -p api-server jump_hop --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx`、`npm run check:spacetime-schema`。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-06-03 创作入口关闭不下架已发布作品

- 背景：`creation_entry_disabled` 曾由 api-server 按 runtime 路由前缀统一熔断，导致用户进入平台首页或启动已发布作品时也可能看到“创作入口已关闭”错误。
- 决策：入口配置的 `open=false` 只表示关闭新建创作入口，不表示下架已有草稿、私有作品或公开作品。后端熔断只拦新建创作、新建草稿、首次生成入口和 Remix 成草稿等会产生新创作的请求；公开广场、公开详情、点赞、已发布作品启动、运行态过程请求、存档 / 浏览记录和已有作品回读不因创作入口关闭而失败。前端平台首页遇到旧服务端返回的 `creation_entry_disabled` 只降级，不弹平台级错误弹窗；关闭态模板卡必须明显禁用并展示 `暂未开放`，不得继续显示泥点消耗。
- 影响范围：`server-rs/crates/api-server/src/creation_entry_config.rs`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、创作入口相关测试与玩法链路文档。
- 验证方式：关闭任一创作入口后，新建创作请求返回 `creation_entry_disabled`；公开作品列表 / 详情 / 启动 / 运行态动作不返回该错误；进入平台首页不弹“平台首页：creation_entry_disabled”；关闭态入口卡显示锁定状态且不显示 `10-20泥点数`。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-06-03 外部内容生成改为持久队列加 worker 角色

- 背景：拼图首图、图集、音频等外部生成链路长期占用 `api-server` HTTP handler，导致扩容只能放大 API 进程，且 HTTP 超时和外部 provider 波动会直接影响创作入口。
- 决策：外部生成任务统一进入 SpacetimeDB `external_generation_job` 持久队列，由 `api-server` 的 `external-generation-worker` 进程角色 claim lease 后执行；HTTP 角色只做鉴权、表单/状态初始化、入队和返回 `queued/running/completed/failed` 操作状态。生产通过 systemd worker 模板增加实例数或提高 `GENARRATIVE_EXTERNAL_GENERATION_WORKER_CONCURRENCY` 动态扩缩容，`GENARRATIVE_PROCESS_ROLE=all` 仅用于本地 smoke。拼图 `compile_puzzle_draft`、结果页 `generate_puzzle_images` 与 `generate_puzzle_ui_background` 已接入 worker；业务写回必须在 SpacetimeDB transaction 内校验 `external_generation_job` 的 `job_id + worker_id + lease_token`、job kind、owner 和 source entity，其中首图 worker 的前置 `compile_puzzle_agent_draft` 也必须带 guard。worker 核心业务写回失败不能返回内存快照并把 job 标成 completed；失败态业务写回成功后才能把 job 标成 failed，失败态未写回则保留租约等待后续重领。拼图业务失败不自动重试，只保留 lease 过期后的崩溃重领，避免钱包扣退费幂等漂移。生产发布会启用默认 `genarrative-external-generation-worker@1.service` 并等待 worker active，worker 停机时停止 claim 新任务并 drain 当前任务。
- 2026-06-07 追加：`GENARRATIVE_EXTERNAL_GENERATION_MODE` 使用 `queue|inline` 显式策略；生产和容器扩缩容验证保持 `queue`。本地开发若需要同步等待结果，应通过 `.env.local` 或本机环境显式配置为 `inline`，由 HTTP handler 复用同一 worker executor 直接返回 `completed`，不创建 `external_generation_job`，不支持 worker 动态扩缩容；脚本不得硬编码该策略。拼图写回 guard 字段改为可选，queue 路径仍必须完整校验 `job_id + worker_id + lease_token`；inline 路径只允许三项同时为空，半空 guard 仍拒绝。
- 2026-06-11 追加：生产新增固定 `external-generation-controller` 进程角色和 `genarrative-external-generation-controller.service`。controller 只读取 `get_external_generation_queue_stats_and_return` 队列统计并管理 `genarrative-external-generation-worker@N.service`，不监听 HTTP、不执行外部生成任务；默认保留 `@1`，按 `claimable_pending + running_active + expired_running` 计算目标实例数，上限由 `GENARRATIVE_EXTERNAL_GENERATION_CONTROLLER_MAX_WORKERS` 控制，缩容需要连续空闲轮数且每轮只停最高编号一个实例。
- 影响范围：`server-rs/crates/spacetime-module/src/external_generation.rs`、`server-rs/crates/spacetime-client/src/external_generation.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`server-rs/crates/api-server/src/external_generation_worker_controller.rs`、`deploy/systemd/genarrative-external-generation-worker@.service`、`deploy/systemd/genarrative-external-generation-controller.service`、`deploy/env/external-generation-controller.env.example`、`scripts/deploy/production-api-deploy.sh`、`scripts/jenkins-server-provision.sh`、拼图 `compile_puzzle_draft`、拼图 `generate_puzzle_images`、拼图 `generate_puzzle_ui_background`、生产 env 模板和运维文档。
- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run check:server-rs-ddd`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`，并在 queue 模式下用 `GENARRATIVE_PROCESS_ROLE=all npm run dev` smoke 至少一次 queued -> worker 完成链路；本地 inline 排查只确认不创建 `external_generation_job`。
- 关联文档：`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-06-03 外部生成 worker lease 使用 SpacetimeDB 时间和 token 栅栏

- 背景：外部生成 worker 支持多进程动态缩扩容后，长任务超过单次 lease、worker 本机时钟漂移或复用 worker id 都可能导致同一任务被重复领取并被过期执行者回写。
- 决策：`external_generation_job` 新增末尾字段 `lease_token`；`claim` 使用 SpacetimeDB `ctx.timestamp` 计算 lease，生成本次 claim token；worker 执行期间调用 `renew_external_generation_job_lease_and_return` 续租；`complete/fail` 必须带 `worker_id + lease_token` 才能回写。拼图 `compile_puzzle_draft` 的 dedupe key 包含本次 `extgen-` job id，避免同一 session 的失败或完成 job 吞掉后续重新生成。拼图首图前置 `compile_puzzle_agent_draft`、图片保存、UI 背景与失败态业务写回同样必须携带 lease guard，并在 `compile_puzzle_agent_draft`、`save_puzzle_generated_images`、`save_puzzle_ui_background`、`mark_puzzle_draft_generation_failed`、`mark_puzzle_level_generation_failed` 的 SpacetimeDB 事务内校验。
- 影响范围：`server-rs/crates/spacetime-module/src/external_generation.rs`、`server-rs/crates/spacetime-module/src/puzzle.rs`、`server-rs/crates/module-puzzle/src/commands.rs`、`server-rs/crates/spacetime-client/src/external_generation.rs`、`server-rs/crates/spacetime-client/src/puzzle.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`server-rs/crates/api-server/src/puzzle/handlers.rs`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/generation.rs`。
- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo test -p spacetime-module external_generation --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server external_generation_worker --manifest-path server-rs/Cargo.toml`、`GENARRATIVE_PROCESS_ROLE=all npm run dev` 后检查 `/healthz`。
- 关联文档：`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`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 最近创作只复用创作模板入口

- 背景：底部加号创作入口的“最近创作”最初由真实作品架摘要驱动，但页面曾按作品标题、摘要和生成状态渲染独立最近创作卡，和其它模板页签的卡片样式及点击语义不一致。
- 决策：“最近创作”仍只由真实后端作品架摘要决定是否展示，但只纳入 `updatedAt` 在最近 7 天内的摘要，且摘要只用于推导最近使用过的模板 ID；实际列表必须从后端入口配置的 `creationTypes` 中筛出对应模板，复用其它页签的模板卡结构、文案和 `onCreateType` 点击行为，不展示具体作品名称、作品摘要或草稿 / 生成状态，也不新增独立最近创作组件。最近创作页签激活时，页面必须显示“仅显示最近7天内使用过的模板”。
- 影响范围：`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、`src/components/custom-world-home/CustomWorldCreationHub.tsx`、`src/components/platform-entry`、创作入口相关测试与玩法链路文档。
- 验证方式：`CustomWorldCreationHub` 测试应断言最近创作页签包含 `creation-template-card`、模板标题 / 副标题，并且不出现旧 `creation-recent-work-grid`、作品标题、作品摘要或“打开最近创作”按钮文案；RPG 入口交互测试应断言最近创作默认页签展示“文字冒险”模板卡。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-06-02 底部加号创作入口页 banner 与最近创作口径

- 背景：创作入口页 banner 曾固定为前端两张主题赛卡，且模板分类兜底会产生 `recent` / `最近创作` 页签，和后台配置及真实作品数据口径冲突。
- 决策：点击底部加号进入的创作入口页 banner 改由后端 `eventBanners` 数组配置，多条自动轮播；旧 `eventBanner` 只保留单条兼容。后台公告配置使用表单维护标题与 HTML 内容，保存时序列化为后端 `eventBannersJson` 传输字段；HTML 只允许经空权限 iframe 展示，不执行 JSX 或直接 DOM 注入。`最近创作` 不再作为模板分类，只由真实草稿 / 作品架后端数据决定是否展示，生成失败草稿也必须进入；模板分类缺失或历史 `recent` 统一归一到 `recommended` / `热门推荐`。移动端草稿页作品卡禁止长按选择文字，但输入框和可编辑区域保留选择能力。
- 影响范围：`server-rs/crates/module-runtime`、`server-rs/crates/spacetime-module`、`server-rs/crates/spacetime-client`、`server-rs/crates/api-server`、`shared-contracts`、`src/components/custom-world-home`、`src/components/platform-entry`、`apps/admin-web`、`src/index.css`。
- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、相关 Rust / Vitest 入口配置测试和浏览器点击底部加号截图。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-05-26 微信小程序充值全面接入虚拟支付

- 背景：泥点和会员都属于小程序内由 Genarrative 控制的虚拟资产/权益，继续走普通小程序支付不符合微信虚拟支付接入口径。
- 决策：小程序 WebView 内充值商品全部使用渠道 `wechat_mp_virtual` 并由 `miniprogram/pages/wechat-pay` 调用 `wx.requestVirtualPayment`；泥点属于代币（coin），使用 `short_series_coin`，`buyQuantity` 必须取当前充值中心商品快照里的 `points_amount`；会员和后台新增道具类商品使用 `short_series_goods`，`signData` 必须带 `productId` 与 `goodsPrice`。后端保存微信小程序 `session_key`，仅用于生成 `signature`，不下发客户端。客户端 success 只作为支付页返回信号，最终到账仍由后端微信通知或查询确认后写订单。
- 影响范围：`src/services/payment/paymentPlatform.ts`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`miniprogram/pages/wechat-pay/`、`server-rs/crates/api-server/src/runtime_profile.rs`、`server-rs/crates/shared-contracts/src/runtime.rs`、`packages/shared/src/contracts/runtime.ts`、微信登录态存储。
- 验证方式：泥点和会员商品在小程序运行态都请求 `wechat_mp_virtual`；小程序页能按 payload 调用 `wx.requestVirtualPayment` / `wx.requestPayment`；`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 与支付相关前端测试通过。
- 关联文档：`docs/【技术方案】微信虚拟支付接入-2026-05-26.md`。

## 2026-05-30 Linux 本地 dev 端口段按系统级注册表分配

- 背景：同一台 Linux 开发机上有多个用户同时跑 `npm run dev` 时，单纯靠各自 `GENARRATIVE_DEV_PORT_RANGE` 容易撞段，且同一用户并发起两个 dev 会话时也会把相同端口段重复拿走。
- 决策：Linux 上的本地 dev 端口段分配统一收口到系统级注册表 `/var/tmp/genarrative-dev-port-ranges/registry.json`，锁文件为 `/var/tmp/genarrative-dev-port-ranges/registry.lock`，可通过 `GENARRATIVE_DEV_PORT_RANGE_REGISTRY_DIR` 覆盖目录。未手动指定时自动从 `10000-10099` 开始按 100 端口块分配，后续块按 `10100-10199`、`10200-10299` 递增；端口段映射固定为 `web = start`、`api = start + 1`、`spacetime = start + 2`、`admin-web = start + 3`；注册表会拒绝不同用户的相同或重叠段，并让同一用户后续启动继续复用自己已占用的固定段。`GENARRATIVE_DEV_PORT_RANGE` 与 `--port-range` 仍可手动指定端口段，但只在 Linux 生效，Windows 继续沿用原有端口探测与漂移逻辑，不读注册表。
- 影响范围：`scripts/dev-stack-port-utils.mjs`、`scripts/dev.mjs`、`scripts/dev-stack-port-utils.test.ts`、`scripts/dev.test.ts`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、本条决策记录、`development-workflow.md`。
- 验证方式：`node --check scripts/dev-stack-port-utils.mjs`、`node --check scripts/dev.mjs`、`node node_modules/vitest/vitest.mjs run scripts/dev-stack-port-utils.test.ts scripts/dev.test.ts` 通过；Linux 下能看到 `[dev] port-range:` 与 `registry.json` 路径日志，自动分配从 `10000-10099` 起步，Windows 不出现注册表分配日志。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-05-30 创作流程统一化门禁扩展为跨玩法矩阵

- 背景：统一创作 / 统一生成门禁已经足够覆盖 Phase 2 的入口与壳层，但当前总计划已经推进到 Phase 3-6，继续只保留单页门禁会让 Phase 4 的特殊工作台、Phase 5 的结果页 / 作品架 / 公开详情和 Phase 6 的冻结验收没有统一入口。
- 决策：`quality-gates/README.md` 继续保留单页门禁与 `dev-stack` 门禁，同时新增跨玩法回归 / 冒烟门禁，按 Phase 2 到 Phase 5 的最小验证集合分层执行；Phase 6 冻结前以这份矩阵为主，不再另外拆新波次。涉及入口配置、统一字段 spec、普通工作台、RPG / Bark Battle / 视觉小说特殊边界、发布 / 公开 / runtime 或本地 smoke 的变更，优先对照这份矩阵补齐验收命令。
- 影响范围：`quality-gates/README.md`、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md`、`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`、后续 Phase 2-6 玩法接入与冻结流程。
- 验证方式：按矩阵执行 `npm run check:encoding`、`npm run typecheck`、`npm run admin-web:typecheck`、对应分期 `npm run test`、`npm run check:visual-novel-vn11`，以及需要时的 `npm run dev:api-server` + `/healthz` smoke。
- 关联文档：`quality-gates/README.md`、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md`、`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`。

## 2026-05-30 跳一跳结果页直达必须优先恢复作品而不是白屏

- 背景：跳一跳结果页已经接入统一壳，但如果用户直接打开 `/creation/jump-hop/result`，旧路径容易因为缺少 `draft` 恢复信息而看起来像白屏，误导成结果页坏了。
- 决策：`PlatformEntryFlowShellImpl` 的跳一跳恢复顺序固定为 `profileId -> getWorkDetail`，再 `sessionId -> getSession`；两者都拿不到时必须展示 `跳一跳草稿未恢复` 恢复面板和 `返回创作`，不能继续留空白结果页。进入结果页的 smoke 允许恢复面板，但不允许纯空白。
- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md`、`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`。
- 验证方式：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "direct jump hop result route"`；手测 `/creation/jump-hop/result` 和 `/creation/jump-hop/result?profileId=<id>`。
- 关联文档：`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`、`quality-gates/【玩法创作】跨玩法回归与冒烟门禁-2026-05-30.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-29 一期统一创作页必须提供可见统一外壳

- 背景：`UnifiedCreationPage` 首版只暴露隐藏 spec 元数据并包裹旧玩法工作台，用户打开拼图创作页时仍只能看到旧工作台外观，无法验收“统一创作页”。
- 决策：一期统一创作页（拼图、抓大鹅、敲木鱼）必须由 `UnifiedCreationPage` 提供统一标题栏、内容区、页面级纵向滚动和隐藏字段契约；字段元信息只留给测试和代码，不再额外作为可见 chip 占用首屏。玩法工作台只承载具体输入控件、上传、历史素材、校验和提交，不再各自渲染巨大入口标题。拼图、抓大鹅与敲木鱼的实现已经统一收口到 `src/components/unified-creation/workspaces/`，统一壳只依赖 `UnifiedCreationWorkspace`。敲木鱼右侧音效和功德面板不得再套内部滚动容器，移动端应自然跟随页面滚动。
- 追加决策：`UnifiedCreationPage` 自己负责页面级滚动；拼图、抓大鹅、跳一跳和敲木鱼四条统一创作入口必须在同一页面壳内从统一标题、表单控件一路滑到提交按钮，避免工作台内部或右侧面板形成套滚动。
- 影响范围：`src/components/unified-creation/UnifiedCreationPage.tsx`、`src/components/unified-creation/UnifiedCreationWorkspace.tsx`、`src/components/unified-creation/workspaces/PuzzleCreationWorkspace.tsx`、`src/components/unified-creation/workspaces/Match3DCreationWorkspace.tsx`、`src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、玩法链路文档。
- 验证方式：`UnifiedCreationPage` 测试应断言隐藏契约仍在但 UI 不再出现字段 chip；拼图和抓大鹅工作台测试应断言 `unifiedChrome=true` 时不再渲染旧巨大标题且仍保留表单输入；木鱼工作台测试或手测应确认敲击音效和功德词条不再停留在独立滚动窗内。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-31 统一创作壳扩展到跳一跳并接管页面级滚动

- 背景：最初的统一创作页只收口拼图、抓大鹅和敲木鱼，跳一跳仍通过独立工作台壳与独立生成壳渲染，导致用户在 `/creation/jump-hop` 看到的可见外壳与其它统一入口不一致。
- 决策：`jump-hop` 也纳入统一创作壳与统一生成壳；`UnifiedCreationPage` 现在承担页面级滚动和统一标题栏，拼图、抓大鹅、跳一跳、敲木鱼四条入口都通过同一外壳承载各自工作台。`JumpHopCreationWorkspace`、`WoodenFishCreationWorkspace` 也补了 `unifiedChrome` / `showBackButton` 受控能力，避免双标题或双返回按钮。
- 追加决策：`UnifiedCreationPage` 的统一页头现在承载唯一返回入口，工作台内部的返回按钮全部关闭，避免同一页面出现双返回按钮；`UnifiedCreationWorkspace` 统一把 `onBack` 透传给页头。
- 追加决策：统一创作页内容区必须保持自然高度，页面级滚动只由 `UnifiedCreationPage` 外层承担，工作台内部只负责内容展开，不再额外包滚动壳。
- 影响范围：`src/components/unified-creation/UnifiedCreationPage.tsx`、`src/components/unified-creation/unifiedCreationSpecs.ts`、`src/components/unified-creation/unifiedGenerationCopy.ts`、`src/components/unified-creation/workspaces/JumpHopCreationWorkspace.tsx`、`src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`server-rs/crates/shared-contracts/src/creation_entry_config.rs`。
- 验证方式：`npm run test -- src/components/unified-creation/unifiedCreationSpecs.test.ts src/components/unified-creation/UnifiedCreationPage.test.tsx src/components/unified-creation/UnifiedGenerationPage.test.tsx src/components/unified-creation/workspaces/JumpHopCreationWorkspace.test.tsx src/components/unified-creation/workspaces/WoodenFishCreationWorkspace.test.tsx`；`npm run test -- src/components/unified-creation/workspaces/PuzzleCreationWorkspace.interaction.test.tsx src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx`；`npm run test -- src/routing/appPageRoutes.test.ts`。

## 2026-05-31 统一创作编排层必须由 UnifiedCreationWorkspace 统一收口

- 背景：`PlatformEntryFlowShellImpl` 仍直接 lazy import 并渲染四个旧工作台分支，虽然统一创作页已存在，但入口壳层仍然依赖旧工作台分支。
- 决策：新增 `UnifiedCreationWorkspace` 作为平台壳唯一依赖的统一创作编排层，由它内部按 `playId` 选择四条入口的真实工作台；平台壳层只再挂这一层，不再直接依赖旧工作台组件。旧工作台已移入 `src/components/unified-creation/workspaces/`，不再作为平台入口编排事实源。
- 影响范围：`src/components/unified-creation/UnifiedCreationWorkspace.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、统一创作页相关测试与后续入口接入。
- 验证方式：平台壳源码中不应再直接出现四个旧工作台的入口渲染分支；创作 Tab 与 `/creation/<play>` 仍可正常进入对应工作台。
- 关联文档：`docs/planning/【玩法创作】创作流程统一总计划-2026-05-30.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-27 生成页总进度圆弧锁定固定 SVG 坐标系

- 背景：多轮圆环角度微调后，`GenerationProgressHero` 的 SVG 圆弧仍会出现底部开口偏斜的问题；后来窄屏验收又发现固定 `400px` 外层宽度会让等待页右侧被裁切。
- 决策：共用 `GenerationProgressHero` 的 SVG 圆弧起始角固定为 `135deg`，轨道和橘黄色填充都从同一个对称起点 `rotate(135 200 200)` 出发；`270deg` 扫描角配合正下方 `90deg` 留空。SVG 内部坐标系固定为 `400x400`，圆弧使用 `r=166` 和 `strokeWidth=18`；外层显示宽度以 `400px` 为上限，窄屏按父容器 `min(400px, calc(100% - 0.75rem))` 等比收缩，避免嵌套页面 padding 或负 margin 下用 `100vw` 误判宽度。预计等待 / 已耗时信息卡在窄屏下落到圆环下方两列，`sm` 及以上再回到左右悬浮。
- 影响范围：`src/components/GenerationProgressHero.tsx`、共用 `CustomWorldGenerationView`、汪汪声浪 `BarkBattleGeneratingView` 以及生成页圆环布局文档。
- 验证方式：`CustomWorldGenerationView` 和 `BarkBattleGeneratingView` 测试断言 `data-ring-start-degrees=135`、`data-ring-fill-start-degrees=135`，且圆环容器包含 `w-[min(400px,calc(100%_-_0.75rem))]`、`max-w-full` 与 `aspect-square`，track / fill transform 都是 `rotate(135 200 200)`；竖屏 smoke 至少覆盖 `280px / 320px / 360px / 390px` 宽度。
- 关联文档：`docs/【玩法创作】生成页圆环布局口径-2026-05-23.md`。

## 2026-05-26 平台跨流程错误统一用可复制来源弹窗展示

- 背景：拼图等生成链路可能同时存在多个草稿或游玩实例，页面内裸错误 banner 容易让用户误以为当前正在看的拼图失败，也不方便复制完整错误给开发排查。
- 决策：平台入口、生成页、结果页、作品详情、作品架和运行态的跨流程错误统一收口到 `PlatformErrorDialog`；弹窗必须带错误来源，例如某个草稿、生成会话、作品详情或游玩实例，并提供复制按钮复制来源与错误内容。页面内旧的裸错误 banner、创作入口 modal 错误、生成页错误徽标等不再重复展示；表单校验和发布确认弹窗里的局部业务错误仍可保留在原弹窗内。
- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/PlatformErrorDialog.tsx`、`src/components/CustomWorldGenerationView.tsx`、`src/components/custom-world-home/CustomWorldCreationHub.tsx`、`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、`src/components/platform-entry/PlatformWorkDetailView.tsx`、`src/components/platform-entry/PlatformEntryCreationTypeModal.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`。
- 验证方式：`npm run test -- src/components/platform-entry/PlatformErrorDialog.test.tsx src/components/platform-entry/PlatformEntryCreationTypeModal.test.tsx`、`npm run typecheck`、`npm run check:encoding` 通过；手测时异步失败应弹出包含“错误来源”和“错误内容”的弹窗，复制按钮应复制完整诊断文本。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-26 生成任务完成在离开生成页后弹独立完成弹窗

- 背景：抓大鹅、拼图等生成任务完成时，用户如果已经离开生成页，草稿页的未读红点不足以表达“这次生成已完成”；但如果用户仍停留在生成页，结果页或试玩页本身就是完成反馈，不需要再叠一个成功提示。
- 决策：平台壳层在 `markDraftReady(..., viewedImmediately=false)` 时额外弹出 `PlatformTaskCompletionDialog`，完成弹窗必须带来源和复制按钮；如果 `viewedImmediately=true`，只保留结果页 / 试玩页本身的完成反馈和草稿未读态，不重复弹窗。
- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/PlatformTaskCompletionDialog.tsx`、`src/components/platform-entry/PlatformErrorDialog.test.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
- 验证方式：`npm run test -- src/components/platform-entry/PlatformErrorDialog.test.tsx`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "completed match3d draft"` 通过后，离开生成页再完成的草稿应出现“生成完成”弹窗，且复制内容包含来源与状态。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-26 “我的”页任务卡读后端任务摘要并移除常驻填邀请码入口

- 背景：移动端“我的”页每日任务卡曾硬编码 `0 / 1`，任务领取完成后只刷新弹窗内任务中心，卡片本身不更新；页面底部还保留旧的“填邀请码”次级按钮，和当前五项常用功能宫格口径重复。
- 决策：`RpgEntryHomeView` 的每日任务卡以 `/api/profile/tasks` 返回的任务中心为事实源，展示当前可操作任务的奖励、进度和状态；领取成功后同步使用 claim 响应里的 `center` 刷新卡片。移动端“我的”页不再渲染常驻“填邀请码”次级入口，邀请码填写仅保留邀请链接 query 自动打开弹窗和其它明确引导。
- 影响范围：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。
- 验证方式：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx` 应断言任务卡显示 `1 / 1`、领取后显示已完成，且新用户账号也没有 `次级入口` / `填邀请码` 常驻按钮；`npm run typecheck`、`npm run check:encoding` 通过。
- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。

## 2026-05-26 生成页总进度圆弧逆时针回调 5 度

- 背景：创作生成页的总进度圆弧在 `160deg` 位置仍需轻微向左微调，用户要求向左逆时针回调 `5deg`。
- 决策：共用 `GenerationProgressHero` 的 SVG 圆弧起始角从 `160deg` 调整为 `155deg`，track 和 fill 都使用同一个 `rotate(155 200 200)` 变换；仍保持 `270deg` 扫描角和正下方 `90deg` 留空。
- 决策：总进度标题与百分比数字在 `GenerationProgressHero` 中显式提升到圆环之上，圆环 SVG 维持背景层级。
- 决策：总进度标题与百分比数字的内容区上边距从 `pt-[4%]` 收紧到 `pt-[2%]`，桌面端使用 `sm:pt-[1.5%]`，进一步拉开与圆环弧线的距离。
- 影响范围：`src/components/GenerationProgressHero.tsx`、共用 `CustomWorldGenerationView`、汪汪声浪 `BarkBattleGeneratingView` 以及生成页圆环布局文档。
- 验证方式：`CustomWorldGenerationView` 和 `BarkBattleGeneratingView` 测试断言 `data-ring-start-degrees=155` 且 track / fill transform 都是 `rotate(155 200 200)`。
- 关联文档：`docs/【玩法创作】生成页圆环布局口径-2026-05-23.md`。

## 2026-05-25 抓大鹅发现页官方 demo 使用静态资源与本地运行态

- 背景：本轮抓大鹅资源管线曾生成一套官方静态 demo，用于验证生图、切图和运行态资源闭环，但该 demo 已被移除，不再作为发现页入口。
- 决策：发现页不再挂载前端固定官方抓大鹅 demo；公开卡片、作品号搜索、详情页和运行态启动全部来自后端真实 profile / gallery 投影，正式作品统一走 server runtime adapter。
- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、原前端 demo 数据文件（已删除）、Match3D 相关测试与原静态资源目录（已删除）。
- 验证方式：发现页不再出现原固定 demo；Match3D 公共详情只从真实后端作品数据读取。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-25 抓大鹅运行态 HUD 收敛为拼图同款低遮挡样式

- 背景：抓大鹅游玩阶段 UI 需要继续对齐拼图运行态的观感，同时移除右上角设置入口、灰白半透底板和显眼锅壳，让棋盘区域更专注。
- 决策：抓大鹅运行态只保留左上透明返回按钮，右上不再显示设置入口；顶部关卡名和倒计时直接复用拼图同款的铭牌 + 下挂计时牌结构、同色板、同造型和 `media/logo-runtime-hud.webp` 产品 logo 小图；底部备选栏和道具图标保持交互边界但不再显示灰白半透底；中央容器图层可以视觉隐藏，但棋盘命中边界和既有交互逻辑保留。
- 影响范围：`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.test.tsx`、`src/index.css`、抓大鹅玩法链路文档。
- 验证方式：运行态页面不再渲染“打开抓大鹅设置”，顶部仍显示关卡名和倒计时，底部槽位和道具按钮 class 中不含旧白底视觉；相关测试通过后保持该口径。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-25 平台首页推荐按桌面与移动断点分流

- 背景：平台首页的推荐页在桌面与移动端之间原先共用同一套推荐运行态逻辑，容易让桌面和移动两套内容同时启动，也让首页的推荐卡与桌面发现壳互相抢状态。
- 决策：`RpgEntryHomeView` 只接受同一个 `isDesktopLayout` 断点判断；桌面端首页渲染桌面发现壳（`今日游戏`、`推荐`、`作品分类` 等），不挂移动推荐嵌入运行态；移动端 `home` 才渲染推荐卡与嵌入运行态。平台壳和首页视图都必须共用 `usePlatformDesktopLayout()`，不能在不同文件里各自判断断点。推荐嵌入运行态不是登录门禁：未登录可直达匿名运行态；已登录或已有 access token 时继续使用账号 Bearer，但必须用 local auth impact 防止推荐卡 401 清空全局登录态。
- 影响范围：`src/components/platform-entry/platformEntryResponsive.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、首页推荐相关测试与 `docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
- 验证方式：桌面宽度下首页应只看到桌面发现壳，窄屏下首页应只看到移动推荐流；`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "recommend"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation"`、`npm run typecheck`、`npm run check:encoding` 通过。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-25 新增玩法接入必须使用统一 SOP skill

- 背景：敲木鱼、跳一跳、汪汪声浪等玩法接入过程中，作品架曾经没有被作为强制闭环验收项，导致玩法可以先完成创作、发布、运行态或广场，但用户在草稿 / 已发布作品架中看不到自己的作品。
- 决策：凡是新增、补齐、迁移或重构玩法入口、玩法类型、创作工作台、生成页、结果页、发布、运行态、作品架、广场或公开 read model 的任务，开始前必须显式读取并按 `.codex/skills/genarrative-play-type-integration/SKILL.md` 执行。需要发布或试玩的玩法，作品架不是可选项，必须补齐私有 `/works` 列表、作品摘要、pending shelf 兜底、统一作品架 adapter、打开详情 / 草稿恢复、已发布分享入口和草稿 / 已发布可见性测试。
- 影响范围：`AGENTS.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、玩法 PRD、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、新增玩法前后端接入流程。
- 验证方式：玩法接入 PRD 和实现验收必须列出作品架链路；若一个玩法具备发布或试玩能力，但缺少 `/api/creation/<play>/works`、前端 client `listWorks`、`CustomWorldCreationHub` props、`creationWorkShelf` adapter 或草稿 / 已发布作品架测试，则接入不算完成。
- 关联文档：`AGENTS.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-26 统一公开作品主读模型收口

- 背景：各玩法原有 `*_gallery_card_view` / `*_gallery_view` / `custom_world_gallery_entry` 已经足够承载各自 source 投影，但公开列表 / 详情在 `api-server` 侧分散拼装会继续放大重复逻辑和契约漂移。
- 决策：新增跨玩法统一公开主读模型 `public_work_gallery_entry` 与 `public_work_detail_entry`。各玩法旧公开 view 不删除，退为 source / 兼容路径；`api-server` 公开列表与详情主路径统一读 public view cache，再映射回现有 HTTP DTO。前端首期仍不直接订阅 SpacetimeDB，只走 BFF HTTP。
- 影响范围：`server-rs/crates/spacetime-module`、`server-rs/crates/spacetime-client`、`server-rs/crates/api-server`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md`。
- 验证方式：`SELECT * FROM public_work_gallery_entry` 与 `SELECT * FROM public_work_detail_entry` 可作为 `api-server` 长期订阅目标；`/api/public-works` 与 `/api/public-works/{publicWorkCode}` 走统一 cache；旧 `/api/runtime/<play>/gallery` 响应 shape 保持兼容。
- 关联文档：`docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-05-26 推荐页拼图下一关 pending 时保留当前运行态

- 背景：推荐页嵌入拼图在点击“下一关”时，`advancePuzzleNextLevel` 的服务端请求会短暂处于 pending。旧逻辑把推荐卡的 `isStartingRecommendEntry` 和拼图局部 busy 混在一起，导致外层直接切回“加载中...”，把当前 `PuzzleRuntimeShell` 一起卸载，视觉上像是切关闪回。
- 决策：推荐页嵌入拼图切关 pending 期间必须保留当前运行态与棋盘，只让拼图壳内部 busy 表现承接同步；`isStartingRecommendEntry` 只表示推荐作品尚未真正启动出来，不再把已有嵌入拼图 run 的局部 busy 一并当成整卡加载态。若下一关落到相似作品，前端还必须把新作品写回推荐缓存并同步 `activeRecommendEntryKey`，避免运行态进入新作品但推荐卡元信息、分享 / 点赞 / 改造和后续“下一个”仍锚定旧作品。
- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、推荐页拼图切关测试与平台链路文档。
- 验证方式：点击推荐页拼图“下一关”后，在 `advancePuzzleNextLevel` 未返回前，页面仍应保留 `puzzle-board`，且不出现 `加载中...` 占位；返回相似作品后，当前推荐卡的 `作品信息` 应显示新作品标题。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-24 创作入口页 banner 曾固定主题赛

- 背景：点击底部加号进入的创作入口页 banner 曾经把后端入口配置里的默认活动横幅和两个主题赛一起轮播，导致出现 58000 奖池活动卡，和当时只强调拼图 / 抓大鹅主题赛的产品口径不一致。
- 决策：当时固定只展示 `拼图主题创作赛` 与 `抓大鹅主题创作赛` 两张主题卡；该口径已被 2026-06-02 的后台 `eventBanners` 配置决策替代。banner 底部顺序固定为开始 / 结束时间条在上、分页点在下，且二者都在封面内容底部。
- 影响范围：`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、`src/components/custom-world-home/CustomWorldCreationHub.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
- 验证方式：`CustomWorldCreationHub.test.tsx` 应断言默认活动标题不出现在 start-only 创作页，且 `creation-event-banner__timebar` 位于 `creation-event-banner__pager` 前。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-24 创作 Tab 首屏字号收敛到普通 UI 档位

- 背景：创作 Tab 的右上角泥点胶囊、赛事 banner、分类 Tab 和玩法卡标题 / 副标题 / 消耗说明曾经偏向展示级字号，和其它页面的常规 UI 字号不一致。
- 决策：创作首屏优先使用 `11px` 到 `14px` 的普通 UI 字号档位；仅在数字本体或强调值上做局部加粗，不使用 `text-lg`、`text-xl` 或更大的展示级字号来撑首屏。
- 影响范围：`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、创作 Tab 相关测试、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
- 验证方式：`CustomWorldCreationHub.test.tsx` 的字号快照测试和本地浏览器检查都应确认右上组件、banner、分类 Tab、模板卡标题 / 副标题 / 消耗说明没有回到大字号。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-24 草稿页未读点统一使用暖棕色

- 背景：草稿页底部 Tab 和作品架的未读点之前仍用固定红色和红色 glow，和平台暖白/陶土橙体系不一致，也会让草稿未读态显得像危险告警。
- 决策：`platform-nav-unread-dot` 与 `creation-work-card__unread-dot` 统一改用平台暖棕色 token，并把 glow 也切到暖棕色，不再直接写红色 literal 或红色阴影。
- 影响范围：`src/index.css`、草稿页底部导航、草稿页作品架、相关 CSS 回归测试。
- 验证方式：`src/index.test.ts` 需要断言两个 unread dot block 都不再包含 `#b64a35` 或 `rgba(239, 68, 68, ...)`，并且仍引用 `--platform-unread-dot-fill` / `--platform-unread-dot-glow`。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-24 创作 Tab 模板卡点击直达已有玩法入口表单

- 背景：创作 Tab 首屏需要对齐参考图，展示赛事 banner、玩法模板分类和两列模板卡；点击模板卡时，空白入口页会让用户多走一层，占位感也会让人误以为功能未接好。
- 决策：`/creation/<play>` 直达对应玩法已有的入口创作表单 stage，不再保留空白创作入口页。RPG、拼图、抓大鹅、汪汪声浪、敲木鱼、视觉小说、宝贝识物等都直接进入既有工作台，继续承接草稿恢复和后续编排。点击底部加号进入的创作入口页 banner 按参考图拆成右上泥点胶囊、主体宣传封面图文、底部开始/结束时间条和分页点；玩法模板卡使用独立 `creation-template-card` 白底信息区，不复用暗图蒙版 `platform-creation-reference-card`，确保标题、描述和“预计消耗 10-20 泥点”可见。
- 影响范围：`src/components/platform-entry/platformEntryTypes.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、创作大厅交互测试与平台入口文档。
- 验证方式：`npm test -- src/routing/appPageRoutes.test.ts`、`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t \"create tab opens match3d entry form from the template card|create tab opens puzzle entry form from the template card|create tab opens bark battle entry form from the template card\"`、`npm run typecheck`、`npm run check:encoding` 通过；创作卡片点击后应进入对应工作台，不再出现空白入口页。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-24 创作 Tab 顶栏余额与赛事奖池分离展示

- 背景：创作页顶部、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`。

## 2026-05-24 发现 / 创作 / 草稿三页去掉外层全局卡片壳

- 背景：发现 Tab、创作 Tab 和草稿 Tab 的页面根区原本都套着 `platform-page-stage`，导致全局内容卡片壳把横向空间吃掉，也让创作页和草稿页与发现页的频道标签 / 列表卡风格拉不开。
- 决策：这三页的根内容区不再使用 `platform-page-stage` 作为外层全局卡片壳，只保留 `platform-remap-surface` 作为主题与输入框样式钩子；草稿页顶部 `全部 / 草稿 / 已发布` 切换复用发现页的 `platform-mobile-home-channel` 频道标签样式。
- 影响范围：`src/components/custom-world-home/CustomWorldCreationHub.tsx`、`src/components/custom-world-home/CustomWorldWorkTabs.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/index.css`、相关创作 / 发现 / 草稿测试。
- 验证方式：创作 Hub 和发现页定向测试通过；浏览器里这三页的根区不再出现 `platform-page-stage`，但仍保留 `platform-remap-surface` 命中。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-23 拼图生成页按后端真实进度推进阶段

- 背景：拼图生成页原先会按本地耗时自动推进步骤，容易在后端真实生成尚未完成时跳到后续阶段，导致页面状态和会话进度脱节。
- 决策：拼图生成页的跨步骤推进只认后端会话 `progressPercent` 的真实里程碑，当前步骤内部再用本地耗时假进度平滑展示；`88/94/96` 只切换当前步骤，不直接作为总进度地板。总进度按已完成步骤权重加当前步骤内假进度推导，非完成态最多停在 `98%`。恢复持久化生成中草稿时，展示态 `startedAtMs` 使用后端 session `updatedAt` 或作品摘要 `updatedAt`，保证已耗时不因重新进入页面清零。只要当前步骤生成内容未完成，就必须停留在当前步骤。页面只展示当前步骤标题和进度，不展示步骤详细描述。`生成拼图首图` 单独按 4 分钟估算，完整 AI 重绘路径约 448 秒；上传图且关闭 AI 重绘路径跳过首图生成，仍约 208 秒。
- 影响范围：`src/services/miniGameDraftGenerationProgress.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/CustomWorldGenerationView.tsx`、拼图生成页相关测试与玩法链路文档。
- 验证方式：拼图生成页恢复、轮询和测试都应以 `puzzleProgressPercent` 驱动阶段推进；`npm run test -- src/services/miniGameDraftGenerationProgress.test.ts src/components/CustomWorldGenerationView.test.tsx`、`npm run typecheck`、`npm run check:encoding` 通过。
- 关联文档：`docs/【玩法创作】拼图生成页进度口径-2026-05-23.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-06-02 生成失败草稿必须留在作品架并覆盖生成中摘要

- 背景：生成页收到失败回包后会进入重试态，但返回草稿 Tab 时，后端作品摘要可能仍短暂保持 `generationStatus=generating`，导致用户看到“生成中”；连续触发多个拼图生成时，失败后如果清掉 pending 条目，还会少显示新增草稿。后台失败如果只写局部生成页错误，用户离开生成页后也收不到通知。
- 决策：平台壳在生成失败时必须同时标记草稿 notice 和 pending 作品架条目为 `failed`，不得删除 pending 条目。失败 notice 要保存错误消息并在用户离开生成页后触发带来源的 `PlatformErrorDialog`；作品架本地失败 notice 要覆盖持久化生成中摘要，失败草稿仍显示为草稿卡但不显示“生成中”。点击失败草稿必须优先恢复失败 / 重试页，不能按持久化 `generating` 重新启动生成；拼图契约已允许 `generationStatus=failed`，pending 拼图和后端失败回写都按 session 独立落失败态，跳一跳 / 木鱼 / 抓大鹅等也直接映射为 `failed` 或对应失败态。
- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/custom-world-home/creationWorkShelf.ts`、`src/components/custom-world-home/CustomWorldCreationHub.tsx`、玩法链路文档和失败态交互测试。
- 验证方式：`node node_modules/vitest/vitest.mjs run src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "failed parallel puzzle|background match3d"`；失败后返回草稿 Tab 应看到对应新增草稿，且没有“生成中”标记；后台失败应弹出错误来源，点击失败草稿应进入失败 / 重试页。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/project-memory/shared-memory/pitfalls.md`。

## 2026-05-23 所有玩法生成页统一圆环主视觉

- 背景：多个玩法生成页分别展示横向总进度条、步骤列表或三槽位列表，和最新参考图里的陶泥儿圆环等待态不一致，也让移动端信息密度偏高。
- 决策：`media/create_bg_video.mp4` 作为固定全屏背景层循环静音播放，主进度统一改为居中大圆弧，正下方保留 90 度留空；生成页顶部只保留返回入口和状态胶囊，圆弧左右悬浮半透明“预计等待 / 已耗时”时间卡，下方保留半透明当前步骤单卡和当前作品信息卡。生成页不再列表展示每个步骤块，只显示当前步骤名称和当前步骤进度；圆弧和当前步骤卡不再被独立大面板嵌套出双层卡片感。视频层需要显式触发播放，不能只依赖 `autoPlay/loop/muted`。顶部返回使用 `text-xs-sm`，右上状态使用 `11px-12px`，时间卡标签使用 `9px-10px`，时间值只展示纯时间，不重复拼“预计还需 / 已耗时”前缀；当前步骤标签使用 `10px-11px`，步骤名使用 `14px-15px`，步骤状态使用 `11px-12px`，底部玩法信息标题固定使用 `13px`，避免生成页 UI 字号大于其它页面。`CustomWorldGenerationView` 承接 RPG、拼图、抓大鹅、大鱼吃小鱼、方洞、跳一跳、敲木鱼、宝贝识物、视觉小说等共用生成页；汪汪声浪独立 `BarkBattleGeneratingView` 也对齐同一垂直布局。
- 影响范围：`src/components/GenerationProgressHero.tsx`、`src/components/CustomWorldGenerationView.tsx`、`src/components/bark-battle-creation/BarkBattleGeneratingView.tsx` 和玩法链路文档。
- 验证方式：执行 `npm run test -- src/components/CustomWorldGenerationView.test.tsx src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx`，并用桌面 / 移动端视口检查生成页只出现圆环和当前步骤卡。
- 关联文档：`docs/【玩法创作】生成页圆环布局口径-2026-05-23.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-23 寓教于乐玩法入口收敛为马路街区式横向延展

- 背景：参考图和视频表明，寓教于乐板块的图形化入口更接近 Toca Life World 式的“中央马路串联主题小建筑群街区”，而不是乐园分区、环形岛屿或世界球体结构。
- 决策：后续寓教于乐入口概念图统一采用“横屏 16:9、中央灰蓝色马路贯穿、建筑群沿路两侧聚集、左右边缘持续出画可接下一屏”的结构；马路必须带车道线、斑马线、路口和小汽车，区域通过水果店、画笔工坊、运动馆、音乐剧场、树屋温室等主题小建筑群暗示，不再使用乐园式分区组织。
- 影响范围：寓教于乐入口概念图、image2 prompt 生成脚本、设计文档、后续横向世界地图探索稿。
- 验证方式：新生成概念图必须满足“马路是主脊线、建筑群成街区聚合、左右边缘可延展、无品牌乐园元素”四项约束；若图面再跑回环形乐园或漂浮岛，需要重新收敛 prompt。
- 关联文档：`docs/design/【前端体验】寓教于乐Toca式横向世界地图入口概念图-2026-05-23.md`、`scripts/generate-edutainment-road-town-map-concepts.mjs`、`output/imagegen/edutainment-road-town-map-concepts-20260523/`。

## 2026-05-22 敲木鱼图片创作采用三图 image2 链路

- 背景：敲木鱼自定义题材只生成中央敲击物时，运行态缺少与新主题匹配的竖屏背景和主题化返回按钮；若直接让背景 prompt 自由发挥，又容易把敲击物或木槌画进背景里。
- 决策：敲木鱼 `compile-draft` / `regenerate-hit-object` 图片链路固定为三步 image2 edits。第一步调用 VectorEngine `/v1/images/edits` + `gpt-image-2`，以默认木鱼图作为结构和画风参考，用户上传参考图只作为同次请求的新主题参考，结合用户题材关键词或参考图主题生成 `1:1` 绿色背景主体图；`api-server` 先对这张绿幕图执行去绿背景处理并写回 `hitObjectAsset`。第二步必须以第一步抠图完成后的透明敲击物图作为参考，结合用户原始题材生成 `9:16` 背景环境图并写回 `backgroundAsset`，避免背景图继承绿幕或纯绿色画布。第三步必须以去绿后的敲击物主体图和背景环境图为参考，生成 `1:1` 绿色背景返回按钮图，服务端去绿后写回 `backButtonAsset`。三步 prompt 使用 PRD 中固定隐藏关键词，不追加额外 negative prompt；返回按钮只允许参考图约束圆形底色和箭头配色，不允许继承复杂造型、花纹、浮雕边、异形外框或装饰图案，主体视觉尺寸比当前模板再放大约 50%，并带主题色外描边；背景图不得包含敲击物本体或木槌互动物品，返回按钮图不得包含文字、数字、水印或额外 UI 面板。
- 影响范围：`api-server` 木鱼图片生成编排、`wooden_fish_work_profile.background_asset_json`、`wooden_fish_work_profile.back_button_asset_json`、shared contracts、前端结果页 / 运行态背景与返回按钮展示、敲木鱼 PRD 和平台链路文档。
- 验证方式：执行 `cargo test -p api-server wooden_fish --manifest-path server-rs/Cargo.toml`、`cargo test -p spacetime-client wooden_fish --manifest-path server-rs/Cargo.toml`、`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run typecheck`。
- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-25 通用系列素材图集实现下沉到 platform-image

- 背景：`generated_asset_sheets` 同时承载 sheet prompt、切图、绿幕去背、边缘 matte 清理和 OSS 持久化准备，长期放在 `api-server` 会把多个玩法的图片 seam 继续绑死在 HTTP crate 上。
- 决策：通用系列素材图集的实现真值源下沉到 `platform-image::generated_asset_sheets`，`api-server::generated_asset_sheets` 只保留 `AppState` / `AppError` 适配与调用方兼容导出，不再承载图像处理和 OSS 请求构造细节。
- 影响范围：`server-rs/crates/platform-image/src/generated_asset_sheets/`、`server-rs/crates/api-server/src/generated_asset_sheets.rs`、`server-rs/crates/api-server/src/match3d/item_assets.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
- 验证方式：`cargo test -p platform-image --test generated_asset_sheets --manifest-path server-rs/Cargo.toml` 与 `cargo check -p api-server --manifest-path server-rs/Cargo.toml` 通过；调用方继续通过 `api-server` 的薄包装访问同一组能力。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-22 敲木鱼敲击物暂不做服务端抠图后处理

- 背景：gpt-image-2 偶尔会把木鱼图直接回成带黑底或其它实底背景的 PNG，但服务端抠图后处理在玉米等主题上误伤过主体像素。
- 决策：敲木鱼 hit object 落盘前暂不做服务端抠图后处理，当前只通过 prompt 强约束真实透明 alpha PNG、透明底、禁止黑底 / 白底 / 棋盘格 / 实底背景。后续若重启后处理，必须先有可验证的保守策略，只能清理画布边缘连通背景，不能抠掉主体内部深色结构或主题细节。
- 影响范围：`server-rs/crates/api-server/src/wooden_fish.rs`、敲木鱼 PRD、平台链路文档、后续同类 image2 单图资产落盘策略。
- 验证方式：`cargo test -p api-server wooden_fish --manifest-path server-rs/Cargo.toml`，并在试玩阶段确认主体像素未被后处理误删。
- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-22 敲木鱼背景中央禁主体要写成硬约束

- 背景：苹果等主题在试玩时，背景图中央仍可能残留主题主体，说明“外围设计”这种软描述不够。
- 决策：敲木鱼背景 prompt 必须显式要求中央主体预留区保持干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子、重复元素或主题主体碎片；主题元素只允许出现在外围氛围。
- 影响范围：`server-rs/crates/api-server/src/wooden_fish.rs`、敲木鱼 PRD、平台链路文档、后续 image2 背景类玩法 prompt。
- 验证方式：背景 prompt 单测应包含中央禁区硬约束，试玩图中央不再出现苹果或其它主题主体。
- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-27 敲木鱼背景 prompt 不再写中央木鱼预设

- 背景：背景 prompt 曾写入“木鱼预设在屏幕中央位置”，与“背景图中不包含新木鱼物品”“中央 40% 禁止出现主题主体”直接冲突，导致 image2 偶发把静态木鱼画回背景中心。
- 决策：背景 prompt 只能写“中央主体预留区”“运行态叠放敲击物的留白区域”“只生成背景环境图”，不得再出现“木鱼预设在屏幕中央位置”或任何等价的中心主体正向描述。
- 影响范围：`server-rs/crates/api-server/src/wooden_fish.rs`、敲木鱼 PRD、平台链路文档、背景 prompt 单测。
- 验证方式：`wooden_fish_background_prompt_uses_hidden_image2_flow` 必须断言旧冲突句子不存在，并断言新的中央留白表述存在。
- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-21 外部 API 失败必须 OTLP 上报并落库

- 背景：图片生成等外部供应商调用失败时，仅返回 502/504 或普通日志无法支持后续按 provider、阶段和重试属性聚合排障。
- 决策：外部 API 调用未成功时，`api-server` 必须同时发送 OTLP 失败观测并写入 `tracking_event`。当前通用 VectorEngine `gpt-image-2` 图片生成 / 编辑适配器记录 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`，metadata 包含 endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel 和 rawExcerpt。
- 落库方式：优先复用 tracking outbox 异步批量写入；outbox 不可写或因保护阈值拒绝时回退同步直写 SpacetimeDB。不新增 SpacetimeDB 表，不让 reducer 做外部 I/O。
- 影响范围：`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`server-rs/crates/api-server/src/telemetry.rs`、tracking outbox、后端架构文档和开发运维文档。
- 验证方式：执行 `cargo test -p api-server external_api_audit --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-05-25 VectorEngine 图片 provider 收到 platform-image

- 背景：`api-server` 里原本同时混着 VectorEngine 创建 / 编辑协议、响应解析、远端图片下载、失败日志和审计落库逻辑，Puzzle / Match3D 还各自藏着一份近似实现，导致“provider 协议”和“业务编排”边界不清。
- 决策：把 VectorEngine `gpt-image-2` 图片 provider 协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志统一收口到 `server-rs/crates/platform-image/src/vector_engine/`，并按 `client.rs`、`transport.rs`、`request.rs`、`payload.rs`、`response.rs`、`image_source.rs` 等小模块拆分，避免把大文件从 `api-server` 平移到平台 crate。`api-server` 只保留配置校验、玩法 prompt 编排、OSS / asset object / binding 持久化、计费和外部 API 失败审计桥接；旧 `openai_image_generation.rs` 只作为兼容转接层，不再承担 provider 实现。
- 影响范围：`server-rs/crates/platform-image`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`、`server-rs/crates/api-server/src/external_api_audit.rs`、后端架构与运维文档。
- 验证方式：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-image --test vector_engine --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-05-26 音频 provider 协议收口到 platform-audio，Hyper3D 继续保持薄代理

- 背景：`api-server/src/vector_engine_audio_generation.rs` 和 `api-server/src/hyper3d_generation.rs` 仍然承担太多 provider 细节，容易把外部协议、下载、解析和 BFF 编排混在一起。
- 决策：VectorEngine Suno/Vidu 音频协议、任务提交/轮询、下载和 OSS 持久化请求准备收口到 `platform-audio`，并继续按 `client.rs`、`request.rs`、`response.rs`、`download.rs`、`persist.rs`、`error.rs` 拆小模块；`api-server` 只保留路由、配置、计费、asset_object confirm、entity binding 和错误映射。Hyper3D 维持后端安全代理和旧数据兼容，`platform-hyper3d` 承接 Rodin 的协议与解析，`api-server` 仅做薄 wrapper。
- 影响范围：`server-rs/crates/platform-audio/`、`server-rs/crates/platform-hyper3d/`、`server-rs/crates/api-server/src/vector_engine_audio_generation.rs`、`server-rs/crates/api-server/src/hyper3d_generation.rs`、相关后端架构文档。
- 验证方式：`cargo test -p platform-audio --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-hyper3d --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 通过；`api-server` 不再包含音频 provider 协议和 Hyper3D parser 主实现。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【后端架构】复杂媒体资产链路Adapter扩展计划-2026-05-14.md`。

## 2026-05-21 拼图参考图主链改为 OSS assetObjectId 与只读签名 URL

- 背景：release 上拼图图生图生成草稿时，旧链路把上传图转成 Data URL/base64 放进创作 action JSON body，容易先触发 Nginx `413 Request Entity Too Large`，也让外部模型调用前的 HTTP body 过大。
- 决策：浏览器参考图先通过资产直传票据上传 OSS，并确认 `asset_object`；拼图 action 主链只提交 `referenceImageAssetObjectId(s)`。`api-server` 按当前登录用户校验 asset owner、bucket、kind、图片 MIME 和大小后签发 OSS 只读 URL，传给 VectorEngine 的 generation fallback 使用；需要 edits multipart 时由后端用该签名 URL 拉取字节，不再让前端把图片塞进 JSON body。
- 兼容边界：旧 `referenceImageSrc(s)` Data URL 与历史 `/generated-*` 路径仅保留给旧草稿、旧入口和迁移期请求；调大 Nginx `client_max_body_size` 只作为兼容兜底，不是长期创作主链。
- 影响范围：拼图创作前端、`packages/shared` / `shared-contracts` action DTO、`api-server` 拼图 VectorEngine 编排、资产确认和 `spacetime-client` 资产读取 facade。
- 验证方式：前端 payload 中 AI 重绘优先出现 `referenceImageAssetObjectId(s)` 且 `referenceImageSrc(s)` 不再携带 Data URL；后端 `puzzle_vector_engine_generation_prefers_signed_reference_url`、`puzzle_reference_image_sources_prefer_asset_object_ids`、`puzzle_asset_object_reference_requires_matching_owner` 通过。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-05-21 Nginx 通用 API 入口放行创作参考图请求体

- 背景：release 上拼图结果页重绘动作携带参考图 Data URL 时，Nginx access log 出现 `413`、`request_time=0.000`、`upstream_status=-`，说明请求被反代层默认 1 MiB 上限拦截，未进入 `api-server`。
- 决策：发布、开发服和容器 Nginx 模板的通用 `location ~ ^/api(?:/|$)` 统一设置 `client_max_body_size 64m`。该值只作为反代放行和旧 Data URL 请求兼容兜底，具体业务请求体和图片字节上限继续由 `api-server` 路由 `DefaultBodyLimit`、OSS asset 确认和业务校验控制，不能替代接口级限制；拼图参考图长期主链见同日 `OSS assetObjectId` 决策。
- 影响范围：`deploy/nginx/genarrative.conf`、`deploy/nginx/genarrative-dev-http.conf`、`deploy/container/nginx.conf`、Nginx README、生产运维文档和 release 排障口径。
- 验证方式：目标机 `nginx -T 2>/dev/null | grep client_max_body_size` 应看到 `client_max_body_size 64m;`；大于 1 MiB 的参考图请求不再在 Nginx 层直接 413，access log 应出现有效 `upstream_status`。
- 关联文档：`deploy/nginx/README.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-05-24 跳一跳推荐页允许未登录直达运行态并记录匿名游玩埋点

- 背景：推荐页的跳一跳作品在未登录时曾被前端登录门禁拦住，导致公开推荐流无法直接游玩；同时游玩埋点如果只接受登录态 userId，会让匿名启动和匿名重开被静默丢失。
- 决策：跳一跳推荐页的运行态启动、跳跃和重开路由统一使用可选鉴权；未登录时仍允许进入运行态，并把 `work_play_start` 以匿名语义记录下来，而不是伪造用户身份或直接跳过埋点。
- 影响范围：`api-server` 跳一跳 runtime 路由、`work_play_tracking`、推荐页进入运行态逻辑、匿名推荐试玩测试、平台入口 / 玩法链路文档。
- 验证：登录态和未登录态都能从推荐页进入运行态；`work_play_start` 事件在匿名时仍产生，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`。

## 2026-05-22 抓大鹅素材生成改为关卡整图派生三图

- 背景：旧抓大鹅素材链路按物品 5x5 sheet、纯背景和独立容器图分开生产，难以保证背景、UI、容器和物品风格一致，也让结果页继续暴露背景 / 容器重生成入口。
- 决策：抓大鹅草稿生成先用 `gpt-image-2` 无参考图生成竖屏 `9:16` 完整关卡画面；关卡画面完成后，以它作为参考并发生成三张可运行资产：`1K 1:1` UI spritesheet、`1K 9:16` 关卡背景图、`2K 1:1` 物品 spritesheet。UI 与物品 spritesheet 都固定要求纯绿色绿幕背景，后端上传 OSS 前扣成真实透明 PNG。物品 spritesheet 固定 `10*10`，每行两种物品、每种五个形态。运行态和编辑器都按 alpha 连通域矩形检测解析 UI 和物品图集，不按固定像素坐标切图。
- 兼容：新增字段继续存入现有 `generatedItemAssets[].backgroundAsset` / `generatedBackgroundAsset` JSON，不新增 SpacetimeDB schema 字段。历史 `containerImage*` 字段只作兼容；如果它与 `uiSpritesheetImage*` 同源，不得再作为运行态中心容器图。
- 影响范围：`server-rs/crates/api-server/src/match3d/*`、`server-rs/crates/shared-contracts/src/match3d_*`、`packages/shared/src/contracts/match3dWorks.ts`、`src/components/match3d-result/Match3DResultView.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`src/services/match3dSpritesheetParser.ts`。
- 验证方式：执行 `cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml`、`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx src/components/match3d-runtime/Match3DRuntimeShell.test.tsx src/services/match3dSpritesheetParser.test.ts src/services/match3dGeneratedModelCache.test.ts`、`npm run typecheck`、`npm run check:encoding`。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-18 Rust 手写模块入口统一不用 mod.rs

- 背景：Rust 目录模块同时存在 `mod.rs` 与同名 `.rs` 两种入口形式，前次拆分已让 `spacetime-client/src/mapper.rs` 采用同名入口；继续新增 `mod.rs` 会让文件定位和评审口径不一致。
- 决策：手写 Rust 模块统一使用同名入口文件，例如 `puzzle.rs`、`match3d.rs`、`gameplay.rs`，子模块继续放在同名目录下；不要再为手写模块新增 `mod.rs`。SpacetimeDB CLI 生成的 bindings 也由生成脚本同步为 `module_bindings.rs` 加 `module_bindings/` 子目录，避免仓库里继续出现 `mod.rs`。
- 边界：本决策只规范文件布局，不改变 module path、HTTP route、DTO、SpacetimeDB schema、生成绑定内容或运行时行为。
- 影响范围：`server-rs/crates/api-server/src/`、`server-rs/crates/spacetime-module/src/`、`server-rs/crates/spacetime-client/src/module_bindings.rs`、`scripts/generate-spacetime-bindings.mjs`。
- 验证方式：执行 `Get-ChildItem server-rs -Recurse -Filter mod.rs` 应无结果；再执行对应 `cargo check` / 定向测试 / 编码检查。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-05-18 大文件拆分继续按聚合入口加领域子模块推进

- 背景：完成拼图 `api-server` 拆分后，`match3d.rs`、`spacetime-client/src/mapper.rs` 与 `PlatformEntryFlowShellImpl.tsx` 仍是后续迭代和评审的高噪音大文件。
- 决策：抓大鹅 Match3D 的 `api-server` 单文件改为同名入口 `src/match3d.rs` 加 `src/match3d/` 子模块目录，`handlers.rs`、`draft.rs`、`works.rs`、`item_assets.rs`、`runtime.rs`、`vector_engine_gemini.rs`、`mappers.rs`、`tags.rs`、`tests.rs` 分担原实现；`spacetime-client/src/mapper.rs` 改为聚合入口，具体 mapper 按领域落到 `src/mapper/*.rs`；平台入口继续以 `PlatformEntryFlowShellImpl.tsx` 为编排壳，独立 UI 片段优先拆到 `PlatformEntryFlowShellImpl/` 子目录，本次已抽出 `PuzzleOnboardingView.tsx`。
- 边界：这些拆分只改变文件组织，不改变 HTTP route、DTO、error envelope、SpacetimeDB schema、生成绑定、procedure result、入口配置事实源、前端行为、VectorEngine / OSS 副作用或计费语义。后续要下沉领域规则时另行讨论并更新设计。
- 影响范围：`server-rs/crates/api-server/src/match3d/`、`server-rs/crates/spacetime-client/src/mapper/`、`src/components/platform-entry/PlatformEntryFlowShellImpl/`、后端架构文档和玩法链路文档。
- 验证方式：执行 `cargo check -p api-server --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server match3d --manifest-path server-rs\Cargo.toml --no-run`、`cargo check -p spacetime-client --manifest-path server-rs\Cargo.toml`、前端 typecheck 或定向 tsc、`git diff --check` 与 `npm run check:encoding`。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-18 api-server 拼图能力按 HTTP/BFF 子模块拆分

- 背景：`server-rs/crates/api-server/src/puzzle.rs` 已膨胀为数千行大文件，混合 Axum handler、草稿编译、图片生成、VectorEngine / OSS 持久化、DTO mapper、标签生成和测试；继续在单文件内迭代会降低定位和评审效率。
- 决策：原超大 `puzzle.rs` 改为同名入口 `server-rs/crates/api-server/src/puzzle.rs` 加 `server-rs/crates/api-server/src/puzzle/` 子模块目录。`puzzle.rs` 只保留聚合入口和 handler re-export；`handlers.rs` 放 HTTP handler；`draft.rs` 放表单草稿 / 编译 / snapshot helper；`generation.rs` 放图片与 UI 背景生成编排；`vector_engine.rs` 放 VectorEngine、下载、OSS、asset object / binding 和错误归一；`mappers.rs` / `tags.rs` 保留映射和标签 / 错误 helper；`tests.rs` 承接原 puzzle 单测。
- 2026-05-21 追加决策：拼图 HTTP/BFF handler 不再直接提取完整 `AppState`，统一通过 `PuzzleApiState` 暴露拼图能力需要的 SpacetimeDB facade、gallery cache、OSS、作者查询、LLM 和少量配置快照。`modules/puzzle.rs` 仍接收全局 `AppState` 以挂接鉴权和回到全局路由树，但内部路由先 `.with_state(PuzzleApiState::from_ref(&state))`，handler 使用 `State<PuzzleApiState>`。确需复用计费、外部失败审计等仍要求 `AppState` 的横切 helper 时，先经 `PuzzleApiState::root_state()` 显式过渡，后续再继续收窄。
- 边界：本次只改变 `api-server` 内部文件组织，不改变 `/api/runtime/puzzle/*` 路由、DTO、error envelope、SpacetimeDB schema、公开 gallery cache 语义或计费语义。领域规则后续仍应逐步沉到 `module-puzzle`，SpacetimeDB 表、reducer、procedure 和 row shape 仍留在 `spacetime-module`。
- 影响范围：`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/api-server/src/puzzle/`、`server-rs/crates/api-server/src/modules/puzzle.rs` 的 handler 引用、后端架构文档。
- 验证方式：执行 `cargo check -p api-server --manifest-path server-rs\Cargo.toml`；后续若改动 puzzle API 行为，再按对应路由补充定向测试和 `npm run dev:api-server` `/healthz` smoke。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-05-18 Windows Jenkins PowerShell 统一改为显式 powershell.exe 启动

- 后续更新：该决策仅适用于历史 Windows Jenkins 节点；当前 `Genarrative-Stdb-Module-Build` 已改为 Linux agent，实际执行路径不再依赖该口径。
- 背景：`Genarrative-Stdb-Module-Build` 在 Windows Jenkins 本地环境里调用裸 `powershell` step 时触发 `CreateProcess error=5, 拒绝访问`，而 `powershell.exe` 本体与 workspace ACL 都正常。
- 决策：Windows Jenkins 上凡是需要执行 PowerShell 逻辑的流水线，优先通过 `bat` 显式调用 `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File ...`，不要再依赖 Jenkins `powershell` step 的隐式启动器。
- 追加决策：`Genarrative-Stdb-Module-Build` 的 Checkout 逻辑应复用 Jenkins GitSCM 已完成的工作区状态。`COMMIT_HASH` 为空或已与当前 `HEAD` 一致时，不再额外执行 `git clean` / `git checkout`；只有需要切到指定且不同的 commit 时才补 fetch、校验和切换，避免在 Windows workspace 里二次清理触发权限拒绝。
- 影响范围：`jenkins/Jenkinsfile.production-stdb-module-build` 及后续所有同类 Windows 构建流水线。
- 验证方式：Jenkins 日志中应能看到 `[jenkins-powershell] user:` 和 `[jenkins-powershell] exe:`，Checkout 阶段会打印当前 `HEAD` 与请求 commit，并在 `COMMIT_HASH` 为空或一致时直接继续；不再停在 `PipelineNodeTreeScanner... Cannot run program "powershell"` 或重复 `git clean` 的退出码 5。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/project-memory/shared-memory/pitfalls.md`。

## 2026-05-19 tracking outbox 改为 rotate 后异步 flush

- 背景：普通 route tracking 写入压力上来后，不能让 HTTP 请求线程等待 SpacetimeDB 批量入库。
- 决策：`api-server` tracking outbox 达到 `BATCH_SIZE` 时立即封存当前 active 文件并切新 active，sealed 文件交给后台 worker 异步 flush；`FLUSH_INTERVAL_MS` 只做长时间未满批的兜底封存；`MAX_BYTES` 只做磁盘保护阈值；成功后删除 sealed，失败保留重试，坏文件隔离为 `corrupt-*`。
- 影响范围：`api-server` tracking outbox、埋点文档、压测口径和后续排障记忆。
- 验证方式：HTTP route 请求在 SpacetimeDB 短暂不可用时仍可返回；恢复后 sealed 文件会被批量写入并清理。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-05-19 OTLP 默认开启但日志本地输出保留

- 背景：生产和容器环境需要默认把 OTLP 接到本机 Collector，但压测或排障时也要能显式关闭。
- 决策：生产与容器 `api-server` env 模板默认 `GENARRATIVE_OTEL_ENABLED=true`；生产 endpoint 用 `http://127.0.0.1:4318`，容器 endpoint 用 `http://otelcol:4318`；`OTEL_EXPORTER_OTLP_ENDPOINT` 只填 Collector HTTP base endpoint，不填 gRPC `4317` 或 Rider 端口；本地日志、Nginx 日志和 `GENARRATIVE_API_LOG` / `RUST_LOG` 仍保留。
- 影响范围：`deploy/env/api-server.env.example`、`deploy/container/api-server.env.example`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`scripts/loadtest/README.md`。
- 验证方式：检查 env 模板默认值与端点口径；压测若要关闭 OTLP，必须显式设置 `GENARRATIVE_OTEL_ENABLED=false`。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`scripts/run-otelcol.mjs`。

## 2026-05-19 容器 collector 可切 Grafana Cloud

- 背景：容器隔离压测时除了本地 debug exporter，还需要临时把 traces / metrics / logs 转发到 Grafana Cloud 做可视化验证。
- 决策：`deploy/container/docker-compose.loadtest.yml` 里的 `otelcol` 支持通过 `GENARRATIVE_CONTAINER_OTELCOL_CONFIG=./otelcol.grafana.yaml` 切换配置；`deploy/container/otelcol.grafana.yaml` 同时保留 debug exporter，并通过 `GRAFANA_CLOUD_OTLP_ENDPOINT` 和 `GRAFANA_CLOUD_BASIC_AUTH_HEADER` 转发到 Grafana Cloud。
- 影响范围：`deploy/container/docker-compose.loadtest.yml`、`deploy/container/otelcol.grafana.yaml`、`deploy/container/README.md`。
- 验证方式：容器 `otelcol` 启动日志应能看到 OTLP receiver ready，debug exporter 仍可输出本地链路；Grafana Cloud 转发凭据只通过当前 shell 环境变量传入，不写入 Git。
- 关联文档：`deploy/container/README.md`、`scripts/loadtest/README.md`。

## 2026-05-17 容器化方案只作为隔离压测与预发模拟路径

- 背景：Windows 本机直连极高 VU 压测会放大本地连接与发送缓冲行为，和线上 Linux + Nginx + systemd 拓扑不一致；需要一个更接近生产网络层的模拟方案，但不能扰动当前生产发布链路。
- 决策：新增 `deploy/container/` 容器化方案，使用 Docker Compose 组合 Linux release `api-server`、容器 SpacetimeDB、容器 Nginx、`otelcol-contrib` debug exporter 和可选 k6。该方案只用于本机或预发压测模拟，不替换当前生产 `systemd + Nginx + Jenkins` 路径。
- 服务器模拟参数：2026-05-18 通过 `ssh genarrative-release` 采样，目标机器为 2 vCPU / 约 2 GiB RAM / Ubuntu 24.04 / Nginx `worker_connections=768`；容器方案按待发布运行口径使用 `nofile=4096`，并在 compose 中限制 `spacetimedb cpus=1.0 mem_limit=896m`、`api-server cpus=2.0 mem_limit=1g`、`external-generation-worker cpus=2.0 mem_limit=1g`、`nginx cpus=0.5 mem_limit=128m`、`otelcol cpus=0.25 mem_limit=128m`、`k6 cpus=1.0 mem_limit=512m`；Collector 镜像默认使用 `otel/opentelemetry-collector-contrib:0.151.0`。
- 隔离边界：容器方案使用独立 `deploy/container/api-server.env`、独立 Nginx 配置、独立 compose 命令和默认 `18080` 端口；真实 token 不进入镜像、不提交 Git；生产 systemd 单元、Jenkins 发布脚本和 `deploy/nginx/` 模板仍是正式线上来源。
- 生产 Collector：server-provision 可安装 `otelcol-contrib.service` 和本机 debug exporter 配置，但二进制由 Jenkins 构建机先准备 `provision-tools/otelcol-contrib` 再上传到 release 部署 agent，目标机不从 GitHub 下载；api-server 是否发送 OTLP 仍由 `GENARRATIVE_OTEL_ENABLED` 控制。
- 影响范围：`deploy/container/`、`scripts/container-compose.mjs`、`package.json` 容器命令、开发运维文档和容器 build context 排除规则。
- 验证方式：执行 `npm run container:config` 展开 compose 配置；需要真实运行时再执行 `npm run container:build`、`npm run container:up`、`npm run container:k6`，并结合容器 Nginx log 与 OTLP debug exporter 判断瓶颈。
- 关联文档：`deploy/container/README.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-05-19 生产 provision 改为 Windows 下载包后由目标机本地安装

- 后续更新：该口径已被 `2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost` 取代；当前 `Genarrative-Server-Provision` 不再走 Windows 下载阶段，而是在 Linux build 节点直接准备 `provision-tools/`。
- 背景：当前 `development` provision 目标实际就是 Linux agent `genarrative-build-01`，之前把 `Prepare Provision Tools` 放在 `linux && genarrative-build` 会让目标机自己连 GitHub 和 `install.spacetimedb.com`，违背“Windows 本机先下载再传到目标机”的运维要求。
- 决策：`Genarrative-Server-Provision` 拆成 Windows 下载阶段和 Linux 目标机安装阶段。Windows 节点的 `Download Provision Tool Archives` 只下载 `spacetime-x86_64-unknown-linux-gnu.tar.gz` 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz`，通过 `stash/unstash` 传到目标 Linux 节点；目标机执行 `scripts/prepare-server-provision-tools.sh` 时设置 `PROVISION_REQUIRE_LOCAL_DOWNLOADS=true`，只消费已下载件生成 `provision-tools/`，缺包直接失败，不回退外网下载。
- 追加决策：Server-Provision 的 Windows helper 不再对 Jenkins `writeFile` 刚写出的 `.ps1` 做原地 UTF-8 BOM 重写，而是由显式 `powershell.exe` 按 UTF-8 读入脚本文本，并用 `ScriptBlock::Create(...)` 在内存中执行；这样既保留中文脚本内容，又避免同一个 workspace 脚本被立即重写时触发 `拒绝访问`。
- 追加决策：GitHub release asset 的可用校验信息使用 `digest` 字段，实际是 `sha256:...`，不是 MD5；Windows 下载阶段先查 digest，再决定是否复用已有文件。
- 影响范围：`jenkins/Jenkinsfile.production-server-provision`、`scripts/prepare-server-provision-tools.sh`、`scripts/jenkins-server-provision.sh`、生产运维文档。
- 验证方式：Jenkins 日志应先出现 Windows 节点的 `[jenkins-powershell] workspace:`、`[jenkins-powershell] loaded bytes:` 和 `[prepare-provision-downloads]` 下载日志，再在 `genarrative-build-01` 上出现“使用已下载的 ...”日志；目标机不应出现直接访问 `install.spacetimedb.com` 或 OpenTelemetry GitHub release 下载地址的回退日志，且不再需要 `spacetimedb-update-*` 作为离线交付包。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-05-19 公开 gallery 入口发布限流以快拒绝保护后端

- 背景：容器 2C / 2G 压测中，公开作品列表在约 5000 HTTP req/s 目标下可以保持 200 请求低延迟，但 SpacetimeDB 内存会随 api-server 重连和高压请求累积到容器上限附近。
- 决策：发布配置采用公开 gallery list 专用入口限流：Nginx `genarrative_gallery_rps rate=5000r/s`、`burst=4096`、gallery list `limit_conn=320`；api-server 对应 `GENARRATIVE_API_GALLERY_MAX_CONCURRENT_REQUESTS=320`，公开详情维持更低的 `GENARRATIVE_API_DETAIL_MAX_CONCURRENT_REQUESTS=64`。超过容量时接受明确 `429`，不继续扩大入口并发。
- 影响范围：`deploy/nginx/` 发布模板、`deploy/env/api-server.env.example`、`deploy/container/` 隔离压测模板和生产运维文档。
- 验证方式：容器连续 10 轮不重启 SpacetimeDB 压测，`PEAK_RPS=2500` 等价约 5000 HTTP req/s，平均实际吞吐约 `4219 HTTP req/s`，总计 `0` 个 5xx，200 请求平均 `p95=123ms`、`p99=234ms`；同时观察 SpacetimeDB 内存高水位，后续优化先处理连接 / 订阅 / tracking 下游状态。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`deploy/container/README.md`。

## 2026-05-19 新增玩法创作工具平台 SOP 冻结

- 背景：新增玩法的创作工具如果默认复制既有玩法的聊天式 Agent、轻输入 Agent 或专属素材模型，平台会不断复制出不可控分支，后续接入、测试和恢复语义都会漂移。
- 决策：新增玩法创作工具统一收敛为平台级 SOP：默认使用表单/图片输入创作工作台；单图资产统一通过 `CreativeImageInputPanel`；系列素材统一走批量规划、sheet 生图、后端切图、透明化、OSS 持久化和局部重生成流水线；不把任一玩法专属素材模型当平台通用模型。
- 影响范围：`CONTEXT.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、`.hermes/skills/genarrative-play-type-integration/SKILL.md`、后续新增玩法 PRD 和工程实现。
- 验证方式：新增玩法 PRD 必须显式声明单图资产槽位和系列素材槽位；新增工作台测试确认没有默认聊天式 Agent 输入；skill 通过 `quick_validate.py`。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`.codex/skills/genarrative-play-type-integration/SKILL.md`、`.hermes/skills/genarrative-play-type-integration/SKILL.md`。

## 2026-05-20 敲木鱼玩法按完整平台纵切接入

- 背景：敲木鱼玩法需要对齐拼图 / 跳一跳的创作闭环，不能做成孤立 demo 或前端本地计数工具。
- 决策：新增 `wooden-fish` 玩法，采用表单 / 图片输入工作台、单图敲击物资产槽位、敲击音效资产槽位和最多 8 条飘字配置；公开作品号前缀为 `WF-*`；运行态只在单次 run 内累计总敲击次数和词条计数。后端新增独立 `module-wooden-fish`、shared contracts、SpacetimeDB `wooden_fish_*` 表 / public views、`spacetime-client` facade 和 `/api/creation/wooden-fish/*`、`/api/runtime/wooden-fish/*` 路由，前端接入平台入口、生成页、结果页、运行态、公开详情和推荐试玩。
- 影响范围：`CONTEXT.md`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`packages/shared/src/contracts/woodenFish.ts`、`server-rs/crates/shared-contracts/src/wooden_fish.rs`、`server-rs/crates/module-wooden-fish/`、`server-rs/crates/spacetime-module/src/wooden_fish*`、`server-rs/crates/spacetime-client/src/wooden_fish.rs`、`src/components/wooden-fish-*`。
- 验证方式：执行敲木鱼契约 / module / facade / runtime model / platform entry 定向测试、`npm run typecheck`、`npm run check:encoding`、`npm run check:spacetime-schema`、`cargo check -p api-server --manifest-path server-rs\Cargo.toml`，本地 smoke 使用 mock 短信配置后检查 `/healthz`。
- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-05-21 敲木鱼敲击音效当前只接受上传、录音或默认音

- 背景：敲木鱼按关键词生成的敲击音效约束不够稳定；当前创作阶段需要先关闭提示词生成音效，避免生成结果不符合敲击体验。
- 决策：通用 `/api/creation/audio/sound-effect` 对木鱼 `hit_sound` 目标也返回 `410 Gone`。木鱼工作台只支持上传或麦克风录制音频；若用户未提供音频，`api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。`hitSoundPrompt` 只作为历史兼容字段保留，当前创作流程不使用；`spacetime-client` 不得合成 `/generated-wooden-fish-assets/...` 假路径。
- 影响范围：`server-rs/crates/api-server/src/vector_engine_audio_generation.rs`、`server-rs/crates/api-server/src/wooden_fish.rs`、`server-rs/crates/spacetime-client/src/wooden_fish.rs`、`shared-contracts` / `packages/shared` 的 `creationAudio` 契约、敲木鱼 PRD 与平台链路文档。
- 验证方式：执行 `cargo test -p shared-contracts creation_audio --manifest-path server-rs\Cargo.toml`、`cargo test -p spacetime-client wooden_fish --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server wooden_fish --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server disabled_creation_audio_targets_return_gone_including_wooden_fish_sound_effects --manifest-path server-rs\Cargo.toml`、`npm run typecheck`、`npm run check:encoding`，本地 smoke 检查 `/healthz`。
- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-05-21 敲木鱼默认敲击物使用内置透明 PNG

- 背景：默认敲木鱼图案若继续用“木鱼”关键词临时生成，image2 容易语义化重画并改变用户认可的原始造型。
- 决策：默认模板使用内置资源 `/wooden-fish/default-hit-object.png` 写回 `bundled-default` 敲击物资产；仅当用户输入自定义关键词、上传参考图或主动重生成敲击物时，才走 image2 -> OSS -> asset object -> entity binding 链路。创作入口卡片、结果页、运行态和公开列表兜底统一使用该 PNG。
- 影响范围：敲木鱼工作台默认提示词、api-server 木鱼默认资产编排、创作入口种子与迁移、平台公开卡片兜底、PRD 与平台链路文档。
- 验证方式：默认 `compile-draft` 返回的 `hitObjectAsset.generationProvider` 应为 `bundled-default` 且 `imageSrc=/wooden-fish/default-hit-object.png`；自定义关键词或参考图仍走 image2；前端静态资源可通过 Vite 直接访问。
- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-23 敲木鱼创作请求需要独立长超时

- 背景：敲木鱼 `createSession` 和 `executeAction` 都会串行等待多段 image2 生成、去绿背景处理和 OSS 落库；共享创作工厂默认 15 秒对这条链路太短，容易让前端先报 `请求超时：15000ms`。
- 决策：敲木鱼 client 单独配置长等待窗口，同时覆盖会话创建和执行动作请求，不修改共享工厂默认值，避免影响其它轻量创作玩法。
- 影响范围：`src/services/wooden-fish/woodenFishClient.ts`、`src/services/creation-agent/creationAgentClientFactory.ts`、敲木鱼工作台与生成页请求行为。
- 验证方式：`npm test -- src/services/wooden-fish/woodenFishClient.test.ts`，并在本地敲木鱼创作时不再提前触发 15 秒超时。
- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-21 RPG publish_world 设定文本以后端草稿真相派生

- 背景：RPG 结果页发布动作只保证提交 `{ action: 'publish_world' }`；旧 agent 会话可能没有 `seed_text`，但 `draft_profile_json` 已经通过 `publish_gate` 并可发布。
- 决策：发布正式世界时，`spacetime-module` 不再把 `session.seed_text` 当作唯一 `setting_text` 兜底，而是调用 `module-custom-world::resolve_custom_world_publish_setting_text(...)` 从 payload、当前草稿 profile 和 seed 依次派生。
- 影响范围：RPG / custom-world agent 发布链路、`custom_world_profile` 编译入库、公开 gallery 投影。
- 验证方式：`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`、`docs/project-memory/shared-memory/pitfalls.md`。

## 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 字段。
- 影响范围：`api-server` 系列素材生成、Match3D 物品五视角素材、后续新增玩法的地块 / 物品 / 障碍 / 装饰图集生成。
- 验证方式：`cargo test -p api-server generated_asset_sheets --manifest-path server-rs\Cargo.toml -- --nocapture` 覆盖通用 prompt、切片、`n` 校验和 prompt 元数据；玩法侧执行对应素材流水线定向测试。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-05-19 跳一跳玩法采用正式 scoring DTO 与 public view 投影

- 背景：跳一跳玩法新增后，前端、shared-contracts、SpacetimeDB 生成绑定和后端 mapper 对 scoring 字段口径不一致，schema guard 也要求 table / view 目录与 `migration.rs` 同步。
- 决策：跳一跳的 `JumpHopScoring` 统一采用 `chargeToDistanceRatio/maxChargeMs/hitBonus/perfectBonus`，公开广场优先使用 `jump_hop_gallery_card_view`，详情兼容投影保留 `jump_hop_gallery_view`。`spacetime-module` 新增的 `jump_hop_*` table 必须同步进入 `migration.rs` 和后端架构文档。
- 影响范围：`packages/shared/src/contracts/jumpHop.ts`、`server-rs/crates/shared-contracts/src/jump_hop.rs`、`server-rs/crates/spacetime-client/src/mapper/jump_hop.rs`、`server-rs/crates/spacetime-module/src/migration.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
- 验证方式：`cargo check -p shared-contracts --manifest-path server-rs/Cargo.toml`、`cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-05-16 公开作品列表短期由 BFF 订阅读模型缓存

- 背景：作品列表压测和实时性讨论中，曾考虑让浏览器前端直接订阅公开作品列表，减少 HTTP 拉取和 BFF 压力。
- 决策：本轮不直接把作品列表整体交给前端订阅。短期继续由 `api-server` / BFF 通过 `spacetime-client` 长期订阅 SpacetimeDB 公开 read model 并读取本地 cache，维持首屏、排序、字段归一、权限降级和 HTTP fallback。中期可以新增或统一稳定的专用公开作品列表 read model，例如 `public_work_gallery_entry`，作为前端可选直连订阅对象。
- 边界：未来前端直订阅只允许面向稳定、低基数、公开的专用 read model。前端不得直接订阅 `puzzle_work_profile`、`custom_world_profile` 等领域源表，也不得在前端自行 join、聚合或执行公开权限逻辑；这些逻辑必须先沉到后端投影 / read model。
- 后续准入：若要落地前端直订阅，必须先完成并验收权限边界、字段契约、排序 / 分页、埋点和 BFF 回退策略；缺任一项时继续走 `api-server` / BFF 订阅缓存方案。
- 影响范围：发现页、推荐流、各玩法公开广场、`api-server` 公开列表缓存、SpacetimeDB public view / public 读模型设计。
- 验证方式：新增公开作品列表订阅能力时，检查前端只消费专用 public read model 或 BFF HTTP DTO；检查源表 row shape、权限判断和跨玩法聚合没有下沉到前端页面。
- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

- 背景：压测与运行观测需要把 HTTP、SpacetimeDB 调用和应用日志串起来，同时保留本地 `journalctl` / 文件日志做故障排障。
- 决策：`api-server` 通过 OTLP HTTP base endpoint 发送 traces、metrics 和 logs；Collector 统一用 `otelcol-contrib`，`npm run otel:debug` 负责 debug 采集，`npm run otel:rider` 负责转发到 Rider；Rider 只是接收与可视化端，不直接替代 Collector。
- 日志口径：Rider Logs 面板只展示 log event 自身字段，请求完成日志需要直接携带 `request_id`、HTTP method、规范化 route、scheme、path、status、status_class、latency 和 slow_request；更完整的 request attributes 仍以 trace/span 为准。
- 影响范围：`server-rs/crates/shared-logging`、`server-rs/crates/api-server`、`scripts/run-otelcol.mjs`、压测与运维文档。
- 验证方式：`cargo test -p shared-logging --manifest-path server-rs/Cargo.toml generic_otlp_http_endpoint_expands_to_signal_paths`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml observability_route_keeps_metrics_labels_low_cardinality`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml resolve_request_scheme_uses_forwarded_proto_first_value`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`scripts/loadtest/README.md`。

## 2026-05-14 创作页图像输入统一封装为图像组件

- 背景：拼图创作页已经具备“画面描述生图 / 多参考图生图 / 上传主图后 AI 重绘 / 上传主图后不重绘”四条路径，抓大鹅封面和后续创作页也会复用同一套交互；继续在页面内复制会导致参考图、预览、删除确认和重绘开关漂移。
- 决策：通用图像输入 UI 统一使用 `src/components/common/CreativeImageInputPanel.tsx`。组件采用受控模式，只负责主图上传卡、画面描述输入、参考图缩略图与预览、AI 重绘开关、错误展示和提交按钮；外层页面负责文件读取/裁剪、历史素材弹层、计费确认、自动保存和具体后端请求。
- 影响范围：拼图创作入口、后续抓大鹅封面生成入口、其它需要复用图像输入链路的创作页。
- 验证方式：拼图入口交互测试继续覆盖四种路径；后续页面接入时只传入业务回调与文案，不复制上传卡和参考图缩略图实现。
- 关联文档：`docs/technical/【前端体验】图像组件统一封装与复用边界-2026-05-14.md`。

## 2026-05-14 汪汪声浪创作入口改为创作 Tab 内嵌轻配置

- 背景：汪汪声浪入口最初走独立配置阶段，和拼图、抓大鹅的创作页内嵌结构不一致，用户在入口切换时会感觉像跳到了另一张页面。
- 决策：`bark-battle` 的创作入口只在创作 Tab 内嵌渲染轻配置表单，入口点击只切到创作页并选中该模板，不再使用 `bark-battle-config` 独立阶段；runtime 退出时回到创作页并恢复汪汪声浪模板选中态。
- 影响范围：`PlatformEntryFlowShellImpl`、`BarkBattleConfigEditor`、`BarkBattleRuntimeShell`、入口配置说明和相关交互测试。
- 验证方式：创作 Tab 中点击汪汪声浪后直接看到内嵌表单，不应再出现单独配置页；发布进入 runtime 后退出应回到创作页的汪汪声浪模板。
- 关联文档：`docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md`。

## 2026-05-14 拼图与抓大鹅生成页移动端收口为等待与计时双栏（历史）

- 背景：拼图与抓大鹅的草稿生成页在移动端同时展示“当前批次”“预计等待”“计时”时，模型执行视角过重，信息也显得散。
- 决策：这两类轻量玩法的生成页隐藏“当前批次”模块，只保留“预计等待”和“计时”并排展示；生成步骤进入页面时按顺序从左侧滑入，强化推进感。2026-05-23 起已被“所有玩法生成页统一圆环主视觉”取代，步骤列表不再作为当前口径。
- 影响范围：`CustomWorldGenerationView`、拼图与抓大鹅创作入口调用处、移动端生成页体验文档。
- 验证方式：拼图与抓大鹅生成页在手机竖屏下只显示等待与计时双栏，步骤卡按顺序滑入；其它未传入隐藏参数的生成页继续保留原批次模块。
- 关联文档：`docs/experience/MOBILE_UI_DEV_EXPERIENCE.md`。

## 2026-05-14 移动端输入法弹出时平台画布不压缩

- 背景：平台根壳使用 `100dvh` 后，手机浏览器输入法弹出会让可见视口变小，导致创作首页、推荐页等固定游戏式画布被重新压缩。
- 决策：主站入口统一注册移动端输入法聚焦适配；输入法未打开时记录稳定布局高度，输入法打开期间 `.platform-viewport-shell` 不跟随 `visualViewport.height` 缩小，只通过 `--platform-keyboard-focus-offset` 上移画面聚焦当前输入框，并临时隐藏移动端底部 dock。
- 影响范围：主站平台壳、移动端创作首页底部输入框、后续所有复用 `.platform-viewport-shell` 的输入表单；业务组件不重复注册键盘适配。
- 验证方式：手机竖屏点击输入框，画布不压缩，输入框移动到输入法上方；输入法关闭后画布回位，底部 dock 恢复。
- 关联文档：`docs/technical/【前端体验】移动端输入法不压缩画布聚焦方案-2026-05-14.md`、`docs/experience/MOBILE_UI_DEV_EXPERIENCE.md`。

## 2026-05-14 抓大鹅物品素材批量重新生成复用 item-assets 替换模式

- 背景：抓大鹅结果页 `素材配置 > 物品` 需要在不改变玩法物品映射的前提下，批量重新生成已存在物品的 2D 五视角图片。
- 决策：继续复用 `POST /api/creation/match3d/works/{profileId}/item-assets`，请求体通过 `mode = "replace"` 表达替换模式；前端面板预填当前素材名称，只提交仍能匹配到已有素材的名称。后端只替换匹配素材的 `imageSrc/imageObjectKey/imageViews/status/error`，保留原 `itemId`、列表顺序、模型兼容字段、UI 背景、历史背景音乐和点击音效字段；未匹配名称不计费、不新增、不持久化。
- 影响范围：Match3D 结果页素材配置、前端/后端 shared contracts、`api-server` Match3D item-assets 编排、运行态物品类型映射和素材生成技术文档。
- 验证方式：执行 `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`、`cargo test -p api-server match3d_item_asset --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server match3d_regenerated_asset --manifest-path server-rs\Cargo.toml`、`npm run check:encoding`。
- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 2026-05-14 拼图与抓大鹅音频生成入口临时关闭

- 背景：当前需要暂时关闭抓大鹅、拼图中生成背景音乐和音效的能力，并隐藏草稿中的相关入口。
- 决策：拼图 `compile_puzzle_draft` 不再自动生成背景音乐，结果页素材配置只保留 `UI`；抓大鹅 `match3d_compile_draft` 和批量新增只生成 2D 图片、背景和容器 UI，不再调用 Suno/Vidu，结果页隐藏 `背景音乐` 子 Tab 与点击音效生成控件；通用 `/api/creation/audio/*` 当前整体返回 `410 Gone`。历史已写入的 `backgroundMusic` / `clickSound` 字段保留，运行态继续兼容播放旧音频。
- 影响范围：`api-server` 拼图/抓大鹅草稿编排、通用创作音频路由、拼图/抓大鹅结果页、生成进度模型、相关技术文档。
- 验证方式：执行拼图/抓大鹅结果页定向测试、生成进度单测、`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 和 `npm run check:encoding`。
- 关联文档：`docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 2026-05-14 抓大鹅物品素材 sheet 改用 VectorEngine Gemini

- 状态：历史决策，已被 `2026-05-22 抓大鹅素材生成改为关卡整图派生三图` 取代；当前物品 spritesheet 走 `gpt-image-2` 参考关卡整图编辑生成 `2K 1:1`、`10*10` 绿幕图，上传 OSS 前扣成透明 PNG。
- 背景：抓大鹅 2D 五视角物品素材仍沿用 5x5 sheet、绿幕去背、切图、OSS 转存和 `generatedItemAssets` 持久化，但用户要求物品素材图片生成步骤改用 VectorEngine Apifox `api-381740608` 对应的 Gemini 原生图片接口。
- 决策：抓大鹅物品素材 sheet 生图固定走 VectorEngine `POST {VECTOR_ENGINE_BASE_URL}/v1beta/models/gemini-3-pro-image-preview:generateContent?key={VECTOR_ENGINE_API_KEY}`，请求体使用 `contents[].parts[].text` 与 `generationConfig.responseModalities = ["TEXT", "IMAGE"]`、`imageConfig.aspectRatio = "1:1"`；响应从 `candidates[].content.parts[].inlineData.data` / `inline_data.data` 读取 base64 图片。封面、9:16 纯背景图、1:1 容器 UI 图、切图、OSS、扣费和运行态消费链路保持不变；音频以后续“拼图与抓大鹅音频生成入口临时关闭”决策为准。
- 影响范围：`server-rs/crates/api-server/src/match3d.rs`、`server-rs/crates/api-server/src/config.rs`、`deploy/env/api-server.env.example`、抓大鹅素材生成技术文档。
- 验证方式：执行 `cargo test -p api-server match3d_material_sheet --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server match3d_vector_engine_gemini --manifest-path server-rs\Cargo.toml`、`cargo check -p api-server --manifest-path server-rs\Cargo.toml`、`npm run check:encoding`。
- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 2026-05-14 草稿页作品卡对齐分类页列表

- 背景：草稿页作品架原本偏封面大卡片，和发现页分类列表的横向卡片样式不一致；生成中状态也缺少整卡级的统一遮罩。
- 决策：草稿页作品卡统一收口为与分类页一致的横向列表卡结构，左侧承载标题/状态/类型/摘要与必要数据，右侧显示带透明度的封面图；移动端保持单列列表，网页端使用两到三列卡片式网格，避免宽屏长条列表。不再常驻“继续创作”“查看详情”“查看进度”等右侧动作按钮。原有删除、分享、积分激励、公开统计、未读红点全部保留，其中删除与分享进入左滑操作层，常态不显示删除按钮，也不得透出删除底层。生成中的作品在整卡上加半透明蒙版、旋转等待符号和“生成中...”标识，但不移除任何原有信息。
- 影响范围：`src/components/custom-world-home/CustomWorldCreationHub.tsx`、`src/components/custom-world-home/CustomWorldWorkCard.tsx`、相关样式与测试、草稿页 UI 文档。
- 验证方式：草稿页作品卡与分类页列表视觉口径保持一致；`npm run test -- src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx`、`npm run typecheck`、`npm run check:encoding`。
- 关联文档：`docs/design/MOBILE_CREATION_WORK_LIST_TWO_COLUMN_LAYOUT_2026-04-29.md`、`docs/experience/MOBILE_UI_DEV_EXPERIENCE.md`。

2026-05-14 补充：草稿页作品卡不再用“草稿 / 已发布”文字标识状态，改为图标化 UI 状态点；作品封面直接铺到卡片右半区并从右向左渐隐；已发布作品右上角常驻分享图标；草稿长按弹出删除面板，已发布长按弹出分享和删除面板。2026-06-02 追加：作品卡片右上角不再放删除按钮；删除只通过左滑、键盘展开或长按 / 右键展开的右侧操作区出现，避免与卡片主点击和分享入口抢占标题区。

## 2026-05-13 认证运行期同步直接导入正式认证表

- 背景：`auth_store_snapshot` 是 Stage 1 整包快照过渡表，主键固定 `default`，会让所有用户状态集中在一条 `snapshot_json` 中；Stage 2/3 已有 `user_account/auth_identity/refresh_session` 正式认证表，继续刷新 `default` 容易让运行时真相和表拆分目标混在一起。
- 决策：运行期认证变更继续由 `module-auth` 生成一致内存快照，但 `api-server` 改为调用 `import_auth_store_snapshot_json` 直接覆盖导入 `user_account/auth_identity/refresh_session`；`auth_store_projection_meta/default` 只记录正式认证表最近一次导入时间；`upsert_auth_store_snapshot` 与 `import_auth_store_snapshot` 仅保留为旧库迁移和兜底入口。
- 影响范围：`spacetime-module` auth procedures/tables、`spacetime-client` auth facade/bindings、`api-server` 认证同步和启动恢复、SpacetimeDB 表目录与认证 Stage 3 文档。
- 验证方式：执行 `npm run spacetime:generate -- --rust-only`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、认证相关定向测试和 `npm run check:encoding`。
- 关联文档：`docs/technical/AUTH_SPACETIMEDB_FORMAL_TABLE_RECOVERY_STAGE3_2026-04-24.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。

## 2026-05-27 auth_store_snapshot 改为行级记录，不再保留 default 聚合单行

- 背景：`auth_store_snapshot/default` 聚合 JSON 行会把整份认证快照收敛到单键，过期快照一旦被导入就可能覆盖 `user_account` / `auth_identity` / `refresh_session` 的整表状态。
- 决策：`auth_store_snapshot` 只保留行级记录，按 `meta/next_user_id`、`user/<user_id>`、`phone/<phone+user>`、`session/<session_id>`、`session_hash/<hash+session>`、`wechat/<provider_uid+user>`、`union/<union+user>` 拆分存储；`api-server` 启动恢复只认正式认证表，`auth_store_snapshot` 仅作为行级备查，不再作为文件快照替代源。
- 影响范围：`spacetime-module` auth procedures、`spacetime-client` auth facade、`api-server` 启动恢复、后端架构文档、开发运维文档、认证排障记忆。
- 验证方式：`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server spacetime_unavailable_router_returns_service_unavailable_for_requests --manifest-path server-rs/Cargo.toml -- --nocapture`、`npm run check:encoding`。

## 2026-05-13 微信小程序支付以后端通知为唯一入账事实

- 背景：“我的”账户充值需要接入微信小程序支付，同时保留本地 / H5 mock 支付联调能力。
- 决策：`paymentChannel = "mock"` 继续创建即 paid 订单并立即入账；`paymentChannel = "wechat_mp"` 先在 `profile_recharge_order` 写入 `pending` 订单，再由 `api-server` 调微信支付 JSAPI 下单并返回小程序 `wx.requestPayment` 参数。小程序或 H5 的支付成功回调只触发刷新，不直接发放泥点或会员；最终入账只由 `/api/profile/recharge/wechat/notify` 验签、解密并确认 `trade_state = SUCCESS` 后完成。`provider_transaction_id` 保存微信支付平台交易号，用于对账、查单、退款和客服排障。
- 影响范围：`profile_recharge_order` 表、SpacetimeDB 充值 procedure、`api-server` 微信支付客户端、小程序 native 支付页、H5 充值弹窗与共享 contract。
- 验证方式：执行 `npm run typecheck`、`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`cargo test -p module-runtime recharge --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server wechat_pay --manifest-path server-rs/Cargo.toml`，后端联调仍用 `npm run dev:api-server` 和 `/healthz`。
- 关联文档：`docs/technical/MY_TAB_ACCOUNT_RECHARGE_IMPLEMENTATION_2026-04-25.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。

## 2026-05-13 修改密码后全设备强制下线

- 背景：修改密码原本只递增 `token_version`，旧 access token 会失效，但旧 refresh cookie 仍可通过 `/api/auth/refresh` 重新签发新 token，不符合“改密后全设备强制下线”的账号安全预期。
- 决策：`POST /api/auth/password/change` 成功后必须在同一认证真相更新中撤销该用户全部 active `refresh_session`，继续递增 `token_version`，响应清除当前 refresh cookie；前端 `changePassword` 成功后清空本地 access token 并回到未登录态。用户需要使用新密码重新登录。
- 影响范围：`module-auth` 修改密码用例、`api-server` password management route、`AuthGate`、`authService`、密码登录/重置技术文档。
- 验证方式：执行 `cargo test -p api-server --manifest-path server-rs/Cargo.toml password_change_allows_login_with_new_password_only -- --nocapture`、`npm run test -- AuthGate.test.tsx authService.test.ts`、`npm run check:encoding`、`git diff --check`。
- 关联文档：`docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md`、`docs/technical/AUTH_SESSIONS_QUERY_DESIGN_2026-04-21.md`。

## 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`，避免误伤其它设备，只有退出全部设备和改密类安全动作提升账号级版本。
- 影响范围：`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`。

## 2026-05-12 抓大鹅入口素材风格改为 2D 常见素材风格

- 背景：抓大鹅草稿素材生成已经收敛为多视角 2D 图片素材，但入口页和旧参考图仍沿用黏土、低多边形、塑料、木雕、体素、金属等偏 3D 素材语言，容易让后续生成链路和用户预期继续漂移。
- 决策：抓大鹅创作入口 `2D素材风格` 固定为 `扁平图标 / 赛璐璐卡通 / 像素复古 / 手绘水彩 / 贴纸描边 / 厚涂图标 / 自定义`；默认风格为 `flat-icon`。入口参考图统一由 `npm run assets:match3d-style-references -- --live` 调用 VectorEngine `gpt-image-2` 生成，输出到 `public/match3d-style-references/`。旧 3D 风格参考图不再保留为入口资产。
- 影响范围：抓大鹅统一创作工作台、抓大鹅入口交互测试、Match3D PRD、素材生成流水线技术文档、F1 入口文档和 `public/match3d-style-references/` 静态资产。
- 验证方式：执行 `npm run test -- src/components/unified-creation/workspaces/Match3DCreationWorkspace.interaction.test.tsx`、`cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml`、`npm run typecheck`、`npm run check:encoding`，并人工抽查 `.tmp/match3d-style-preview.png`。
- 关联文档：`docs/prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`、`docs/technical/MATCH3D_F1_CREATION_ENTRY_AND_AGENT_UI_2026-04-30.md`。

## 2026-05-12 拼图与抓大鹅草稿背景音乐按纯音乐自动生成

- 背景：拼图和抓大鹅需要在草稿生成阶段直接产出可试听、可重生成、可进入运行态循环播放的背景音乐。
- 决策：复用通用 VectorEngine Suno 创作音频链路，不新增 SpacetimeDB 表；拼图音乐保存到首关 `PuzzleDraftLevel.backgroundMusic`，运行态通过 `PuzzleRuntimeLevelSnapshot.backgroundMusic` 下发；抓大鹅音乐保存到首个 `generatedItemAssets[].backgroundMusic`。两者草稿生成都使用 `title` 驱动、`prompt = ""`、`make_instrumental = true`；自动草稿阶段必须拿到可播放 `audioSrc` 才能返回成功，失败时停留在生成页并允许重试同一 session/profile。结果页内的手动重新生成继续作为已有草稿的补救入口。
- 影响范围：`api-server` 音频生成、拼图草稿编译、抓大鹅草稿编译、Puzzle/Match3D 结果页和运行态音频播放。
- 验证方式：检查草稿 response / work detail 中的 `backgroundMusic.audioSrc`，运行态开局后隐藏 audio 循环播放；执行音频相关后端 check、前端 typecheck 和编码检查。
- 关联文档：`docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 2026-05-12 拼图 UI 背景图复用 levels_json 持久化

- 背景：拼图草稿结果页需要像抓大鹅一样支持 UI 背景生成，但首版只需要作品级/首关背景，不应为图片生成结果新增 SpacetimeDB 表结构。
- 决策：拼图 UI 背景字段存入首关 `levels_json`，字段为 `uiBackgroundPrompt`、`uiBackgroundImageSrc`、`uiBackgroundImageObjectKey`；`compile_puzzle_draft` 草稿编译阶段自动生成首关 UI 背景，自动草稿阶段必须拿到 `uiBackgroundImageSrc` 或 `uiBackgroundImageObjectKey` 才能返回成功；结果页新增 `UI` Tab，可编辑提示词并触发 `generate_puzzle_ui_background`，手动生成失败只展示在当前面板。`api-server` 读取 `public/ui-previews/puzzle-image-compact-ui-2026-05-08.png` 作为非拼图 UI 参考图，调用 VectorEngine `gpt-image-2` 生成 9:16 背景并要求中央正方形拼图区与外部 UI 背景边界清晰。SpacetimeDB 只保存结果，不做外部 I/O。
- 2026-05-18 追加：为缩短首版草稿等待，`compile_puzzle_draft` 在首关命名和 `uiBackgroundPrompt` 稳定后并行启动首关关卡图生成与 UI 背景生成；上传主图且关闭 AI 重绘时，并行执行上传图持久化与 UI 背景生成。生成页预计完成时间按 5 分钟展示。
- 2026-05-21 追加：拼图结果页独立“素材配置”Tab 已移除，UI spritesheet 与关卡纯背景收口到每关图片生成资产包。每次 `gpt-image-2` 预计 90 秒；2026-05-24 起草稿首图生成单独按 4 分钟展示，草稿完整 AI 重绘路径约 448 秒，上传图且关闭 AI 重绘路径跳过首图生成约 208 秒。结果页关卡详情继续复用 `CreativeImageInputPanel`，本次上传/历史选择图优先成为主图卡片，正式图只作为无新参考图时的预览；仅有正式图时仍允许在画面描述框上传多张参考图。
- 影响范围：拼图结果页、拼图运行态背景渲染、拼图 agent action、`module-puzzle` / `spacetime-module` / `spacetime-client` 的拼图关卡 JSON 映射、拼图流程技术文档。
- 验证方式：执行 `npm run test -- src/components/puzzle-result/PuzzleResultView.test.tsx`、`cargo test -p api-server puzzle_ui_background --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding`。
- 关联文档：`docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md`。

## 2026-05-12 抓大鹅结果页素材编辑统一走作品级资产面板

- 背景：抓大鹅结果页需要支持封面图上传 / AI 重绘、物品素材独立预览、单项删除和批量新增，且不能把素材编辑继续做成列表内联展开或前端临时状态。
- 决策：结果页 `作品信息` 的封面图点击打开独立面板，封面图面板对齐拼图入口上传卡。已有上传主图时，请求体传 `uploadedImageSrc`，AI 重绘走 VectorEngine `/v1/images/edits`，后端把上传图作为 multipart `image` part 传入 `gpt-image-2`；关闭 AI 重绘时只写回上传图，不调用生图。没有上传主图但存在 `referenceImageSrcs` 时，多参考图同样走 edits 的多个 `image` part；完全无参考图时走 `/v1/images/generations`。生成结果统一调用 `POST /api/creation/match3d/works/{profileId}/cover-image` 并转存到 `generated-match3d-assets`。`素材配置 > 物品` 列表项点击打开独立预览面板，不再提供单项重新生成按钮；单项删除和批量新增都写回同一份 `generated_item_assets_json`。批量新增调用 `POST /api/creation/match3d/works/{profileId}/item-assets`；该接口的物品 spritesheet 生成口径已被 2026-05-22 决策更新为关卡整图参考、`10*10` 绿幕图和上传前透明化。
- 影响范围：Match3D 结果页、Match3D works shared contracts、`api-server` Match3D 作品路由、生成资产历史类型和草稿恢复路径。
- 验证方式：执行 `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`、`npm run typecheck`、`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 2026-05-12 平台法律文档入口与登录协议确认

- 背景：生产发布需要在个人页展示用户协议、隐私政策、免责声明和备案号；登录页首次登录需要显式确认法律协议。
- 决策：法律文档内容读取 `media/files/*.md`，统一通过 `LegalDocumentModal` 独立弹窗展示；“我的”页常用功能区固定 3 列，设置入口下方展示法律信息和 `京ICP备2026025677号` 外链。登录弹窗用 `genarrative.auth.legal-consent.v1` 记录本机确认，首次未勾选时短信 / 密码登录按钮禁用，法律链接不自动勾选。
- 影响范围：平台个人页、登录弹窗、法律 Markdown 渲染和前端认证交互测试。
- 验证方式：执行 `npm run test -- src/components/auth/AuthGate.test.tsx src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、触碰文件 ESLint、`npm run check:encoding`。
- 关联文档：`docs/prd/PROFILE_LEGAL_INFO_AND_AUTH_AGREEMENT_PRD_2026-05-12.md`。

## 2026-05-12 微信小程序待绑定手机号优先走原生手机号授权

- 背景：微信小程序 `web-view` 壳登录后若返回 `pending_bind_phone`，H5 仍会展示手输手机号和短信验证码绑定页，体验上多了一步。
- 决策：小程序壳在 `pending_bind_phone` 时暂不打开 H5，先展示原生 `button open-type="getPhoneNumber"`；用户同意后把 `bindgetphonenumber` 返回的 `code` 作为 `wechatPhoneCode` 调用 `/api/auth/wechat/bind-phone`。后端通过微信 `stable_token` 与 `getuserphonenumber` 换取平台验证后的手机号，再复用现有微信待绑定账号合并逻辑并重新签发 active 系统 token。H5 旧短信验证码绑定流程继续作为非小程序环境兜底。
- 影响范围：`miniprogram/pages/web-view/index.*`、`server-rs/crates/platform-auth`、`server-rs/crates/api-server/src/wechat_auth.rs`、认证共享契约、微信小程序 web-view 壳技术文档。
- 验证方式：执行 `npm run check:encoding`、`node scripts/check-wechat-miniprogram-auth-smoke.mjs`、`cargo test -p shared-contracts wechat_bind_phone_request_accepts_mini_program_phone_code --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server wechat_miniprogram_bind_phone_code_activates_pending_user --manifest-path server-rs/Cargo.toml -- --nocapture`。
- 关联文档：`docs/technical/WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md`。

## 2026-05-26 微信小程序进入即开 H5，登录按需走原生手机号授权

- 背景：当前产品要求微信小程序进入后不再立刻取手机号，而是默认直接进入 `web-view`，登录状态与 Web 端统一；只有 H5 触发受保护操作时才走微信手机号授权。
- 决策：小程序壳首次进入只打开 H5，不再把登录态当作启动前置条件；H5 侧在小程序运行态触发登录时，不展示普通登录弹窗，而是跳转到小程序原生手机号授权流程，授权结果再回灌到 H5。未触发登录时保持游客态，与 Web 端一致。
- 影响范围：`miniprogram/pages/web-view/index.*`、`src/components/auth/AuthGate.tsx`、`src/components/auth/LoginScreen.tsx`、`src/services/authService.ts`、相关测试与说明文档。
- 验证方式：执行 `npm run check:encoding`、`npm run typecheck`、`npx vitest run src/components/auth/AuthGate.test.tsx src/services/authService.test.ts scripts/miniprogram-web-view-auth.test.ts`。

## 2026-05-13 宝贝爱画先作为寓教于乐独立本地 Demo 落地

- 背景：第三关 `宝贝爱画` 需要默认出现在“发现 / 寓教于乐”板块下方，但本阶段只验证画板、手部绘制、绘画魔法和本地保存闭环，不进入创作模板、公开作品或正式持久化。
- 决策：`baby-love-drawing / 宝贝爱画` 先作为独立运行态接入，入口由发现页寓教于乐默认卡片打开，并支持 `/runtime/baby-love-drawing` 直达；关闭 `VITE_ENABLE_EDUTAINMENT_ENTRY` 时前端不展示频道/卡片且直达路由回落主应用。绘画魔法统一走 `POST /api/creation/edutainment/baby-love-drawing/magic` 后端安全代理，使用 VectorEngine `gpt-image-2` 与原始画布 Data URL 参考图生成绘本风图片；保存只写 localStorage，正式持久化后续再设计。
- 影响范围：`packages/shared/src/contracts/edutainmentBabyDrawing.ts`、`src/components/edutainment-runtime/BabyLoveDrawingRuntimeShell.tsx`、`src/services/edutainment-baby-drawing/`、`src/routing/appRoutes.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`server-rs/crates/api-server/src/edutainment_baby_drawing.rs`、`src/index.css`、宝贝爱画 PRD 与技术方案。
- 验证方式：执行宝贝爱画 model/runtime/service/route 定向测试、`npm run typecheck`、定向 ESLint、`cargo test -p api-server edutainment_baby_drawing --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server resolves_runtime_paths_to_creation_type_ids --manifest-path server-rs/Cargo.toml` 和编码检查；真实魔法生成需配置 `VECTOR_ENGINE_BASE_URL` 与 `VECTOR_ENGINE_API_KEY`。
- 关联文档：`docs/prd/BABY_LOVE_DRAWING_EDUTAINMENT_LEVEL_PRD_2026-05-13.md`、`docs/technical/BABY_LOVE_DRAWING_RUNTIME_DEMO_IMPLEMENTATION_2026-05-13.md`。

## 2026-05-12 宝贝识物创作同时生成玩法视觉主题包

- 背景：`宝贝识物` 创作原本只根据两个关键词生成物品透明图，运行态背景、UI、礼物盒和篮子仍使用固定 CSS 绘本风，无法根据“小猪佩琪 / 奥特曼”或“苹果 / 橘子”等创作者提示词做主题化包装。
- 决策：`POST /api/creation/edutainment/baby-object-match/assets` 同一次 image-2 / VectorEngine 调用链返回两个物品图和 `visualPackage`。为降低调用成本，新链路只生成一张 `1024x1024` 的 `2x2` 素材 sheet 和一张 `1536x1024` 场景背景图；`2x2` sheet 固定左上物品 A、右上物品 B、左下篮子、右下礼物盒，服务端按格切图并把物品、篮子和礼物盒转透明 PNG。视觉包必需资源为 `background`、`gift-box`、`basket`；总风格保持寓教于乐明亮卡通绘本插画风，主题按两个物品关键词匹配。左右手位置指示器是运行态默认静态素材，使用项目内置第一人称半抓握手，不再随每次创作生成。运行态中礼物盒按约 2 倍视觉尺寸展示、篮子按约 1.5 倍展示，中央物品 UI 与篮子物品图标使用固定正方形槽位并等比 `contain` 缩放，礼物盒打开烟雾特效由 CSS 兜底；历史草稿中的 `ui-frame` / `smoke-puff` / `left-hand` / `right-hand` 仅兼容读取或忽略。前端草稿保存该包，运行态消费该包；旧草稿以 `visualPackage = null` 继续使用 CSS 兜底。
- 影响范围：`packages/shared/src/contracts/edutainmentBabyObject.ts`、`server-rs/crates/api-server/src/edutainment_baby_object.rs`、`src/services/edutainment-baby-object/babyObjectMatchClient.ts`、`src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.tsx`、`src/index.css`、宝贝识物 PRD 与技术方案。
- 验证方式：执行宝贝识物 service / runtime 定向测试、`cargo test -p api-server edutainment_baby_object --manifest-path server-rs/Cargo.toml`、相关 ESLint 与编码检查；真实生图需配置 `VECTOR_ENGINE_BASE_URL` 与 `VECTOR_ENGINE_API_KEY`。
- 关联文档：`docs/prd/BABY_OBJECT_MATCH_EDUTAINMENT_TEMPLATE_PRD_2026-05-11.md`、`docs/technical/BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md`。

## 2026-05-11 拼图与抓大鹅结果页音频资产复用通用创作音频链路

- 背景：拼图和抓大鹅结果页需要接入 Suno 背景音乐，抓大鹅还需要物体点击音效，但当前两类作品没有独立的作品级音频表或 metadata 字段。
- 决策：新增 `/api/creation/audio/*` 通用创作音频路由，后端统一负责 VectorEngine 音频任务、OSS 转存、`asset_object` 与 `asset_entity_binding` 写入；视觉小说旧路由保留并复用同一持久化逻辑。拼图背景音乐暂存到首关 `levels_json[0].backgroundMusic/background_music`；抓大鹅背景音乐暂存到 `generated_item_assets_json[0].backgroundMusic/background_music`，单物体点击音效存到对应 item 的 `clickSound/click_sound`。本轮不新增 SpacetimeDB 表和字段。
- 2026-05-12 补充：抓大鹅入口页新增 `generateClickSound` 开关，默认关闭；开启时 `match3d_compile_draft` 在生成首批 2D 物品素材后并行生成各物品点击音效，并继续复用通用创作音频路由的 OSS、资产绑定和扣费口径。
- 影响范围：拼图结果页、抓大鹅结果页、抓大鹅运行态音频播放、通用创作音频 shared contracts、`api-server` 音频路由和资产绑定。
- 验证方式：执行拼图/抓大鹅结果页定向测试、`npm run typecheck`、`cargo test -p api-server vector_engine_audio_generation`、`cargo test -p shared-contracts creation_audio`、`cargo check -p api-server`，真实生成需配置 VectorEngine 与 OSS 私密环境。
- 关联文档：`docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md`。

## 2026-05-11 寓教于乐公开作品使用独立 `edutainment` 来源接入

- 背景：`宝贝识物` 首关需要通过创作模板发布后进入寓教于乐板块，同时关闭入口时必须从发现页、搜索、详情深链、作品号和历史入口完全不可见；若继续落入 RPG 默认公共作品链路，容易出现误启动、误改造或近似标签误归类。
- 决策：寓教于乐公开作品在前端公共作品模型中使用 `sourceType = edutainment`，当前只承接 `templateId = baby-object-match`、`templateName = 宝贝识物`；进入“发现 / 寓教于乐”频道仍必须携带精确等于 `寓教于乐` 的公开标签，不因模板名或近似标签自动归类。公开详情、推荐运行态、改造、编辑、点赞和分享链路都必须显式识别 `edutainment`，不得回落到 RPG 默认处理。
- 影响范围：公开作品卡、发现页频道、作品号搜索、公开详情深链、分享、作品架聚合、后续儿童动作 Demo 模板的发布结果展示。
- 验证方式：执行第4线程定向单测、前端类型检查、ESLint 与编码检查；关闭 `VITE_ENABLE_EDUTAINMENT_ENTRY` 时确认精确 `寓教于乐` 作品不可通过任何公开入口访问。
- 关联文档：`docs/design/CHILD_MOTION_EDUTAINMENT_DISCOVER_ENTRY_2026-05-09.md`、`docs/prd/BABY_OBJECT_MATCH_EDUTAINMENT_TEMPLATE_PRD_2026-05-11.md`、`docs/technical/BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md`。

## 2026-05-10 儿童动作 Demo 视觉资产统一为绘本草地舞台

- 背景：儿童动作 Demo 需要从暗色科技风切换到更适合儿童互动的卡通绘本草地风格，并且要让背景、地面、UI、地面指示环和用户轮廓使用同一套 image-2 资源口径。
- 决策：热身舞台及后续儿童动作 Demo 场景、物品、UI 资源统一采用明亮卡通绘本草地视觉语言。真实资源默认输出到 `public/child-motion-demo/`。背景沿用 `picture-book-grass-stage.png`；地面、指示环、角色指示器和 UI 已拆分为用途专属资源：`picture-book-foreground-grass-v2.png`、`picture-book-ground-ring-v3.png`、`picture-book-character-outline-v4.png`、`picture-book-hud-strip-v2.png`、`picture-book-calibration-strip-v2.png`、`picture-book-start-panel-v2.png` 和 `picture-book-ui-button-v2.png`。其中角色指示器 v4 基于 v2 本地后处理为更细的白色描边样式，内部透明，耳朵、手指、脚趾等细节已弱化，页面显示尺寸相对上一版放大 50%。生成脚本固定为 `scripts/generate-child-motion-demo-assets.mjs`，并通过 `npm run assets:child-motion-demo` 调用 VectorEngine `gpt-image-2`；透明资源使用品红底生成后本地去背，中间源图仅保存在 `tmp/child-motion-demo-assets/`。在缺少 `VECTOR_ENGINE_BASE_URL` 或 `VECTOR_ENGINE_API_KEY` 时，只允许 dry-run 和 CSS 兜底，不伪造 live 生图结果。
- 影响范围：`src/index.css`、`src/components/child-motion-demo/ChildMotionWarmupDemo.tsx` 的舞台视觉层、儿童动作 Demo 技术文档、后续 image-2 资产生成流程。
- 验证方式：检查 `/child-motion-demo` 舞台是否在未生成资产时仍有可用草地绘本兜底；补齐 VectorEngine 私密配置后运行 `npm run assets:child-motion-demo -- --live` 或 `--live --only <asset-id>` 应能写出对应 PNG，并确认页面静态资源返回 `image/png`。若只调整透明去背、裁切或品红边缘，可运行 `npm run assets:child-motion-demo -- --live --postprocess-only --force --only <asset-id>` 复用源图后处理。页面接入时必须按资源原始比例等比使用，不得把方形软纸面板拉伸成 HUD、状态条或底部草坪。
- 关联文档：`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`、`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`。

## 2026-05-10 方洞挑战从创作页入口和作品架隐藏

- 背景：运营节奏要求创作页完全隐藏方洞挑战，不能只隐藏新建入口后仍从创作页作品架暴露已有方洞草稿或已发布作品。
- 决策：SpacetimeDB `creation_entry_type_config` 中 `square-hole.visible=false` 作为创作页统一开关；创作 Tab 模板入口、旧选择弹层、创作 Hub 卡带和创作页作品架都基于该开关隐藏方洞挑战。既有方洞详情、作品号、广场和运行态链路暂不删除，api-server 路由熔断只按 `open=false` 禁用玩法 API。
- 影响范围：SpacetimeDB 入口配置默认种子、`platformEntryCreationTypes`、`CustomWorldCreationHub`、`PlatformEntryFlowShellImpl` 以及创作入口相关文档和回归测试。
- 验证方式：执行入口配置、创作 Hub 和平台入口交互定向测试，确认看不到“方洞挑战” Tab、按钮和作品架条目。
- 关联文档：`docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md`、`docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md`。

## 2026-05-14 视觉小说从创作页入口隐藏

- 背景：当前创作页需要关闭视觉小说模板入口，不能继续在模板 Tab、旧选择弹层或创作 Hub 卡片中展示。
- 决策：SpacetimeDB `creation_entry_type_config` 默认种子中 `visual-novel.visible=false` 且 `open=false`；旧默认可见配置会被迁移为隐藏和关闭。前端继续只消费 `GET /api/creation-entry/config`，不得用硬编码恢复视觉小说模板入口。
- 影响范围：SpacetimeDB 入口配置默认种子、api-server 测试配置、创作页模板 Tab、创作 Hub 测试和创作入口文档。
- 验证方式：执行入口配置、创作 Hub、平台入口交互和 api-server 路由熔断定向测试，确认“视觉小说”不出现在创作页且 `/api/creation/visual-novel/*` 默认被熔断。
- 关联文档：`docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md`、`docs/technical/ADMIN_CREATION_ENTRY_SWITCH_CONFIG_2026-05-11.md`。

## 2026-05-20 RPG 创作入口开放

- 背景：RPG 文字冒险能力已经具备历史 custom-world 创作和运行闭环，但入口默认种子仍 `visible=false`，创作页不展示。
- 决策：SpacetimeDB `creation_entry_type_config` 默认种子中 `rpg.visible=true` 且 `open=true`，旧默认隐藏配置只在标题、subtitle、badge、图片、排序和开关完全匹配时迁移为可见可创建。`airp` 仍保持 AI RPG 占位，不接管当前 RPG 链路。结构化创作 / RPG JSON 链路默认关闭 Responses `web_search`，需要联网增强时才通过 `GENARRATIVE_RPG_LLM_WEB_SEARCH_ENABLED=true` 或 `GENARRATIVE_CREATION_AGENT_LLM_WEB_SEARCH_ENABLED=true` 显式启用；未开通工具的上游会返回 `ToolNotOpen`，不能把这类失败暴露成“模型返回结果解析失败”。
- 影响范围：创作入口默认种子、旧库入口纠偏、`api-server` 入口熔断、创作页模板 Tab、创作 Hub 测试、玩法链路文档和后端路由文档。
- 验证方式：执行入口配置、api-server 路由熔断、创作 Hub 和平台入口交互定向测试，确认“文字冒险”出现在创作入口，`/api/runtime/custom-world*`、`/api/story/*`、`/api/runtime/chat/*` 都按 `rpg` 入口开关熔断。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-05-10 运行态输入设备抽象层全项目通用化

- 背景：拼图运行态接入 mocap 后，鼠标/触控和 mocap 各自维护输入逻辑会导致合并大块、拖拽语义和取消会话行为不一致；后续其他玩法也需要复用体感、摇杆、键盘等设备输入。
- 决策：前端运行态输入统一通过 `src/services/input-devices/` 承接，设备适配层只输出 `press / move / release / tap / drop` 等通用语义和通用坐标；玩法组件自己解释目标对象、落点和业务动作，输入层不得写拼图等玩法专用规则。
- 影响范围：拼图运行态鼠标/触控/mocap 输入、后续运行态设备接入、运行态输入技术文档与相关前端回归测试。
- 验证方式：执行 `npm run test -- src\services\input-devices\runtimeDragInputController.test.ts`、`npm run test -- src\components\puzzle-runtime\PuzzleRuntimeShell.test.tsx`、`npm run typecheck` 和编码检查。
- 关联文档：`docs/technical/RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md`、`docs/technical/PUZZLE_RUNTIME_FRONTEND_LOGIC_REHOME_2026-05-02.md`。

## 2026-05-11 前端调试模式统一判断

- 背景：拼图 mocap 调试面板此前在运行态常驻展示，生产构建和正式体验里容易遮挡棋盘内容；后续其它局部诊断 UI 也需要统一的调试模式入口。
- 决策：前端新增 `src/config/debugMode.ts` 作为全局调试模式判断，默认跟随 Vite 开发态，允许 `VITE_DEBUG_MODE=true/false` 显式覆盖。2026-05-14 起，拼图运行态已临时移除 mocap 调用、体感光标和 mocap 调试面板；调试模式仍供其它局部诊断 UI 使用。
- 影响范围：前端局部调试 UI、拼图运行态 mocap 诊断面板、`.env.example` 和运行态输入技术文档。
- 验证方式：执行 `npm run test -- src\components\puzzle-runtime\PuzzleRuntimeShell.test.tsx`、`npm run typecheck` 和编码检查。
- 关联文档：`docs/technical/RUNTIME_INPUT_DEVICE_ABSTRACTION_2026-05-10.md`。

## 2026-05-10 儿童动作热身关直接消费 mocap 数据源

- 背景：儿童动作 Demo 不能只依赖浏览器摄像头状态和键鼠调试输入，否则真实硬件接入后会出现“mocap 在线但页面提示摄像头不可用”或“能看到画面但动作不推进”的卡点。
- 决策：热身关全流程直接接入 `useMocapInput`，通过本地 mocap WebSocket `/stream` 消费 `general.body.center_norm` 身体中心、`actions/action/gesture/gestures/event/name/type` 动作名，以及 `hands[]`、`leftHand/rightHand`、`left_hand/right_hand` 手部坐标；位置步骤由身体中心推进，`wave_greeting`、`wave_left_hand`、`wave_right_hand` 和 `jump_once` 由 mocap 手势/轨迹推进。浏览器摄像头只作为背景层，动作数据源状态优先展示，键鼠仍作为本地调试兜底。
- 影响范围：`src/services/useMocapInput.ts`、`src/components/child-motion-demo/ChildMotionWarmupDemo.tsx`、对应单测与热身关技术文档。
- 验证方式：执行 `npx vitest run src/services/useMocapInput.test.ts src/components/child-motion-demo/ChildMotionWarmupDemo.test.tsx src/components/child-motion-demo/childMotionWarmupModel.test.ts src/services/child-motion-demo/childMotionDebugInput.test.ts src/routing/appRoutes.test.ts`、`npx eslint ...`、`npm run typecheck`、`npm run check:encoding`，并确认 `http://127.0.0.1:8876/stream` WebSocket 可握手、`http://127.0.0.1:3000/child-motion-demo` 可访问。

## 2026-05-18 寓教于乐频道补充热身关入口

- 背景：用户希望在发现页的寓教于乐板块里直接看到热身关入口，而不是只依赖独立直达路由。
- 决策：`child-motion-demo` 作为寓教于乐频道的独立卡片展示，点击后直接进入 `/child-motion-demo`；该入口与 `宝贝爱画` 并列，仍复用现有独立热身关路由，不新增新的创作模板或运行态壳层。
- 影响范围：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
- 验证方式：执行入口回归测试、`npm run typecheck`、`npm run check:encoding`，并在发现页的寓教于乐频道确认热身关卡卡片可点击进入 `/child-motion-demo`。
- 关联文档：`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。

## 2026-05-09 GPT-image-2 图片生成统一迁移到 VectorEngine

- 背景：仓库内 RPG、拼图、方洞和本地模板脚本的 GPT-image-2 生图此前依赖 APIMart 图片网关；团队要求参考 VectorEngine Apifox `api-448710071`，后续不再使用 APIMart 执行 GPT-image-2 图片生成。
- 决策：所有 GPT-image-2 无参考图生图请求统一走 VectorEngine `POST /v1/images/generations`，有参考图请求走 `POST /v1/images/edits` multipart，基础配置读取 `VECTOR_ENGINE_BASE_URL` / `VECTOR_ENGINE_API_KEY` / `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`，上游模型使用 `gpt-image-2`，请求体不再携带 `official_fallback`。APIMart 只保留给创意 Agent 的 `gpt-5` Responses 文本/多模态链路。
- 影响范围：`api-server` 共享图片 helper、拼图图片生成、角色主图、RPG 场景图、开局 CG 故事板、方洞视觉资产、生产环境示例、gpt-image-2 本地 skill 和相关技术文档。
- 验证方式：执行 `npm run check:encoding`、`cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server custom_world_ai --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server character_visual --manifest-path server-rs/Cargo.toml`，并用 `npm run dev:api-server` + `/healthz` 做后端 smoke。
- 关联文档：`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`、`docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md`。

## 2026-05-21 GPT-image-2 参考图统一走 edits multipart

- 背景：VectorEngine Apifox 创建 `api-446794806` 与编辑 `api-446794807` 明确区分无参考图创建和有参考图编辑；仓库旧实现曾把参考图塞入 `gpt-image-2` generations 的 `image` 数组，导致与供应商当前契约不一致。
- 决策：所有 GPT-image-2 无参考图生成调用 `POST /v1/images/generations`，所有有参考图生成调用 `POST /v1/images/edits`，模型固定 `gpt-image-2`，参考图作为 multipart `image` part 传入；仓库不再调用 `gpt-image-2-all`。
- 影响范围：`api-server` 共享图片 helper、拼图图片生成、Match3D 封面重绘和容器 UI 图、gpt-image-2 本地 skill、玩法链路文档和后端架构文档。
- 验证方式：搜索仓库不应再出现 VectorEngine 图片编辑路径调用；执行 `cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server puzzle_vector_engine --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server match3d_background --manifest-path server-rs/Cargo.toml`。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-05-08 Hyper3D Rodin Gen-2 只通过后端安全代理接入

- 背景：需要接入 Hyper3D Rodin Gen-2 的文生 3D 模型与图生 3D 模型，但供应商 API Key 不能进入前端、文档或 Git；本次只是外部副作用代理，不需要新增平台真相表。
- 决策：Hyper3D 统一走 `api-server` 的 `/api/assets/hyper3d/*` 鉴权路由，配置只读取 `HYPER3D_BASE_URL` / `HYPER3D_API_KEY` / `HYPER3D_MODEL_REQUEST_TIMEOUT_MS` 及兼容 `RODIN_*` 变量；生成提交、状态查询和下载列表都由后端代理。首版不写 SpacetimeDB、不确认 `asset_object`，下载链接后续由调用方决定是否进入 OSS 资产链。
- 影响范围：`api-server` 外部服务配置、Hyper3D route、`shared-contracts` / TS contract、前端 service、生产环境示例和外部服务环境变量文档。
- 验证方式：执行 `cargo test -p api-server hyper3d --manifest-path server-rs/Cargo.toml`、`cargo test -p shared-contracts hyper3d --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run typecheck` 和编码检查；真实 API smoke 只在本地私密环境配置 key 后手动执行。
- 关联文档：`docs/technical/HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md`、`docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md`。

## 2026-05-08 APIMart 接口统一携带 `official_fallback`

> 2026-05-09 追认：本决策中的图片生成部分已被“GPT-image-2 图片生成统一迁移到 VectorEngine”覆盖；当前只保留 APIMart `gpt-5` Responses 文本/多模态链路继续显式携带 `official_fallback`。

- 背景：APIMart 的图片生成和 Responses 接口在仓库内分散于 `api-server`、`platform-llm` 和本地 skill 脚本，若只修单点，容易出现不同入口的上游请求体不一致。
- 决策：凡是仓库内调用 APIMart 的 OpenAI 兼容接口，请求体统一携带 `official_fallback: true`；其中图片生成请求直接固定写入，`platform-llm` 的 APIMart GPT-5 client 通过显式开关开启，不默认扩散到 Ark 等其它 provider。
- 影响范围：`server-rs/crates/api-server/src/openai_image_generation.rs`、`server-rs/crates/api-server/src/puzzle.rs`、`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/platform-llm/src/lib.rs`、`.codex/skills/gpt-image-2-apimart/` 和相关技术文档。
- 验证方式：图片生成与 creative-agent APIMart 路径的单测都应断言 `official_fallback` 已写入请求 JSON；编码检查和相关 Rust 测试应持续通过。
- 关联文档：`docs/technical/PUZZLE_APIMART_IMAGE_MODEL_ROUTING_2026-05-01.md`、`docs/technical/RPG_IMAGE_GENERATION_GPT_IMAGE_2_MIGRATION_2026-05-02.md`、`docs/technical/CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md`。

## 2026-05-07 server-rs Cargo 依赖集中到 workspace

- 背景：`server-rs` 多 crate 已稳定成 DDD workspace，成员 `Cargo.toml` 中重复散写第三方版本和本地 path 依赖，升级 SpacetimeDB SDK、`serde`、`reqwest`、`tokio` 等依赖时容易漂移。
- 决策：`server-rs/Cargo.toml` 的 `[workspace.dependencies]` 统一维护第三方依赖版本和 workspace 内部 crate path；成员 crate 默认使用 `{ workspace = true }`，只保留自身 feature、optional 或 target-specific 差异；不再新增 `sha1`，OSS 与阿里云 OpenAPI 签名统一走 `sha2::Sha256` 对应的 V4/V3 口径。
- 影响范围：`server-rs/Cargo.toml`、所有 `server-rs/crates/*/Cargo.toml`、`platform-oss`、`platform-auth`、后续新增 Rust crate 或新增 Rust 依赖的开发流程。
- 验证方式：修改 Cargo 配置后先执行 `cargo metadata --manifest-path server-rs\Cargo.toml --format-version 1 --no-deps`，再按影响范围执行 `cargo check`、DDD 边界检查和编码检查。
- 关联文档：`docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md`。

## 2026-05-08 资料页反馈提交必须走 Rust 后端与 SpacetimeDB

- 背景：`/profile/feedback` 首版页面曾只做前端成功态，无法沉淀到用户账号和数据库，也容易与主站平台主题脱节。
- 决策：反馈提交统一走鉴权 HTTP 路由 `POST /api/profile/feedback`，由 `api-server` 取当前 access token 用户，调用 `spacetime-client` facade，再通过 `spacetime-module` procedure 写入私有表 `profile_feedback_submission`；前端只负责输入采集、Data URL 预览和提交元数据，不再保存 `File[]` 作为外部契约。
- 影响范围：`src/components/platform-entry/PlatformFeedbackView.tsx`、`src/services/rpg-entry/rpgProfileClient.ts`、`packages/shared/src/contracts/runtime.ts`、`server-rs/crates/shared-contracts`、`api-server`、`module-runtime`、`spacetime-client`、`spacetime-module`、表目录与 bindings。
- 验证方式：前端定向测试应覆盖 Data URL 预览与 `/api/profile/feedback` 请求体；后端变更需同步 `migration.rs`、`SPACETIMEDB_TABLE_CATALOG.md` 和生成绑定；API smoke 使用 `npm run dev:api-server` 和 `/healthz`。
- 关联文档：`docs/prd/PROFILE_FEEDBACK_ENTRY_PRD_2026-05-08.md`、`docs/technical/PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md`。

## 2026-05-06 Maincloud 历史残留引用禁止再使用

- 背景：项目已经全面移除 Maincloud 运行口径，但历史脚本、测试名和文档仍可能让后续开发误用 `api-server:maincloud` 或 `GENARRATIVE_SPACETIME_MAINCLOUD_*`。
- 决策：`maincloud` / `Maincloud` / `MAINCLOUD` 相关代码、脚本、测试、环境变量、命令和文档要求全部视为历史残留，后续禁止新增、运行或引用；后端 API smoke 统一使用 `npm run dev:api-server` 并检查 `/healthz`。
- 影响范围：`AGENTS.md`、`docs/technical/`、`docs/project-memory/shared-memory/`、后端启动脚本、测试支撑和所有后续工程文档。
- 验证方式：新增或修改后端相关文档时，检查不得要求 `api-server:maincloud` 或 `GENARRATIVE_SPACETIME_MAINCLOUD_*`；触碰历史残留时同步删除或改名。
- 关联文档：`docs/technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md`、`docs/technical/SPACETIMEDB_CLOUD_CONFIG_REMOVAL_2026-05-02.md`。

## 2026-05-05 新手引导首版复用拼图本地运行时

- 背景：首次打开产品的新用户需要先体验输入想法、生成拼图、通关、登录保存、回到首页的闭环，但首版不应引入新的持久化表或独立玩法运行时。
- 决策：未登录首次访问由前端 localStorage 标记触发；生成入口走公开 BFF `POST /api/runtime/puzzle/onboarding/generate` 生成 1 关临时拼图；登录后保存走鉴权 BFF `POST /api/runtime/puzzle/onboarding/save`，由服务端创建当前用户拼图 agent session 并更新其草稿作品 profile；游玩阶段复用现有本地拼图运行时。
- 影响范围：平台入口首屏、新手引导 PRD、拼图 BFF、拼图作品契约与前端 puzzle runtime。
- 验证方式：未登录首次访问应展示新手引导；生成后只进入 1 关本地拼图；通关后登录保存应在当前用户拼图作品架出现草稿作品；不应产生 SpacetimeDB schema 变更。
- 关联文档：`docs/prd/FIRST_LAUNCH_PUZZLE_ONBOARDING_PRD_2026-05-05.md`。

## 2026-05-05 text-game 作为陶泥儿幕间文字游戏模板接入

- 背景：团队希望参考 MOKU / 幕间类 AI 文游，设计可在陶泥儿内落地的 AI 文字游戏模板，但不能把外部平台社区、支付、榜单、论坛、账号或私有存档迁入 Genarrative。
- 决策：新增 `text-game` 作为陶泥儿 AI 原生文字游戏模板口径，展示名可用“幕间”或“幕间文字”；它与 `visual-novel` 分离，重点是 AI GM、自由行动、状态后果、长期记忆、章节目标和轻量剧本模拟器；入口、作品、发布、资产、钱包、埋点、存档和广场全部复用陶泥儿平台接口；禁止新增 replay、外部社区、外部支付、外部榜单和私有存档系统。
- 影响范围：后续 `text-game` shared contracts、`module-text-game`、SpacetimeDB 表、`api-server` 路由、前端入口 / workspace / result / runtime、平台作品架和发现聚合。
- 验证方式：后续落地时确认路由使用 `/api/creation/text-game/*` 与 `/api/runtime/text-game/*`；确认正式业务真相在 Rust / SpacetimeDB 后端；确认没有 `replay` 能力和外部平台功能误入；确认 `text-game` 不复用 `visual-novel` step 契约作为运行态真相。
- 关联文档：`docs/prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md`。

## 2026-05-05 2048 玩法模板采用 `twenty-forty-eight` 工程域

- 背景：平台计划新增 2048 游戏玩法模板，需要同时适配前端 stage、HTTP 路由、Rust 模块、SpacetimeDB 表和公开作品号；裸 `2048` 不适合作为模块或文件命名前缀。
- 决策：面向用户展示名保持 `2048`，工程玩法 ID 固定为 `twenty-forty-eight`，Rust 模块与表前缀使用 `twenty_forty_eight`，公开作品号前缀使用 `TF-`；玩法按完整闭环设计，包含 Agent 创作、结果页、试玩、发布、公开运行、后端棋盘裁决、排行榜和作品架 / 广场接入。
- 影响范围：后续 SpacetimeDB 创作入口配置、平台 `SelectionStage`、前端 `twenty-forty-eight-*` 组件与 service、`module-twenty-forty-eight`、`shared-contracts`、`spacetime-module` 表、`spacetime-client` facade、`api-server` 路由、作品号和 PRD 索引。
- 验证方式：后续落地时确认用户可见标题为 `2048`，代码、路由和表统一使用 `twenty-forty-eight` / `twenty_forty_eight`；移动、合并、生成新方块、目标达成、失败和榜单成绩由后端正式裁决，前端不伪造分数或目标达成。
- 关联文档：`docs/prd/AI_NATIVE_2048_GAMEPLAY_TEMPLATE_PRD_2026-05-05.md`。

## 2026-05-05 幸存者类玩法作为平台模板接入

- 背景：平台继续扩展新玩法模板，需要把幸存者 / 割草 / 轻度 Roguelite 类玩法纳入统一创作中心、作品架、广场和运行态体系，避免再起一套独立小游戏工程。
- 决策：新增 `survivor` 作为 Genarrative 平台玩法模板，统一使用 `server-rs + Axum + SpacetimeDB`，创作端、结果页、试玩、发布和运行态都复用平台接口；前端只负责表现和高频模拟，不承接正式规则真相。
- 影响范围：`docs/prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md`、后续 `survivor` shared contracts、前端入口 / result / runtime、`server-rs` DDD 分层、SpacetimeDB 表设计和平台作品闭环。
- 验证方式：后续落地时检查 `survivor` 入口、session、work profile、runtime run、checkpoint、升级候选和结算接口是否都落在平台统一链路内，并确认没有新增独立小游戏壳层。
- 关联文档：`docs/prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md`。

## 2026-05-05 视觉小说 TXT 玩法只作为平台模板接入且删除回放

- 背景：`Interactive-fiction-backend` 与 `Interactive-fiction-frontend` 是完整平台类工程，其中 TXT / Galgame 玩法可借鉴，但账号、商城、后台、公开市场、回放等平台能力不能迁入 Genarrative。
- 决策：`visual-novel` 只作为 Genarrative 视觉小说模板接入，保留想法 / 文档 / 空白创建、世界观 / 角色 / 场景 / 剧情阶段编辑、视觉小说 step 运行时、历史和重生成等模板能力；入口、作品、发布、资产、钱包、存档和广场全部使用 Genarrative 平台接口；彻底删除回放、分享回放、回放编译、回放路由、回放表和回放 UI。
- 影响范围：视觉小说 PRD、旧 TXT 文档口径、后续 `visual-novel` shared contracts、前端入口 / result / runtime、`server-rs` DDD 分层、SpacetimeDB 表设计和平台存档接入。
- 验证方式：后续落地时扫描前端、后端、契约、表和文档，确认不存在 `replay` 能力；确认视觉小说没有迁入外部平台账号、订单、会员、促销、后台、公开市场或私有存档系统；确认后端落在 `server-rs + Axum + SpacetimeDB`。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/prd/TXT_MODE_CORE_GAMEPLAY_PRD_2026-04-20.md`、`docs/technical/TXT_MODE_VISUAL_NOVEL_MIGRATION_EXECUTION_PLAN_2026-04-20.md`。

## 2026-05-05 视觉小说 VN-02 表与 spacetime-client facade 收口

- 背景：`visual-novel` 后续 API、创作工作台和运行时需要稳定的 SpacetimeDB schema 与 Rust facade，且必须延续“无回放、无私有存档”的产品边界。
- 决策：视觉小说首批数据库只落六张表：`visual_novel_agent_session`、`visual_novel_agent_message`、`visual_novel_work_profile`、`visual_novel_runtime_run`、`visual_novel_runtime_history_entry`、`visual_novel_runtime_event`；`visual_novel_runtime_event` 是 `public event` 审计事件表，不是 replay 数据源；运行历史只保存继续体验与历史重生成需要的 typed step 和快照哈希。`api-server` 后续接入必须经 `spacetime-client/src/visual_novel.rs` typed facade，不直接依赖生成 bindings。
- 影响范围：`server-rs/crates/spacetime-module/src/visual_novel.rs`、`migration.rs`、`server-rs/crates/spacetime-client/src/visual_novel.rs`、`module_bindings/`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`、VN-05 API 联调。
- 验证方式：执行 `npm run spacetime:generate -- --rust-only`、`cargo check -p spacetime-module`、`cargo check -p spacetime-client`、`npm run check:encoding`；扫描视觉小说 schema / facade / 表目录确认没有 `replay` 表、路由或私有 save 表。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。

## 2026-05-05 视觉小说 VN-07 前端创作闭环按阶段边界落地

- 背景：`visual-novel` 模板需要先完成创作工作台与结果页，真实生成和正式玩家 runtime 仍依赖 VN-05 后端路由。
- 决策：VN-07 前端只接入口、Agent 工作台、可编辑 `VisualNovelResultDraft` 结果页和测试 run；`blank` 起点直接生成本地空白草稿进入结果页，`idea` / `document` 继续调用 `/api/creation/visual-novel/sessions`；结果页保存先更新当前 session 草稿，显式“编译草稿”才调用 `/compile`，测试 run 在真实 runtime 不可用时降级为本地 test run。
- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/visual-novel-creation/`、`src/components/visual-novel-result/`、`packages/shared/src/contracts/visualNovel.ts`、视觉小说 PRD。
- 验证方式：执行前端 typecheck、视觉小说工作台 / 结果页定向测试和编码检查；确认未新增 replay、作品聚合或正式 runtime 能力。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`。

## 2026-05-07 视觉小说 VN-11 负向扫描门禁

- 背景：视觉小说 TXT 模板进入收口后，需要一个可重复执行的守门方式，避免工程代码误入回放能力或外部平台功能。
- 决策：新增 `npm run check:visual-novel-vn11`，由 `scripts/check-visual-novel-vn11-negative-scan.mjs` 扫描 `src/`、`packages/shared/src/`、`server-rs/crates/`、`docs/` 与 `docs/project-memory/shared-memory/`；工程代码中不允许出现 replay / 回放 / 录制 / 复盘类直出命中；外部平台能力误入只在视觉小说实现路径内检查，避免把平台已有账号、会员、后台等能力误判为视觉小说迁入。
- 影响范围：视觉小说 VN-11 验收、后续 `visual-novel` 增量改动、同类新玩法负向扫描脚本。
- 验证方式：执行 `npm run check:visual-novel-vn11`，报告写入 `docs/audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md`；当前扫描结论为工程代码无回放类直出命中，视觉小说实现路径无外部平台能力误入。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/audits/VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md`。

## 2026-05-07 视觉小说 VN-12 采用单独验收门禁脚本

- 背景：VN-12 是视觉小说模板的全链路联调与自动化验收收口任务，需要把关键路径、API smoke、前端测试和报告输出固化成可复跑门禁，避免后续改动只靠手工口述结论。
- 决策：新增 `npm run check:visual-novel-vn12`，由 `scripts/check-visual-novel-vn12-acceptance.mjs` 校验 PRD、VN-11 报告、关键前端测试、视觉小说 service client、`api-server` / `module-visual-novel` / `shared-contracts` 相关文件和路由命中，并生成 `docs/audits/VN12_FULL_CHAIN_ACCEPTANCE_REPORT_2026-05-07.md`。
- 影响范围：VN-12 验收、视觉小说后续回归、同类玩法的收口门禁模式。
- 验证方式：执行 `npm run check:visual-novel-vn12 -- --write-report`，报告应覆盖自动化验收清单、API smoke、前端关键路径、桌面/移动端检查说明和已执行命令；若脚本失败，直接回流到对应 owner 修复。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/audits/VN12_FULL_CHAIN_ACCEPTANCE_REPORT_2026-05-07.md`。

## 2026-05-07 视觉小说 VN-13 文档与交接收口

- 背景：视觉小说模板主链已经落地完成，需要把 PRD、表目录、prompt 工具说明、负向扫描报告和维护经验收成新开发者可直接接手的一组文档，避免后续仍回头查旧 TXT 迁移方案。
- 决策：视觉小说后续维护的正式入口固定为 `AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`SPACETIMEDB_TABLE_CATALOG.md`、`VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md`、`VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`、`VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md` 和 `VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md`；旧 TXT 迁移文档仅保留历史参考地位。
- 影响范围：视觉小说 PRD 收口、技术文档索引、经验文档索引、项目共享记忆和后续维护阅读顺序。
- 验证方式：打开上述文档即可获得当前实现边界、表目录、Prompt 口径、负向扫描和维护经验；后续维护不需要把旧 TXT 平台工程文档重新当作实现目标。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`、`docs/experience/VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md`。

## 2026-05-05 平台移动端一级 Tab 改为推荐/发现/创作/草稿/我的

- 背景：移动端平台入口需要从旧“首页/排行/创作/存档/我的”调整为更直接的推荐流和应用式底部导航。
- 决策：前端内部继续复用 `PlatformHomeTab` 的 `home/category/create/saves/profile` 状态值，但用户看到的一级 Tab 分别为“推荐/发现/创作/草稿/我的”；`home` 直接展示公开推荐流，`category` 承载发现页及排行子 Tab，`saves` 承载草稿作品架，原存档结构并入“我的-玩过”弹层。
- 影响范围：平台入口导航、移动端推荐页、发现页子 Tab、创作中心作品架、个人页玩过弹层、相关设计文档。
- 验证方式：检查移动端底部导航文案和顺序，确认登录态为“推荐/发现/创作/草稿/我的”，未登录态为“推荐/创作/发现”且创作居中；“推荐”无搜索/频道栏直出作品流，“发现”包含搜索/推荐/今日/分类/排行，“创作”只显示新建入口，“草稿”显示作品架，“我的-玩过”可恢复存档。
- 关联文档：`docs/design/PLATFORM_MOBILE_RECOMMEND_DISCOVER_DRAFT_TAB_REDESIGN_2026-05-05.md`。

## 2026-05-14 推荐页卡片主视觉优先于底部作者热区

- 背景：移动端推荐页的卡片底部作者与操作区如果过高，会压缩作品运行态可视高度，影响首屏沉浸感。
- 决策：推荐页卡片底部信息区保持紧凑固定高度，切换手势仍只绑定在该区域；视觉主体高度优先扩展，不再让作者信息区占用过多首屏空间。
- 影响范围：`src/components/rpg-entry/RpgEntryHomeView.tsx` 的推荐页卡片布局，以及 `src/index.css` 中的推荐页卡片热区样式。
- 验证方式：移动端推荐页首屏应明显看到更大的作品内容区，底部作者信息区只保留紧凑一条，不再明显挤压运行态。
- 关联文档：`docs/technical/PLATFORM_MOBILE_RECOMMEND_CARD_SAFE_SWIPE_LAYOUT_2026-05-12.md`。

## 2026-05-05 创作 Tab 固定为智能创作首页，草稿 Tab 承接旧作品架

- 背景：创作首页需要变成面向对话式生成的智能创作页，旧模板卡和作品架继续保留但不应再占据创作首屏。
- 决策：`create` 只承载 `CreativeAgentHome` 智能创作首页与会话流，顶部品牌栏、问候、快捷胶囊、底部输入框和左侧抽屉是主结构；旧的新建作品类型卡不再在 `create` 里展示。原本的 RPG / 拼图 / 大鱼 / Match3D / 方洞 / 视觉小说作品架统一归到 `saves` 草稿 Tab。
- 影响范围：平台创作页布局、创作首页抽屉、草稿页作品架、相关交互测试、旧创作入口 helper。
- 验证方式：移动端点击“创作”直接看到智能创作首页；点击“草稿”看到旧作品架；旧模板入口不再从创作页出现。
- 关联文档：`docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md`。

## 2026-05-05 创意互动内容生成 Agent 采用 LangChain-Rust 六模块闭环

- 背景：需要支持用户输入文字、图片或文档后，先理解创作意图，再从多个模板候选中选择一个，并把内容填入拼图等目标玩法草稿契约中。
- 决策：新增方案改为基于 LangChain-Rust 的六模块 Agent 架构，核心模块是感知、思考、记忆、行动、反思、协作；首版只支持拼图玩法，但必须先展示多个拼图子模板候选，用户选择某个模板后，再确认该模板下的关卡模式、关卡数和预计积分范围，确认后才生成草稿；Agent 理解、规划和修订统一使用 APIMart Responses `gpt-5` 并支持文本/图像多模态输入；Agent 创作方式就是填充和修订模板草稿字段，表单化创作页与 Agent 自然语言修订都操作同一份 `PuzzleResultDraft`，且草稿可编辑字段只收敛为 `workTitle`、`workDescription`、`workTags`、`levels[].levelName`、`levels[].pictureDescription`、`levels[].pictureReference`；其中 `pictureReference` 已采用 `PuzzleDraftLevel.pictureReference` / Rust `picture_reference` 正式字段方案，不再走 metadata 过渡；单关卡/多关卡图片生成通过拼图模块 Tool 与模板协议实现；生成好的内容必须可立即试玩。
- 影响范围：创作中心入口、`platform-agent`、`module-creative-agent`、`module-puzzle` 拼图模板协议和工具、`shared-contracts`、`api-server` creative facade、SpacetimeDB creative agent 表、拼图玩法工具。
- 验证方式：后续落地时以创意互动内容生成 Agent 技术方案和 Phase 1 PRD 为编码依据，优先完成拼图 Phase 1，并执行 shared contracts、module、platform-agent、api-server、前端 typecheck 与编码检查。
- 关联文档：`docs/technical/CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md`、`docs/prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md`。

## 2026-05-05 creative-agent Task C 首版平台 PoC 已落地

- 背景：Phase 1 的平台侧需要先把 LangChain-Rust 适配层、APIMart `gpt-5` 多模态 Responses 请求和工具注册边界立起来，才能继续接 API facade。
- 决策：新增 `server-rs/crates/platform-agent` 作为独立 workspace crate，保留项目自有 `CreativeAgentExecutor`、工具注册表、回调事件和 mock executor；`platform-llm` 的 Responses 请求体扩展为可序列化 `input_text` / `input_image` content part。
- 影响范围：`server-rs/Cargo.toml`、`server-rs/crates/platform-agent`、`server-rs/crates/platform-llm`、任务 C 的后续 API / SSE 接入。
- 验证方式：`cargo check -p platform-agent`、`cargo test -p platform-agent`、`cargo test -p platform-llm responses_multimodal` 已通过。
- 关联文档：`docs/technical/CREATIVE_INTERACTIVE_CONTENT_AGENT_TECHNICAL_SOLUTION_2026-05-05.md`。

## 2026-05-05 creative-agent Task E API / SSE facade 已落地

- 背景：Phase 1 需要先把创意 Agent 的 HTTP/SSE 门面接入 Rust `api-server`，用于前端工作区调用和拼图模板确认闭环。
- 决策：`api-server` 挂载 `/api/runtime/creative-agent/*` 六个鉴权路由；creative session 在 Task D 表未收口前暂存在 `api-server` 运行态并按 authenticated user 校验 owner；未确认模板前不创建拼图 session，`confirm-template` 后才通过既有 `spacetime-client` 创建/编译 `puzzle_agent_session`；`gpt-5` 请求只从 `APIMART_BASE_URL` / `APIMART_API_KEY` 构造专用 Responses client，不复用通用 `GENARRATIVE_LLM_API_KEY`。
- 影响范围：`server-rs/crates/api-server/src/creative_agent.rs`、`creative_agent_sse.rs`、`app.rs`、`state.rs`、`module-puzzle` creative template/tool、Phase 1 PRD。
- 验证方式：`cargo check -p api-server`、`cargo test -p module-puzzle creative`、`cargo test -p api-server creative_agent`、`npm run dev:api-server` 后检查 `/healthz`、`POST /api/runtime/creative-agent/sessions`、`POST /api/runtime/creative-agent/sessions/{sessionId}/messages/stream`。
- 关联文档：`docs/prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md`。

## 2026-05-10 视觉小说入口收敛为单句创作 + 画风选择

- 背景：视觉小说入口页要对齐抓大鹅式的线性创作入口，只保留最小可用输入，避免再暴露文档 / 空白 / 对话式工作台。
- 决策：入口页只展示一句话创作输入框和横向视觉画风卡片；画风通过 `seedText` 追加 `视觉画风` 和 `画风要求` 两行透传给既有创作链路；点击生成后先进入 `visual-novel-generating` 过程页，再自动进入 `visual-novel-result`。画风卡片主视觉固定消费 `public/visual-novel-style-references/` 下由 VectorEngine `gpt-image-2` 生成的静态参考图，不在前端运行时现场调用生图接口。
- 影响范围：`VisualNovelAgentWorkspace`、`visualNovelEntryGeneration`、`PlatformEntryFlowShellImpl`、视觉小说 PRD 和创作 Tab 设计文档；不新增后端字段或数据库结构。
- 验证方式：执行 `npm run test -- VisualNovelAgentWorkspace`、视觉小说工作台相关 ESLint、`npx prettier --check` 和 `npm run check:encoding`；`npm run typecheck` 若失败需先区分是否来自无关 Match3D / RPG 既有改动。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/design/PLATFORM_CREATE_TAB_CREATIVE_AGENT_HOME_2026-05-05.md`。

## 2026-05-10 用户标签只做后端白名单投影

- 背景：运营邀请码需要给账号打标签，但标签默认不能暴露到前端通用用户资料；拼图排行榜仅需展示特定标签。
- 决策：`user_account.user_tags` 保存账号标签，数据库默认 `None`，业务按空数组读取；后台预置邀请码使用后授予的标签不再使用独立列，统一存放并解析自 `profile_invite_code.metadata_json.userTags`，兼容读取 `user_tags`。通用登录态和个人资料不返回原始标签。首版只在拼图排行榜 `visibleTags` 中白名单投影 `北科`。
- 影响范围：用户认证表、邀请码后台、邀请兑换事务、拼图排行榜响应和 UI。
- 验证方式：表结构变更需同步 `migration.rs`、`SPACETIMEDB_TABLE_CATALOG.md` 和 SpacetimeDB bindings；后端运行 `cargo check -p api-server`，后台运行 `npm run admin-web:typecheck`。
- 关联文档：`docs/technical/USER_TAG_INVITE_AND_PUZZLE_LEADERBOARD_2026-05-10.md`。

## 2026-05-10 抓大鹅草稿元信息由 gpt-4o 生成

- 背景：抓大鹅草稿生成需要基于入口题材设定生成作品名称，结果页作品信息要对齐拼图草稿，不再把封面和作品名称拆成两个模块。
- 决策：`match3d_compile_draft` 使用 `gpt-4o` 生成 `gameName` 与 3 到 6 个标签；`summary` 默认保持空字符串；标签可由结果页 `作品信息` Tab 手动编辑或再次 AI 生成。草稿生成会按难度产出多视角 2D 物品图片并写入 `generated_item_assets_json`，运行态必须优先消费 `generatedItemAssets[].imageViews[]`，默认积木只做兜底。
- 影响范围：`api-server` Match3D 编译、Match3D works 标签接口、结果页 `作品信息` 与 `素材配置` Tab、运行态 `Match3DRuntimeShell` / `Match3DPhysicsBoard`、生成进度和 Match3D 技术文档。
- 验证方式：执行 `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`、`npm run test -- src/services/miniGameDraftGenerationProgress.test.ts`、`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`，并用 `npm run dev:api-server` 检查 `/healthz`。
- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`；`docs/technical/MATCH3D_RODIN_ASSET_TAB_2026-05-10.md` 仅作历史参考。

## 2026-05-12 抓大鹅物品种类从消除次数中拆出并改为 2D 五视角素材

- 背景：结果页草稿素材已经能生成和预览，但标准 / 硬核难度仍可能按 `clearCount` 误判需要 12 / 20 种素材，且继续生产 GLB 会拉长草稿生成耗时。
- 决策：难度配置统一使用运行态 `物品种类`：轻松 3、标准 9、进阶 15、硬核 20；历史硬核 `clearCount=20` 在运行态仍升为 21 组三消，但类型池最多 20 种。新草稿和批量新增不再调用 Rodin、不再生成 GLB。每次固定从 `2K 1:1`、`10*10` 物品 spritesheet 解析并持久化 20 个物品、每个 5 个不同 2D 形态，物品信息列表全部展示 20 个；持久化行列索引按每行两种物品计算，不能超过 `1..=10`。发布必须校验已生成 `image_ready` 且有 `imageViews[]`、首图引用或可解析的物品 spritesheet 满足当前难度；试玩通过 `itemTypeCountOverride` 自动降到可用 2D 素材数量。历史模型字段只作为旧数据兼容，不再进入新生产链路。
- 影响范围：Match3D 结果页、运行态启动契约、`module-match3d` 初始 run 生成、SpacetimeDB start input / restart、发布校验和 Match3D 技术文档。
- 验证方式：`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`、`cargo test -p module-match3d --manifest-path server-rs\Cargo.toml`、相关后端 check / tests。
- 关联文档：`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 2026-05-07 移动端整页缩放由入口统一锁定

- 背景：移动端游戏式页面如果允许浏览器整页缩放，容易把固定画布、HUD 和底部操作区一起放大或缩小，破坏操作节奏。
- 决策：主站入口统一使用 `viewport` 锁定 `minimum-scale=1.0`、`maximum-scale=1.0`、`user-scalable=no` 和 `viewport-fit=cover`，并在应用启动时调用 `lockMobileViewportZoom()` 拦截 iOS `gesture*` 与多指 `touchmove` 触发的页面级缩放。
- 影响范围：主站 `index.html`、`src/main.tsx`、后续所有依赖主入口的移动端游戏/画布页面；不要求每个画布组件重复实现缩放锁定。
- 验证方式：移动端打开主站后，双指捏合和快速双击不应再缩放整页；单指滚动、点击和组件内交互保持正常。
- 关联文档：`docs/experience/MOBILE_UI_DEV_EXPERIENCE.md`。

## 2026-05-07 视觉小说 VN-10 资产引用统一走平台资产对象

- 背景：视觉小说文档输入、封面、场景背景、角色立绘和音乐需要接入平台资产链路，不能在前端状态或 SpacetimeDB 中保存大 Data URL、二进制对象或外部 R2 路径。
- 决策：VN 上传统一复用 `/api/assets/direct-upload-tickets`、OSS 直传、`/api/assets/objects/confirm`、`/api/assets/read-url`。文档上传后只把 `assetObjectId` 放入 `sourceAssetIds`，`seedText` 仅放截断摘要；封面、场景、角色、音乐只写 `/generated-*` 引用和平台 asset id。角色立绘写入 `imageAssets[].source = platform_asset`。运行时图片渲染统一使用 `ResolvedAssetImage` 换签。
- 影响范围：`src/services/visual-novel-creation/visualNovelAssetClient.ts`、`VisualNovelAgentWorkspace`、`VisualNovelResultView`、`VisualNovelRuntimeShell`、`server-rs/crates/api-server/src/visual_novel.rs`。
- 验证方式：VN 定向前端测试、`npm run typecheck`、`npm run check:encoding`、`cargo test -p api-server visual_novel`、`cargo test -p api-server creation_agent_document_input`。
- 关联文档：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`。

## 2026-05-04 在仓库 `.hermes/` 中建立团队共享记忆

- 背景：团队有 3 名开发人员，均在各自本地安装 Hermes，并需要独立拉取仓库、修改代码、本地测试；团队希望形成共享的长期项目记忆。
- 决策：不共享个人 `~/.hermes`，先在 Genarrative 仓库内使用 `.hermes/` 保存可 Git 同步的团队共享记忆、计划和未来 skills。
- 影响范围：`AGENTS.md`、`.hermes/README.md`、`docs/project-memory/shared-memory/`。
- 验证方式：任一开发者拉取仓库后，在项目根目录启动 Hermes，均可读取同一套 `docs/project-memory/shared-memory/` 文件。
- 关联文档：`.hermes/README.md`、`docs/project-memory/shared-memory/team-conventions.md`。

## 2026-04-25 后端唯一落地口径固定为 Rust / SpacetimeDB

- 背景：项目经历过 Node/Express/PostgreSQL、Go 试验、Rust/SpacetimeDB 等多条后端路线，旧路线文档容易造成开发歧义。
- 决策：新功能以后端当前基线为准：HTTP 门面使用 Rust `api-server` / Axum，业务真相使用 SpacetimeDB，领域和契约在 `server-rs` 多 crate 分层维护。
- 影响范围：所有后端、数据真相、运行时状态、创作结果、用户系统、资产、任务、埋点、后台 API 等相关开发。
- 验证方式：开发前优先阅读 `CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`；旧 `server-node`、Express、PostgreSQL、Go 方向只允许作为迁移参考。
- 关联文档：`docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`、`AGENTS.md`。

## 2026-05-18 寓教于乐电视端入口概念图采用横屏乐园地图方案

- 背景：寓教于乐板块需要面向电视端 / 横屏大屏的一组图形化入口概念图，既要像儿童乐园地图，又要和现有绘本插画风一致。
- 决策：概念探索优先采用横屏乐园地图结构，推荐顺序为环形乐园岛、展开绘本地图、云朵空中岛、草地舞台地图；生成时优先复用 `public/child-motion-demo/picture-book-grass-stage.png` 作为风格参考，输出仅保留在 `output/imagegen/` 概念目录中，不直接进入正式资源目录。
- 影响范围：寓教于乐板块视觉探索、后续前端入口设计、`scripts/generate-edutainment-tv-map-concepts.mjs`、相关设计文档。
- 验证方式：概念图需保持无文字、无真实品牌 IP、无暗色科技风，并与现有草地绘本资源在配色和笔触上保持一致。
- 关联文档：`docs/design/【前端体验】寓教于乐电视端乐园地图入口概念图-2026-05-18.md`。

## 2026-04-28/29 server-rs DDD 分层与契约矩阵冻结

- 背景：server-rs 模块多、上下文多，需防止领域规则、SpacetimeDB 表、HTTP BFF、前端临时逻辑互相污染。
- 决策：按 DDD 总纲和 G1 契约/路由矩阵开发：`module-*` 承载领域，`spacetime-module` 承载表和事务，`spacetime-client` 承载 facade，`api-server` 承载 HTTP/SSE/BFF，`platform-*` 承载外部副作用，`shared-contracts` 承载 DTO。
- 影响范围：server-rs 全部 crate、前端 API client、SpacetimeDB schema、旧接口清理。
- 验证方式：执行任务前对照 DDD 总纲、并行任务清单、G1 矩阵；提交前运行相关 DDD 边界检查和定向测试。
- 关联文档：`SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md`、`SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`、`SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md`。

## SpacetimeDB 表结构变更必须显式维护迁移与表目录

- 背景：SpacetimeDB 的 schema 迁移模型不同于 PostgreSQL，部分变更会触发冲突或拒绝自动迁移。
- 决策：凡涉及 table、reducer、procedure、row shape 或 binding 变化，必须同步 `migration.rs`、表目录和生成绑定；涉及 private 表迁移时按 JSON 导入导出和分片导入流程处理。
- 影响范围：`server-rs/crates/spacetime-module`、`spacetime-client` bindings、`SPACETIMEDB_TABLE_CATALOG.md`、部署/发布脚本。
- 验证方式：发布前检查 `SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md` 清单，更新 `SPACETIMEDB_TABLE_CATALOG.md`，执行生成绑定和相关测试。
- 关联文档：`SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`、`SPACETIMEDB_TABLE_CATALOG.md`、`SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md`。

## 生产部署切换到 systemd + Nginx + 自托管 SpacetimeDB

- 背景：旧一体化启动脚本和历史 Jenkinsfile 已不再是生产发布唯一入口。
- 决策：生产部署以 systemd 托管 SpacetimeDB 与 Rust `api-server`，Nginx 负责站点和代理，生产 Jenkinsfile 按 web/api/stdB module/build/deploy/publish 拆分。
- 影响范围：部署脚本、服务器目录、维护模式、Jenkins、Nginx、systemd 服务。
- 验证方式：生产发布、服务器配置、Jenkins Job 重建或回滚时，先看 `PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。
- 关联文档：`PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。

## 2026-05-19 release server provision 需预装 Nginx Brotli 动态模块

- 背景：release 服务器的 Nginx 站点配置已经预留 Brotli 指令占位，但当前 provision 流程只装了基础构建依赖，没有把 Ubuntu apt 下的 brotli 动态模块一起装上，导致 release 机器即使模板支持也可能无法启用 Brotli。
- 决策：`scripts/jenkins-server-provision.sh` 在 apt 系统上额外安装 `libnginx-mod-http-brotli-filter` 与 `libnginx-mod-http-brotli-static`，然后继续用会先 `include /etc/nginx/modules-enabled/*.conf` 的临时 `nginx -t` 配置做能力探测；非 apt 系统仍只做探测不强制安装。不要用 `nginx -V` 判断该动态模块是否可用。
- 影响范围：`jenkins/Jenkinsfile.production-server-provision`、`scripts/jenkins-server-provision.sh`、`deploy/nginx/README.md`、release 服务器 Nginx 初始化。
- 验证方式：server provision 跑过后，目标机应同时具备 Brotli 模块包与 `nginx -t` 可接受的 brotli 指令；再由 Nginx 模板启用对应指令。
- 关联文档：`deploy/nginx/README.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-05-19 server provision 下载件固定由 Windows 节点断点续传

- 后续更新：该口径已被 `2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost` 取代；当前不再维护 Windows 下载阶段和 `.download` 断点续传 helper。
- 背景：`SpacetimeDB` 和 `otelcol-contrib` release 资产在 Linux 目标机直接下载很慢；改到 Windows Jenkins 节点下载后，GitHub 大文件仍可能出现 `curl: (18)` 响应体截断。
- 决策：`Genarrative-Server-Provision` 的 `Download Provision Tool Archives` 阶段继续只在 Windows 节点下载，再通过 `stash/unstash` 交给目标 Linux agent；下载前查 GitHub release asset `digest`，本地最终文件 SHA256 命中即跳过，`.download` 临时文件用于 `curl -C -` 断点续传，完整返回但 digest 不匹配才清理重下。
- 影响范围：`jenkins/Jenkinsfile.production-server-provision`、目标机 `scripts/prepare-server-provision-tools.sh` 的本地下载件消费路径、生产 provision 运维排障。
- 验证方式：Windows 下载日志应出现 digest 查询、已存在校验跳过或 `curl 断点续传`；Linux 目标机阶段只使用 `provision-tool-downloads/` 中的 tarball，不访问 GitHub 下载地址。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-06-01 生产 Jenkins 流水线统一改为 Linux 优先并先查 localhost

- 背景：生产流水线长期混用 Windows、Linux 和公网 Git 入口，导致构建 / 发布 / provision 的 checkout 口径分叉；同时 `Genarrative-Server-Provision` 还残留过 Windows 下载 helper，和当前 Linux 构建 / 发布部署路径不一致。
- 决策：生产 Jenkins 流水线统一把执行节点收口到 Linux label，`Pipeline script from SCM` 仍保留公网域名，但所有生产流水线首次 `GitSCM checkout` 先尝试 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后再回退到 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；`Genarrative-Stdb-Module-Build`、`Genarrative-Server-Provision`、`Genarrative-Notify-Email` 也都切到 Linux 节点。`Genarrative-Server-Provision` 的工具准备不再依赖 Windows helper，而是在 Linux build 节点直接生成 `provision-tools/` 后交给后续 Linux 发布阶段。
- 影响范围：`jenkins/Jenkinsfile.production-*`、`scripts/jenkins-checkout-source.sh`、`scripts/prepare-server-provision-tools.sh`、生产运维文档。
- 验证方式：扫描 Jenkinsfile 时应看到 `linux && genarrative-*` 节点和 localhost-first checkout 口径；`Genarrative-Server-Provision` 日志不再出现 Windows 相关 helper 输出，工具准备阶段应直接生成 `provision-tools/`。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-06-01 Web Deploy 只从 Jenkins 构建归档取发布包

- 背景：`Genarrative-Web-Deploy` 曾在发布阶段读取构建机本地缓存目录，release 目标还可能通过 `rsync` 回构建机拉取 `web.tar.gz`，导致发布依赖机器拓扑和本地路径。
- 决策：`Genarrative-Web-Build` 直接归档 `build/<version>/web.tar.gz`、`web.tar.gz.sha256` 和 `release-manifest.json`；`Genarrative-Web-Deploy` 只使用 Jenkins `copyArtifacts` 从指定上游构建复制完整 Web 发布包，不再维护 `WEB_ARTIFACT_ROOT`、`WEB_ARTIFACT_SYNC_HOST` 或 `web-artifact-pointer.txt`。
- 影响范围：`jenkins/Jenkinsfile.production-web-build`、`jenkins/Jenkinsfile.production-web-deploy`、Web 发布排障流程。
- 验证方式：deploy 工作区直接存在 `build/<version>/web.tar.gz`、`web.tar.gz.sha256` 和 `release-manifest.json`，随后由 `scripts/deploy/production-web-deploy.sh` 校验 checksum 并解压发布。
- 关联文档：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 个人任务与埋点首版边界冻结

- 背景：“我的”Tab、任务、奖励、钱包和埋点涉及用户、运营、分析多条链路，需要避免范围泛化。
- 决策：埋点原始事实进入 `tracking_event`，聚合投影进入 `tracking_daily_stat`；个人任务配置/进度/领奖/钱包分别进入 `profile_task_config`、`profile_task_progress`、`profile_task_reward_claim`、`profile_wallet_ledger`；首版个人任务 scope 仅支持 `user`。
- 影响范围：用户侧任务中心、后台任务配置、运营查询、埋点查询、钱包流水。
- 验证方式：非 `user` scope 的个人任务配置应被 API 和领域构造层拒绝；任务查询与埋点查询分别放在 `docs/operations/` 和 `docs/tracking/`。
- 关联文档：`PROFILE_TASK_AND_TRACKING_SYSTEM_2026-05-03.md`、`RUNTIME_PROFILE_TASK_SCOPE_2026-05-04.md`、`ANALYTICS_DATE_DIMENSION_IMPLEMENTATION_2026-05-04.md`。

## 普通 route tracking 先写本机 outbox 再批量入库

- 背景：公开作品列表压测中，成功响应后的全局 route tracking 会逐条调用 SpacetimeDB，导致数据库内存和事务压力先到边界。
- 决策：普通 HTTP route tracking 先写入 `api-server` 本机 NDJSON outbox，后台按数量或时间阈值批量调用 SpacetimeDB；`daily_login`、`work_play_start`、支付、任务领奖、钱包等关键事件保持同步直写。
- 默认阈值：每批 500 条或 1 秒 flush 一次；outbox 磁盘上限 256 MiB，超过后丢弃低价值 route 事件并记录指标 / 日志。
- 影响范围：`api-server` tracking 中间件、SpacetimeDB tracking procedure、部署数据目录、OTLP 指标和运维排障。
- 验证方式：数据库不可用时公开 route 请求不失败且 outbox 文件保留；恢复后批量写入成功并删除本地 sealed 文件；关键事件仍立即影响任务 / 统计。

## 2026-05-19 跳一跳平台公开链路采用独立玩法路由

- 背景：跳一跳玩法已接入平台入口、推荐、公开详情、试玩和运行态，后续继续扩展公开广场或推荐流时需要避免把它当成拼图兼容分支。
- 决策：跳一跳公开路由统一依赖 `sourceType='jump-hop'` 和 `JH-*` public code；平台首页、推荐、公开作品列表/详情、试玩和运行态都按 `jump-hop` 独立玩法分发。后端仍是作品、运行和发布状态的业务真相，前端只做展示、交互和临时 UI 状态，不在页面层补业务规则或权限判断。
- 影响范围：平台入口、推荐流、公开详情、试玩启动、跳一跳运行态、`api-server` / SpacetimeDB 公开投影和 shared contracts。
- 验证方式：从平台推荐或公开详情进入跳一跳作品时，路由 source type 为 `jump-hop`、public code 为 `JH-*`，运行态启动消费后端返回的完整 profile / run 数据；后端 smoke 统一使用 `npm run dev:api-server` 启动并检查 `/healthz`。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 2026-05-28 跳一跳重设计为 5x5 地块图集与弹弓拖拽

- 背景：旧跳一跳模板仍保留角色生图、有限路径、score/combo 和 `2x3` 地块图集口径，和当前“俯视角平台跳跃 + 主题生成地块池 + 无限路径”的产品需求不一致。
- 决策：`jump-hop` v1 创作端只保留主题输入；image2 生成一张 `5x5`、共 25 个 2D 地块图标的图集，后端按均匀网格切出 25 个 `JumpHopTileAsset`。角色不再单独生图，运行态使用陶泥儿 logo 透明 PNG 角色；运行态输入为按住后拉蓄力、松手反向弹出，前端提交 `chargeMs + dragVectorX + dragVectorY`，后端裁决落点。草稿试玩必须使用 `runtimeMode=draft`，正式作品使用 `runtimeMode=published`；排行榜按作品维度每玩家只保留 1 条最佳记录，排序为成功跳跃次数降序、游戏时长升序、更新时间升序。
- 决策补充：跳一跳创作入口的事实源仍是 SpacetimeDB `creation_entry_type_config`。默认种子和旧默认行都必须同步迁移到 `subtitle=主题驱动平台跳跃`、`image_src=/creation-type-references/jump-hop.webp`；后端只在系统默认旧值命中时自动纠偏，避免覆盖后台手动配置。
- 影响范围：`jump-hop` PRD、`api-server` 生成编排、`module-jump-hop` 领域规则、`spacetime-module` / `spacetime-client` 跳一跳契约、前端工作台 / 结果页 / runtime / 平台壳调用链。
- 验证方式：`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`、`cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、跳一跳工作台和 runtime 定向前端测试。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-06-01 跳一跳运行态地块视觉尺寸和命中半径统一放大一倍

- 背景：当前跳一跳运行态里地块视觉尺寸偏小，玩家反馈“很难跳上去”，但仅放大前端展示会造成画面和后端裁决脱节。
- 决策：`jump-hop` 运行态的地块视觉尺寸、`width/height` 玩法世界尺寸以及 `landingRadius/perfectRadius` 同步乘以 2；前端平台渲染抽成统一尺寸 helper，保证单测可以直接校验放大结果。
- 影响范围：`server-rs/crates/module-jump-hop/src/application.rs`、`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、对应定向测试。
- 验证方式：`npm test -- src/services/jump-hop/jumpHopRuntimeModel.test.ts src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx`、`cargo test -p module-jump-hop --manifest-path server-rs/Cargo.toml -- --nocapture`。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-06-02 跳一跳起跳距离减半并加入飞行动画缓冲

- 背景：用户反馈当前跳跃到目标位置需要拖得太远，且松手后缺少角色翻腾到目标地块的过渡动画，导致跳跃手感偏硬。
- 决策：`jump-hop` 的 `chargeToDistanceRatio` 统一从 `0.004` 提升到 `0.008`，让同等跳跃距离所需拖动距离减半；前端 runtime 把“后端真实 run”和“当前屏幕显示态”拆开，松手瞬间先生成 `visualJump`，用当前角色位置作为起点、前端预测落点作为终点，播放约 `560ms` 的飞行动画；该路径不得等待后端新 run。角色弹到预测落点后若新 run 尚未返回，必须停在预测落点等待，再进入约 `1440ms` 的相机层推进过渡。推进期间地块 DOM 层和 DOM 角色层统一包在同一个 camera layer 下移动，旧当前地块自然离开视野，新预览地块从上方露出，避免 p1/p2 单独 top/left 过渡导致角色和地块不同步。相机推进必须同时使用 X/Y 偏移，从旧目标地块位置斜向滑到新当前地块聚焦位置，不能先横向瞬切居中再纵向推进。地块保留当前 / 目标 / 预览的深度尺寸差异，但该差异通过固定基准宽高上的 CSS transform scale 表达，并在相机推进期间同样使用 `1440ms` 缓动；当前态不再额外叠 CSS scale。
- 影响范围：`server-rs/crates/module-jump-hop/src/application.rs`、`src/services/jump-hop/jumpHopRuntimeModel.ts`、`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、跳一跳运行态定向测试。
- 验证方式：`npm test -- src/services/jump-hop/jumpHopRuntimeModel.test.ts src/components/jump-hop-runtime/JumpHopRuntimeShell.test.tsx`、`cargo test -p module-jump-hop --manifest-path server-rs/Cargo.toml -- --nocapture`、`npm run check:encoding`。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-06-03 跳一跳角色形象改为陶泥儿 logo 透明 PNG

- 背景：跳一跳运行态此前仍使用旧内置 / CSS 角色形象，和用户要求的陶泥儿 logo 角色不一致，也容易和 DOM 地块层出现遮挡层级问题。
- 决策：`jump-hop` v1 不再渲染内置 3D 角色几何体；运行态和结果页统一使用 `public/branding/jump-hop-taonier-character.png`，该文件由陶泥儿 logo 处理为透明 PNG 后接入。蓄力时角色沿拖拽方向明显拉长，落地后向反方向回弹两次。`characterAsset` 继续仅作为历史兼容描述字段，不能重新打开角色生图槽或把角色图片作为创作者可配置输入。
- 影响范围：`src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`、`src/components/jump-hop-result/JumpHopResultView.tsx`、跳一跳 PRD 和平台链路文档。
- 验证方式：跳一跳运行态 / 结果页测试需要断言角色图片 src 为 `/branding/jump-hop-taonier-character.png`，并确认旧默认角色 fallback 不再出现。
- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

# 2026-05-20 陶泥儿主视觉配色回收为暖白/陶土橙

- 背景：用户要求只替换产品各界面的 UI 颜色，不改布局，并以两张陶泥儿主视觉图作为配色依据。
- 决策：平台亮色主题的主色回收到暖白 / 米杏底、陶土橙主按钮、深棕正文与浅杏边框；后台管理也同步切换到同一暖橙体系。主题变量优先通过 `src/index.css` 的 `--platform-*` token 统一控制，零散组件只做必要的局部替换。
- 影响范围：主站平台壳层、常用表单 / 按钮 / 卡片 / 背景、后台管理 UI、业务进度条和小游戏结果条的通用强调色。
- 验证方式：优先检查 `src/index.css` 与 `apps/admin-web/src/styles/admin.css` 是否还存在旧粉色主色；再用编码检查和可执行的本地 typecheck / build 验证。
- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。

## 2026-05-20 汪汪声浪 v1 公开闭环计划

- 背景：Bark Battle v1 需要把创作、生成、结果、发布、详情和正式运行态收成一条闭环，避免把草稿试玩、公开广场和正式成绩混在一起。
- 决策：`bark-battle` 入口改为 6 字段表单（作品标题、简介、主题 / 竞技背景描述 `themeDescription`、玩家形象描述、对手形象描述、难度）；提交后进入 `bark-battle-generating` 独立生成页，自动生成玩家形象、对手形象和竞技背景三图，部分失败也继续进入结果页。旧“角色设定 / 狗狗皮肤预设 / themePreset”统一退场，配置和文档只使用“形象描述 / themeDescription”。结果页只保留单槽重试、重新生成和上传，不再保留一次生成按钮、音频配置入口、皮肤预设入口或排名配置。发布后先跳统一作品详情页 `/works/detail?work=BB-xxxxxxxx`，再由详情页进入正式 `published` runtime；正式 runtime 必须真实麦克风，`draft` 可试玩、可 mock 且不写正式统计。公开广场统一读取 `bark_battle_gallery_view` read model。
- 影响范围：`BarkBattleConfigEditor`、`BarkBattleGeneratingView`、`BarkBattleResultView`、`BarkBattleRuntimeShell`、`PlatformEntryFlowShellImpl`、`appPageRoutes`、Bark Battle creation/runtime client、公开广场聚合与相关交互测试。
- 验证方式：提交表单后先进入生成页；生成页部分失败仍能落到结果页；结果页只出现单槽重试 / 重新生成 / 上传；发布后先到 `/works/detail?work=BB-xxxxxxxx` 再进正式 runtime；正式 runtime 会要求麦克风并写基础统计，草稿试玩可 mock 且不写正式 run；公开广场读取 `bark_battle_gallery_view`。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-22 汪汪声浪运行态与作品外显信息收口

- 背景：Bark Battle v1 在正式运行态、图片生成提示词和作品外部卡片上仍存在体验漂移：能量条推满后还要等计时结束、进入正式 runtime 后还要二次点击声控、角色形象 prompt 会默认注入狗主体、草稿 / 已发布卡片外部看不到创作者。
- 决策：能量条到玩家或对手边界即结算；正式 `published` runtime 从作品详情启动后立即申请真实麦克风权限，授权成功后立刻进入倒计时，并使用 start run 返回的 `runtimeConfig` 作为本局前端规则参数；结束后弹出独立结算弹窗，运行态固定提供返回按钮。玩家 / 对手形象图提示词保持用户填写的形象描述，只要求单个完整形象、正面和透明背景，不把非狗描述改写成狗；草稿架、已发布作品架、统一作品详情和公开广场列表都展示后端返回的 `authorDisplayName`。Bark Battle 卡片封面按竞技背景、玩家形象、对手形象、入口参考图兜底；works summary 优先读取 `publishedSnapshotJson` 的最终发布素材。拟声词进入配置 JSON，未手动编辑时随主题 / 形象描述重算，手动编辑后保持创作者自定义；触发阈值降到 `0.35`、冷却降到 `150ms`，后端 `BarkBattleRuleset.min_bark_gap_ms` 同步为 `150`，局内有效触发后快速随机展示高能词池。
- 影响范围：`BarkBattleSession`、`BarkBattleRuntimeShell`、`BarkBattleConfigEditor`、`BarkBattleConfig`、Bark Battle 生图 prompt、Bark Battle works/gallery summary、创作中心作品架卡片、公开作品码、`module-bark-battle` ruleset 和玩法链路文档。
- 验证方式：能量条推到 `100/-100` 的领域测试应提前 finished；发布态 runtime mount 后应自动调用麦克风 sampler、登记正式 run 并使用服务端 runtimeConfig；prompt 单测应覆盖透明背景、正面和非狗描述不强注入狗；作品架测试应覆盖草稿与已发布卡片作者展示和封面兜底；拟声词测试应覆盖主题自动重算、自定义保持和随机展示。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-19 汪汪声浪默认开放并区分草稿试玩与正式运行态

- 背景：`bark-battle` 已具备草稿结果页、发布链路与运行态 API，继续在入口层标记“敬请期待”会阻断创作闭环；同时草稿试玩不应污染正式成绩统计。
- 决策：默认入口改为 `visible=true`、`open=true`、`badge=可创建`，参考图固定为 `/creation-type-references/bark-battle.webp`。系统默认迁移只纠偏未被后台人工改过的汪汪声浪入口。发布后先进入统一作品详情页 `/works/detail?work=BB-xxxxxxxx`；正式 runtime 使用 `runtimeMode=published` 并必须真实麦克风，调用 `startBarkBattleRun` / `finishBarkBattleRun` 写正式 run；草稿结果页试玩仍使用 `runtimeMode=draft`，允许 mock 且不写正式 run。
- 验证方式：入口配置响应应返回汪汪声浪可创建和专属参考图；发布后地址应为 `/works/detail?work=BB-xxxxxxxx`；草稿试玩不调用 runtime run API；正式 runtime 无麦克风时不登记正式 run，结算后提交派生指标。

## 2026-05-20 汪汪声浪生成页负责三图自动生成

- 背景：结果页承载预览、修补和发布，若继续放“一次生成”按钮会把初始生成和结果修补职责混在一起。
- 决策：初始三图生成改由 `bark-battle-generating` 独立生成页自动执行，目标槽位只有玩家形象、对手形象和竞技背景；表单术语统一为 `themeDescription`、玩家形象描述和对手形象描述，不再回退 `themePreset`、狗狗皮肤预设或“角色设定”。部分失败也进入结果页。结果页不再提供一次生成按钮，音频配置和排名配置不进入 v1 公开闭环；结果页只保留单槽重试、重新生成和上传。发布时 SpacetimeDB `bark_battle_published_config.config_json` 使用规范化后的最终 `publishedSnapshot`，`published_snapshot_json` 同步保存同一份快照。
- 验证方式：表单提交后进入 `bark-battle-generating`；结果页不会出现一次生成按钮、音频槽、皮肤预设入口或排名配置；Bark Battle 发布后正式 runtime 应读取结果页最终图片素材而不是初始草稿素材。

## 2026-05-24 敲木鱼结果页先补录作品信息再试玩 / 发布

- 背景：敲木鱼工作台只应保留生成所需输入，作品标题、简介和主题标签适合放在生成草稿后的补录阶段。
- 决策：敲木鱼的 `workTitle`、`workDescription` 和 `themeTags` 从工作台首屏移到结果页；结果页编辑后在试玩或发布前先调用 `update-work-meta` 写回当前作品信息。主题标签编辑样式对齐拼图结果页的胶囊标签编辑器。
- 影响范围：敲木鱼统一创作工作台、`WoodenFishResultView`、`PlatformEntryFlowShellImpl`、敲木鱼 PRD 和平台入口链路文档。
- 验证方式：工作台首屏不再出现标题 / 简介 / 标签输入；结果页修改后点试玩或发布会先写回当前作品信息。
- 关联文档：`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` 等名称，会把内部模型路由暴露给普通用户。
- 决策：前端展示层统一改用产品化名称，如“标准模式”“创意模式”，以及“素材”“图片生成模式”等中性文案；内部 `imageModel`、`generationProvider` 和后端契约值保留不变，只改 UI 文案与错误提示。
- 影响范围：拼图图片模型选择器、拼图结果页关卡重生成面板、拼图生成进度文案、宝贝识物结果页占位提示和相关错误提示。
- 验证方式：前端可见文本中不再出现 `gpt-image-2` / `gemini-3.1-flash-image-preview` / `image-2 资源`；相关交互测试改为断言产品化模式名，但提交 payload 仍保持原有模型 ID。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-05-27 微信新用户用户名与孤儿作品作者回退收口

- 背景：用户数据清空后，旧作品的 `owner_user_id` 可能落到空洞或顺序号账号上，新注册用户会错误顶替历史作品；同时微信新用户默认用户名过于固定，不便于区分 openid。
- 决策：微信新用户的用户名统一改为 `名字_openid`，内部 `user_id` 改为不可复用的 `user_` 前缀 UUID 风格；作品作者找不到真实账号时统一回退到占位作者 `wx-openid-placeholder`，显示名固定为 `失效作者`，公开陶泥号固定为 `SY-00000000`。
- 影响范围：`module-auth`、`api-server` 作品作者解析、`AppState` 启动初始化、历史孤儿作品离线回填脚本与相关文档。
- 验证方式：`cargo test -p module-auth --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml work_author`、`npm run test -- scripts/rebind-orphan-work-owners.test.ts`。
- 关联文档：`server-rs/crates/module-auth/src/domain.rs`、`server-rs/crates/module-auth/src/lib.rs`、`server-rs/crates/api-server/src/work_author.rs`、`scripts/rebind-orphan-work-owners.mjs`。

## 2026-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 的作品架没有当前用户作品列表接口，导致已发布作品在发布后不能立即出现在“已发布”筛选和推荐流里。
- 决策：新增 `GET /api/creation/wooden-fish/works` 作为当前用户木鱼作品架事实源，返回 `WoodenFishWorksResponse.items` 摘要；平台壳在发布成功后必须同时刷新作品架和公开广场列表。
- 影响范围：`server-rs/crates/api-server/src/wooden_fish.rs`、`server-rs/crates/api-server/src/modules/wooden_fish.rs`、`src/services/wooden-fish/woodenFishClient.ts`、`src/components/custom-world-home/creationWorkShelf.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`。
- 验证方式：发布一个木鱼作品后，草稿 Tab 的已发布筛选应立刻出现 `WF-*` 作品卡，推荐 / 最新流也应立即刷新出公开卡片。
- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`。

## 2026-05-27 认证快照完全去文件化并仅保留行级备查

- 背景：`api-server` 依赖本地 `auth-store.json` 或 `GENARRATIVE_AUTH_STORE_PATH` 恢复认证真相会在 SpacetimeDB 不可用时把旧快照回灌到 `auth_identity` / `user_account`，导致用户数据被清空或覆盖。
- 决策：`api-server` 启动时只允许从 SpacetimeDB 正式认证表恢复；`module-auth` 不再维护本地持久化文件，只保留内存工作集和 JSON 导入 / 导出；`spacetime-module` 的认证快照只保留行级 `auth_store_snapshot` 备查，不再提供旧 `get_auth_store_snapshot` / `upsert_auth_store_snapshot` / `import_auth_store_snapshot` 兼容入口。
- 影响范围：`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/module-auth/src/lib.rs`、`server-rs/crates/spacetime-module/src/auth/procedures.rs`、`server-rs/crates/spacetime-client/src/auth.rs`、对应生成 bindings。
- 验证方式：`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 切片会显得像错误素材。
- 决策：`boardBackgroundPrompt` 成为中央场地底图的优先 prompt 来源，只有该字段为空时才回退读取 `themePrompt`；用户上传底图时只执行平台资产持久化和换签，不用主题词重写上传资产。复合图 atlas prompt 只描述“可被服务端按等大 1x1 方格切分”，禁止模型在图案上绘制切分线、边框、网格线或裁切参考线。
- 影响范围：拼消消工作台 payload、`shared-contracts` / `packages/shared` 契约、api-server 生成编排、SpacetimeDB session/work snapshot、文档与生成进度展示。
- 验证方式：`npm run spacetime:generate`、`npm run check:encoding`、`npm run check:server-rs-ddd`、`cargo test -p module-puzzle-clear`、`cargo test -p spacetime-client puzzle_clear -- --nocapture`、`npm run test -- src/components/puzzle-clear-creation/PuzzleClearWorkspace.test.tsx src/services/miniGameDraftGenerationProgress.test.ts src/routing/appPageRoutes.test.ts src/services/publicWorkCode.test.ts`。
- 关联文档：`docs/prd/【玩法创作】拼消消玩法模板PRD-2026-05-30.md`、`docs/technical/【玩法创作】拼消消玩法模板技术方案-2026-05-30.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 2026-06-06 统一创作页表头按契约 title 原样显示

- 背景：统一创作页长期使用固定表头 `想做个什么玩法？`，导致跳一跳等玩法希望按自身语义展示标题时只能改前端或默认契约。
- 决策：`creationTypes[].unifiedCreationSpec.title` 继续作为统一创作页表头传输字段，但读取和保存时都按契约内容原样显示和持久化，不再用入口 `title` 自动覆盖。默认 spec 可以给出玩法中文名；旧库中已经持久化为 `想做个什么玩法？` 的契约也保持原样，若需要改表头应在后台契约结构卡片中点击修改并编辑 `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 Pingora 网关先独立二进制试点

- 背景：评估 Pingora 是否逐步替代当前生产 Nginx 时，需要先验证 Genarrative 的现有反向代理、静态资源、维护模式和最小 SpacetimeDB 公网路由口径。
- 决策：新增 `server-rs/crates/pingora-gateway` 作为独立 binary crate，默认监听 `127.0.0.1:18081` 做影子网关；当前不绑定 `80/443`，不替代 `deploy/nginx/genarrative.conf`，生产仍以 Nginx 为公网入口。
- 影响范围：Rust workspace、Pingora 依赖、网关环境变量、`deploy/pingora/pingora-gateway.env.example` 和运维技术方案。
- 验证方式：先执行 `cargo fmt --manifest-path server-rs/Cargo.toml -p pingora-gateway`、`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`；替换前必须补齐路由 parity、压缩、TLS、限流、systemd、Jenkins 和健康巡检。
- 关联文档：`docs/technical/【开发运维】Pingora独立网关试点-2026-06-11.md`。
- 决策补充：`/api` 通用路由必须同时检查 `Content-Length` 与实际流式请求体累计字节数；缺少长度头时超过上限也返回统一 `PAYLOAD_TOO_LARGE` JSON。影子部署模板使用 `deploy/systemd/genarrative-pingora-gateway.service`，默认读取 `/etc/genarrative/pingora-gateway.env`，仍只监听本机高端口；`/__genarrative_pingora/healthz` 只在配置并匹配 `X-Genarrative-Pingora-Probe` token 时返回 shadow JSON。
- 决策补充：生产 `genarrative-health-patrol.service` 只在显式配置 `GENARRATIVE_HEALTH_PATROL_PINGORA_BASE_URL` 与 `GENARRATIVE_HEALTH_PATROL_PINGORA_PROBE_TOKEN` 时检查 Pingora shadow probe；未配置时巡检口径不变。Pingora shadow 日志必须保留 request/route/upstream/body 字段，方便和 Nginx access log 做 canary 对照。
- 决策补充：生产健康巡检的公网入口模式必须显式区分 `nginx` 和 `pingora-direct`。默认 `GENARRATIVE_HEALTH_PATROL_GATEWAY_MODE=nginx` 检查 API、SpacetimeDB 和 Nginx；Pingora 直连接管公网后切到 `pingora-direct`，改为检查 API、SpacetimeDB 和 `genarrative-pingora-gateway.service`，不再要求 `nginx.service` active。目标机本机探测 `127.0.0.1` 时用 `GENARRATIVE_HEALTH_PATROL_PUBLIC_HOST=<域名>` 保留正式 Host / vhost 语义。
- 决策补充：Pingora 影子网关产物不进入默认 API release；只有显式传 `--include-pingora-gateway` 或在 `Genarrative-Api-Build` 勾选 `INCLUDE_PINGORA_GATEWAY` 时，才构建并打包 `pingora-gateway` / `pingora-gateway.sha256`。真实构建 Pingora 前必须先检查 `cmake`、C 编译器和 C++ 编译器；Jenkins 勾选 `INCLUDE_PINGORA_GATEWAY` 时也要先 fail-fast 检查这些工具，避免进入 Cargo 后才因 `libz-ng-sys` 构建依赖缺失失败。`production-api-deploy.sh` 仅在两者同时存在时校验并复制到 current release，避免现有 API 流水线被 Pingora 构建依赖影响。发布包包含 Pingora 时，API deploy 会在提升 release 前读取 `systemctl cat genarrative-pingora-gateway.service` 和其 `EnvironmentFile`，拒绝 direct-entry `CAP_NET_BIND_SERVICE`、拒绝非 `127.0.0.1:18081` 的 shadow listen、拒绝 `TLS_LISTEN` / `HTTP_REDIRECT_LISTEN`，确认仍是本机 shadow 高端口后才切换 current；切换后执行 `systemctl restart genarrative-pingora-gateway.service` 并复核 active，让 shadow / canary 机器加载同一份 current release 网关二进制。该自动拉起不会启用公网 `80/443` 直连入口；已经进入 direct-entry 状态的机器应走正式直连 runbook 或先回退到 shadow。`npm run check:production-api-release` 必须同时验证默认 API release 不登记 Pingora，以及显式 `--include-pingora-gateway --skip-pingora-gateway-build` 时发布包包含 `pingora-gateway`、`pingora-gateway.sha256` 并写入 manifest。
- 决策补充：生产健康巡检的显式 `--timeout-ms`、`--slow-ms`、`GENARRATIVE_HEALTH_PATROL_TIMEOUT_MS` 和 `GENARRATIVE_HEALTH_PATROL_SLOW_MS` 必须是正整数，非法值直接失败，不静默回退默认 `5000ms` / `3000ms`。Pingora canary live 的 `--timeout-ms` / `GENARRATIVE_PINGORA_CANARY_TIMEOUT_MS`、direct live 的 `--timeout-ms` / `GENARRATIVE_PINGORA_DIRECT_TIMEOUT_MS`、canary access log 对账的 `--since-lines` / `GENARRATIVE_PINGORA_CANARY_ACCESS_LOG_SINCE_LINES` 也必须正整数。Pingora direct live 和 release readiness 读取的直连布尔 env 必须严格解析，只接受 `true/false`、`1/0`、`yes/no`、`on/off` 或空值，非法值直接失败，避免 `REQUIRE_WSS_UPGRADE`、preflight 开关或 `SKIP_WSS` 因拼写错误被当成 false。canary live 的 base URL、prefix、Host、额外 path 和 timeout 不能包含换行或 NUL；脚本必须在发起 canary 请求前失败，避免污染参数进入 URL、Host header 或 JSON 输出。canary access log 对账的日志路径、prefix、必需路径、tail 行数以及日志行中解析出的 URI / path 也不能包含换行或 NUL；脚本必须失败并给出对应参数或日志行诊断，不能把污染值写入 JSON 对账输出。direct live 的 HTTPS / HTTP base URL、Host、redirect Host、probe token、额外 path、SpacetimeDB 数据库名、access log 路径、timeout 和布尔 env 都不能包含换行或 NUL；脚本必须在发起 HTTPS / HTTP / WSS 请求前失败，避免污染参数进入请求头、URL、日志对账或 JSON 证据。Pingora 切换窗口调整巡检、live smoke、日志对账阈值或直连布尔开关时，把参数解析失败视为配置错误，而不是继续执行检查。
- 决策补充：即使不打包 Pingora 二进制，API release 也必须随包携带 Pingora release readiness 聚合门禁、直连启用 / 回退 / preflight / live smoke / current release 自审脚本、直连彩排状态脚本，以及 `deploy/systemd/`、`deploy/pingora/` 支撑配置；`pingora-direct-enable.sh` 和正式 cutover runbook 默认从 `/opt/genarrative/current` 推导这些路径，启用前 release readiness 基础门禁和启用后 `--require-direct` 复核也必须调用 `/opt/genarrative/current/scripts/check-pingora-release-readiness.mjs`，切换窗口不得依赖 Jenkins 工作区或目标机源码 checkout。API release 还必须携带 `build/<version>/scripts/deploy/production-api-deploy.sh` 和同目录 `maintenance-on.sh` / `maintenance-off.sh`；`Genarrative-Api-Deploy` 只能复制并执行 build 产物内的 deploy 脚本，禁止继续执行部署工作区根部脚本，避免 workspace 中的旧脚本掩盖发布包布局缺陷。`production-api-deploy.sh` 对数据库备份脚本、健康巡检脚本和 Pingora 直连依赖都执行 fail-fast，发布产物缺失时保持维护模式并停止部署，不再从部署工作区兜底复制；API deploy 必须要求 `--release-root`、`--current-link`、`--api-env-file` 使用绝对路径，且 `--version` 必须以数字或字母开头并拒绝点目录，再先写 `${RELEASE_ROOT}/.${VERSION}.staging.$`，全部复制完成后再用非合并语义提升为 `${RELEASE_ROOT}/${VERSION}`，并用固定替换语义切换 current 符号链接，同版本 release 已存在、提升前竞态出现或 current 路径不是符号链接时拒绝覆盖 / 合并，失败时清理 staging 且不留下正式 release；`npm run check:production-api-release` 与 `npm run check:production-api-deploy` 必须进入 `check:pingora-release-readiness` 聚合门禁，前者用临时 `CARGO_TARGET_DIR` 和假 `api-server` release binary 验证 `build-production-release.sh --component api-server --skip-api-build` 产物自包含，后者用临时 release 和 fake `systemctl` / `curl` 验证从发布产物内执行 deploy 脚本后 current release 自包含，并覆盖缺少备份脚本、健康巡检脚本、release readiness 聚合门禁脚本、current release 自审脚本、直连彩排状态脚本、direct live smoke 脚本、相对 release root / current link / api env file、点目录或点开头 version、既有 release 目录、目录型 current 或提升前 release 目录竞态时的失败维护模式。
- 决策补充：正式直连 runbook 在采集状态快照前必须先执行 current release 自审：`/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs --release-root /opt/genarrative/current --require-pingora-gateway --systemd-show`。该脚本只读检查发布包自包含、`pingora-gateway` 可执行，以及 systemd `ExecStart` 是否指向 current release 网关二进制；失败时应先修发布包、Jenkins 归档过滤、deploy 复制或 systemd 指向，再继续切换。
- 决策补充：直连前的 dev / release 彩排状态使用 `/opt/genarrative/current/scripts/ops/pingora-direct-rehearsal-status.mjs --release-root /opt/genarrative/current --expect-public-gateway nginx --require-pingora-shadow --require-realpath-canary --require-current-release-gateway --fail-on-critical`。该脚本只读读取 health patrol env、Pingora env、`systemctl`、`ss -H -ltnp`、realpath canary 配置和 current release 自审结果；`nginx` 期望模式要求公网 `80/443` 仍由 Nginx 监听，Pingora 只在 `127.0.0.1:18081` shadow，realpath canary 在 `127.0.0.1:18083`，不会写 `/etc`、reload systemd 或修改 Nginx / Pingora。
- 决策补充：Pingora 切换证据链正式纳入 `npm run check:pingora-current-release-audit`、`npm run check:pingora-cutover-status-snapshot`、`npm run check:pingora-cutover-evidence-bundle`、`npm run check:pingora-cutover-command-evidence`、`npm run check:pingora-cutover-evidence-verify`、`/opt/genarrative/current/scripts/ops/pingora-current-release-audit.mjs`、`/opt/genarrative/current/scripts/ops/pingora-cutover-status-snapshot.mjs`、`/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-bundle.mjs` 与 `/opt/genarrative/current/scripts/ops/pingora-cutover-evidence-verify.mjs`。状态快照按 `pre-cutover`、`post-enable`、`post-rollback` 三个阶段输出只读 JSON evidence，收录 `summary`、`healthPatrolEnv`、`pingoraEnv`、`releaseArtifacts`、`systemd` 和 `checks`；直连 runbook 的三个证据包阶段都显式透传绝对路径 `--output-root` 和 `--require-pingora-gateway`，让 `checks.current-release-audit.details` 同步归档 Pingora 二进制、sha256、release manifest 和 systemd `ExecStart` 自审结果；证据包脚本把快照 JSON、stdout、stderr、命令记录和 manifest 写入 `--output-root` 下的新证据目录，manifest 对已生成 snapshot、direct live、stdout / stderr、命令记录和 parse-error 文件记录 `path`、`sizeBytes` 与 `sha256`；每个阶段证据目录生成、复制或归档后，都必须用随包 verifier 按 `manifest.files` 只读复核文件存在、大小和 sha256，路径逃逸、符号链接证据目录、非目录证据路径、缺文件、大小漂移或 sha256 漂移都应失败。命令证据脚本把 direct enable apply / rollback apply 的真实 stdout、stderr、退出码、脱敏命令记录和 manifest 写入同一证据根目录，命令记录同时保留脱敏后的可读命令和结构化 `executable` / `args[]`，manifest 对 `command.stdout.txt`、`command.stderr.txt` 和 `command-record.json` 同样记录 `path`、`sizeBytes` 与 `sha256`，便于切换窗口后复核归档文件未漂移；runbook 必须在命令证据生成后立即用随包 verifier 验真 `<enable-apply-bundle-dir>` / `<rollback-apply-bundle-dir>`，再继续 health patrol 切换、回退后 env 复核或最终总审计，且 `--phase` 只允许 ASCII 字母、数字、点、下划线和短横线，非法阶段名直接失败，不做隐式清洗。自审和快照只读采集，证据包只写归档目录且不覆盖既有文件，证据验真脚本只读 manifest 和证据文件，命令证据脚本只执行 `--` 后面的真实命令并归档输出，证据目录权限固定为 `0750`，证据文件权限固定为 `0640`，这些脚本都不写 `/etc`、不 reload systemd，也不修改 Nginx 或 Pingora；probe token 和其他 env 敏感值只允许以是否存在或 `<redacted>` 的形式进入证据链，聚合门禁真实执行日志、dry-run plan、cutover runbook、直连启用脚本 direct live 命令日志、直连回退脚本 shadow probe 命令日志、gateway smoke 命令日志和证据包命令记录都不得输出 token 原文，状态快照在收录健康巡检、current release 自审等子检查 stdout / stderr 前必须按 env 敏感值脱敏，状态快照、证据包、命令证据和证据验真自测必须确认 token 原文不会进入 stdout、snapshot、manifest、命令记录或子检查输出；正式 runbook 应在 `--fail-on-critical` 下把自审、快照、证据包和 manifest 验真当成阻断证据，避免把发布包 checksum / manifest 漂移、env 漂移、systemd capability 残留、巡检失败或归档文件损坏带入后续阶段。
- 决策补充：正式直连 runbook 的即时证据 verifier 和最终证据根目录总审计内部复用 verifier 时，都必须使用 `--require-summary-ok`；总审计不能退化成只验 `manifest.files` hash，还要把 `manifest.summary.status=OK` 作为底层 verifier 严格模式的一部分。
- 决策补充：Pingora 切换命令证据生成端必须在执行前约束真实命令身份：`-- <command>` 本身必须是绝对路径，不能是文件系统根目录；真实命令和每个真实命令参数都不能包含换行或 NUL 字符。正式 runbook 因此直接执行 current release 随包 enable / rollback 脚本绝对路径，禁止用 `node`、`bash`、脚本名或其它 PATH 裸命令名包装。
- 决策补充：Pingora release readiness、canary access log 对账、direct live、direct preflight 和 cutover evidence bundle 的显式日志 / env 文件路径必须是绝对路径且不能是文件系统根目录。`--live-nginx-access-log`、`--live-pingora-access-log`、`--direct-pingora-access-log`、`--direct-health-patrol-env-file`、`--direct-preflight-env-file`、canary 对账脚本的 `--nginx-log-file` / `--pingora-log-file`、direct live 的 `--pingora-access-log`、direct preflight 的 `--env-file` 与 evidence bundle `--run-direct-live` 的 `--direct-pingora-access-log` 都不能指向 `/`，避免切换窗口把日志扫描或 env 复核误绑到根目录。证据包 `--run-direct-live` 的 direct URL、Host、probe token、SpacetimeDB 数据库名、Pingora access log 路径和 access log tail 行数还必须在配置层拒绝换行或 NUL，避免污染参数进入状态快照或 direct live 子命令后才失败。
- 决策补充：证据根目录总审计按 `--require-phase` 查找阶段证据时，只接受不带 `manifest.commandName` 的状态快照证据包；enable / rollback apply 的命令证据只能通过 `--require-command`、`--require-command-executable` 和 `--require-command-arg` 审计，不能冒充同名 phase 的阶段证据。
- 决策补充：直连回退的 Nginx smoke 不能只看 `curl --fail` / HTTP 200。`pingora-direct-rollback.sh` 支持 `--nginx-smoke-expect-body <片段>`；正式 cutover runbook 必须显式传入切换前真实 Nginx 入口和响应片段，不再默认假定 `/healthz` 会返回 `"ok":true`。dev 真实直连验证确认公网 Nginx 首页 `https://dev.genarrative.world/` 与 `<!doctype html>` 是可用 smoke，而固定 `http://127.0.0.1/healthz` / `"ok":true` 可能误卡回退或验证到错误入口。
- 决策补充：`check-pingora-release-readiness.mjs --require-direct` 是启用后直连复核，不再强制要求 `--direct-preflight-check-ports-free`；`--dry-run-cutover` 和启用前 preflight 仍必须要求端口空闲，用于证明 Nginx、Gitea 等占用 `80/443` 的进程已释放。dev 真实 direct 接管 `80/443` 后，启用后复核应看到端口由 Pingora 占用而不是空闲。
- 决策补充：Pingora 网关行为变更必须运行 `npm run check:pingora-gateway-smoke`；该脚本用临时 mock 上游验证静态路由、API 代理头、请求体限制、429 接流保护、上游断连 JSON 错误、维护模式和 SpacetimeDB WebSocket Upgrade，避免只靠单元测试遗漏接流路径。代理路径的上游失败必须返回稳定 JSON code，例如 `GATEWAY_UPSTREAM_ERROR` / `GATEWAY_UPSTREAM_TIMEOUT`。静态协商缓存、非读取方法和 Range 边界请求必须用固定 `X-Request-Id` 反查 Pingora access log，确认 `304`、`405`、`206`、`416` 这些本地响应状态也可进入切换证据链。
- 决策补充：Nginx 到 Pingora 的 canary 先采用 `deploy/nginx/snippets/genarrative-pingora-canary.conf` 的前缀手动入口，Server-Provision 只安装 snippet，不默认 include；启用时必须替换 probe token、限制来源，并用 `X-Genarrative-Nginx-Handoff: pingora-canary` 与 Pingora shadow 日志证明请求确实经过 handoff。
- 决策补充：Pingora shadow / canary 必须配置可落盘 access log，默认示例为 `/var/log/genarrative/pingora-gateway.access.log`；Server-Provision 创建 `/var/log/genarrative`、安装 `deploy/logrotate/genarrative-pingora-gateway`，并让 systemd 沙箱允许写该目录。canary 对照时同时看 Nginx access log、Pingora access log 与 tracing 日志。
- 决策补充：Pingora 前缀 canary live 通过后不能只看 `X-Genarrative-Nginx-Handoff` 响应头，还必须运行 current release 随包 `scripts/check-pingora-canary-access-log-parity.mjs` 按 `request_id` 对照 Nginx handoff access log 和 Pingora access log，确认 method/status/path 没有漂移。Nginx canary exact `/healthz` 按真实 snippet 映射到 Pingora shadow `/__genarrative_pingora/healthz`，其余 canary 前缀路径按 rewrite 后路径比对；该脚本只读日志，不修改日志、不 reload Nginx 或 Pingora。
- 决策补充：Pingora 启动必须 fail fast 拒绝不安全配置。`GENARRATIVE_PINGORA_GATEWAY_PROBE_TOKEN` 不能是占位值或短 token；开启 `GENARRATIVE_PINGORA_GATEWAY_TRUST_X_FORWARDED_FOR=true` 时必须同时设置 `GENARRATIVE_PINGORA_GATEWAY_TRUSTED_FRONT_PROXY_CONFIRMED=true` 并确认前置代理已清洗 `X-Forwarded-For`；接流保护 `BURST>0` 时对应 `RATE_PER_SECOND` 不能为 `0`。当前接流保护默认只覆盖单进程单实例；`GENARRATIVE_PINGORA_GATEWAY_PROTECTION_ENABLED=true` 且 `GENARRATIVE_PINGORA_GATEWAY_INSTANCE_COUNT>1` 时，必须先落地共享限流 / 共享并发保护层并设置 `GENARRATIVE_PINGORA_GATEWAY_SHARED_PROTECTION_CONFIRMED=true`，否则网关启动和 direct preflight 都要失败；关闭网关保护后的多实例必须明确由前置 Nginx / LB 承担全局接流保护。
- 决策补充：Pingora Nginx canary snippet 变更必须运行 `npm run check:nginx-pingora-canary`；该脚本静态校验本机来源限制、handoff 响应头、probe token 占位、前缀 rewrite、低缓冲和 SpacetimeDB WebSocket Upgrade。目标 agent 或 CI 有 Nginx 时必须运行 `node scripts/check-nginx-pingora-canary.mjs --require-nginx`，把 snippet 包进临时 `server {}` 强制执行 `nginx -t`。
- 决策补充：Pingora 与 Nginx 的核心路由 parity 以 `deploy/pingora/nginx-route-parity.matrix.json` 为共享检查输入；涉及 Nginx 模板、Pingora 路由、限流分组或路由文档时必须同步更新矩阵，并运行 `npm run check:pingora-route-parity` 与 `cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml matches_nginx_route_parity_matrix`。Rust 单测读取同一份矩阵验证 `classify_path`、body limit 和接流保护分组，Node 检查同时覆盖生产 / 开发 Nginx 模板和试点文档片段。
- 决策补充：Pingora 前缀 canary 在目标 Nginx 中人工 include 并 reload 后，必须运行 `npm run check:pingora-canary-live`；该脚本只读访问 `__genarrative_pingora_canary` 前缀下的 healthz、代表性 API、SpacetimeDB identity、静态资源和拒绝入口，并强制校验 `X-Genarrative-Nginx-Handoff: pingora-canary`，避免只通过 snippet 静态检查却没有证明真实 handoff 链路可用。
- 决策补充：Pingora release readiness 分为源码全量门禁和 current release runtime-only 门禁。源码 checkout / CI / 构建环境继续运行默认 `check-pingora-release-readiness.mjs`，覆盖 Cargo、npm、Docker、Nginx 静态 / 真机校验和发布包构建烟测；目标机 `/opt/genarrative/current` 的启用前基础门禁和启用后 `--require-direct` 复核必须调用随包 `scripts/check-pingora-release-readiness.mjs --release-runtime-only`，只执行 current release 自审、启用前直连彩排状态、live canary、access log 对账、direct preflight、health patrol env 复核和 direct live smoke。未带 `--require-direct` 时 runtime-only 必须自动运行随包 `scripts/ops/pingora-direct-rehearsal-status.mjs --expect-public-gateway nginx --require-pingora-shadow --require-realpath-canary --require-current-release-gateway --fail-on-critical`，确认公网 `80/443` 仍由 Nginx 接流、Pingora shadow `127.0.0.1:18081`、realpath canary `127.0.0.1:18083` 和 current release 自审均通过；启用后 `--require-direct` 复核不再要求 Nginx 接公网彩排状态，改为检查 direct preflight、health patrol 直连模式和 direct live smoke。API release / current release 必须随包携带 `scripts/check-pingora-release-readiness.mjs`、`scripts/check-pingora-canary-live.mjs`、canary access log 对账脚本、直连彩排状态脚本和 direct preflight / live 子脚本；runtime-only 模式不得依赖源码 checkout、npm project root、Docker 或目标机 Nginx 静态校验。
- 决策补充：Pingora 直连静态响应必须显式写入缓存头。HTML、目录 index 和 SPA fallback 默认 `Cache-Control: no-cache`；`/assets/*` 与 `/admin/assets/*` 中带 Vite 指纹文件名的资源默认 `Cache-Control: public, max-age=31536000, immutable`；非指纹静态和 ACME challenge 默认 `no-cache`。三档由 `GENARRATIVE_PINGORA_GATEWAY_HTML_CACHE_CONTROL`、`GENARRATIVE_PINGORA_GATEWAY_ASSET_CACHE_CONTROL` 和 `GENARRATIVE_PINGORA_GATEWAY_STATIC_CACHE_CONTROL` 覆盖，配置值不能包含换行或 NUL；`npm run check:pingora-gateway-smoke` 必须覆盖这些缓存头，避免直连后入口 HTML 被长期缓存或指纹资源失去长期缓存收益。
- 决策补充：Pingora 直连同一公网 IP 上的多域名时，必须先保住非主站域名的 Host 语义。dev 上 `dev.genarrative.world` 与 `git.genarrative.world` 共用 `80/443`，因此 direct env 必须配置 `GENARRATIVE_PINGORA_GATEWAY_GITEA_HOSTS=git.genarrative.world` 和 `GENARRATIVE_PINGORA_GATEWAY_GITEA_UPSTREAM=127.0.0.1:3000`，命中 Gitea Host 的请求整站代理到 Gitea，且不走应用维护页、API body limit 或网关接流保护。当前 Pingora TLS listener 只加载一组 cert/key；同时接管 `dev.genarrative.world` 和 `git.genarrative.world` 前，证书必须覆盖两个域名，不能使用单域名 SAN 证书。
## 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`。

## 2026-06-11 图片画布编辑器作为独立画布工程接入

- 背景：网站需要新增 Lovart 风格图片画布编辑器能力，既要支持素材栏、平移缩放、工具模式、吸附线、元数据窗口和修改结果并排展示，也要能保存当前用户的画布视图、图层布局和资源元数据。
- 决策：主站新增 `/editor` 对应 `image-editor` 阶段，编辑器作为独立图片画布工程挂在平台壳下，并在创作 Tab 提供入口；工程与资源通过 `editor_project` / `editor_project_resource` 落到 SpacetimeDB，经 `spacetime-client` facade 和 `/api/editor/projects*` BFF 读写。图片生成 / 修改 provider、计费和真实任务进度暂不接入，本期修改结果允许使用 mock 生成资源，但必须按生成资源元数据形状保存。
- 影响范围：主站路由、平台创作入口、图片画布编辑器组件、editor project API client、`api-server` BFF、`spacetime-client` facade、`spacetime-module` 表 / procedure、后端数据契约文档和前端架构文档。
- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run test -- src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、`npm run check:encoding`、`git diff --check`、headless Playwright smoke。
- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。

## 2026-06-14 图片画布素材库按账号级持久化

- 背景：图片画布需要 Lovart 式素材管理，素材不应只挂在单个 project 临时状态里；用户在任意项目上传的图片素材，都应作为账号素材库在其它项目中可见，同时画布自身的图层、视图和分组仍属于项目下的画布数据。
- 决策：新增 `editor_asset_folder` / `editor_asset` 作为账号级素材库表，以 `owner_user_id` 为归属；`editor_project` 继续承载工程元数据，`editor_canvas` 继续承载 project 下的画布视图和图层布局，`editor_project_resource` 继续承载具体画布资源引用。素材库 CRUD 统一经 `spacetime-client` facade 和 `/api/editor/assets*` BFF，前端只保留选择模式、框选、拖拽上传、图层打组和小地图拖拽等交互状态，不直接绕过后端持久化。
- 影响范围：`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`server-rs/crates/spacetime-client/src/editor_project.rs`、`server-rs/crates/api-server/src/editor_project.rs`、`src/services/image-editor/editorProjectClient.ts`、`src/components/image-editor/ImageCanvasEditorView.tsx`、后端数据契约文档和图片画布前端技术方案。
- 验证方式：`npm run spacetime:generate -- --rust-only`、`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`npm run typecheck`、`npm run check:spacetime-schema`、`npm run check:encoding`、`cargo check -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`、`git diff --check`。
- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 2026-06-15 图片画布角色图层新增动画生成入口

- 背景：图片画布已有角色形象图层标记 `assetKind="character"`，需要只对角色图片开放动画生成，不让普通素材误触发角色动画链路。
- 决策：角色动画入口只由画布图层 `assetKind="character"` 控制，在图片上方浮动工具条和右键菜单显示 `生成动画`；非角色图层不展示入口。点击后打开独立 `角色动画生成面板`，桌面端锚定到图片右侧，移动端按底部面板承接。前端固定提交 `seedance2.0-fast`、分辨率 / 比例 / 帧数 / 时长 / 价格字段；后端经 `/api/editor/character-animations/generations` 使用角色图作为首帧和尾帧生成视频，并立即抽取 32 / 40 / 48 帧、绿幕去背后写入 OSS。
- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/services/image-editor/editorProjectClient.ts`、`server-rs/crates/api-server/src/character_animation_assets.rs`、`server-rs/crates/shared-contracts/src/assets.rs`、图片画布技术方案。
- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/services/image-editor/editorProjectClient.test.ts`、`cargo test -p api-server editor_character_animation --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 关联文档：`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。

## 2026-06-16 图片画布图标素材面板采用 Lovart 式参考卡与横向增宽布局

- 背景：图标素材生成面板里，规范入口与素材描述项过于平铺，且子面板内部采用滑动列表，和 Lovart 风格画布的参考卡 / 物料卡不一致。
- 决策：`生成图标素材` 面板不使用内部纵向滚动列表；每新增一个素材描述项就让面板整体增宽，保持描述项横向卡片一眼可扫。图标规范入口改为 Lovart 式参考卡：缩略图、名称、绑定状态和轻量动作分区分开呈现，独立菜单只负责来源切换，不再承载说明文案。
- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/index.css`、图标素材生成专项设计文档。
- 验证方式：新增或增删素材描述项时，面板宽度应随项数变化；图标规范入口应呈现参考卡视觉而非纯文本按钮；移动端下仍应固定在底部锚定，不出现内部滚动条。
- 关联文档：`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。

## 2026-06-16 图片画布图标素材与角色生成支持双图片模型

- 背景：图片画布需要一次生成多枚 UI 图标素材，并保证生成后能按用户输入顺序命名、拆成独立透明素材铺回画布；角色形象生成也需要和图标素材共用同一套图片模型选择、比例和大小口径。
- 决策：底部 `生成图标素材` 入口创建一叠空白图标占位和独立面板；图标规范参考图只允许绑定 `assetKind="icon-spec"`。`生成角色形象` 与 `生成图标素材` 均支持 VectorEngine `gemini-3.1-flash-image-preview`（UI 显示 `nanobanana2`）和 `gpt-image-2`，默认 `nanobanana2`，用户在两类面板中切换过模型后下一次打开继续沿用上次模型。前端提交 `model`、`aspectRatio`、`imageSize`；后端不再按图标数量分 `512x512/1024x1024`，而是按模型归一尺寸：`nanobanana2` 走 `/v1beta/models/{model}:generateContent`，把参考图写成 `inline_data`，并在 `generationConfig.imageConfig` 写入比例和大小，`0.5K` 传 `"512"`；`gpt-image-2` 无参考图走 generations，有参考图走 edits，按文档支持的 `size` 字符串映射。图标素材仍先生成绿幕 spritesheet，再由 `platform-image` 绿幕去背并按 8 邻域连通域从上到下、从左到右拆分。成品图标图层写入 `assetKind="icon"`，角色图层写入 `assetKind="character"`。
- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`src/services/image-editor/editorProjectClient.ts`、`server-rs/crates/api-server/src/editor_project.rs`、`server-rs/crates/platform-image/src/vector_engine/*`、`server-rs/crates/platform-image/src/generated_asset_sheets/sheet.rs`、图片画布技术方案。
- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/ImageCanvasGenerationPlacementModel.test.ts src/services/image-editor/editorProjectClient.test.ts`、`cargo test -p api-server editor_generation_dimensions_follow_model_options --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-image nanobanana_generate_content --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 关联文档：`docs/【编辑器】画板图标素材生成入口设计-2026-06-15.md`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。

## 2026-06-16 图片画布生成面板与浮层层级收口

- 背景：图片画布底部工具栏和角色参考图行都存在局部滚动 / 裁切容器，生成规范菜单和角色规范来源菜单如果仍内嵌在触发按钮附近，会被边界遮挡；同时生成类面板打开后隐藏底部工具栏会破坏连续创作节奏。
- 决策：`生成规范`、`角色规范来源` 和 `图标规范来源` 菜单统一通过页面级 fixed portal 渲染到 `document.body`，触发按钮只提供定位锚点；点击 `生成工具`、`生成角色形象` 或 `生成图标素材` 后底部 AI 工具栏保持可见。点击画布空白区域只关闭当前生成面板并清除图片选中样式，不删除新建的占位图。角色面板中的 `角色规范` 与 `上传常规参考图` 入口统一改为 Lovart 式参考图卡片。
- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、`src/index.css`、`src/components/image-editor/ImageCanvasEditorView.test.tsx`、图片画布前端技术方案和角色形象生成设计文档。
- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
- 关联文档：`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。

## 2026-06-16 图片画布图片信息页不展示生图 Prompt

- 背景：图片画布中每张生成图片的信息页原来展示 `Prompt` 和复制 Prompt，但该字段可能是后端组装后的生图提示词，不适合作为用户可见的图片输入信息。
- 决策：图片信息页删除生图 Prompt 展示和复制入口，改为展示生成时的用户面板输入快照，包括普通生成提示词、规范表单字段、角色设定、图标素材描述、修改要求，以及角色规范、常规参考图、图标规范和修改参考图等参考图卡片。旧数据或上传图片没有输入快照时显示 `-`，不得回退展示内部 Prompt。
- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、图片画布 layout snapshot、图片画布技术方案。
- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx` 应覆盖图片信息页无 `Prompt`、无 `复制Prompt`，并展示普通生成、角色生成、图标素材和修改结果的输入快照。
- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。

## 2026-06-16 图片画布按 Resolution 原分辨率显示

- 背景：图片画布图层曾同时维护展示 `Size` 与资源 `Resolution`，旧布局快照里的 `width/height` 可能把大图缩成小图，导致画布视觉和图片信息里的原始分辨率不一致。
- 决策：图片图层不再把独立 `Size` 作为用户可见字段或展示真相；画布图层渲染宽高、悬浮尺寸胶囊和图片信息页统一以 `originalWidth/originalHeight`（即 `Resolution`）为准。旧 layout 中的 `width/height` 只作为缺少 Resolution 时的兼容兜底，不再优先决定展示大小。
- 影响范围：`src/components/image-editor/ImageCanvasEditorView.tsx`、图片画布 layout hydrate、新建 / 上传 / 生成 / 快速编辑 / 图标素材生成结果铺回画布逻辑，以及图片画布技术方案。
- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "hydrates canvas images from Resolution instead of saved Size|opens generated image info from the corner button and creates a real right-side edit result|shows image resolution on hover"`。
- 关联文档：`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。

## 2026-06-17 图片画布底部生成视频接入 Lovart 面板

- 背景：编辑器画板底部工具栏需要新增 `生成视频`，并和现有 Lovart 式生成类面板、泥点展示、占位图和画布结果图层保持一致。
- 决策：`生成视频` 点击后创建独立视频生成占位和极简面板，提交 `POST /api/editor/videos/generations`；首期前端仅开放 `seedance2.0-fast`、`seedance2.0`、`kling3.0`、`kling3.0-omni`，不展示 Veo 模型入口，默认 `seedance2.0-fast`。后端必须严格区分 Seedance 2.0 Fast 与标准版：`seedance2.0-fast` 映射 `doubao-seedance-2-0-fast-260128`，`seedance2.0` 映射 `doubao-seedance-2-0-260128`，不得混用；固定文字转视频、`16:9`、标准模式和静音。后端复用 Ark / VectorEngine content generation task 轮询链路，下载视频后持久化到 OSS。生成结果在画布中写入 `mediaType="video"` 与 `assetKind="video"`，图片信息弹窗按视频显示为 `视频信息` / `视频类型`。生成类泥点价格统一走 `editor_generation_config`，视频和角色动画均为 480p 每秒 10 泥点、720p 每秒 20 泥点。
- 影响范围：图片画布生成工作流、前端 editorProjectClient、`shared-contracts`、`api-server` 视频生成 BFF、编辑器技术方案和生成类面板方案。
- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorView.test.tsx -t "opens the bottom generate video panel"`、`npm run test -- src/components/image-editor/ImageCanvasMetadataModalView.test.tsx`、`npm run test -- src/services/image-editor/editorProjectClient.test.ts`、`cargo test -p shared-contracts editor_video --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_video --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。

## 2026-06-17 图片画布生成器快照纳入画布布局

- 背景：生成占位图和生成器对话框里包含用户输入、参数、参考图、占位框位置和生成结果绑定，刷新后丢失会让已生成图片无法回到 Lovart 式跟随编辑状态。
- 决策：生成器对象统一作为 `editor_canvas` 布局 JSON 的 `itemType: "generation-dialog"` 项保存，不新增表；成功生成后仍保留生成器快照和最后占位框位置，并通过 `generatedLayerId` 锚定到成品图层，渲染时不重复显示灰色占位框。图片类生成结果同步写入账号级素材库；视频结果当前只作为画布视频资源保存。
- 影响范围：图片画布 layout 序列化 / hydrate、生成工作流、生成器渲染、项目自动保存、素材库回填和编辑器技术方案。
- 验证方式：`npm run test -- src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/useCanvasGenerationDialogs.test.tsx src/components/image-editor/useImageCanvasProjectPersistence.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`、浏览器刷新 smoke。
- 关联文档：`docs/【编辑器】生成类面板Lovart统一改造方案-2026-06-17.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`。

## 2026-06-18 编辑器画板音效待生成占位类型化

- 背景：`/editor/canvas` 新建视频、角色形象、音效和背景音乐待生成对象时沿用图片占位 icon，音效面板仍把 `type` 与 `tempo` 分成两个旧字符串选项，不符合 Lovart 式简洁参数按钮和 BPM 输入需求。
- 决策：画布待生成占位按生成器模式渲染专属空白样式、icon 与右上角标签：视频、角色、音效、背景音乐不再统一使用图片 icon；角标继续按 viewport 反向缩放。原计划中的 `type + tempo/BPM` 音效参数已在 2026-06-19 被 Vidu `prompt + duration` 契约替代，后续不要再恢复 `单次·120BPM` 入口。
- 影响范围：`src/components/image-editor/ImageCanvasWorldView.tsx`、`ImageCanvasGenerationComposerView.tsx`、`ImageCanvasEditorTypes.ts`、`ImageCanvasGenerationSubmissionModel.ts`、`src/services/image-editor/editorProjectClient.ts`、`server-rs/crates/shared-contracts/src/assets.rs`、`server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs`、`server-rs/crates/platform-audio/src/request.rs`。
- 验证方式：`npx vitest run src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasEditorModel.test.ts src/components/image-editor/ImageCanvasGenerationModel.test.ts src/services/image-editor/editorProjectClient.test.ts --reporter verbose`、`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-audio --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server editor_sound_effect --manifest-path server-rs/Cargo.toml`。

## 2026-06-18 图片画布角色动画改为角色动作生成占位

- 背景：旧角色动画入口点击后打开窄侧边面板，和 Lovart 式新建图片 / 视频占位不一致；点击生成好的角色图时也容易被误解为会自动进入重绘或生成面板。
- 决策：点击已生成角色图只选中图层并显示浮动工具栏，不自动弹出重绘、快速编辑或角色动画面板。点击工具栏或右键菜单的 `生成动画` 后，创建 `mode="character-animation"` 的画布 generation dialog，占位走统一避让落点与视口居中；占位使用角色动作 icon、橙色动作配色和右上角 `动作` 标签。角色动画参数面板复用原内容，但作为统一 generation composer 跟随占位底部，宽度对齐图片生成面板。提交成功后以首帧创建 `assetKind="character-animation"` 的角色动作图片图层，右上角标签显示 `动作`。
- 影响范围：`src/components/image-editor/useImageCanvasGenerationWorkflow.ts`、`useImageCanvasGenerationSurface.tsx`、`ImageCanvasCharacterAnimationPanelView.tsx`、`ImageCanvasWorldView.tsx`、`ImageCanvasGenerationLayerModel.ts`、`useImageCanvasGenerationSubmissionWorkflow.ts`、`src/index.css`。
- 验证方式：`npx vitest run src/components/image-editor/ImageCanvasWorldView.test.tsx src/components/image-editor/ImageCanvasGenerationDialogModel.test.ts src/components/image-editor/useImageCanvasGenerationWorkflow.test.tsx src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx --reporter=dot`、`npx vitest run src/components/image-editor/ImageCanvasEditorGenerationIntegration.test.tsx -t "character animation" --reporter=dot`。

## 2026-06-19 编辑器游戏音效默认改用 Vidu 文生音频

- 背景：VectorEngine Apifox `创建文生音频任务` 文档明确 Vidu `/ent/v2/text2audio` 请求体使用 `model: "audio1.0"`、`prompt`、`duration` 和可选 `seed`；编辑器此前把游戏音效提交到 Suno `task: "sound"`，与当前游戏音效默认模型要求不一致。
- 决策：`/editor/canvas` 的 `生成游戏音效` 入口继续保留，但默认且暂时唯一可用模型为 Vidu `audio1.0`，前端请求固定发送 `prompt`、`model: "audio1.0"`、`duration` 和 `priceMudPoints`，面板只显示 `Vidu` 与 `2-10` 秒时长选项，默认 `5` 秒；不再展示 `type`、`tempo`、BPM 或 Suno 文生音效入口。后端 `/api/editor/audios/sound-effects/generations` 只接受空模型或 `audio1.0`，拒绝 Suno / `chirp-*`；提交到 VectorEngine 时对内 `prompt` 同步映射为上游 body 的 `prompt` 与 `sound`，兼容 Apifox 文档和线上网关实际 `missing field sound` 校验；提交和轮询改走 Vidu `/ent/v2/text2audio` 与 `/ent/v2/tasks/{taskId}/creations`。背景音乐仍保留 Suno `/suno/submit/music`、`/suno/fetch/{taskId}` 和 wav clip 兜底逻辑。
- 影响范围：`server-rs/crates/platform-audio`、`server-rs/crates/api-server/src/vector_engine_audio_generation/generation.rs`、`server-rs/crates/shared-contracts/src/assets.rs`、`src/services/image-editor/editorProjectClient.ts`、`src/components/image-editor/ImageCanvasGeneration*`。
- 验证方式：`cargo test -p platform-audio --manifest-path server-rs/Cargo.toml --test vector_engine_audio`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_sound_effect`、`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml editor_audio_requests_and_response_use_canvas_audio_shape`、`npx vitest run src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasGenerationComposerView.test.tsx src/components/image-editor/ImageCanvasGenerationModel.test.ts --reporter=dot`。

## 2026-06-19 角色主图抠图补充内部镂空检测

- 背景：编辑器角色形象和 Big Fish 正式图复用 `character_visual_assets::try_apply_background_alpha_to_png` 的角色主图透明背景后处理；原算法主要从画布四边扩散清理绿幕 / 近白背景，对主体包围的内部绿幕或近白镂空不稳定。
- 决策：角色主图抠图继续保留在 `api-server` 的 `character_visual_assets` 口径内，不切换到 `platform-image::generated_asset_sheets`。在边缘连通背景 BFS 之后、软边扩展和边缘去污染之前，新增内部背景连通域检测：只清理不触画布边界、像素数达到阈值、且为高置信绿幕 / 近白背景的内部连通域，避免误伤普通角色纹理。
- 影响范围：`server-rs/crates/api-server/src/character_visual_assets.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
- 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml character_background_alpha_removes_internal_green_holes`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_character_image_postprocess`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。

## 2026-06-19 编辑器角色形象回填改用通用抠图

- 背景：画板编辑器里的 `生成角色形象` 属于编辑器图片生成链路，用户要求把“人物抠图”改成通用抠图方法，不再与 RPG / 资产工坊角色主图专用后处理绑定。
- 决策：仅 `/api/editor/images/generations` 中 `kind = "character"` 的编辑器角色形象回填改用 `platform-image::generated_asset_sheets` 通用绿幕 / 近白去背能力，并开启内部镂空检测；输出仍归一为透明 PNG。`character_visual_assets::try_apply_background_alpha_to_png` 继续服务 RPG 角色主图与 Big Fish 等“角色主图口径”调用者，本轮不改变这些链路。
- 影响范围：`server-rs/crates/api-server/src/editor_project.rs`、`docs/【编辑器】画板角色形象生成入口设计-2026-06-15.md`。
- 验证方式：`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_character_image_general_cutout`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。