ADR 0203: 物理目录结构 Framework + Modules
状态
已采纳 (Accepted)
日期
2026-06-30
背景
BitzOrcasVNext 的 src/ 目录早期使用 BuildingBlocks/ + Platform/ 扁平结构。随着模块化单体演进和业务模块增长，该结构存在两个问题：
- 语义模糊：
BuildingBlocks名称不直接表达“框架底座”语义，Platform不区分系统级平台与业务模块。 - 防腐隔离不足：框架内核（Domain/Application/Infrastructure/SG）与默认 Platform 能力在同一层，后续模块更新可能耦合框架底座。
ABP 等成熟框架实践表明：框架底座与业务模块应在物理目录层面明确分离，避免代码演进时的耦合。
决策
将 src/ 顶级目录重组为 Framework/ + Platform/ + Modules/ 物理分层结构：
1. BuildingBlocks → Framework
src/Framework/ 存放纯技术框架底座（零业务依赖），包含：
| 子分组 | 项目 | 职责 |
|---|---|---|
| 核心 | Domain / Application / Modularity | 领域模型、应用管线、模块治理 |
| SourceGenerators | DI.Attributes / DI.SourceGenerator / Endpoint.SourceGenerator | 编译期零反射 DI 与端点发现（ADR 0103） |
| CodeGeneration | CodeGeneration.Abstractions / CodeGeneration.Scriban | 模版代码生成与输入审计 |
| Persistence.Metadata | Persistence.Metadata / Persistence.Metadata.Generator | provider-neutral metadata 与 ORM Fluent 配置生成 |
| Infrastructure | Infrastructure / Infrastructure.SqlSugar / EfCore / Dapper / Storage.S3Compatible | ORM 适配器与持久化 |
| Workflow | Workflow.Abstractions / Engine / Persistence / SqlSugar / EfCore / Dapper | 自研轻量级高性能工作流引擎 |
2. Platform → src/Platform
src/Platform/ 是模板默认 Platform 的正式位置，用于存放模板内置平台能力的 Contracts / Domain / Application / Infrastructure / Endpoints 项目。Platform 与 src/Modules/** 同级，物理上区分模板资产与采用模板后的业务模块。
| 位置 | 职责 | 状态 |
|---|---|---|
src/Platform/** | 默认 Platform 的目标结构；承载 36 个模板内置平台能力 | 正式路径 |
src/Modules/<Category>/<Module>/** | 采用模板后的业务系统自建业务模块 | 业务路径 |
src/Modules/Sandbox/** | 模板演示与架构测试样例 | 示例路径 |
未来采用模板的业务系统应在 /src/Modules/{BusinessModule}/ 创建自己的模块分组，不得把定制代码塞回默认 Platform 目录。
3. 不变的约定
- Assembly 名不变：所有
.csproj的<AssemblyName>保持原值（如BitzOrcas.Platform.Application），架构测试的Assembly.Load不受影响。 - 命名空间不变：所有 C# 源代码的
namespace声明保持不变。 - Hosts/Tooling 不变：
src/Hosts/和src/Tooling/保持原位。
限制与约束
- 项目名（
.csproj文件名）不改，仅改物理目录路径。 - 新建默认 Platform 能力应使用
src/Platform/<Capability>/。 - 新增业务模块时，应在
Modules/下创建独立子目录（如Modules/Business/Cases/），与 Platform 系统级模块物理隔离。