Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative

docs/technical/JENKINS_RUST_BUILD_DEPLOY_PIPELINES_2026-04-23.md

@@ -28,7 +28,7 @@
 12. `WEB_PORT` 必须在 `构建并部署` 与 `部署` 两条流水线之间使用同名参数传递；部署脚本会把最终端口写入固定部署目录 `.env.local` 的 `GENARRATIVE_WEB_PORT`，避免 `sudo` 启动 hook 时环境变量被清理导致端口回退。
 13. `DATABASE` 必须匹配 SpacetimeDB CLI 数据库名规则 `^[a-z0-9]+(-[a-z0-9]+)*$`：只能使用小写字母、数字，并用单个短横线分隔；大写字母、点号、下划线、首尾短横线和连续短横线都会被拒绝，否则 `spacetime publish` 会报 `invalid characters in database name`。
 14. Jenkins 日志必须能看到构建参数中的 SpacetimeDB 发布数据库，以及 `start.sh` 最终加载环境文件后的运行时数据库、server 和 root-dir，避免 `.env.local` 覆盖默认值后无法判断实际发布目标。
-15. `构建并部署` 流水线开头固定把 Jenkins 用户下的 Node、Cargo、SpacetimeDB 常用安装目录加入 `PATH` 前缀：`/var/lib/jenkins/.nvm/versions/node/v22.22.2/bin:/var/lib/jenkins/.cargo/bin:/var/lib/jenkins/.local/bin:/var/lib/jenkins/bin`。
+15. `构建并部署` 流水线开头通过 `GENARRATIVE_TOOLS_PATH` 固定声明 Jenkins 用户下的 Node、Cargo、SpacetimeDB 常用安装目录：`/var/lib/jenkins/.nvm/versions/node/v22.22.2/bin:/var/lib/jenkins/.cargo/bin:/var/lib/jenkins/.local/bin:/var/lib/jenkins/bin`，并显式保留 `/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin`，避免覆盖系统路径导致 `sh` 步骤无法启动。
 
 ## 3. 节点与工作区要求
 
@@ -155,7 +155,7 @@ jenkins/Jenkinsfile.build-and-deploy
 10. `MIGRATION_IMPORT_TOKEN`：可选，新库已授权迁移操作员 token，只在清库发布新 wasm 后导入回灌时使用。
 
 如果当前 Jenkins 没有额外配置独立 Agent，而是直接在控制器自身执行任务，`AGENT_LABEL` 应填写 `built-in`。
-如果 `node`、`cargo` 或 `spacetime` 安装在 Jenkins 用户目录下，`构建并部署` 已默认把 `/var/lib/jenkins/.nvm/versions/node/v22.22.2/bin`、`/var/lib/jenkins/.cargo/bin`、`/var/lib/jenkins/.local/bin`、`/var/lib/jenkins/bin` 追加到流水线 `PATH` 前缀；仍应确保这些目录和其中二进制文件对 Jenkins 运行用户可读可执行。
+如果 `node`、`cargo` 或 `spacetime` 安装在 Jenkins 用户目录下，`构建并部署` 已默认把 `/var/lib/jenkins/.nvm/versions/node/v22.22.2/bin`、`/var/lib/jenkins/.cargo/bin`、`/var/lib/jenkins/.local/bin`、`/var/lib/jenkins/bin` 写入流水线 `PATH` 前缀；仍应确保这些目录和其中二进制文件对 Jenkins 运行用户可读可执行。
 如果 Jenkins 进程以默认 `jenkins` 用户运行，部署目录建议直接放在 `/var/lib/jenkins/deploy/Genarrative` 这类 Jenkins 自有目录下，避免再依赖 `/home/ubuntu/*` 的额外写权限。
 如果目标 Ubuntu 的 Jenkins `sh` 默认实际落到 `/bin/sh -> dash`，而流水线脚本又使用了 `set -euo pipefail`，则必须显式通过 `bash -lc` 执行命令，不能直接依赖 Jenkins 默认 `sh` 解释器。
 

docs/technical/MATCH3D_Q1_INTEGRATION_ACCEPTANCE_2026-05-01.md

