开发指南是业务研发与平台运维同学日常开发的高频实战手册。它总结了从单文件垂直切片编写、前后端元数据自动充水、六边形适配器扩展，到本地 Aspire 基础设施编排与代客操作沙箱的标准化落地范式。
开发指南全景路线图
核心指南实战矩阵
| 指南名称与链接 | 核心解决问题 | 适合角色 |
|---|---|---|
| 1. 编写写操作切片 | 一用例一文件标准、10 级管道拦截与领域聚合根编写 | 后端开发 / 全员 |
| 2. 前后端集成与自动充水 | OpenAPI 零手写 SDK、页级元数据投影与字典多语言充水 | 全栈 / 前端开发 |
| 3. 新增后台管理页面 | React 19 + TanStack Query 仪表盘页面与 RBAC 权限挂载 | 前端开发 |
| 4. 为现有模块新增 Feature | 规范化增加新业务能力、命令/查询分流与单元测试 | 后端开发 |
| 5. 从零新增独立业务模块 | 规划 Contracts/Domain 物理工程、IAppModule 与 ArchUnit 门禁 | 核心开发 / 架构师 |
| 6. 编写六边形适配器 | 定义领域窄端口、封装三方超时重试与 Fallback 安全回退 | 后端开发 |
| 7. 本地基础设施编排 | .NET Aspire 一键拉起 SQL Server / Redis、数据持久化与重置 | 全员 / 运维 |
| 8. 平台代客模拟沙箱 | 运维短效 JWT 模拟登录、双身份审计与只读安全沙箱 | 运维 / 安全 |
| 9. 声明式种子数据填充 | 模块级 ISeedDataContributor 编写与幂等数据填充 | 后端开发 / 实施 |
| 10. 框架版本升级指南 | .NET 10 升级策略、Roslyn 缓存重置与无缝数据库迁移 | 架构师 / 运维 |
| 11. 接入全局搜索与索引治理 | 同事务增量索引事件、权威重建源、来源目录配置、命中复核与端到端验证 | 后端开发 / 架构师 |
| 12. CLI 双轨发布与分发 | 公共 NuGet.org 与企业云效私有源双轨流水线、packageSourceMapping 防投毒与 CI/CD 自动化 | 平台工程 / 运维 / 架构师 |
本章核心导航
- 01/15
实战：如何编写一个写操作切片（Command Slice）
遵循“一用例一文件”原则，从零编写一个企业级写操作垂直切片：包含 Minimal API 路由契约、RBAC 动作鉴权、IRequestRule 纯函数校验规则、ICommandRepository 窄端口恢复与领域聚合根状态流转。
- 02/15
实战：前后端集成与元数据自动充水（Hydration）
深入掌握 BitzOrcas.Modern 前后端集成范式：OpenAPI 零手写 TypeScript SDK 自动生成、IReadModelMetaMapped 页级元数据投影、10 级管道第 10 级字典与关联实体充水与 React 19 最佳实践。
- 03/15
实战：为现有业务模块新增一个完整 Feature
掌握在 BitzOrcas.Modern 既有业务模块中新增功能的标准化 5 步流水线：扩展领域聚合根不变量、编写单文件命令切片、声明式配置端点与 RBAC 权限、使用 ICommandRepository 持久化与编写 Testcontainers 集成测试。
- 04/15
实战：从零新增一个独立业务模块（Module）
掌握在 BitzOrcas.Modern 中新增独立深模块的完整工程规范：规划 Contracts/Domain/Application 物理工程划分、继承 TenantAggregateRoot 领域聚合根、配置 IAppModule 架构治理元数据与编写 ArchUnit 架构守卫防线。
- 05/15
实战：编写六边形架构基础设施适配器（Adapter）
掌握 BitzOrcas.Modern 六边形端口与适配器模式：在领域层定义依赖倒置窄端口（Port）、在基础设施层编写生产适配器（Adapter）、封装第三方网络异常、配置 Polly 弹性策略与注册 Fallback 安全回退。
- 06/15
实战：新增一个后台管理页面（Dashboard Page）
掌握在 BitzOrcas.Modern React 19 + TanStack Query 现代前端单体工程中新增管理页面的标准全流程：声明路由与菜单元数据、消费 OpenAPI 自动生成的强类型 TypeScript SDK、实现页级元数据自动充水表格与绑定 RBAC 细粒度权限看门狗。
- 07/15
实战：本地基础设施与 .NET Aspire 编排环境
深入掌握 BitzOrcas.Modern 本地开发环境编排：使用 .NET Aspire AppHost 一键拉起 SQL Server 2022、Redis 7 与 MinIO 容器、真实端口映射矩阵、数据卷持久化配置与零停机数据库架构重置。
- 08/15
实战：平台代客操作模拟（Operator Impersonation）与安全审计
掌握 BitzOrcas.Modern 平台运维代客模拟机制：签发短效双身份 JWT 令牌、DelegatedSessionRestrictionPipelineBehavior 敏感操作阻断守卫与不可篡改操作员双身份审计追踪。
- 09/15
实战：声明式种子数据填充（Seed Data）与幂等初始化
掌握 BitzOrcas.Modern 种子数据初始化规范：实现 ISeedStep 契约、分层环境门禁（Global / Tenant / Demo / ProductionSafe）、依赖 DAG 拓扑解析与基于 --init-schema 的幂等自动化播种。
- 10/15
实战：框架版本升级指南与变更迁移手册
BitzOrcas.Modern 框架版本平滑升级指南：NuGet 包依赖集中版本锁定（CPM）、Roslyn 增量生成器缓存清理、数据库架构平滑迁移、前端 Yarn 依赖对齐与全仓架构门禁验收。
- 11/15
实战：业务模块接入全局搜索与索引治理
掌握业务模块接入 BitzOrcas.Modern 全局搜索的完整闭环：同事务发布增量索引事件、编写权威重建源、宿主来源目录配置、权威命中复核器与架构测试锁定，以及治理页全量对账与端到端验证。
- 12/15
实战：Bitz CLI 的 NuGet 双轨分发与发版运维手册
Bitz CLI 工具链的双轨分发与发布管理实战指南：面向公网 NuGet.org 与企业云效私有制品源的双轨流水线、packageSourceMapping 防投毒隔离、离线本地包验证与自动化发版 CI/CD。
- 13/15
EF Core 同构集成与拦截器实战
实战指南：在 BitzOrcas.Modern 中配置与使用 EF Core，深入 Audit 拦截器、PII 数据加密、全局租户过滤与 CAP 事务发件箱集成。
- 14/15
Dapper 只读连接池与极限查询优化
实战指南：在 BitzOrcas.Modern 中使用 Dapper 与只读从库连接池，压榨复杂报表、全文大屏与高并发分页查询的极限吞吐。
- 15/15
企业架构十大反模式与避坑宝典
资深全栈架构师视角的生产避坑指南：剖析异步死锁、跨模块穿透、租户隔离泄露、分表时钟漂移等 10 大典型违规反模式与防御方案。