项目结构

解决方案文件

SeatFlow 使用新版 XML 格式的解决方案文件 SeatFlow.slnx（.slnx 格式，而非传统 .sln）。所有 9 个项目均在此解决方案中管理。

SeatFlow.slnx
├── SeatFlow.Core/                  → 领域核心
├── SeatFlow.Contracts/             → 跨层插件契约
├── SeatFlow.Application/           → 应用编排层
├── SeatFlow.Infrastructure/        → 基础设施实现
├── SeatFlow.Plugins.Sdk/           → 插件 SDK
├── SeatFlow.Presentation.Avalonia/ → 桌面 UI
├── SeatFlow.Core.Tests/            → 核心测试
├── SeatFlow.Application.Tests/     → 应用层测试
└── SeatFlow.Infrastructure.Tests/  → 基础设施测试

项目列表与用途

项目	类型	用途
`SeatFlow.Core`	类库	领域实体、策略接口和 7 条内置策略、领域服务、工作区、数据提供者接口、能力系统、工具类
`SeatFlow.Contracts`	类库	`IPluginSeatingStrategy` — 插件与主程序间的跨层契约
`SeatFlow.Application`	类库	外观接口/实现、策略管道执行器、命令模式、插件管理器、脚本适配器、DI 扩展方法
`SeatFlow.Infrastructure`	类库	CSV/XLSX/JSON 数据提供者、导出器、布局构建器、JSON 仓库、文件迁移系统、序列化、SeatSets 服务
`SeatFlow.Plugins.Sdk`	类库	轻量级 SDK，供外部插件项目引用。包含 `IPluginSeatingStrategy`、`IPluginWorkspace` 和插件清单模型
`SeatFlow.Presentation.Avalonia`	桌面应用	Avalonia 12 桌面应用。输出 EXE 名为 `SeatFlow.exe`
`SeatFlow.Core.Tests`	测试 (xUnit v3)	Core 层单元测试
`SeatFlow.Application.Tests`	测试 (xUnit v3)	Application 层单元测试
`SeatFlow.Infrastructure.Tests`	测试 (xUnit v3)	Infrastructure 层单元测试

项目依赖图

Presentation.Avalonia ──────┐
       │                    │
       ▼                    │
   Application              │
       │                    │
    ┌──┼──────────┐         │
    ▼  ▼          ▼         │
  Core Contracts Infrastructure
                              │
                              ▼
                         Plugins.Sdk
                         (仅外部引用)

严格的分层依赖：

Presentation.Avalonia → Application
Application → Core、Contracts、Infrastructure
Plugins.Sdk 不在主项目的依赖链中，仅由外部插件项目引用
无循环依赖，下层不引用上层

关键目录和文件

每个项目内的典型目录结构

SeatFlow.Core/
├── Models/              ← 领域实体 (Student, Seat, LayoutDefinition 等)
├── Strategies/
│   ├── Interfaces/      ← ISeatingStrategy, IDependentSeatingStrategy
│   ├── Manifests/       ← 策略 manifest JSON 文件（声明式配置）
│   ├── FixedSeatStrategy.cs
│   ├── FrontRowRotationStrategy.cs
│   ├── RandomFillStrategy.cs
│   ├── DefragStrategy.cs
│   ├── DeskMateStrategy.cs
│   ├── GenderRestrictedSeatStrategy.cs
│   ├── NoRepeatDeskMateStrategy.cs
│   └── Capability.cs    ← 能力常量和接口
├── DomainServices/      ← 领域服务
│   ├── ObstacleProcessor.cs
│   ├── SeatGeometryHelper.cs
│   ├── StrategyManifestProvider.cs
│   └── SeatAdjacencyHelper.cs
├── Workspace/           ← SeatingWorkspace
├── Utilities/           ← CircularHistory<T>, AttributeBag
└── Abstractions/        ← 数据提供者接口

