本文档是 BitzOrcas.Modern 团队的代码协同规范。所有成员提交代码时都需要遵守——保持提交历史干净、Review 流程顺畅、架构约束不被突破。

1. 分支命名规范

分支名称采用 <type>/<description> 格式，全部小写，单词间使用连字符（-）分隔。

前缀	用途	示例
`feature/`	新功能开发	`feature/workflow-canary-deploy`
`bugfix/`	Bug 修复	`bugfix/tenant-filter-null-ref`
`hotfix/`	生产环境紧急修复	`hotfix/sql-injection-auth`
`refactor/`	代码重构（不改变外部行为）	`refactor/audit-interceptor-async`
`docs/`	文档更新	`docs/cli-workflow-migrator`
`test/`	测试补充与修复	`test/architecture-module-boundary`
`chore/`	构建、CI、依赖更新	`chore/update-sqlsugar-5.1.0`
`release/`	发布准备分支	`release/v1.2.0`

命名规则

全部小写：feature/add-user-auth（非 Feature/Add-User-Auth）
连字符分隔：bugfix/fix-null-exception（非 bugfix/fix_null_exception）
简洁描述：控制在 3–5 个单词以内，清晰表达变更意图
避免个人前缀：不要使用 john/feature-xxx，分支属于团队

分支策略

main          ──●────●────●────●────●────  (生产就绪，受保护)
                 \       \       \
feature/xxx      ●──●──●  \       \        (功能分支，从 main 切出)
                           \       \
release/v1.2.0              ●──●───●       (发布分支，冻结后仅修 Bug)
                                     \
hotfix/urgent                         ●──● (紧急修复，直接从 main 切出)

main：受保护分支，禁止直接推送。所有变更必须通过 PR 合并。
功能分支：从 main 切出，开发完成后通过 PR 合回 main。
发布分支：从 main 切出，用于版本冻结与预发布测试。Bug 修复在此分支进行，然后反向合并回 main。
紧急修复分支：从 main 切出，修复完成后同时合并到 main 和当前发布分支。

2. Commit Message 规范

团队采用 Conventional Commits 规范，格式如下：

<type>(<scope>): <subject>

[body]

[footer]

2.1 Type（提交类型）

Type	说明	示例
`feat`	新功能	`feat(workflow): add canary deployment binding`
`fix`	Bug 修复	`fix(audit): correct shard routing for platform tenant`
`docs`	文档变更	`docs(cli): add Workflow.Migrator usage guide`
`refactor`	代码重构	`refactor(identity): extract token service to port`
`test`	测试相关	`test(architecture): add module boundary assertion`
`chore`	构建/工具/依赖	`chore(deps): bump SqlSugarCore to 5.1.0`
`style`	格式调整（不影响逻辑）	`style: apply .editorconfig whitespace rules`
`perf`	性能优化	`perf(workflow): batch-load instance states`
`ci`	CI/CD 变更	`ci: add trim-publish hard gate`

2.2 Scope（影响范围）

Scope 为可选项，用于标注变更影响的模块或构建块。推荐使用以下范围：

Scope	对应模块
`workflow`	工作流引擎
`identity`	身份认证与授权
`audit`	审计模块
`files`	文件管理
`notifications`	通知模块
`webhooks`	Webhook 模块
`billing`	计费模块
`catalog`	商品目录
`tickets`	工单模块
`chat`	即时通讯
`cli`	CLI 工具
`building-blocks`	构建块基础设施
`deps`	依赖项更新

2.3 Subject（提交摘要）

使用中文或英文，团队当前约定：源码相关使用中文，基础设施/CI 使用英文
不超过 72 个字符
使用祈使语气（“添加”而非”添加了”）
首字母小写（中文可忽略），结尾不加句号

2.4 Body（提交正文，可选）

用于解释 为什么 要做这个变更，以及如何做的。每行不超过 72 个字符。

Breaking Changes：以 BREAKING CHANGE: 开头，描述不兼容变更
关联 Issue：Closes #123 或 Refs #456

2.6 完整示例

feat(workflow): 新增灰度发布部署绑定

