如何参与 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（下载）
  • WASM 工作负载（dotnet workload install wasm-tools，构建浏览器版所需）
  • Git
  • 推荐 IDE：Rider、Visual Studio 2022+、VS Code + C# 扩展

克隆和构建

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

构建浏览器壳前需安装 WASM 工作负载：

dotnet workload install wasm-tools
dotnet build src/SeatFlow.Browser

运行测试

# 运行所有测试
dotnet test

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

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

分支策略

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

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

编码规范

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

  • C# 命名遵循 .NET 惯例
  • ViewModel 继承 ViewModelBase；MVVM 双范式共存（CommunityToolkit.Mvvm 8.4.2 存量 + ReactiveUI.Avalonia 12.1.5 新代码优先，决策见主仓库 docs/adr/ADR-014-reactiveui-and-canvas-architecture.md）
  • Axaml 根元素必须 x:DataType，全量编译绑定（ReflectionBinding 实际使用为 0）
  • 颜色/间距/圆角/字阶只用 Resources/Tokens/ 令牌，不硬编码 hex
  • 对话框与日志构造函数注入，禁止静态可变状态；构造器禁止 fire-and-forget 加载（实现 IPageLifecycle）
  • 日志使用 ILogger<T> 构造函数注入
  • 异步方法以 Async 结尾

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

Pull Request 流程

提交前检查清单

  • 代码通过 dotnet build 无错误
  • 所有测试通过 dotnet test（当前全量 448 用例）
  • UI 改动后本地跑过 tests/SeatFlow.Presentation.Tests（该项目的 Headless 用例目前不在 CI 中）
  • 新功能有对应的测试
  • 公共 API 变更有 XML 文档注释
  • 相关文档已更新（见下方「文档联动规则」）

PR 描述模板

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

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

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

## 关联 Issue
Closes #xxx

代码审查

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

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

文档联动规则

重要：修改代码时需同步更新相关文档。文档地图与联动规则详见 docs/INDEX.md。

必须更新的文档

代码变更 需同步更新的文档
新增/修改策略 AGENTS.md 策略表 + ADR（如有架构变更）
新增/修改 ViewModel AGENTS.md 对应章节
新增 i18n 资源键 用 python3 scripts/i18n.py add（自动同步三文件 + Designer.cs）
文件格式版本号变更 file_versions.json + Model 类 + 迁移步骤（可选 scripts/version.py bump-file）
公共 API 变更 XML 文档注释
新增页面 AGENTS.md「新增页面」约定 + docs/INDEX.md
架构/UI 重大变更 docs/adr/ 新增 ADR，并在 docs/UI_REFACTOR.md / docs/INDEX.md 登记
修改 CLI 命令 scripts/ToolsCollection.md

AI 指南唯一来源

根 AGENTS.md 是 AI 编码指南的唯一来源（根 CLAUDE.md 仅为指向它的指针），修改指南只改 AGENTS.md；不要再维护 docs/CLAUDE.md 副本。

测试指南

测试框架

  • xUnit v3（tests/ 下 4 个项目，共 448 用例）
  • FluentAssertions（断言）
  • NSubstitute（模拟）
  • Avalonia.Headless.XUnit + Avalonia.Skia（Presentation.Tests 的 Headless UI 与视觉基线）

测试项目

项目 用例数 测试范围
tests/SeatFlow.Core.Tests 195 领域实体、策略、领域服务
tests/SeatFlow.Application.Tests 61 应用服务、管道、命令
tests/SeatFlow.Infrastructure.Tests 125 数据访问、迁移、导出
tests/SeatFlow.Presentation.Tests 67 Headless UI、页面生命周期、视觉基线

运行测试

dotnet test                                                  # 全部 4 个项目（448 用例）
dotnet test --filter "FullyQualifiedName~Strategy"           # 策略相关
dotnet test tests/SeatFlow.Core.Tests                        # 单个项目

cd scripts && python3 -m pytest tests/ -v                    # 脚本测试

详见 测试指南。

添加新功能

添加新页面

当前为 7 页 IA（排座工作台为默认入口；原 Home、FreeformManagement 页已移除）：

  1. 在 Services/INavigationService.cs 的 PageKey 枚举中添加新值
  2. 创建 ViewModels/NewPageViewModel.cs（继承 ViewModelBase，构造注入 IDialogService/logger；如需页面加载则实现 IPageLifecycle）
  3. 创建 Views/NewPageView.axaml + .axaml.cs（根元素设 x:DataType，ViewLocator 按命名约定解析）
  4. 在桌面与浏览器启动壳的 Program.cs 中注册 ViewModel：services.AddSingleton<NewPageViewModel>()
  5. 在 Views/MainView.axaml 侧边栏添加导航按钮（桌面 MainWindow 复用同一外壳）
  6. 在 Data/page_navigation.json 中添加页面启/禁用状态（禁用时按 Opacity + ToolTip.Tip 约定处理）
  7. 用脚本添加资源键：python3 scripts/i18n.py add Nav_NewPage --zh "..." --en "..."
  8. 若页面需要引导演示数据，实现 IGuideSeedTarget 并在 AddGuideSeedTargets() 中注册

添加新策略

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

新策略以内置方式加入代码库。如需提议尚未支持的新策略，可通过 .github/ISSUE_TEMPLATE/new-strategy.md 模板提交建议。

详见 策略管道深度解析。

添加文件版本迁移

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

详见 版本与迁移系统。

国际化

添加新语言时：

  1. 创建 Lang/Resources.xx-XX.resx 并翻译全部键
  2. 运行 python3 scripts/i18n.py check 校验一致性
  3. 在 AppSettings.Language 可选值中加入对应语言代码（设置页选项）
  4. 浏览器端语言切换依赖卫星资源预加载（UseSystemResourceKeys=false + main.js 的 loadAllSatelliteResources: true），详见 国际化系统

新增资源键时使用 scripts/i18n.py（自动同步 .resx 三文件与 Designer.cs）：

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

详见 国际化系统。

发布流程

  1. 确保所有测试通过（dotnet test 448 用例 + 脚本测试），CHANGELOG.md 与根目录 RELEASE.md 已更新
  2. 运行 python3 scripts/version.py bump-app patch --force 更新版本号（唯一来源 version.json，勿手改 commitId/buildDate）
  3. 将 version.json 变更推送/合并到 main（只有该文件变更会触发发布）
  4. CI 自动执行：release.yml 多平台 + vpk 打包（稳定版从 OSS 同步打包历史并缓存，保证 delta 链完整）→ publish.yml 创建 GitHub Release / OSS 分发 → publish-web.yml 发布在线版（仅正式版）
  5. 发布说明来自 RELEASE.md（publish.yml 会校验其存在并附加 SHA256 校验表）；手动触发发布（workflow_dispatch）始终按 pre-release 处理且不上传 OSS

本地需要一键编排（构建 + 打包 + OSS/GitHub Release）时可用：

python3 scripts/release/release.py --dry-run
python3 scripts/release/release.py

本地 dotnet r build/test 等任务仅限开发使用，禁止进入 CI/CD。详见 构建与发布 与 CI/CD 工作流。

获取帮助