Genarrative/server-rs

server-rs 工作区占位说明

日期：2026-04-20

1. 目录用途

server-rs/ 是本项目新 Rust 后端的固定根目录，用于承载以下重写目标：

1. Axum HTTP / SSE 边界层
2. SpacetimeDB 状态机模块
3. 阿里云 OSS 资产接入与应用层编排

该目录固定放在仓库根目录，与 src/、docs/ 同级。旧 server-node/ 已完成物理删除，后续只可通过历史提交或迁移文档追溯。

2. 当前阶段说明

当前目录已经完成以下三十七项初始化：

1. 为新后端预留正式目录并把路径固定到仓库结构中。
2. 创建虚拟 workspace Cargo.toml，后续 crate 会逐项挂入。
3. 明确内部采用“crates/* 统一承载主工程 crate 与独立模块 crate”的多 crate 组织方式。
4. 创建 crates/api-server/ 目录占位，固定 Axum 主工程 crate 落位。
5. 创建 crates/spacetime-module/ 目录占位，固定 SpacetimeDB 主工程 crate 落位。
6. 创建 crates/module-auth/ 目录占位，固定鉴权模块 crate 落位。
7. 创建 crates/module-runtime/ 目录占位，固定运行时状态基座模块 crate 落位。
8. 创建 crates/module-story/ 目录占位，固定故事主循环模块 crate 落位。
9. 创建 crates/module-combat/ 目录占位，固定战斗规则模块 crate 落位。
10. 创建 crates/module-inventory/ 目录占位，固定背包与物品变更模块 crate 落位。
11. 创建 crates/module-npc/ 目录占位，固定 NPC 状态与互动模块 crate 落位。
12. 创建 crates/module-progression/ 目录占位，固定成长与章节推进模块 crate 落位。
13. 创建 crates/module-quest/ 目录占位，固定任务运行时模块 crate 落位。
14. 创建 crates/module-runtime-item/ 目录占位，固定运行时物品模块 crate 落位。
15. 创建 crates/module-custom-world/ 目录占位，固定自定义世界与 agent 模块 crate 落位。
16. 创建 crates/module-assets/ 目录占位，固定资产任务与对象绑定模块 crate 落位。
17. 创建 crates/module-ai/ 目录占位，固定 AI 编排模块 crate 落位。
18. 创建 crates/shared-contracts/ 目录占位，固定前后端兼容 contract 共享 crate 落位。
19. 创建 crates/shared-kernel/ 目录占位，固定跨模块共享领域内核 crate 落位。
20. 创建 crates/shared-logging/ 目录占位，固定工作区统一日志 crate 落位。
21. 创建 crates/platform-auth/ 目录占位，固定鉴权平台适配 crate 落位。
22. 创建 crates/platform-oss/ 目录占位，固定 OSS 平台适配 crate 落位。
23. 创建 crates/platform-llm/ 目录占位，固定大模型平台适配 crate 落位。
24. 创建 crates/spacetime-client/ 目录占位，固定 SpacetimeDB 客户端适配 crate 落位。
25. 创建 crates/tests-support/ 共享测试支撑 crate，固定 smoke/contract 测试辅助能力落位。
26. 创建 scripts/dev.ps1，固定 Windows 本地开发入口。
27. 创建 scripts/dev.sh，固定 Unix-like 本地开发入口。
28. 创建 scripts/test.ps1，固定 Windows 本地测试入口。
29. 创建 scripts/test.sh，固定 Unix-like 本地测试入口。
30. 创建 scripts/check.ps1，固定 Windows 本地统一检查入口。
31. 创建 scripts/check.sh，固定 Unix-like 本地统一检查入口。
32. 创建 scripts/smoke.ps1，固定 Windows 本地冒烟验证入口。
33. 创建 scripts/smoke.sh，固定 Unix-like 本地冒烟验证入口。
34. 创建 scripts/spacetime-dev.ps1，固定 Windows 本地 SpacetimeDB 启动入口。
35. 创建 scripts/spacetime-dev.sh，固定 Unix-like 本地 SpacetimeDB 启动入口。
36. 创建 scripts/oss-smoke.ps1，固定 Windows 本地阿里云 OSS 真实联调入口。
37. 固定 Vite dev proxy 的 Rust api-server 默认目标与 GENARRATIVE_RUNTIME_SERVER_TARGET 覆盖开关。

后续任务会继续在本目录内按顺序补齐：

1. crates/spacetime-module 的表、reducer、view 聚合入口
2. module-auth 的身份表、JWT 与 refresh cookie 主链
3. platform-oss 的浏览器直传签名、旧 /generated-* 前缀到 OSS object key 的映射与对象 URL 解析能力；/generated-* 不再作为可裸读 HTTP 路由

当前本地脚本补充说明：

1. scripts/smoke.ps1 用于验证 api-server 的本地 /healthz 基础 contract。
2. scripts/oss-smoke.ps1 用于验证真实阿里云 OSS：
   • 读取仓库根目录 .env / .env.local
   • 启动临时 api-server
   • 请求 /api/assets/direct-upload-tickets
   • 实际执行 PostObject 上传
   • 校验对象存在并默认自动删除

3. 已冻结边界

本目录后续落地时必须继续遵守 M0 已冻结的边界：

1. 旧 server-node/ 不再作为当前工程目录保留；若需查证旧实现，只允许通过历史提交、迁移文档或已迁移到 server-rs/ 的实现对照。
2. 前端在 M0 ~ M6 期间只访问 Axum，不直连 SpacetimeDB。
3. 外部副作用统一收口在 Axum / crate 内应用层 / infra。
4. crates/api-server 只组合与暴露协议，不直接吞并业务模块实现。
5. crates/spacetime-module 只负责汇总各模块 crate 的表、reducer、view。
6. 当前允许在 M3 / M4 / M5 前先行落地 OSS 基础设施，但不因此跳过后续资产状态建模与绑定迁移。

4. SpacetimeDB 实施约束

凡是涉及 SpacetimeDB 的工程修改、脚本执行、接口接入与前端绑定，统一要求显式使用以下 skill：

1. $spacetimedb-cli
2. $spacetimedb-rust
3. $spacetimedb-concepts
4. $spacetimedb-typescript

执行口径：

1. spacetime CLI、发布、绑定生成、本地联调按 spacetimedb-cli 执行。
2. crates/spacetime-module 的 Rust 表、reducer、view 与模块 API 按 spacetimedb-rust、spacetimedb-concepts 执行。
3. 前端或 Node 侧的 SpacetimeDB TypeScript SDK、订阅、绑定使用按 spacetimedb-typescript、spacetimedb-concepts 执行。
4. 若仓库内旧实现或旧文档与这些 skill 冲突，先修正文档和方案，再继续编码。

6. DDD 目录与边界

2026-04-28 起，server-rs 进入 DDD 边界收口阶段，完整规则见 ../docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md。

新增或迁移业务代码时必须遵守：

1. module-* 统一维护 domain.rs、commands.rs、application.rs、events.rs、errors.rs。
2. module-* 不新增 Axum、reqwest、OSS、LLM、文件系统、SpacetimeDB table/reducer/procedure 依赖。
3. mapper.rs 只允许出现在 api-server、spacetime-module、spacetime-client 等 adapter crate。
4. spacetime-module 新增业务入口前先确认是否已有对应上下文目录，禁止继续把大段业务流程堆回 src/lib.rs。
5. 根目录可执行 npm run check:server-rs-ddd 检查第一阶段 DDD 骨架与绝对边界。

5. 关联文档

1. ../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md
2. ../backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md
3. ../backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md