通过 DeploymentBinding 实现在 (Tenant, Office) 维度绑定流程版本，
新建实例自动使用最新部署版本，存量实例不受影响。

- 新增 IDeploymentService.PublishAsync 方法
- 新增 WorkflowDeployment 持久化实体
- 新增 CanaryDeploymentTests 集成测试

Closes #234

fix(audit): 修复平台租户分片路由错误

AuditShardRouter 在 TenantId == "PLATFORM" 时未正确处理分片键，
导致审计记录写入默认分片。

根本原因：ShardKeyResolver 对平台租户返回 null，未回退到常量分片。
修复方案：新增 PlatformShardFallback 常量，当租户为 PLATFORM 时使用。

BREAKING CHANGE: IShardKeyResolver.Resolve 方法签名新增 CancellationToken 参数

3. 代码 Review 标准

3.1 Review 流程

开发者提交 PR
      │
      ▼
  ┌─────────────┐     ┌──────────────┐
  │ CI 自动检查  │────▶│ 修复后重新推送 │
  └──────┬──────┘ 失败 └──────────────┘
         │ 通过
         ▼
  ┌──────────────┐
  │ 分配 Reviewer │
  └──────┬───────┘
         ▼
  ┌──────────────┐     ┌──────────────┐
  │ Reviewer 审查 │◀────│ 开发者修改代码 │
  └──────┬───────┘ 需改 └──────────────┘
         │ 通过
         ▼
   是否需要第二 Reviewer?
    │              │
   是 (核心模块)   否
    │              │
    ▼              │
  ┌──────────────┐ │
  │ 第二 Reviewer │ │
  └──────┬───────┘ │
         │ 通过     │
         ▼         ▼
     ┌───────────────┐
     │  合并到 main   │
     └───────────────┘

3.2 Review 清单

每位 Reviewer 在审查 PR 时必须逐项检查以下内容：

架构一致性

模块边界是否遵守？跨模块调用是否仅通过 *.Contracts 进行？
依赖方向是否正确？Endpoints → Application → Domain，不得反向引用
是否引入了新的外部依赖？新依赖是否已在 Directory.Packages.props 中统一管理？

代码质量

命名是否符合团队规范？（PascalCase 公共成员，_camelCase 私有字段）
是否有足够的 XML 文档注释（中文）？
是否有明显的代码异味（过长方法、过深嵌套、重复代码）？
错误处理是否使用 Result / Result<T> 模式，而非抛出异常？
是否避免了反射使用（AOT 兼容项目）？

测试覆盖

新增功能是否有对应的单元测试？
涉及持久化的变更是否有集成测试？
模块边界变更是否有架构测试验证？
CI 是否全部通过（构建 + 测试 + 裁剪发布）？

安全性

是否包含硬编码密钥、连接串或 API Key？
用户输入是否经过验证？
租户隔离是否正确实现？
敏感操作是否有审计记录？

3.3 Review 礼仪

对事不对人：评论针对代码而非作者
解释原因：不只是说”改成 X”，要解释”为什么 X 更好”
区分严重程度：使用标签区分建议和强制修改
- [must]: 必须修改（阻塞合并）
- [should]: 建议修改（非阻塞）
- [nit]: 锦上添花（完全可选）

3.4 审批规则

变更类型	最少审批人数	额外要求
文档 / 注释	1	无
Bug 修复	1	CI 全部通过
新功能（非核心模块）	1	单元测试 + 集成测试
新功能（核心模块：Workflow、Auth、Audit）	2	架构测试 + 架构负责人之一审批
API / 契约变更	2	架构负责人之一审批
构建块变更	2	跨模块影响评估
依赖版本升级	1	CI 全部通过 + 兼容性检查

4. PR 完整操作指南

4.1 准备工作：Fork 与克隆

注意：对于团队内部成员，通常直接克隆主仓库并创建分支即可。以下 Fork 流程适用于外部贡献者或跨团队协作场景。

# 1. 在 Git 平台上 Fork 主仓库（通过 Web UI 操作）

# 2. 克隆你的 Fork 到本地
git clone https://github.com/YOUR_USERNAME/BitzOrcas.Modern.git
cd BitzOrcas.Modern

