搭建 SeatFlow 开发环境的完整指南，包括前置要求、构建、测试和运行

本页目录
全部文档

开发环境搭建

前置要求

工具 最低版本 说明
.NET SDK 10.0 从 dotnet.microsoft.com 下载
Git — 版本控制
IDE — 推荐 Rider、VS Code + C# 扩展、Visual Studio 2022+

支持的操作系统：

  • Windows 10+
  • macOS 12+（安装包暂未提供，需从源码构建）
  • Linux 任意发行版

克隆并构建

# 克隆仓库
git clone <repo-url>
cd SeatFlow

# 还原依赖
dotnet restore

# 构建全部 10 个项目（6 个源码 + 4 个测试）
dotnet build

dotnet build 使用 SeatFlow.slnx 解决方案文件（新版 XML 格式），自动构建所有项目。

dotnet r 快捷任务

仓库根目录 global.json 以 npm scripts 风格定义了快捷任务，首次使用先还原本地工具：

dotnet tool restore

dotnet r build      # 等价 dotnet build
dotnet r test       # 等价 dotnet test
dotnet r run        # 启动桌面应用
dotnet r web        # dotnet publish src/SeatFlow.Browser -c Release
dotnet r desktop    # dotnet publish src/SeatFlow.Desktop -c Release
dotnet r clean      # 等价 dotnet clean
dotnet r format     # 等价 dotnet format
dotnet r ci         # build + test（仅本地；CI 请直接调用 dotnet test/build）
dotnet r build -- -c Release   # `--` 之后的参数透传给命令

仅限本地开发：dotnet r 依赖第三方 run-script 工具，需要 restore 与 roll-forward，禁止在 CI/CD 流水线中使用。

运行测试

# 运行所有测试（448 个用例）
dotnet test

# 运行单个测试
dotnet test --filter "FullyQualifiedName~TestName"

测试技术栈

框架/库 用途
xUnit v3 测试框架 (Microsoft.Testing.Platform)
FluentAssertions 可读性断言
NSubstitute 对象模拟
Avalonia.Headless.XUnit 共享 UI 无头测试（Headless 应用构建、控件交互）
Avalonia.Skia Headless 下的真实绘制（视觉基线/像素回归）

测试项目（4 个）：

  • tests/SeatFlow.Core.Tests — Core 层单元测试（xunit.v3 4.0.1）
  • tests/SeatFlow.Application.Tests — Application 层单元测试（xunit.v3 4.0.1）
  • tests/SeatFlow.Infrastructure.Tests — Infrastructure 层单元测试（xunit.v3 4.0.1）
  • tests/SeatFlow.Presentation.Tests — 共享 UI 无头测试（Avalonia.Headless.XUnit 12.1.3 + Avalonia.Skia 真实绘制 + 视觉基线）

版本锁定：SeatFlow.Presentation.Tests 锁定 xunit.v3 3.2.2（Headless 包的编译基线，用 4.x 会 MissingMethodException），其余测试项目为 4.0.1；该项目的 SkiaSharp.NativeAssets.Linux 锁定 4.153.1，否则 Linux 上真实绘制会崩溃。这类版本锁不要”顺手升级”。

每个测试项目已启用 <ImplicitUsings>enable</ImplicitUsings>（自动引入 System、System.Collections.Generic、System.Linq、System.Threading.Tasks）。项目特定的 global usings 在 Usings.cs（Application.Tests 中为 Using.cs）中定义。

脚本自身的测试单独运行：

cd scripts && python3 -m pytest tests/ -v

运行桌面应用

dotnet run --project src/SeatFlow.Desktop

