决策记录

用途：记录已经确认、会影响后续开发的长期技术/产品/协作决策。短期讨论不要写在这里。

记录格式

## YYYY-MM-DD 决策标题

- 背景：为什么需要这个决策
- 决策：最终决定是什么
- 影响范围：涉及哪些模块/文档/流程
- 验证方式：如何确认决策仍有效
- 关联文档：相关 PRD、技术文档、提交或 Issue

背景：项目已经全面移除 Maincloud 运行口径，但历史脚本、测试名和文档仍可能让后续开发误用 api-server:maincloud 或 GENARRATIVE_SPACETIME_MAINCLOUD_*。
决策：maincloud / Maincloud / MAINCLOUD 相关代码、脚本、测试、环境变量、命令和文档要求全部视为历史残留，后续禁止新增、运行或引用；后端 API smoke 统一使用 npm run api-server 并检查 /healthz。
影响范围：AGENTS.md、docs/technical/、.hermes/shared-memory/、后端启动脚本、测试支撑和所有后续工程文档。
验证方式：新增或修改后端相关文档时，检查不得要求 api-server:maincloud 或 GENARRATIVE_SPACETIME_MAINCLOUD_*；触碰历史残留时同步删除或改名。
关联文档：docs/technical/MAINCLOUD_REFERENCE_REMOVAL_POLICY_2026-05-06.md、docs/technical/SPACETIMEDB_CLOUD_CONFIG_REMOVAL_2026-05-02.md。

背景：团队有 3 名开发人员，均在各自本地安装 Hermes，并需要独立拉取仓库、修改代码、本地测试；团队希望形成共享的长期项目记忆。
决策：不共享个人 ~/.hermes，先在 Genarrative 仓库内使用 .hermes/ 保存可 Git 同步的团队共享记忆、计划和未来 skills。
影响范围：AGENTS.md、.hermes/README.md、.hermes/shared-memory/。
验证方式：任一开发者拉取仓库后，在项目根目录启动 Hermes，均可读取同一套 .hermes/shared-memory/ 文件。
关联文档：.hermes/README.md、.hermes/shared-memory/team-conventions.md。

背景：项目经历过 Node/Express/PostgreSQL、Go 试验、Rust/SpacetimeDB 等多条后端路线，旧路线文档容易造成开发歧义。
决策：新功能以后端当前基线为准：HTTP 门面使用 Rust api-server / Axum，业务真相使用 SpacetimeDB，领域和契约在 server-rs 多 crate 分层维护。
影响范围：所有后端、数据真相、运行时状态、创作结果、用户系统、资产、任务、埋点、后台 API 等相关开发。
验证方式：开发前优先阅读 CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md；旧 server-node、Express、PostgreSQL、Go 方向只允许作为迁移参考。
关联文档：docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md、AGENTS.md。

背景：server-rs 模块多、上下文多，需防止领域规则、SpacetimeDB 表、HTTP BFF、前端临时逻辑互相污染。
决策：按 DDD 总纲和 G1 契约/路由矩阵开发：module-* 承载领域，spacetime-module 承载表和事务，spacetime-client 承载 facade，api-server 承载 HTTP/SSE/BFF，platform-* 承载外部副作用，shared-contracts 承载 DTO。
影响范围：server-rs 全部 crate、前端 API client、SpacetimeDB schema、旧接口清理。
验证方式：执行任务前对照 DDD 总纲、并行任务清单、G1 矩阵；提交前运行相关 DDD 边界检查和定向测试。
关联文档：SERVER_RS_DDD_FULL_REFACTOR_2026-04-28.md、SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md、SERVER_RS_DDD_PARALLEL_TASKLIST_2026-04-29.md。

背景：SpacetimeDB 的 schema 迁移模型不同于 PostgreSQL，部分变更会触发冲突或拒绝自动迁移。
决策：凡涉及 table、reducer、procedure、row shape 或 binding 变化，必须同步 migration.rs、表目录和生成绑定；涉及 private 表迁移时按 JSON 导入导出和分片导入流程处理。
影响范围：server-rs/crates/spacetime-module、spacetime-client bindings、SPACETIMEDB_TABLE_CATALOG.md、部署/发布脚本。
验证方式：发布前检查 SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md 清单，更新 SPACETIMEDB_TABLE_CATALOG.md，执行生成绑定和相关测试。
关联文档：SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md、SPACETIMEDB_TABLE_CATALOG.md、SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md。

背景：旧一体化启动脚本和历史 Jenkinsfile 已不再是生产发布唯一入口。
决策：生产部署以 systemd 托管 SpacetimeDB 与 Rust api-server，Nginx 负责站点和代理，生产 Jenkinsfile 按 web/api/stdB module/build/deploy/publish 拆分。
影响范围：部署脚本、服务器目录、维护模式、Jenkins、Nginx、systemd 服务。
验证方式：生产发布、服务器配置、Jenkins Job 重建或回滚时，先看 PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md。
关联文档：PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md。

背景：“我的”Tab、任务、奖励、钱包和埋点涉及用户、运营、分析多条链路，需要避免范围泛化。
决策：埋点原始事实进入 tracking_event，聚合投影进入 tracking_daily_stat；个人任务配置/进度/领奖/钱包分别进入 profile_task_config、profile_task_progress、profile_task_reward_claim、profile_wallet_ledger；首版个人任务 scope 仅支持 user。
影响范围：用户侧任务中心、后台任务配置、运营查询、埋点查询、钱包流水。
验证方式：非 user scope 的个人任务配置应被 API 和领域构造层拒绝；任务查询与埋点查询分别放在 docs/operations/ 和 docs/tracking/。
关联文档：PROFILE_TASK_AND_TRACKING_SYSTEM_2026-05-03.md、RUNTIME_PROFILE_TASK_SCOPE_2026-05-04.md、ANALYTICS_DATE_DIMENSION_IMPLEMENTATION_2026-05-04.md。