# 3. 添加主仓库为 upstream 远程源
git remote add upstream https://github.com/shbitz/BitzOrcas.Modern.git

# 4. 验证远程配置
git remote -v
# origin    https://github.com/YOUR_USERNAME/BitzOrcas.Modern.git (fetch)
# origin    https://github.com/YOUR_USERNAME/BitzOrcas.Modern.git (push)
# upstream  https://github.com/shbitz/BitzOrcas.Modern.git (fetch)
# upstream  https://github.com/shbitz/BitzOrcas.Modern.git (push)

4.2 创建功能分支

# 1. 确保在 main 分支且与上游同步
git checkout main
git fetch upstream
git rebase upstream/main

# 2. 创建功能分支（使用规范的命名格式）
git checkout -b feature/workflow-canary-deploy

# 3. （可选）推送空分支到远程，确认分支名称可用
git push -u origin feature/workflow-canary-deploy

4.3 日常开发与提交

# 1. 进行代码修改并保存

# 2. 查看变更状态
git status

# 3. 暂存变更（建议使用交互式暂存，避免一次性提交所有文件）
git add -p

# 或者暂存特定文件
git add src/Platform/BitzOrcas.Workflow/Engine/DeploymentService.cs

# 4. 提交（遵循 Conventional Commits 规范）
git commit -m "feat(workflow): 新增灰度发布部署绑定

通过 DeploymentBinding 实现在 (Tenant, Office) 维度绑定流程版本，
新建实例自动使用最新部署版本，存量实例不受影响。

- 新增 DeploymentBinding 持久化实体
- 新增 PublishDeploymentAsync API
- 新增 CanaryDeploymentTests 集成测试"

# 5. 定期与上游同步（避免合并冲突累积）
git fetch upstream
git rebase upstream/main

# 解决冲突后继续
git rebase --continue
# 或放弃本次 rebase
git rebase --abort

# 6. 推送分支（rebase 后需要强制推送）
git push -u origin feature/workflow-canary-deploy
# 如果已经推送过且经过了 rebase，需要强制推送：
git push --force-with-lease origin feature/workflow-canary-deploy

4.4 发起 Pull Request

# 1. 推送最终版本到远程
git push origin feature/workflow-canary-deploy

# 2. 通过 Git 平台 Web UI 创建 Pull Request
#    - Base 分支：upstream/main（或 origin/main）
#    - Compare 分支：feature/workflow-canary-deploy

PR 描述模板

在 Git 平台上创建 PR 时，请使用以下模板填写描述：

## 变更概述
<!-- 简要描述此 PR 做了什么，以及为什么这么做 -->

## 变更类型
- [ ] 新功能 (feat)
- [ ] Bug 修复 (fix)
- [ ] 重构 (refactor)
- [ ] 文档 (docs)
- [ ] 测试 (test)
- [ ] 构建/依赖 (chore)
- [ ] 性能优化 (perf)

## 影响范围
<!-- 标记受影响的模块或构建块 -->
- [ ] Workflow Engine
- [ ] Authentication / Authorization
- [ ] Audit
- [ ] Files / Notifications / Webhooks / Chat / Tickets / Billing / Catalog
- [ ] Building Blocks
- [ ] CLI Tools
- [ ] CI / Build System
- [ ] Documentation

## 测试计划
<!-- 描述你如何测试了这些变更 -->
- [ ] 单元测试已添加/更新
- [ ] 集成测试已添加/更新
- [ ] 架构测试通过
- [ ] 手动验证步骤（如有）：

## 架构影响评估
<!-- 此 PR 是否涉及以下内容？ -->
- [ ] 模块公共契约变更（*.Contracts 程序集）
- [ ] 新外部依赖引入
- [ ] 数据库 Schema 变更
- [ ] Breaking Change（不兼容变更）
- [ ] 无架构影响

## 关联 Issue
<!-- 使用 Closes / Refs 关键字关联 Issue -->
Closes #

## 截图 / 日志（可选）
<!-- 如有 UI 变更或关键日志，请附上 -->

