# 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,不做无行为收益的大规模搬迁。