server-rs 工作区占位说明
日期：2026-04-20
1. 目录用途
server-rs/ 是本项目新 Rust 后端的固定根目录，用于承载以下重写目标：
AxumHTTP / SSE 边界层SpacetimeDB状态机模块阿里云 OSS资产接入与应用层编排
该目录固定放在仓库根目录，与 src/、docs/ 同级。旧 server-node/ 已完成物理删除，后续只可通过历史提交或迁移文档追溯。
2. 当前阶段说明
当前目录已经完成以下三十八项初始化：
- 为新后端预留正式目录并把路径固定到仓库结构中。
- 创建虚拟 workspace
Cargo.toml，后续 crate 会逐项挂入。 - 明确内部采用“
crates/*统一承载主工程 crate 与独立模块 crate”的多 crate 组织方式。 - 创建
crates/api-server/目录占位，固定 Axum 主工程 crate 落位。 - 创建
crates/spacetime-module/目录占位，固定 SpacetimeDB 主工程 crate 落位。 - 创建
crates/module-auth/目录占位，固定鉴权模块 crate 落位。 - 创建
crates/module-runtime/目录占位，固定运行时状态基座模块 crate 落位。 - 创建
crates/module-story/目录占位，固定故事主循环模块 crate 落位。 - 创建
crates/module-combat/目录占位，固定战斗规则模块 crate 落位。 - 创建
crates/module-inventory/目录占位，固定背包与物品变更模块 crate 落位。 - 创建
crates/module-npc/目录占位，固定 NPC 状态与互动模块 crate 落位。 - 创建
crates/module-progression/目录占位，固定成长与章节推进模块 crate 落位。 - 创建
crates/module-quest/目录占位，固定任务运行时模块 crate 落位。 - 创建
crates/module-runtime-item/目录占位，固定运行时物品模块 crate 落位。 - 创建
crates/module-custom-world/目录占位，固定自定义世界与 agent 模块 crate 落位。 - 创建
crates/module-assets/目录占位，固定资产任务与对象绑定模块 crate 落位。 - 创建
crates/module-ai/目录占位，固定 AI 编排模块 crate 落位。 - 创建
crates/shared-contracts/目录占位，固定前后端兼容 contract 共享 crate 落位。 - 创建
crates/shared-kernel/目录占位，固定跨模块共享领域内核 crate 落位。 - 创建
crates/shared-logging/目录占位，固定工作区统一日志 crate 落位。 - 创建
crates/platform-auth/目录占位，固定鉴权平台适配 crate 落位。 - 创建
crates/platform-oss/目录占位，固定 OSS 平台适配 crate 落位。 - 创建
crates/platform-llm/目录占位，固定大模型平台适配 crate 落位。 - 创建
crates/spacetime-client/目录占位，固定 SpacetimeDB 客户端适配 crate 落位。 - 创建
crates/tests-support/共享测试支撑 crate，固定 smoke/contract 测试辅助能力落位。 - 创建
scripts/dev.ps1，固定 Windows 本地开发入口。 - 创建
scripts/dev.sh，固定 Unix-like 本地开发入口。 - 创建
scripts/test.ps1，固定 Windows 本地测试入口。 - 创建
scripts/test.sh，固定 Unix-like 本地测试入口。 - 创建
scripts/check.ps1，固定 Windows 本地统一检查入口。 - 创建
scripts/check.sh，固定 Unix-like 本地统一检查入口。 - 创建
scripts/smoke.ps1，固定 Windows 本地冒烟验证入口。 - 创建
scripts/smoke.sh，固定 Unix-like 本地冒烟验证入口。 - 创建
scripts/spacetime-dev.ps1，固定 Windows 本地 SpacetimeDB 启动入口。 - 创建
scripts/spacetime-dev.sh，固定 Unix-like 本地 SpacetimeDB 启动入口。 - 创建
scripts/oss-smoke.ps1，固定 Windows 本地阿里云 OSS 真实联调入口。 - 固定 Vite dev proxy 的 Rust
api-server默认目标与GENARRATIVE_RUNTIME_SERVER_TARGET覆盖开关。 - 固定
Cargo.toml依赖集中配置口径，第三方版本和 workspace 内部 crate path 统一维护在根server-rs/Cargo.toml。
后续任务会继续在本目录内按顺序补齐：
crates/spacetime-module的表、reducer、view 聚合入口module-auth的身份表、JWT 与 refresh cookie 主链platform-oss的浏览器直传签名、旧/generated-*前缀到 OSS object key 的映射与对象 URL 解析能力；/generated-*不再作为可裸读 HTTP 路由
当前本地脚本补充说明：
scripts/smoke.ps1用于验证api-server的本地/healthz基础 contract。scripts/oss-smoke.ps1用于验证真实阿里云 OSS：- 读取仓库根目录
.env/.env.local - 启动临时
api-server - 请求
/api/assets/direct-upload-tickets - 实际执行
PostObject上传 - 校验对象存在并默认自动删除
- 读取仓库根目录
3. 已冻结边界
本目录后续落地时必须继续遵守 M0 已冻结的边界：
- 旧
server-node/不再作为当前工程目录保留；若需查证旧实现，只允许通过历史提交、迁移文档或已迁移到server-rs/的实现对照。 - 前端在
M0 ~ M6期间只访问 Axum，不直连 SpacetimeDB。 - 外部副作用统一收口在 Axum / crate 内应用层 / infra。
crates/api-server只组合与暴露协议，不直接吞并业务模块实现。crates/spacetime-module只负责汇总各模块 crate 的表、reducer、view。- 当前允许在
M3 / M4 / M5前先行落地OSS基础设施，但不因此跳过后续资产状态建模与绑定迁移。
4. SpacetimeDB 实施约束
凡是涉及 SpacetimeDB 的工程修改、脚本执行、接口接入与前端绑定，统一要求显式使用以下 skill：
执行口径：
spacetimeCLI、发布、绑定生成、本地联调按spacetimedb-cli执行。crates/spacetime-module的 Rust 表、reducer、view 与模块 API 按spacetimedb-rust、spacetimedb-concepts执行。- 前端或 Node 侧的 SpacetimeDB TypeScript SDK、订阅、绑定使用按
spacetimedb-typescript、spacetimedb-concepts执行。 - 若仓库内旧实现或旧文档与这些 skill 冲突，先修正文档和方案，再继续编码。
6. DDD 目录与边界
2026-04-28 起，server-rs 进入 DDD 边界收口阶段，完整规则见 ../docs/technical/SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md。
新增或迁移业务代码时必须遵守：
module-*统一维护domain.rs、commands.rs、application.rs、events.rs、errors.rs。module-*不新增 Axum、reqwest、OSS、LLM、文件系统、SpacetimeDB table/reducer/procedure 依赖。mapper.rs只允许出现在api-server、spacetime-module、spacetime-client等 adapter crate。spacetime-module新增业务入口前先确认是否已有对应上下文目录，禁止继续把大段业务流程堆回src/lib.rs。- 根目录可执行
npm run check:server-rs-ddd检查第一阶段 DDD 骨架与绝对边界。
7. Cargo 依赖配置口径
2026-05-07 起，server-rs 的依赖版本和 workspace 内部 crate path 统一维护在根 Cargo.toml 的 [workspace.dependencies]，完整记录见 ../docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md。
成员 crate 的 Cargo.toml 默认使用 { workspace = true } 继承依赖；只在成员 crate 内保留本 crate 的 feature、optional、target-specific dependency 等差异。新增 crate 或新增依赖时，应优先补根 workspace 依赖，再在成员 crate 中继承。