在长期演进的企业级大型工程中，框架底层与核心依赖库的升级是一项高风险活动：个别工程私自升级包版本引发依赖冲突、Roslyn 增量生成器因本地磁盘缓存未刷新导致类型丢失，以及数据库架构变更引发停机故障。

BitzOrcas.Modern 贯彻“集中管控、无状态生成与全自动化验收”的现代化升级范式：

集中式包版本管理（Central Package Management, CPM）：全仓所有的 NuGet 包版本均在根目录 Directory.Packages.props 中唯一声明，单个子 .csproj 严禁出现版本号；
生成器缓存绝对清理：升级底层框架包后，必须清除本地 bin/、obj/ 与 Roslyn 增量磁盘缓存，保障类型生成 100% 纯净；
数据库架构平滑演进：通过 API Host 组合根的 --init-schema 机制，自动对数据库执行幂等比对与索引补强；
前后端双轨门禁验收：全仓通过 dotnet test（架构守卫与 Testcontainers 容器测试）及前端 yarn build（Bundle Budget 预算门禁）共同闭环。

本手册为架构师与研发运维团队提供标准 4 步升级作业流程。

框架升级 4 步标准操作流

第一步：在集中式依赖文件中统一更新版本号

全仓所有的 NuGet 包版本均由根目录下的 Directory.Packages.props 集中管控，严禁在单个子 .csproj 文件中硬编码 Version 属性：

<Project>
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
  </PropertyGroup>

  <ItemGroup>
    <!-- .NET 10 官方运行时与扩展库基线 -->
    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Logging.Abstractions" Version="10.0.0" />
    <PackageVersion Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="10.0.0" />

    <!-- 数据库与 ORM 依赖组件 -->
    <PackageVersion Include="Microsoft.EntityFrameworkCore.SqlServer" Version="10.0.0" />
    <PackageVersion Include="SqlSugarCore" Version="5.1.4.195" />

    <!-- 分布式与集成中间件 -->
    <PackageVersion Include="DotNetCore.CAP" Version="8.3.0" />
    <PackageVersion Include="DotNetCore.CAP.RabbitMQ" Version="8.3.0" />
    <PackageVersion Include="DotNetCore.CAP.SqlServer" Version="8.3.0" />
    <PackageVersion Include="StackExchange.Redis" Version="2.8.24" />

    <!-- 测试框架与 Testcontainers 容器基线 -->
    <PackageVersion Include="Testcontainers.MsSql" Version="4.1.0" />
    <PackageVersion Include="Testcontainers.Redis" Version="4.1.0" />
    <PackageVersion Include="ArchUnitNET.xUnit" Version="0.11.1" />
  </ItemGroup>
</Project>

第二步：彻底清理 Roslyn 增量源生成器缓存

由于 BitzOrcas 深度依赖 Roslyn 增量源生成器（如 BitzOrcas.Endpoint.SourceGenerator 与 BitzOrcas.DI.SourceGenerator）生成 Minimal API 端点与持久化 DI 装配代码，升级框架包后必须清理本地旧缓存：

# 1. 彻底清除全仓 bin 与 obj 目录 (保留 IDE 配置文件)
git clean -xdf -e ".vs" -e ".idea"

# 2. 重新恢复并强制全量无增量编译 (Release 配置)
dotnet restore BitzOrcas.Modern.slnx
dotnet build BitzOrcas.Modern.slnx -c Release --no-incremental

第三步：执行数据库架构兼容性平滑迁移

使用 API Host 提供的标准化运维命令执行数据库架构比对与种子数据增量校准：

# 1. 执行表结构检查并自动补全缺失字段与索引
dotnet run --project src/Hosts/BitzOrcas.Api -- --init-schema

# 2. 若涉及演示密码重置需求 (开发与测试环境)
USER__ADMIN__PASSWORD="YourStrongPassword123!" dotnet run --project src/Hosts/BitzOrcas.Api -- --init-schema --reset-demo-passwords

第四步：全仓双轨自动化门禁验收

升级完成后，必须依次在终端执行后端测试套件与前端构建门禁：

# 1. 后端：运行模块边界架构守卫测试 (防横向依赖穿透)
dotnet test tests/BitzOrcas.Architecture.Tests/

# 2. 后端：运行基于 Testcontainers 的容器化真实全链路集成测试
dotnet test tests/BitzOrcas.Integration.Tests/

# 3. 前端：切换至 frontend/ 运行严格类型检查与打包预算验证
cd frontend
yarn install --immutable
yarn typecheck
yarn workspace @bitz/app build

常见升级故障与排错策略

升级故障现象	根本原因剖析	对应标准处置方案
`NU1008: Projects that use central package management should not define the version`	某些子模块 `.csproj` 中残存硬编码的 `<PackageReference Version="1.0.0" />`	移除子工程中的 `Version` 特性，统一移至 `Directory.Packages.props` 中声明
`CS0246: The type or namespace name 'XxxEndpoint' could not be found`	本地 Roslyn 增量生成器缓存未失效，导致新端点未能触发重新生成	执行 `git clean -xdf` 清理所有 `obj/` 目录并使用 `--no-incremental` 重构
`SqlException: Invalid object name 'SysPlatformConfig'`	升级引入了新数据表，但未执行架构初始化同步	运行 `dotnet run --project src/Hosts/BitzOrcas.Api -- --init-schema` 完成建表
`Bundle budget exceeded in @bitz/app`	前端依赖升级导致特定 chunk 体积超出了限制	检查 `vite.config.ts` 中的手动分包策略（`manualChunks`），优化打包配置

总结

遵循 BitzOrcas.Modern 标准升级流程，将底层基础设施迭代的风险降至最低：

全依赖强管控：CPM 集中管理彻底杜绝团队各模块之间的版本分裂；
编译器绝对无状态：无增量清理流程确保代码生成代码与领域模型严格同步；
双轨实测闭环：架构守卫、真实数据库容器测试与前端打包预算构建了全天候防爆护城河。