106 lines
6.6 KiB
Markdown
106 lines
6.6 KiB
Markdown
# 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 落位。
|
||
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. 创建 `scripts/m7-preflight.ps1`，固定 M7 切流前 Rust 后端预检入口。
|
||
38. 固定 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-*` 前缀映射与对象 URL 解析能力
|
||
|
||
当前本地脚本补充说明：
|
||
|
||
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](.codex\\skills\\spacetimedb-cli\\SKILL.md)
|
||
2. [$spacetimedb-rust](.codex\\skills\\spacetimedb-rust\\SKILL.md)
|
||
3. [$spacetimedb-concepts](.codex\\skills\\spacetimedb-concepts\\SKILL.md)
|
||
4. [$spacetimedb-typescript](.codex\\skills\\spacetimedb-typescript\\SKILL.md)
|
||
|
||
执行口径：
|
||
|
||
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 冲突，先修正文档和方案，再继续编码。
|
||
|
||
## 5. 关联文档
|
||
|
||
1. [../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)
|
||
2. [../backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md](../backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md)
|
||
3. [../backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md](../backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md)
|