如何参与 SeatFlow 项目开发 — PR 流程、代码审查、文档联动

本页目录
全部文档

贡献指南

感谢你对 SeatFlow 项目的关注！本文档介绍如何参与项目开发。

行为准则

本项目采用 Contributor Covenant 行为准则。请在所有项目互动中保持尊重和建设性。

如何贡献

报告 Bug

  1. 在 GitHub Issues 搜索是否已有相同问题
  2. 使用 Bug 报告模板创建新 Issue
  3. 包含以下信息：
    • 操作系统和版本
    • SeatFlow 版本（在「关于」页面查看）
    • 复现步骤
    • 预期行为和实际行为
    • 相关截图（如有）

功能建议

  1. 在 Issues 中搜索是否已有类似建议
  2. 使用功能建议模板
  3. 描述使用场景和期望效果

代码贡献

  1. Fork 本仓库
  2. 从 develop 分支创建功能分支
  3. 编写代码和测试
  4. 提交 Pull Request 到 develop 分支

开发环境

前置要求

  • .NET 10 SDK（下载）
  • Git
  • 推荐 IDE：Rider、Visual Studio 2022+、VS Code + C# 扩展

克隆和构建

git clone https://github.com/Helio-RC/Seatflow.git
cd Seatflow
dotnet build

运行测试

# 运行所有测试
dotnet test

# 运行特定测试
dotnet test --filter "FullyQualifiedName~TestName"

详细开发环境搭建请参考 开发环境搭建。

分支策略

分支 用途
main 稳定发布版本
develop 日常开发，PR 目标分支

功能分支命名建议：feature/xxx、fix/xxx、docs/xxx、refactor/xxx。

编码规范

SeatFlow 遵循以下编码规范（详见 编码规范）：

  • C# 命名遵循 .NET 惯例
  • ViewModel 继承 ViewModelBase，使用 CommunityToolkit.Mvvm 源码生成器
  • Axaml 绑定使用 x:DataType 编译绑定
  • 颜色使用 DynamicResource/StaticResource，不硬编码 hex
  • 日志使用 ILogger<T> 构造函数注入
  • 异步方法以 Async 结尾

类型：feat、fix、docs、refactor、test、chore、style、perf。

Pull Request 流程

提交前检查清单

  • [ ] 代码通过 dotnet build 无错误
  • [ ] 所有测试通过 dotnet test
  • [ ] 新功能有对应的测试
  • [ ] 公共 API 变更有 XML 文档注释
  • [ ] 相关文档已更新（见下方「文档联动规则」）

PR 描述模板

## 变更说明
简要描述做了什么

## 变更类型
- [ ] Bug 修复
- [ ] 新功能
- [ ] 重构
- [ ] 文档
- [ ] 其他

## 测试
- [ ] 新增测试覆盖
- [ ] 已有测试全部通过

## 关联 Issue
Closes #xxx

代码审查

所有 PR 需要至少一位维护者审查。审查关注五个维度：

维度 关注点
正确性 逻辑是否正确，边界条件是否处理
可读性 命名是否清晰，结构是否易懂
架构 是否遵循分层架构，依赖方向是否正确
安全性 输入验证、文件路径安全
性能 无明显性能问题

文档联动规则

⚠️ 重要：修改代码时需同步更新相关文档。规则详见 docs/INDEX.md。

必须更新的文档

代码变更 需同步更新的文档
新增/修改策略 CLAUDE.md 策略表 + ADR（如有架构变更）
新增/修改 ViewModel CLAUDE.md 对应章节
新增 i18n 资源键 运行 python3 scripts/i18n.py sync
文件格式版本号变更 file_versions.json + Model 类 + 迁移步骤
公共 API 变更 XML 文档注释 + Plugin SDK README（如影响插件）
新增页面 CLAUDE.md「Adding a New Page」相关说明
修改 CLI 命令 scripts/ToolsCollection.md

根 CLAUDE.md 与 docs/CLAUDE.md

/CLAUDE.md 和 /docs/CLAUDE.md 必须保持同步。修改根 CLAUDE.md 后必须更新 docs/CLAUDE.md。

测试指南

测试框架

  • xUnit v3
  • FluentAssertions（断言）
  • NSubstitute（模拟）

测试项目

项目 测试范围
SeatFlow.Core.Tests 领域实体、策略、领域服务
SeatFlow.Application.Tests 应用服务、管道、命令
SeatFlow.Infrastructure.Tests 数据访问、迁移、导出

运行测试

dotnet test                                              # 全部
dotnet test --filter "FullyQualifiedName~Strategy"       # 策略相关
dotnet test SeatFlow.Core.Tests                          # 单个项目

详见 测试指南。

添加新功能

添加新页面

  1. 在 INavigationService.cs 中添加 PageKey 枚举值
  2. 创建 ViewModels/NewPageViewModel.cs（继承 ViewModelBase）
  3. 创建 Views/NewPageView.axaml + .axaml.cs
  4. 在 Program.cs 中注册 ViewModel：services.AddSingleton<NewPageViewModel>()
  5. 在 MainWindow.axaml 侧边栏添加导航按钮
  6. 在 Data/page_navigation.json 中添加页面启/禁用状态
  7. 如需要，在 Lang/Resources.resx 中添加相关资源键

添加新策略

  1. 实现 ISeatingStrategy（独立）或 IDependentSeatingStrategy（依赖）
  2. 创建 Manifest JSON 文件：SeatFlow.Core/Strategies/Manifests/{StrategyId}.json
  3. 在 ServiceCollectionExtensions 中注册
  4. 添加测试

详见 策略管道深度解析。

添加文件版本迁移

  1. 创建 Migrator 类（实现 IFileMigrator）
  2. 注册到 DI
  3. 更新 file_versions.json
  4. 更新 Model 默认 Version
  5. 添加迁移测试

详见 版本与迁移系统。

国际化

添加新语言时：

  1. 创建 Lang/Resources.xx-XX.resx
  2. 在 App.ApplyLanguageFromSettings() 中添加语言切换逻辑（如有特殊处理）
  3. UI 会自动识别并加载

新增资源键时使用 scripts/i18n.py：

python3 scripts/i18n.py add KeyName --zh "中文" --en "English"
python3 scripts/i18n.py sync

详见 国际化系统。

发布流程

  1. 确保 develop 分支所有测试通过
  2. 运行 python3 scripts/version.py bump-app patch --force 更新版本号
  3. 更新 CHANGELOG.md
  4. 提交版本变更并合并到 main
  5. 运行 scripts/publish.sh 构建发布包
  6. 在 GitHub Releases 发布

详见 构建与发布。

获取帮助