refactor: split large modules and normalize rust layout

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -40,6 +40,12 @@ server-rs + Axum + SpacetimeDB
 npm run check:server-rs-ddd
 ```
 
+## `spacetime-client` mapper 组织
+
+`server-rs/crates/spacetime-client/src/mapper.rs` 只作为聚合入口，负责声明 `src/mapper/` 下的领域子模块并 re-export 原有 record / mapper 能力；不要在该文件继续堆叠大段映射实现。
+
+当前子模块按调用领域拆分：`assets.rs`、`auth.rs`、`runtime.rs`、`runtime_profile.rs`、`custom_world.rs`、`puzzle.rs`、`match3d.rs`、`square_hole.rs`、`visual_novel.rs`、`big_fish.rs`、`story.rs`、`ai.rs`、`bark_battle.rs`、`combat.rs`、`inventory.rs`、`npc.rs`，跨领域轻量 helper 和共享 record 统一放在 `common.rs`。该拆分只改变 `spacetime-client` 文件组织，不改变 SpacetimeDB schema、生成绑定、procedure result 契约或外部 DTO；后续新增 mapper 时优先落到对应领域子模块，不得重新引入跨层 JSON 字符串兼容结构。
+
 ## API 路由分组
 
 路由树由 `server-rs/crates/api-server/src/app.rs` 统一构造。当前主要分组：
@@ -73,11 +79,12 @@ npm run check:server-rs-ddd
 2. `app.rs` 只保留全局 middleware、TraceLayer、request context、tracking middleware、入口开关和少量顶层 glue。
 3. 路由迁移和业务重构分阶段处理；先移动路由装配，再拆 handler 内部实现。
 4. 大 handler 拆分时优先按 `router.rs`、`handlers.rs`、`application.rs`、`assets.rs`、`mapper.rs`、`errors.rs` 分层。`handlers.rs` 只做 Axum extract、鉴权和 request/response，业务规则继续下沉到 `module-*`。
+5. 手写 Rust 模块入口统一使用同名 `.rs` 文件，例如 `puzzle.rs` + `puzzle/*.rs`、`match3d.rs` + `match3d/*.rs`；不要再新增 `mod.rs` 入口。生成的 SpacetimeDB Rust bindings 也由生成脚本同步为 `module_bindings.rs` + `module_bindings/*.rs` 布局。
 
 拼图 `api-server` 内部拆分：
 
 - `server-rs/crates/api-server/src/modules/puzzle.rs` 只负责路由装配、鉴权层和参考图 body limit；对外继续引用同一批 handler 名称。
-- `server-rs/crates/api-server/src/puzzle/mod.rs` 只作为聚合入口，保留共享 import / 常量、内部模块声明和 handler re-export，不继续承载大段实现。
+- `server-rs/crates/api-server/src/puzzle.rs` 只作为聚合入口，保留共享 import / 常量、内部模块声明和 handler re-export，不继续承载大段实现。
 - `server-rs/crates/api-server/src/puzzle/handlers.rs` 承接 Axum handler，负责 extract、鉴权上下文、调用 SpacetimeDB facade / 编排 helper，并返回 HTTP/SSE 响应。
 - `server-rs/crates/api-server/src/puzzle/draft.rs` 承接表单草稿保存、草稿编译、首关命名、UI 背景 prompt、降级 snapshot 和初始资产就绪校验。
 - `server-rs/crates/api-server/src/puzzle/generation.rs` 承接拼图图片与 UI 背景的生成编排、计费包裹和 reference image 路径选择。
@@ -87,6 +94,19 @@ npm run check:server-rs-ddd
 
 该拆分只改变 `api-server` 文件组织，不改变 `/api/runtime/puzzle/*` route、DTO、error envelope、SpacetimeDB schema、公开 gallery cache 语义或计费语义；后续继续细分时也必须先保持行为不变，再单独讨论领域规则下沉。
 
+抓大鹅 Match3D `api-server` 内部拆分：
+
+- `server-rs/crates/api-server/src/modules/match3d.rs` 继续负责路由装配和 body limit；对外 handler 名称保持不变。
+- `server-rs/crates/api-server/src/match3d.rs` 只作为聚合入口，保留共享 import / 常量 / 内部类型、模块声明和 handler re-export。
+- `server-rs/crates/api-server/src/match3d/handlers.rs` 承接 Axum handler，负责 extract、鉴权上下文、调用 SpacetimeDB facade / 编排 helper，并返回 HTTP 响应。
+- `server-rs/crates/api-server/src/match3d/draft.rs` 承接 Agent session、草稿编译、题材 / 难度 / 物品计划和草稿持久化编排。
+- `server-rs/crates/api-server/src/match3d/works.rs` 承接作品 CRUD、封面 / 背景 / 容器资产生成入口、发布 / Remix / 点赞 / 游玩记录和作品级 helper。
+- `server-rs/crates/api-server/src/match3d/item_assets.rs` 承接物品 sheet 生成、绿幕 / 近白底透明化、切图、append / replace / delete / sort / merge 和素材持久化。
+- `server-rs/crates/api-server/src/match3d/vector_engine_gemini.rs` 承接 VectorEngine Gemini 请求体、响应解析、base64 图片下载和上游错误归一。
+- `server-rs/crates/api-server/src/match3d/runtime.rs` 保留运行态轻量归一 helper；`mappers.rs` / `tags.rs` / `tests.rs` 分别承接 DTO 映射、标签 / 通用错误 helper 和原有单测。
+
+该拆分只改变 `api-server` 文件组织，不改变 `/api/creation/match3d/*`、`/api/runtime/match3d/*` route、DTO、error envelope、SpacetimeDB schema、公开 gallery cache 语义、VectorEngine / OSS 副作用边界或计费语义；后续继续细分时也必须先保持行为不变，再单独讨论领域规则下沉到 `module-match3d`。
+
 生成资产 Adapter 规则：
 
 1. 稳定单图链路可收敛到 `api-server` 内部生成资产 Adapter：provider 生成、下载/base64 解码、MIME/extension 归一、OSS private upload、HEAD、asset object confirm、entity binding。
@@ -240,7 +260,7 @@ npm run check:server-rs-ddd
 ### `battle_state`
 
 - Rust 结构体：`BattleState`
-- 源码：`server-rs/crates/spacetime-module/src/gameplay/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`
 
 ### `big_fish_agent_message`
 
@@ -278,7 +298,7 @@ npm run check:server-rs-ddd
 ### `chapter_progression`
 
 - Rust 结构体：`ChapterProgression`
-- 源码：`server-rs/crates/spacetime-module/src/gameplay/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`
 
 ### `creation_entry_config`
 
@@ -293,38 +313,38 @@ npm run check:server-rs-ddd
 ### `custom_world_agent_message`
 
 - Rust 结构体：`CustomWorldAgentMessage`
-- 源码：`server-rs/crates/spacetime-module/src/custom_world/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
 
 ### `custom_world_agent_operation`
 
 - Rust 结构体：`CustomWorldAgentOperation`
-- 源码：`server-rs/crates/spacetime-module/src/custom_world/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
 
 ### `custom_world_agent_session`
 
 - Rust 结构体：`CustomWorldAgentSession`
-- 源码：`server-rs/crates/spacetime-module/src/custom_world/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
 
 ### `custom_world_draft_card`
 
 - Rust 结构体：`CustomWorldDraftCard`
-- 源码：`server-rs/crates/spacetime-module/src/custom_world/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
 
 ### `custom_world_gallery_entry`
 
 - Rust 结构体：`CustomWorldGalleryEntry`
-- 源码：`server-rs/crates/spacetime-module/src/custom_world/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
 - 作用：自定义世界公开作品列表读模型。`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM custom_world_gallery_entry` 与 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'custom-world'`，`/api/runtime/custom-world-gallery` 从本地 cache 排序并聚合 `recentPlayCount7d`，不再每个 HTTP 请求调用 `list_custom_world_gallery_entries` procedure。旧 procedure 只用于兼容旧库缺少 gallery 读模型行时的一次性同步兜底。
 
 ### `custom_world_profile`
 
 - Rust 结构体：`CustomWorldProfile`
-- 源码：`server-rs/crates/spacetime-module/src/custom_world/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
 
 ### `custom_world_session`
 
 - Rust 结构体：`CustomWorldSession`
-- 源码：`server-rs/crates/spacetime-module/src/custom_world/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
 
 ### `database_migration_import_chunk`
 
@@ -339,7 +359,7 @@ npm run check:server-rs-ddd
 ### `inventory_slot`
 
 - Rust 结构体：`InventorySlot`
-- 源码：`server-rs/crates/spacetime-module/src/gameplay/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`
 
 ### `match3d_agent_message`
 
@@ -365,18 +385,18 @@ npm run check:server-rs-ddd
 
 - Rust view：`match3d_gallery_view`
 - 返回类型：`Vec<Match3DGalleryViewRow>`
-- 源码：`server-rs/crates/spacetime-module/src/match3d/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/match3d.rs`
 - 说明：抓大鹅公开广场列表投影，只暴露 `publication_status = published` 的作品卡片字段；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM match_3_d_gallery_view` 与 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'match3d'` 后，从本地 cache 构造 `/api/runtime/match3d/gallery` 响应。公开列表不再每个 HTTP 请求调用 `list_match3d_works` procedure；个人作品列表、详情、发布、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。
 
 ### `npc_state`
 
 - Rust 结构体：`NpcState`
-- 源码：`server-rs/crates/spacetime-module/src/gameplay/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`
 
 ### `player_progression`
 
 - Rust 结构体：`PlayerProgression`
-- 源码：`server-rs/crates/spacetime-module/src/gameplay/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`
 
 ### `profile_dashboard_state`
 
@@ -546,12 +566,12 @@ npm run check:server-rs-ddd
 ### `quest_log`
 
 - Rust 结构体：`QuestLog`
-- 源码：`server-rs/crates/spacetime-module/src/gameplay/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`
 
 ### `quest_record`
 
 - Rust 结构体：`QuestRecord`
-- 源码：`server-rs/crates/spacetime-module/src/gameplay/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`
 
 ### `refresh_session`
 
@@ -592,18 +612,18 @@ npm run check:server-rs-ddd
 
 - Rust view：`square_hole_gallery_view`
 - 返回类型：`Vec<SquareHoleGalleryViewRow>`
-- 源码：`server-rs/crates/spacetime-module/src/square_hole/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/square_hole.rs`
 - 说明：方洞挑战公开广场列表投影，只暴露 `publication_status = published` 的作品卡片字段；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM square_hole_gallery_view` 与 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'square-hole'` 后，从本地 cache 构造 `/api/runtime/square-hole/gallery` 响应。公开列表不再每个 HTTP 请求调用 `list_square_hole_works` procedure；个人作品列表、详情、发布、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。
 
 ### `story_event`
 
 - Rust 结构体：`StoryEvent`
-- 源码：`server-rs/crates/spacetime-module/src/gameplay/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`
 
 ### `story_session`
 
 - Rust 结构体：`StorySession`
-- 源码：`server-rs/crates/spacetime-module/src/gameplay/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`
 
 ### `tracking_daily_stat`
 
@@ -618,7 +638,7 @@ npm run check:server-rs-ddd
 ### `treasure_record`
 
 - Rust 结构体：`TreasureRecord`
-- 源码：`server-rs/crates/spacetime-module/src/gameplay/mod.rs`
+- 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`
 
 ### `user_account`
 

docs/【玩法创作】平台入口与玩法链路-2026-05-15.md

@@ -8,6 +8,8 @@
 
 当前创作 Tab 固定为智能创作首页与模板入口，草稿 Tab 承接作品架。点击独立入口后应切换到对应内嵌创作表单或生成页；不要额外做一张平行配置页，除非玩法本身需要完整独立工作台。
 
+`PlatformEntryFlowShellImpl.tsx` 仍是平台入口编排壳，后续维护时应优先把独立 UI 片段、公开作品映射、草稿生成 notice 和运行态状态 helper 拆到 `src/components/platform-entry/PlatformEntryFlowShellImpl/` 或同目录紧邻 helper 文件。拆分只允许改变文件组织，不改变入口配置事实源、默认导出、props、页面阶段、UI 文案或现有交互；其中拼图首访 onboarding 已拆为 `PlatformEntryFlowShellImpl/PuzzleOnboardingView.tsx`。
+
 ## 草稿与作品架
 
 1. 草稿页作品卡对齐发现页列表卡风格：左侧信息，右侧封面图，移动端单列，桌面两到三列。