From fc2e9132a5ac3709ebb88837acf01edf4748ef0d Mon Sep 17 00:00:00 2001 From: kdletters Date: Tue, 21 Apr 2026 00:24:11 +0800 Subject: [PATCH] docs: keep side effects in axum boundary --- .../01_M0_M2_FOUNDATION_AND_AUTH.md | 3 +- ...EPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md | 43 ++++++++++++++++++- ...M_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md | 1 + 3 files changed, 45 insertions(+), 2 deletions(-) diff --git a/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md b/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md index 0b9d4072..0fc0a257 100644 --- a/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md +++ b/backend-rewrite-tasklist/01_M0_M2_FOUNDATION_AND_AUTH.md @@ -25,7 +25,8 @@ 交付物：[M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md](./M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md) - [x] 确认前端第一阶段仍然只访问 Axum，不直连 SpacetimeDB 交付物：[M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md](./M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md) -- [ ] 确认外部副作用统一收口在 Axum，不放进 SpacetimeDB 模块 +- [x] 确认外部副作用统一收口在 Axum，不放进 SpacetimeDB 模块 + 交付物：[M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md](./M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md) ### 交付物 diff --git a/backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md b/backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md index a47023ac..39d98caf 100644 --- a/backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md +++ b/backend-rewrite-tasklist/M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md @@ -21,7 +21,7 @@ | Rust 后端新目录名与根目录落位方案 | 已确认 | 新 Rust 后端固定为仓库根目录下的 `server-rs/`，与 `server-node/` 同级。 | | 旧 `server-node/` 在迁移期继续保留，不提前删除 | 已确认 | `server-node/` 在 `M0 ~ M6` 期间持续保留，直到 `M7` 切流与回退验证完成后再评估清理。 | | 前端第一阶段仍然只访问 Axum，不直连 SpacetimeDB | 已确认 | `M0 ~ M6` 前端统一只访问 Axum 暴露的 `/api/*`、`/healthz`、SSE 与静态资源兼容层，不新增直连 SpacetimeDB 原生协议路径。 | -| 外部副作用统一收口在 Axum，不放进 SpacetimeDB 模块 | 待确认 | 后续补充。 | +| 外部副作用统一收口在 Axum，不放进 SpacetimeDB 模块 | 已确认 | OSS、LLM、短信、微信 OAuth、本地文件系统等外部副作用统一落在 Axum/application/infra，不进入 SpacetimeDB reducer/module。 | ## 3. 已确认决议一：`server-rs/` 固定落在仓库根目录 @@ -156,3 +156,44 @@ Genarrative/ 1. `M1 ~ M2` 的 Axum 中间件与鉴权必须先跑通，再谈前端联调。 2. `M3 ~ M6` 新增的 SpacetimeDB reducer/view 先通过 Axum facade 暴露，不直接要求前端改成原生 SpacetimeDB 客户端。 3. 若后续要让前端直连 SpacetimeDB，只能作为第二阶段优化事项，不能混入当前重写主链。 + +## 7. 已确认决议四：外部副作用统一收口在 Axum + +### 7.1 决议内容 + +本次重写固定采用以下边界： + +1. `SpacetimeDB` 只负责状态、规则、reducer、view、订阅读模型。 +2. `Axum/application/infra` 统一负责所有外部副作用。 + +固定收口到 Axum 的外部副作用包括： + +1. 阿里云 OSS 上传、下载、签名、直传凭证 +2. DashScope / Ark / 其他 LLM 请求 +3. 微信 OAuth +4. 手机验证码短信发送与校验编排 +5. 本地文件系统读写 + +### 7.2 明确不允许放进 SpacetimeDB 的内容 + +以下能力当前明确禁止进入 `spacetime-module/`： + +1. 直接发 HTTP 请求给第三方供应商 +2. 直接访问 OSS SDK +3. 直接读写本地磁盘 +4. 直接处理 Cookie、回调跳转、multipart 上传 +5. 直接承担供应商重试、熔断、超时与日志策略 + +### 7.3 这样决议的原因 + +1. 这些能力都强依赖 HTTP 头、Cookie、SDK、签名、超时与日志，不适合绑进 SpacetimeDB 模块发布周期。 +2. 当前前端 contract、鉴权、SSE、静态资源兼容都要求一个稳定的 HTTP 边界层，Axum 更适合承担这个角色。 +3. 把副作用统一收口到 Axum，才能让 SpacetimeDB 保持“状态机真相源”的纯度。 + +### 7.4 对后续任务的直接约束 + +从这一条决议开始，后续任务必须遵守： + +1. `M1` crate 设计时，`oss-service`、`llm-service`、`auth-service` 固定属于 Axum/application 侧。 +2. `M2 ~ M6` 设计 reducer 时，只写状态变更，不直接发外部请求。 +3. 若确实需要异步副作用，也必须由 Axum worker 或应用层作业执行，再把结果回写 SpacetimeDB。 diff --git a/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md b/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md index 1af552b8..5e0ef994 100644 --- a/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md +++ b/docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md @@ -75,6 +75,7 @@ - `SpacetimeDB` 负责状态、规则、订阅、命令执行与读模型。 - `Axum` 负责所有外部副作用与 HTTP 协议。 +- 在本次重写中，不为 SpacetimeDB module 增加任何外部副作用例外通道。 ### 3.2 Axum 的边界