Prune stale docs and update .hermes content
Delete a large set of outdated documentation (many files under docs/ and .hermes/plans/, including audits, design, prd, technical, planning, assets, and todos). Update and consolidate .hermes content: refresh shared-memory pages (decision-log, development-workflow, document-map, pitfalls, project-overview, team-conventions) and several skills/references under .hermes/skills. Also modify AGENTS.md, README.md, UI_CODING_STANDARD.md, docs/README.md and .encoding-check-ignore. Purpose: clean up stale planning/audit material and keep current hermes documentation and related top-level docs in sync.
This commit is contained in:
@@ -1,134 +0,0 @@
|
||||
# M7 联调、回归、部署与切流执行方案
|
||||
|
||||
日期：`2026-04-22`
|
||||
|
||||
归档说明：截至 `2026-04-26`，Rust 迁移已完成，旧 `server-node/` 已删除，M7 阶段性预检包装入口已移除。后续长期检查统一使用 `server-rs/scripts/check.ps1`、`server-rs/scripts/smoke.ps1`、`server-rs/scripts/oss-smoke.ps1` 与 `npm run api-server`。
|
||||
|
||||
## 1. 文档目标
|
||||
|
||||
这份文档把 `M7：联调、回归、部署与切流任务清单` 从高层勾选项细化为可直接执行的工程方案。
|
||||
|
||||
M7 的目标不是新增玩法功能，而是在 `M0 ~ M6` 已迁移的 Rust 后端基础上完成切流前收口：
|
||||
|
||||
1. 固定本地、灰度、切流前的检查命令。
|
||||
2. 固定 `Axum + SpacetimeDB + OSS` 的部署与回滚口径。
|
||||
3. 固定观测字段、慢请求、上游失败日志与资产任务日志。
|
||||
4. 固定旧 `server-node` 删除后的 Rust 主线回归与部署验证方式。
|
||||
5. 等价拆分 `server-rs/crates/spacetime-module/src/lib.rs`，避免 SpacetimeDB 主工程继续退化为单大文件。
|
||||
|
||||
## 2. 执行约束
|
||||
|
||||
1. 不改变现有 HTTP contract、SSE contract、SpacetimeDB 表名、reducer 名、procedure 名和对象键前缀。
|
||||
2. 不把 LLM、OSS、短信、微信等外部副作用移入 SpacetimeDB reducer。
|
||||
3. `spacetime-module` 拆分只做物理结构收口，不做 schema 重命名、字段删除、字段重排或 reducer/procedure 改名。
|
||||
4. `server-node/` 已进入物理删除流程，M7 不再把旧 Node 后端作为运行时回退锚点。
|
||||
5. 前端默认指向 Rust `api-server`；如需临时覆盖目标，只允许使用 `RUST_SERVER_TARGET` 或 `GENARRATIVE_RUNTIME_SERVER_TARGET` 指向 Rust 兼容服务。
|
||||
|
||||
## 3. 测试体系
|
||||
|
||||
M7 固定四层测试入口：
|
||||
|
||||
1. Rust crate 级别：`cargo check/test` 覆盖 `api-server`、`spacetime-module`、`shared-contracts` 与模块 crate。
|
||||
2. Axum handler 级别：继续复用 `api-server` 内已有 `build_router + tower::ServiceExt` 测试，重点覆盖 `healthz/auth/runtime/assets/custom-world/story` 的兼容响应。
|
||||
3. SpacetimeDB 模块级别：`cargo check -p spacetime-module` 作为 schema/reducer/procedure 的最低门禁；需要真实数据库行为时使用 `spacetime publish --server local --yes` 后再跑 smoke。
|
||||
4. 端到端主流程：`server-rs/scripts/smoke.ps1` 与 `server-rs/scripts/oss-smoke.ps1` 分别覆盖基础 HTTP contract 与真实 OSS 链路。
|
||||
|
||||
推荐本地顺序：
|
||||
|
||||
```powershell
|
||||
.\server-rs\scripts\check.ps1
|
||||
.\server-rs\scripts\smoke.ps1
|
||||
```
|
||||
|
||||
## 4. 部署准备
|
||||
|
||||
Axum 部署方式：
|
||||
|
||||
1. `cargo build -p api-server --release` 生成发布二进制。
|
||||
2. 进程环境显式配置 `GENARRATIVE_API_HOST`、`GENARRATIVE_API_PORT`、`GENARRATIVE_API_LOG`。
|
||||
3. 反向代理继续保留 `Host`、`X-Forwarded-For`、`X-Forwarded-Proto`、`X-Request-Id`。
|
||||
4. SSE 路由必须禁用代理缓冲。
|
||||
|
||||
SpacetimeDB 发布方式：
|
||||
|
||||
1. 本地开发先执行 `server-rs/scripts/spacetime-dev.ps1` 启动 standalone。
|
||||
2. 发布模块使用 `spacetime publish genarrative-dev --server local --yes --module-path server-rs/crates/spacetime-module`。
|
||||
3. 若需要重置开发库，必须显式加 `--clear-database --yes`，不得默认清库。
|
||||
4. 生成绑定时使用仓库根目录 `spacetime.json` 中的 `typescript` 与 `rust` 输出目录。
|
||||
|
||||
OSS / CDN / 域名方案：
|
||||
|
||||
1. 正式对象真相仍为 `bucket + object_key`。
|
||||
2. bucket 默认私有读写，浏览器不直接匿名读取。
|
||||
3. `/generated-*` 旧路径由 Axum 同源代理或 CDN 边缘回源到 Rust API。
|
||||
4. CDN 只缓存可公开缓存的派生读结果，不把私有签名 URL 写入业务表。
|
||||
|
||||
环境变量最小清单：
|
||||
|
||||
1. `GENARRATIVE_API_HOST`、`GENARRATIVE_API_PORT`、`GENARRATIVE_API_LOG`
|
||||
2. `GENARRATIVE_JWT_ISSUER`、`GENARRATIVE_JWT_SECRET`
|
||||
3. `GENARRATIVE_SPACETIME_SERVER_URL`、`GENARRATIVE_SPACETIME_DATABASE`、`GENARRATIVE_SPACETIME_TOKEN`
|
||||
4. `ALIYUN_OSS_BUCKET`、`ALIYUN_OSS_ENDPOINT`、`ALIYUN_OSS_ACCESS_KEY_ID`、`ALIYUN_OSS_ACCESS_KEY_SECRET`
|
||||
5. `GENARRATIVE_LLM_PROVIDER`、`GENARRATIVE_LLM_BASE_URL`、`GENARRATIVE_LLM_API_KEY`
|
||||
6. `DASHSCOPE_BASE_URL`、`DASHSCOPE_API_KEY`
|
||||
7. `SMS_AUTH_ENABLED` 与短信供应商变量
|
||||
8. `WECHAT_AUTH_ENABLED` 与微信 OAuth 变量
|
||||
9. `RUST_SERVER_TARGET`、`GENARRATIVE_RUNTIME_SERVER_TARGET`
|
||||
|
||||
## 5. 灰度与切流
|
||||
|
||||
灰度环境固定为三段：
|
||||
|
||||
1. `preflight`：只跑 Rust 预检、smoke 与人工主链验证，不接正式用户流量。
|
||||
2. `limited-rust`：小范围账号或灰度域名访问 Rust `api-server`，差异必须登记到 M7 验收记录。
|
||||
3. `rust-primary`：反向代理或 Vite dev proxy 指向 Rust `api-server`，旧 Node 后端不作为运行时入口保留。
|
||||
|
||||
前端切换方式：
|
||||
|
||||
1. 默认使用 `RUST_SERVER_TARGET` 或 `GENARRATIVE_API_TARGET` 指向 Rust `api-server`。
|
||||
2. 本地或灰度可覆盖 `GENARRATIVE_RUNTIME_SERVER_TARGET`，但目标仍必须是 Rust 兼容服务。
|
||||
3. 紧急回退优先回滚到上一个 Rust 发布包或反向代理配置，不恢复 `server-node/` 工程目录。
|
||||
|
||||
## 6. API 回归
|
||||
|
||||
第一批删除后不再保留 Node/Rust 对比脚本，M7 回归改为 Rust 主线 contract 验证：
|
||||
|
||||
1. `server-rs/scripts/check.ps1` 覆盖 Rust 工作区格式、clippy、构建与测试门禁。
|
||||
2. `server-rs/scripts/smoke.ps1` 覆盖 `/healthz`、envelope 与 request id 基础 contract。
|
||||
3. `server-rs/scripts/oss-smoke.ps1` 覆盖真实 OSS 链路。
|
||||
4. 新增只读 contract 时优先补进 Rust 侧 smoke 或 handler 测试，不恢复 Node 对比脚本。
|
||||
|
||||
带登录、写入、OSS 或 SSE 的主流程仍由专门 smoke、handler 测试和人工验证清单负责。
|
||||
|
||||
## 7. 观测能力
|
||||
|
||||
M7 观测字段固定为：
|
||||
|
||||
1. HTTP 访问日志：`method`、`uri`、`status`、`latency_ms`、`slow_request`、`request_id`
|
||||
2. 错误日志：`request_id`、`status`、`error_code`
|
||||
3. 上游失败：`provider`、`operation`、`request_id`、`status/code`、`message`
|
||||
4. 关键 reducer：操作名、主实体 ID、结果状态
|
||||
5. 资产任务：`task_id`、`character_id/entity_id`、`asset_kind`、`status`
|
||||
|
||||
慢请求阈值默认 `1000ms`，可通过 `GENARRATIVE_SLOW_REQUEST_THRESHOLD_MS` 覆盖。
|
||||
|
||||
## 8. 数据迁移与回滚
|
||||
|
||||
当前 M7 不做一次性历史数据导入 SpacetimeDB 的危险迁移，采用按主链确认的渐进策略：
|
||||
|
||||
1. 已迁移主链以 SpacetimeDB 为真相源。
|
||||
2. 未迁移或灰度失败主链必须继续迁入 Rust 主线后再开放，不回退到旧 Node 工程。
|
||||
3. 资产二进制以 OSS 为真相，不回滚到本地 `public/generated-*` 写盘。
|
||||
4. 若 SpacetimeDB schema 需要清库重发，只允许在开发库或明确灰度库执行 `--clear-database`。
|
||||
5. 生产回滚优先切反向代理目标，不优先改代码。
|
||||
|
||||
## 9. 验收定义
|
||||
|
||||
M7 完成时必须满足：
|
||||
|
||||
1. M7 文档、脚本、任务清单均同步。
|
||||
2. `api-server` 和 `spacetime-module` 至少通过 `cargo check`。
|
||||
3. 基础 smoke 脚本可执行，并覆盖 `healthz + envelope + request id`。
|
||||
4. Rust 主线预检和 smoke 脚本可执行。
|
||||
5. Vite dev proxy 默认指向 Rust `api-server`，仅保留 Rust 目标覆盖开关。
|
||||
6. `spacetime-module` 已从单 `lib.rs` 拆为按 `runtime / gameplay / custom_world / asset_metadata / ai` 组织的文件结构。
|
||||
Reference in New Issue
Block a user