Genarrative/server-rs/crates/module-puzzle

module-puzzle 独立模块 package 说明

日期：2026-04-29

1. package 职责

module-puzzle 是拼图创作、作品 profile 与运行态规则模块 package，后续负责：

1. Puzzle Agent 会话、消息、锚点包与结果草稿的纯领域模型。
2. 拼图作品 profile、发布门禁、标签规则与作品列表投影。
3. 拼图运行态开局、交换、拖动、合并、拆分、过关和下一关推荐规则。
4. 与 spacetime-module 的拼图表、reducer、procedure 和事件聚合对接。

2. 当前阶段说明

当前阶段已经不再只是目录占位，已先固定拼图领域 contract 与最小规则函数。

当前已落地：

1. src/domain.rs 承接 Puzzle 基础 ID 前缀、标签数量、洗牌次数常量、基础枚举、Agent session、message、anchor、result draft、work profile、runtime board/run 等领域类型。
2. src/commands.rs 承接 SpacetimeDB procedure/reducer 写入输入。
3. src/application.rs 承接 procedure 返回包装、标签归一化、草稿编译、发布覆盖、开局、交换、拖动、合并、拆分和下一关推荐的纯规则。
4. src/errors.rs 承接拼图字段错误与中文错误文案。
5. src/events.rs 承接草稿变化、作品发布和运行态推进的最小领域事件。
6. spacetime-types feature 下可供 SpacetimeDB 绑定复用的类型派生。
7. 正式平台 Puzzle 运行态已经接入后端真相源：结果页草稿预览、作品开局、交换、拖动、下一关和排行榜都通过 Rust API / SpacetimeDB procedure 裁决。
8. 旧 /api/runtime/puzzle/runs/local-next-level 已由 WP-DEL 物理删除；正式 API 只保留 run scoped 的 /api/runtime/puzzle/runs/{run_id}/next-level。

当前 crate 仍然只承接：

1. 拼图领域常量、枚举、快照类型和纯规则。
2. 字段校验、标签归一化与运行态规则。
3. 后续 spacetime-module 聚合表时需要复用的领域边界。

当前阶段明确不提前进入：

1. 图片生成、OSS 上传或 AI prompt 编排。
2. Axum 路由、SSE 或前端展示状态。
3. SpacetimeDB table、reducer、procedure 的直接定义。

当前设计依据：

1. ../../../docs/technical/SERVER_RS_DDD_WP_PZ_DOMAIN_ENUM_REHOME_2026-04-29.md
2. ../../../docs/technical/SERVER_RS_DDD_WP_PZ_DOMAIN_SPLIT_2026-04-29.md
3. ../../../docs/technical/SERVER_RS_DDD_WP_PZ_RUNTIME_BACKEND_TRUTH_CLOSURE_2026-05-01.md
4. ../../../docs/technical/SERVER_RS_DDD_WP_DEL_CLEANUP_2026-05-01.md
5. ../../../docs/technical/PUZZLE_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-22.md
6. ../../../docs/technical/PUZZLE_RESULT_AUTOSAVE_AND_TAG_GATE_FIX_2026-04-28.md

3. 边界约束

1. module-puzzle 不直接调用图片生成、OSS、HTTP、SSE 或 SpacetimeDB SDK。
2. 领域函数不依赖前端临时状态，拼图运行态真相最终由 SpacetimeDB 表承载。
3. api-server 负责 LLM、图片生成和请求响应映射；spacetime-module 负责表、reducer、procedure 与事件。
4. 后续迁移必须优先复用现有 domain.rs、commands.rs、application.rs、events.rs、errors.rs 骨架。