@@ -0,0 +1,146 @@
+# 抓大鹅 Match3D Q1 集成验收与收口记录 2026-05-01
+
+## 1. 本轮目标
+
+Q1 不新增玩法规则，只把第一至第三波已经形成的 Match3D 独立玩法域接成可跑主链：
+
+1. 创作 Agent 前端从本地 mock 切到 `api-server` HTTP/SSE facade。
+2. 结果页从临时草稿承接页升级为可编辑、可保存、可试玩、可发布的作品工作台。
+3. 试玩运行态从结果页启动真实 `/api/runtime/match3d/*` run，并继续保持“前端即时反馈 + 后端权威确认”。
+4. 创作中心至少能读取当前用户 Match3D 作品列表，并支持打开草稿继续编辑。
+
+本轮结论：已按合并顺序完成 Q1 主链集成。第一至第三波的主体能力均已落到工程，Q1 已把它们串成“创作 Agent -> 结果页保存/发布/试玩 -> 公开详情/作品号搜索 -> 运行态”的最小可跑链路。
+
+## 2. 第一至第三波验收口径
+
+### 第一波 A0
+
+文档已存在：
+
+```text
+docs/technical/MATCH3D_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-30.md
+```
+
+结论：已完成。该文档冻结了独立玩法域、表与 procedure、HTTP facade、前端即时反馈协议和合并顺序。
+
+### 第二波 B1 + B2
+
+已落点：
+
+```text
+server-rs/crates/module-match3d/
+server-rs/crates/shared-contracts/src/match3d_*.rs
+packages/shared/src/contracts/match3d*.ts
+```
+
+结论：已完成。领域 crate、Rust DTO、TypeScript DTO 已存在，并已通过 Q1 定向复跑。
+
+### 第二波 B3
+
+已落点：
+
+```text
+server-rs/crates/spacetime-module/src/match3d/
+server-rs/crates/spacetime-module/src/migration.rs
+```
+
+结论：已完成。四张 Match3D 表已纳入 migration，procedure 已接 `module-match3d` 领域规则。本轮不改表结构，不需要新增 migration。
+
+### 第二波 F1
+
+已落点：
+
+```text
+src/components/match3d-creation/
+src/services/match3d-creation/
+src/components/platform-entry/
+```
+
+结论：已完成并已接入 Q1。入口与 Agent UI 已存在，`match3dCreationClient` 已从本地 mock 切到 `api-server` HTTP/SSE facade；本地 mock 只保留在测试夹具和 `/match3d` playground 运行调试链路中。
+
+### 第二波 F3
+
+已落点：
+
+```text
+src/components/match3d-runtime/
+src/services/match3d-runtime/match3dLocalRuntime.ts
+src/Match3DPlaygroundApp.tsx
+```
+
+结论：已完成并已接入 Q1。圆形空间、7 格备选栏、乐观点击、三消反馈、结算面板和回滚校正语义已存在；Q1 已补真实 runtime client 与平台入口接线。
+
+### 第三波 B4 + B5
+
+已落点：
+
+```text
+server-rs/crates/spacetime-client/src/match3d.rs
+server-rs/crates/api-server/src/match3d.rs
+server-rs/crates/api-server/src/app.rs
+```
+
+结论：已完成。HTTP facade 路由已注册，Q1 前端已按这些稳定路由接入。
+
+### 第三波 F2
+
+目标落点：
+
+```text
+src/components/match3d-result/
+src/services/match3d-works/
+```
+
+结论：已完成并已接入 Q1。新增 `Match3DResultView` 和 `match3d-works` service，支持基础信息编辑、保存、发布、试玩入口；发布仍要求封面和标签门槛，试玩只要求基础配置可保存。
+
+### 第三波 F4
+
+结论：已完成 Q1 最小平台分发。创作中心作品货架、公开卡片映射、统一作品详情、`M3-xxxxxxxx` 作品号搜索和详情页启动运行态已接入；排行榜、点赞、改造统计和更复杂推荐策略仍留到后续优化。
+
+## 3. Q1 本轮代码落点
+
+本轮实际落点：
+
+1. `src/services/match3d-creation/`：替换本地 mock 为 HTTP/SSE facade。
+2. `src/services/match3d-works/`：新增作品读取、保存、发布 service。
+3. `src/services/match3d-runtime/`：新增真实运行态 service，保留本地 playground mock。
+4. `src/components/match3d-result/`：新增结果页组件。
+5. `src/components/platform-entry/`：串起结果页、试玩 run、作品列表刷新。
+6. `src/components/custom-world-home/` 与展示映射：扩展 Match3D 作品货架、公开卡片、统一详情页。
+7. `src/services/publicWorkCode.ts` 与 `src/routing/appPageRoutes.ts`：新增 `M3-xxxxxxxx` 作品号与公开详情路由识别。
+8. `src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`：补齐 Match3D 作品号搜索启动运行态回归，并同步统一详情页后的 RPG/Big Fish 旧测试语义。
+
+## 4. 验收命令
+
+本轮已通过：
+
+```powershell
+npm test -- src/components/match3d-result/Match3DResultView.test.tsx src/components/match3d-runtime/Match3DRuntimeShell.test.tsx src/routing/appPageRoutes.test.ts src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx --reporter=verbose --silent
+```
+
+结果：`6 passed`，`65 passed`。
+
+```powershell
+cargo test -p module-match3d
+cargo test -p shared-contracts
+cargo check -p api-server
+cargo check -p spacetime-client
+npm run check:encoding
+```
+
+结果：
+
+1. `module-match3d`：`7 passed`。
+2. `shared-contracts`：`47 passed`。
+3. `api-server`：`cargo check` 通过。
+4. `spacetime-client`：`cargo check` 通过。
+5. 编码检查：`2804 file(s)` 通过。
+
+## 5. 本轮不做与遗留风险
+
+1. 不改 Match3D 表结构。
+2. 不扩展排行榜、点赞、二次创作统计。
+3. 不把 Match3D 公开广场并入更复杂的推荐、排行和运营榜单策略。
+4. 不删除 `/match3d` 本地 playground；它作为开发调试入口继续保留。
+5. 全量 `npm run typecheck` 曾存在非 Match3D 既有阻塞，本轮以 Q1 定向测试和后端定向检查作为集成验收口径。
+6. Maincloud 运行态仍依赖当前 SpacetimeDB 环境稳定性；如 `npm run api-server:maincloud` 现场遇到订阅 HTTP 500，应按 Maincloud/SpacetimeDB 联调链路单独排查。