应用启动后依次执行：

  1. StartupGuard.CheckEnvironment() 验证 .NET 10 运行时和操作系统
  2. App.Initialize() 先应用语言设置，再 AvaloniaXamlLoader.Load(this) 加载 XAML
  3. OnFrameworkInitializationCompleted 解析 MainShellViewModel / MainWindow 并设置 TopLevel（文件/对话框服务）
  4. 启动 Watchdog（UI 线程每 3 秒 Ping()）、附加 ChineseInputNormalizer、KeyboardShortcutHandler、FileDropHandler
  5. SafeInitializeAsync()：自动导入 .seatsets → 首次启动检测 → 恢复主题/语言/窗口设置 → 遥测同意 → 启动引导 → 自动更新检查

无头环境：Avalonia DevTools（avdt）仅在桌面 GUI 环境可用；无 DISPLAY/WAYLAND_DISPLAY 时跳过即可，dotnet build / dotnet test 不受影响。

运行浏览器（WASM）版本

浏览器壳需要一次性安装 WASM 工作负载，然后发布为静态站点：

# 一次性：安装 wasm-tools 工作负载（每台构建机）
dotnet workload install wasm-tools

# 发布（输出到 src/SeatFlow.Browser/bin/Release/net10.0-browser/publish/wwwroot/）
dotnet publish src/SeatFlow.Browser -c Release

# 或使用快捷任务
dotnet r web

必须安装 wasm-tools：缺少该 workload 时 dotnet publish 可能”构建成功”但原生库不完整，部署后白屏（SkiaSharp.SKImageInfo 初始化异常）。发布产物为纯静态文件，数据存储于浏览器 IndexedDB。

IDE 推荐

VS Code

安装以下扩展：

  • C# Dev Kit (Microsoft)
  • .NET MAUI / Avalonia 扩展（可选）

JetBrains Rider

原生支持 .NET 10 和 Avalonia UI。推荐使用。

Visual Studio 2022+

需要安装 .NET 10 SDK 和 “使用 .NET 的桌面开发” 工作负载。Avalonia 扩展提供 AXAML 设计器和预览功能。

项目配置文件速查

文件 用途
SeatFlow.slnx 解决方案文件（新版 XML 格式，10 个项目）
global.json dotnet r 任务定义（build/test/run/web/desktop/clean/format/ci）
dotnet-tools.json dotnet 本地工具清单（avdt / vpk / run-script）
AGENTS.md AI 编码代理唯一主指南（架构、约定、测试、脚本）
scripts/build/publish.sh / publish.ps1 多平台发布脚本
scripts/build/clean.sh / clean.ps1 递归清理 bin/obj
scripts/i18n.py i18n 资源管理
scripts/version.py 跨文件版本管理
scripts/ui-inspect/ 无头 WASM UI 查看/交互/性能采样工具链
docs/UI_REFACTOR.md 2.1.0 UI 重构（M0–M6）记录与性能验收

常见问题

构建失败：找不到 Resources.Designer.cs

首次克隆仓库后，Resources.Designer.cs 可能不存在。运行以下命令生成：

python3 scripts/i18n.py sync

csproj 中已包含条件编译设置，在 Designer.cs 不存在时会跳过编译，但不影响其他文件的构建。建议尽快运行 i18n.py sync 生成该文件。

无头环境中无法使用 avdt

avaloniaui.developertools 仅在桌面环境中可用。在 CI 或无头服务器上构建/测试时，确保不调用 avdt 相关功能。

Shared UI 测试崩溃：SkiaSharp.SKImageInfo 初始化失败

SeatFlow.Presentation.Tests 使用 Avalonia.Skia 真实绘制，Linux 上需要 SkiaSharp.NativeAssets.Linux。该项目已锁定与桌面壳一致的 4.153.1，若手动升级了此包或删除了引用会导致崩溃。

WASM 构建后白屏

确认已安装 dotnet workload install wasm-tools。缺少工作负载时 dotnet publish 可能成功但原生库不完整。

.NET 10 SDK 未找到

确保安装了 .NET 10 SDK。验证方式：

dotnet --list-sdks

如果输出中没有 10.x 版本，请从 dotnet.microsoft.com 下载。