SeatFlow.Application/
├── IApplicationFacade.cs  ← 外观接口
├── ApplicationFacade.cs   ← 外观实现
├── StrategyExecutionPipeline.cs  ← 管道执行器
├── Commands/             ← IUndoableCommand, CommandHistory
├── PluginManagement/     ← PluginManager, PluginLoadContext
├── Scripting/            ← 脚本适配器
└── ServiceCollectionExtensions.cs  ← DI 注册

SeatFlow.Infrastructure/
├── Providers/            ← Csv/Xlsx/Json/Composite/InMemory 数据提供者
├── Writers/              ← Json/Csv/Xlsx 数据写入器
├── Exporters/            ← Excel/Csv/Pdf/Image 导出器
├── LayoutBuilders/       ← Grid/Polar/Freeform 布局构建器
├── Repositories/         ← JsonVenue/JsonAppSettings/StrategyConfig/等
├── Migration/            ← FileMigrationService, IFileMigrator
│   ├── file_versions.json  ← 各文件类型当前版本号
│   ├── Migrators/         ← 版本迁移器实现
│   └── Seatsets/          ← 数据包打包/解包
└── Serialization/         ← SeatJsonConverter 等

SeatFlow.Presentation.Avalonia/
├── App.axaml / App.axaml.cs  ← 应用入口和启动序列
├── Program.cs             ← DI 配置和主入口
├── ViewModels/            ← 10 个页面 ViewModel
├── Views/                 ← 对应 10 个页面的 View
├── Services/              ← INavigationService, IDialogService, IFileService, WatchdogService
├── Lang/                  ← .resx 国际化资源文件
├── Behaviors/             ← CanvasZoomPan, ZoomOnScroll, ChineseInputNormalizer
├── Converters/            ← BoolConverters, ValueConverters
├── Controls/              ← 自定义控件
└── Data/                  ← 嵌入资源 (about.json, onboarding_config.json, page_navigation.json)

NuGet 包管理

不使用 Directory.Build.props 或 Directory.Packages.props。包版本直接在每个 .csproj 中管理。这确保了每个项目的依赖版本显式可见。

主要 NuGet 包

包名	用于
`Avalonia` / `Avalonia.Desktop`	跨平台 UI 框架
`CommunityToolkit.Mvvm`	MVVM 源码生成器
`Serilog` / `Serilog.Sinks.File`	结构化日志
`Microsoft.Extensions.DependencyInjection`	DI 容器
`Microsoft.Extensions.Logging.ILogger<T>`	日志抽象
`EPPlus`	XLSX 文件读写
`QuestPDF`	PDF 导出
`xunit.v3` / `FluentAssertions` / `NSubstitute`	测试栈

csproj 关键设置

Avalonia 项目设置 (`SeatFlow.Presentation.Avalonia.csproj`)

<!-- 编译绑定默认启用 -->
<AvaloniaUseCompiledBindingsByDefault>true</AvaloniaUseCompiledBindingsByDefault>

<!-- 输出 EXE 名称，而非项目名称 -->
<AssemblyName>SeatFlow</AssemblyName>

<!-- 抑制 DI 构造函数注入警告 -->
<NoWarn>AVLN3001</NoWarn>

<!-- Designer.cs 不存在时跳过编译（首次克隆时） -->
<Compile Remove="Lang\Resources.Designer.cs"
         Condition="!Exists('Lang\Resources.Designer.cs')" />

<!-- Windows DPI 感知 -->
<ApplicationManifest>app.manifest</ApplicationManifest>

<!-- 确定性构建 -->
<Deterministic>true</Deterministic>
<PathMap>$([System.IO.Path]::GetFullPath('$(MSBuildProjectDirectory)'))=./</PathMap>

Git 提交哈希注入

MSBuild 目标 GenerateGitCommit 在每次构建前运行 git rev-parse --short HEAD，生成 GitCommit.g.cs（位于 $(IntermediateOutputPath)Generated\），提供 GitCommit.Hash 常量。git 不可用时回退到 "unknown-commit-id"。该文件不提交到版本控制。

dotnet 工具

仓库根目录的 dotnet-tools.json 中安装了 avaloniaui.developertools (avdt)，仅在桌面环境下可用，在无头环境中跳过。