BitzOrcas 开发说明书

这套说明书既服务第一次接触 BitzOrcas 的开发者，也服务要做架构决策、生产部署和商业交付的负责人。文档以当前源码、自动化门禁和可运行示例为事实来源；带“设计”或“待交付”标记的页面不会冒充现成功能。

按目标进入

• 第一次运行：从认识 BitzOrcas和快速开始进入。
• 开发业务能力：先看第一个垂直切片，再看新增模块。
• 理解技术边界：阅读架构总览和模块化单体。
• 选择平台能力：使用模块目录和对应运行手册。
• 处理数据库与消息：从持久化和事件开始。
• 准备交付：执行测试策略、Consumer Contract与Commercial GA。

先区分两种读者环境

客户项目不复制或修改 Framework、Platform、Licensing Runtime 与核心 Generator 源码。需要定制时，使用 Contracts、Store、Policy、Strategy、Options、Integration Event 或 Pipeline Hook。

文档怎样表达成熟度

如果正文与源码冲突，以源码和自动门禁为准，并修正文档与 verify-source 事实。不要为了“教程顺畅”虚构接口、幂等性或可靠性。

最小源码核查

# 在产品源码仓库根目录执行。
dotnet build BitzOrcas.Modern.slnx --configuration Release
dotnet test tests/BitzOrcas.Architecture.Tests/BitzOrcas.Architecture.Tests.csproj --configuration Release

最小说明书核查

# 在说明书仓库根目录执行。
npm run verify:docs
npm run verify:docs-source
npm run verify:docs-depth
npm run build

局部页面通过不等于全站完成。最终交付还要求严格深度审计归零所有 baseline 页面、双语链接可解析、Mermaid 与代码块可渲染、生产静态构建和搜索索引成功。

一次变更应带走哪些证据

1. 业务结果、失败语义和安全边界的说明。
2. 带领域语义注释的可运行或明确标记伪代码。
3. 真正帮助理解责任交接的图，而不是装饰性流程框。
4. 单元、集成、架构、Provider parity 与 Consumer 测试中适用的部分。
5. 可复制的源码扫描命令、预期结果和允许例外。
6. 当前未实现能力进入知识库/架构治理清单，不在说明书里伪装完成。

• 01

  快速开始

  BitzOrcas.Modern 开发者上手总览：从架构哲学认知、前置依赖审查、Docker 容器基础设施拉起，到执行首个多租户垂直切片业务用例。

  6 页
• 02

  实战教程

  BitzOrcas.Modern 官方进阶实战通关地图。通过 6 个循序渐进的工业级真实业务场景（案件立案、合同模块、利冲校验、合伙人审批流、实时通知与集成测试），系统掌握 .NET 10 模块化单体开发技能。

  6 页
• 03

  开发指南

  BitzOrcas.Modern 核心开发指南目录：涵盖垂直切片编写、前端元数据充水、功能与模块新增、六边形适配器扩展、本地 Aspire 基础设施与代客模拟沙箱。

  15 页
• 04

  核心构建块

  全景梳理 BitzOrcas.Modern 核心构建块武器库，从统一聚合根、QueryShape 列表查询内核、CAP Outbox 到多级缓存与 S3 存储。

  16 页
• 05

  横切关注点

  理解 BitzOrcas 如何在 HTTP 中间件、Mediator 管线和生产适配器之间分配横切职责。

  14 页
• 06

  安全与授权

  从认证、授权、租户隔离、请求完整性、数据保护和审计理解 BitzOrcas 的纵深防御。

  14 页
• 07

  架构体系

  全面解析 BitzOrcas.Modern 企业级架构体系：模块化单体物理边界、垂直切片架构、10 级执行管道、编译期零反射双 ORM 与 Native AOT 架构支点。

  7 页
• 08

  架构决策 (ADR)

  BitzOrcas ADR 索引——分类法、生命周期、编号，以及与交付、安全、运维和模块化最相关的已选决策。

  9 页
• 09

  全景架构图

  BitzOrcas.Modern 系统架构的可视化图表集合。

  22 页
• 10

  工程治理

  让一次 BitzOrcas 发布具备可交付性的质量门禁、生产就绪棘轮、扩展接入、模块治理、就绪矩阵与行业中立规则。

  7 页
• 11

  平台能力中心

  BitzOrcas.Modern 平台级专业业务子系统、跨模块核心引擎与规则治理中心。

  51 页
• 12

  业务模块扩展

  深入解析 BitzOrcas.Modern 业务模块架构规范、ADR 0203 物理隔离准则、ADR 0205 平台扩展模式与 Sandbox 黄金样例。

  3 页
• 13

  工作流引擎

  从可视化设计器、定义 DSL、部署绑定、实例与任务，到通知、历史、迁移、嵌入和生产运维的源码校验导航。

  11 页
• 14

  AI 与智能体

  深入解析 BitzOrcas.Modern 原生 AI-Native 架构：基于 Model Context Protocol (MCP) 与编译期代码生成，将企业垂直切片无缝转变为智能体工具。

  3 页
• 15

  前端架构

  BitzOrcas 前端是一个 Yarn 4 单仓。Web 管理端是 React 19 + Vite；移动端是 Taro 4 + Capacitor。两侧都经唯一的类型化契约抵达 .NET 后端。

  9 页
• 16

  Design Token

  BitzOrcas Design System 1.2 的冻结范围、权威顺序、稳定主题、体验 Profile 与代码实现状态。

  9 页
• 17

  CLI 工具

  选择 Consumer Solution 模板、代码生成、Schema、Seed、Workflow 与数据库维护入口，并理解每个工具的写入面、权限和证据边界。

  14 页
• 18

  测试体系

  从单元测试到商业发布证据，理解 BitzOrcas 的五层测试体系，并按改动选择正确验证集。

  7 页
• 19

  生产部署

  从本地 Aspire 到生产 Host、配置、数据库、可观测性和商业 GA，规划 BitzOrcas 部署。

  12 页
• 20

  商业交付

  从产品仓库、NuGet 包、Consumer Solution 到正式 GA，理解 BitzOrcas 的商业交付边界和证据链。

  5 页
• 21

  其他

  查阅代码提交约定、文档维护方式、版本记录和后续投资方向。

  5 页