# 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](../../../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](../../../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](../../../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](../../../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](../../../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](../../../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` 骨架。