Files
persionalBrand/docs/adr/0027-api-module-boundaries-and-route-regression.md

45 lines
3.0 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 0027. API Module 边界与路由防回潮
## Context
多品牌 API 已经按 public、customer、admin 领域拆分 Controller,但 `AppModule` 仍一次性注册所有 Controller 和 Provider,后台 workspace Controller 也承担了 offerings、template、capability、inquiry 等多个资源入口。连续重构后,API 模块需要明确共享层、领域层和根模块的职责边界,并用测试防止后续路由意外变化。
## Decision
- API 根模块只负责组装领域 Module 和全局配置,不直接注册领域 Controller 或业务 Provider。
- 领域 Module 按职责拆分为 `PublicModule`、`CustomerModule`、`SessionModule`、`TenantModule`、`WorkspaceModule`、`AdminModule`、`BookingModule`、`HealthModule`。
- `PrismaService`、鉴权、模板工作区、发布快照等跨领域基础设施统一放在 `InfrastructureModule`,由领域 Module 显式导入。
- 共享 infrastructure 不得 import feature module;feature 之间的依赖必须通过被导入 Module 的显式 export 暴露。
- workspace 后台路由按资源拆分 Controller,但保持 URL、方法、请求体和响应契约不变。
- 路由清单测试锁定拆分后的 admin workspace 与 uploads 路由;新增或迁移路由必须同步更新清单测试。
- Controller 只处理 transport:路由、DTO、鉴权入口、状态码和响应形状;key 生成、存储、持久化和校验进入 service。
## Alternatives
1. 继续在 `AppModule` 集中注册所有 Controller 和 Provider:启动简单,但任何领域变更都会触碰根模块,依赖边界无法约束。
2. 为每个 Controller 建立独立 Module:文件更多,且共享服务容易重复实例化,不适合当前规模。
3. 只靠 code review 约束路由不变:无法防止路由搬迁或前缀拼写错误,不能作为回归门槛。
## Consequences
### Positive
- 领域边界与依赖方向清晰,新增领域时不会继续膨胀根模块。
- 共享服务单例归属明确,跨 Module 依赖必须在 export / import 中显式声明。
- 路由清单测试为 API 路径提供防回潮保护,降低连续拆分的风险。
- Controller 更薄,授权与业务行为更容易通过 service 单测和 HTTP 集成测试分层验证。
### Negative
- Module 数量和文件数量增加,新成员需要先理解组装关系。
- 路由新增或迁移必须同步维护清单测试。
- 共享服务放入 infrastructure 前需要确认是否真的跨领域,避免形成新的上帝层。
## Migration Plan
1. 已完成 workspace Controller 和 `AppModule` 领域化拆分。
2. 已完成媒体上传 DTO、service 与 controller 边界拆分。
3. 已加入路由清单测试、上传服务边界测试和完整 HTTP 集成回归。
4. 后续新增 API 领域时先创建领域 Module,再由根模块组装;新增后台路由必须加入路由清单测试。
5. 剩余大 Controller 在修改对应领域时按同一规则逐步下沉 service,不做无行为收益的大规模搬迁。