docs/technical/README.md

@@ -14,6 +14,7 @@
 - [MATCH3D_F2_RESULT_AND_PUBLISH_2026-04-30.md](./MATCH3D_F2_RESULT_AND_PUBLISH_2026-04-30.md)：冻结抓大鹅 F2 结果页、基础信息编辑、发布前试玩入口、发布门槛、自动保存和已发布作品二次编辑恢复口径。
 - [MATCH3D_SPACETIME_CLIENT_AND_API_FACADE_2026-04-30.md](./MATCH3D_SPACETIME_CLIENT_AND_API_FACADE_2026-04-30.md)：记录抓大鹅 B4+B5 已落地的 SpacetimeDB bindings、`spacetime-client` facade、`api-server` HTTP 路由、shared contract 对齐和验收命令。
 - [MATCH3D_CREATION_ENTRY_COMING_SOON_2026-05-01.md](./MATCH3D_CREATION_ENTRY_COMING_SOON_2026-05-01.md)：记录抓大鹅创作页入口临时改为“敬请期待”、不可点击，以及保留既有 Match3D 能力不删除的边界。
+- [MATCH3D_Q1_INTEGRATION_ACCEPTANCE_2026-05-01.md](./MATCH3D_Q1_INTEGRATION_ACCEPTANCE_2026-05-01.md)：记录抓大鹅 Match3D 第一至第三波完成度复核、Q1 主链集成落点、定向验收命令和遗留风险。
 - [PLATFORM_MOBILE_BOTTOM_DOCK_VIEWPORT_FIX_2026-04-30.md](./PLATFORM_MOBILE_BOTTOM_DOCK_VIEWPORT_FIX_2026-04-30.md)：记录平台首页底部 dock 在手机浏览器地址栏展开时脱离可见区域的根因，以及 `100dvh`、固定底部锚点和安全区占位的修复口径。
 - [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md)：记录 SpacetimeDB private 表迁移 JSON 导出/导入 procedure、迁移操作员授权、HTTP 413 分片导入、Jenkins 自动迁移回灌和导入脚本参数。
 - [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)：记录 `Genarrative-Database-Export` / `Genarrative-Database-Import` 两条 SCM-backed 数据库迁移流水线参数、默认 dry-run、token 边界和 `CHUNK_SIZE` 413 规避参数。