认识 BitzOrcas.Modern：设计哲学、架构拓扑与执行管道

分布式系统的第一法则是不要过早进行分布式拆分。在过去十年的企业软件演进中，大量团队陷入了“微服务狂热（Microservices Hype）”：一个仅有十几人研发规模的系统被强行拆解成数十个独立服务，随之而来的是分布式事务崩溃、链路网络延迟不可控、跨服务版本断崖式失配以及指数级膨胀的 Kubernetes 基础设施维护成本。

然而，退回传统的“三层单体架构（Layered Monolith）”同样充满陷阱：控制器臃肿不堪、业务逻辑四散在各个 Service 内部、跨领域的直接数据库外键依赖横行无忌，最终软件在几年内迅速退化为不可维护的大泥球（Big Ball of Mud）。

BitzOrcas.Modern 旨在终结这种非此即彼的架构撕裂。作为面向 .NET 10 LTS 与 C# 14 构建的企业级模块化单体底座，它通过严格的物理边界治理（ArchUnitNET）、垂直切片架构（Vertical Slice）与零反射编译期生成器（Source Generators），在单一代码仓库和单一进程内同时实现单体架构的开发调试极速体验与微服务级别的强物理隔离。

核心架构拓扑全景

BitzOrcas.Modern 的系统分层自上而下严格遵循单向依赖，底层基础设施与编译期生成器共同为上层业务领域提供零反射运行时：

一次入站请求的完整生命周期（端到端时序）

在 BitzOrcas.Modern 中，任何写操作（Command）或复杂读操作（Query）均不直接在 Controller 或 Minimal API Lambda 中堆砌业务逻辑。请求被包装为强类型的 Mediator 请求后，必须顺次穿透由框架严格受控的 10 级线性执行管道：

核心架构原则与设计权衡

1. 垂直切片架构（Vertical Slice Architecture）

传统架构通常采用自上而下的横向技术分层：

Controllers/ ──> Services/ ──> Repositories/ ──> Entities/

当团队需要为“律所利益冲突检索”新增一个校验字段时，开发者必须在 ConflictController、IConflictService、ConflictService、ConflictDto、ConflictMapper、ConflictEntity 之间来回跳跃，认知负荷极其沉重。

BitzOrcas 彻底颠覆这一模式，采用**“以业务用例为核心的垂直切片”**。每个业务切片独立内聚为一个独立的编译单元：

src/Platform/Identity/BitzOrcas.Identity.Application/Commands/Login/
├── Login.cs               # Minimal API 路由定义 + Mediator Command 契约
├── LoginHandler.cs        # 纯粹的业务领域编排逻辑
├── LoginRequestRule.cs    # 强类型不变量静态校验规则 (Tier 1)
└── LoginResult.cs         # 强类型返回模型 (无贫血包装)

• 高内聚低耦合：业务变更仅限于单个切片目录，多人并行开发零 Git 冲突；
• 重构自愈：删除一个业务功能只需物理删除对应切片目录，不会在全工程留下难以清理的死代码残留。

2. 10 级应用执行管道（Mediator Pipeline Behaviors）

框架将所有企业级非功能性需求（Non-Functional Requirements）全部下沉至管道中由框架托管。各管道按严格的确定性顺序执行，保证业务 Handler 纯净无污染：

3. 统一聚合根与编译期双 ORM 生成

在许多传统系统中，开发者被要求区分 DomainModel 与 DatabaseEntity，导致系统充斥着成百上千个毫无实际意义的 AutoMapper 映射配置。

在 BitzOrcas.Modern 中，对于 95% 的业务场景，领域聚合根即持久化模型（Unified Aggregate Root）：

• 聚合根继承自 Entity<TId> 或 AggregateRoot<TId>，使用强类型 ID（如 UserId、MatterId）；
• 通过标记中立的 Fluent 映射元数据，Roslyn 增量生成器（Incremental Source Generator）在编译期直接产出高性能的静态绑定逻辑；
• 双 ORM 生产级适配：支持 SqlSugar（默认主适配器）与 EF Core 并列运行，业务层完全基于 IEntitySet<TAggregate> 进行抽象，永不泄漏具体 ORM 的底层类型。

跨模块协作硬性物理法则

为了防止单体项目在团队规模扩大后退化为纠缠不清的复杂网络，模块间交互必须严格遵守以下 5 项硬性物理法则：

1. 契约单向依赖：模块 A 如需调用模块 B 的能力，只允许项目引用 B.Contracts，严禁直接引用 B.Application、B.Domain 或 B.Infrastructure。
2. 读操作走只读查询端口：跨模块同步数据获取必须通过目标模块在 *.Contracts 中暴露的专用只读服务（如 IUserLookupService），严禁跨模块直接注入对方的 IEntitySet<T>。
3. 写操作必须走命令分派或异步事件：跨模块的业务联动优先通过 CAP 事务性发件箱发布集成事件（Integration Event）完成最终一致性；同步写操作必须分派强类型 Mediator Command。
4. 领域事件严禁跨越模块边界：聚合根通过 AddDomainEvent() 产生的事件仅在当前模块内部、同一事务的执行管道中分发；跨模块通知必须转换为明确的集成事件。
5. 数据库 Schema 严格隔离：各模块在物理数据库中拥有独立的表前缀或独立的 Database Schema，严禁书写跨模块表的隐式 SQL JOIN 查询。

核心术语字典（Glossary）

解决方案物理组织架构

在 /Users/linxinyu/Git/Repos/Codeup/BitzOrcasVNext 中，源码仓库按照严格的工程边界进行物理分层：

src/
├── Framework/                         # 零业务依赖的纯技术底座
│   ├── BitzOrcas.Application/         # 10 级管道行为、校验策略接口、授权抽象
│   ├── BitzOrcas.Domain/              # 实体基类、统一聚合根接口、Result/Error 原语
│   ├── BitzOrcas.Persistence/         # 双持久化 Adapter (SqlSugar / EF Core) 与元数据
│   └── BitzOrcas.Workflow/            # 自研轻量级 DAG 状态机工作流引擎内核
├── Platform/                          # 平台通用商业能力模块 (以 NuGet/私有包交付)
│   ├── Identity/                      # 多租户管理、用户认证、2FA、外部登录与密码加密
│   ├── Authorization/                 # RBAC、ABAC、ReBAC Lite 统一授权决策中心
│   ├── Auditing/                      # 全局活动审计日志、实体变更 Diff 追踪与信封
│   ├── Files/                         # 对象存储抽象、分片上传与文件生命周期
│   └── Notifications/                 # 站内信、邮件、短信多通道消息分发
├── Hosts/                             # 运行宿主与组合根 (Composition Root)
│   ├── BitzOrcas.Api/                 # Minimal API 主程序入口，装配全量模块路由
│   ├── BitzOrcas.Gateway/             # YARP 边缘反向代理与流量调度中心
│   └── BitzOrcas.JobHost/             # Quartz.NET 独立作业宿主，承载租户定时任务
└── Tooling/                           # 研发效能与工程工具链
    ├── BitzOrcas.Cli/                 # 官方 CLI 脚手架，一键生成垂直切片与模块
    └── BitzOrcas.Generators/          # Roslyn 增量源生成器，消除反射装配

通过这一套严谨的架构设计，BitzOrcas.Modern 既赋予了开发者在单体中飞速编码与联调的敏捷度，又赋予了企业在架构演进至超大规模时无缝拆分微服务的物理自由度。