4.5 Code Review 阶段

# 收到 Review 意见后，在本地完成代码修改并验证

# 1. 修改代码

# 2. 追加提交（或使用 fixup commit）
git add .
git commit -m "fixup: 根据 Review 意见调整 DeploymentService 异常处理"

# 3. 推送修改
git push origin feature/workflow-canary-deploy

# 4. 在 PR 页面回复 Review 评论，标记已解决的问题

# 5. 所有 Review 通过后，使用 interactive rebase 整理提交历史
git rebase -i upstream/main

# 在编辑器中：
#   pick <commit1> feat(workflow): 新增灰度发布部署绑定
#   fixup <commit2> fixup: 调整异常处理
#   fixup <commit3> fixup: 补充文档注释

# 6. 整理后强制推送
git push --force-with-lease origin feature/workflow-canary-deploy

4.6 合并与清理

合并策略由团队 CI/CD 配置决定，通常采用 Squash Merge（将 PR 中所有提交压缩为一个）或 Rebase Merge（保持线性历史）。

# PR 合并后，清理本地环境

# 1. 切换回 main 并拉取最新代码
git checkout main
git pull upstream main

# 2. 删除本地功能分支
git branch -d feature/workflow-canary-deploy

# 3. 删除远程功能分支（如果 PR 合并后未自动删除）
git push origin --delete feature/workflow-canary-deploy

# 4. 清理本地已删除远程分支的引用
git remote prune origin

5. 常见问题

5.1 合并冲突如何处理？

# 1. 从 main 同步最新代码
git fetch upstream
git rebase upstream/main

# 2. 如果出现冲突，Git 会暂停并标记冲突文件
#    编辑冲突文件，解决冲突标记（<<<<<<<  / ======= / >>>>>>>）

# 3. 标记为已解决
git add <resolved-file>

# 4. 继续 rebase
git rebase --continue

# 5. 如果冲突太复杂，放弃本次 rebase
git rebase --abort

5.2 不小心提交了敏感信息怎么办？

# 1. 立即修改敏感信息（如修改密码、撤销密钥）

# 2. 如果未推送到远程，使用 interactive rebase 移除敏感提交
git rebase -i HEAD~3

# 3. 如果已推送，立即联系仓库管理员清理远程历史
#    注意：已推送的敏感信息视为已泄露，必须立即轮换密钥

5.3 CI 检查失败怎么处理？

查看 CI 日志，确定失败原因
如果是代码问题（编译错误、测试失败），在本地修复后重新推送
如果是 CI 基础设施问题（超时、网络错误），可以请求重新运行 CI
在 CI 全部通过之前，PR 不应被合并

6. 项目结构速查

src/
├── Framework/          → 框架底座、Source Generator 与基础设施适配器
│   ├── BitzOrcas.Domain/              → 领域原语（Entity, AggregateRoot, Result）
│   ├── BitzOrcas.Application/         → CQRS 抽象（Command, Query, Pipeline）
│   ├── BitzOrcas.DI.* / Endpoint.*    → 编译期 DI 与端点生成
│   ├── BitzOrcas.Infrastructure.*/    → 持久化 / 缓存 / 消息 / 存储适配器
│   └── BitzOrcas.Workflow/            → 自研工作流引擎（零 ORM 依赖）
├── Platform/           → 按能力拆分的平台模块（当前真实目录）
├── Modules/Sandbox/    → Golden Use Case 与业务模块布局示例
├── Hosts/              → Gateway、Api、JobHost、AppHost、ServiceDefaults
└── Tooling/            → CLI 工具（4 个工具）
    ├── BitzOrcas.CodeGeneration.Cli/  → 代码生成器 CLI
    ├── BitzOrcas.Modern.Templates/    → dotnet new 解决方案模板
    ├── BitzOrcas.SeedData.Exporter/   → 种子数据导出工具
    └── BitzOrcas.Workflow.Migrator/   → 流程定义迁移工具
tests/                  → 单元、应用、架构、集成、parity、Consumer 与商业门禁

本文档基于团队内部约定制定，如有改进建议请提交 PR 到本文档。

代码提交规范