一、问题拆解：分析即算子的编排
回归本质，无论是数据分析还是数据质检，其最小执行单元都可以抽象为一个原子动作：
输入数据 → 执行操作 → 产出结果
这个原子动作我们称之为算子（Operator）。一个"缓冲区分析"是算子，一个"属性完整性检查"也是算子。它们的差异不在于执行机制，而在于输出形态——质检场景输出问题清单，分析场景输出中间数据集。
因此，框架的核心能力不是"做分析"或"做质检"，而是：
发现与注册算子 —— 内置算子 + 插件化扩展
编排算子执行 —— DAG 依赖解析、拓扑排序、串并行调度
适配异构数据 —— 统一的数据读写抽象，屏蔽 PostGIS / Shapefile / GeoJSON 差异
过程可追溯 —— 执行日志、中间结果、质检问题与评分
在这种思路下，框架被设计为方案驱动（Plan-Driven）：用户通过 JSON 配置定义一个"分析方案"，描述要执行哪些算子、数据从哪来、结果写到哪、依赖关系如何、失败怎么处理。框架负责解析方案、校验合法性、构建执行计划并调度运行。
二、架构设计：七层分治
整体架构采用七层分层设计，每层职责单一，通过接口解耦：
┌─────────────────────────────────────────────────────┐
│ CLI 层 (OpenGisDAF.Cli) │
│ 命令路由 · 异常处理 · DI 容器 │
├─────────────────────────────────────────────────────┤
│ 方案管理层 (OpenGisDAF.PlanManagement) │
│ CRUD · JSON 序列化 · 版本管理 · 校验 │
├─────────────────────────────────────────────────────┤
│ 调度引擎层 (OpenGisDAF.Scheduling) │
│ DAG 构建 · Kahn 拓扑排序 · 失败策略 · 并发控制 │
├─────────────────────────────────────────────────────┤
│ 执行引擎层 (OpenGisDAF.Execution) │
│ 算子执行 · 结果缓存 · 超时重试 · 质量报告 │
├─────────────────────────────────────────────────────┤
│ 算子池 (OpenGisDAF.Operators) │
│ 9 个内置算子 · 插件发现 · 动态加载 · 辅助工具 │
├─────────────────────────────────────────────────────┤
│ 适配器层 (OpenGisDAF.Adapters) │
│ IFeatureSource 数据源 (4) · IFeatureSink 输出 (4) │
│ 映射工具: FieldTypeMapper · GeometryTypeMapper │
├─────────────────────────────────────────────────────┤
│ 基础设施层 (OpenGisDAF.Infrastructure) │
│ 配置 · 日志 (Serilog) · 密码加密 (DPAPI) │
└─────────────────────────────────────────────────────┘
2.1 为什么选择七层而不是简单的三层？
传统三层架构（表示层 / 业务逻辑层 / 数据访问层）在面对"多种数据源 + 可插拔算子 + 复杂调度"这种场景时，会出现职责混杂的问题。
举例来说，如果执行引擎和调度引擎合并为一层，那么"重试机制"的代码就会散落在算子执行和任务调度两个不同的关注点中。同理，如果算子注册和数据适配在同一层，每当新增一种数据源，算子池的代码也需要改动。
七层的划分原则是：每个模块只处理一个维度的变化。数据源变了只改 Adapters，调度策略变了只改 Scheduling，算子增加了只改 Operators。各层之间通过 Core 层定义的接口通信（IOperator、IFeatureSource、ISchedulingEngine 等），Core 层自身不包含任何实现细节。
三、核心设计模式
3.1 算子体系：一切皆为 IOperator
所有算子实现统一的接口：
public interface IOperator
{
OperatorMetadata Metadata { get; }
ValidationResult Validate(AnalysisItem config);
Task ExecuteAsync(
IReadOnlyDictionary<string, IFeatureSource> inputs,
IReadOnlyDictionary<string, object?> parameters,
ExecutionContext context,
CancellationToken cancellationToken);
}
每个算子自带元数据（Metadata）：ID、名称、分类、标签、参数定义、输入输出 schema——这些信息不仅用于运行时查找，也是方案校验时的重要依据。例如，校验器会检查 parameters 中传入了不支持的参数名，或参数值不在 AllowedValues 范围内。
内置的 9 个算子覆盖了 GIS 领域最核心的需求：
分类 算子 关键技术点
空间运算 buffer、clip GDAL WKT 几何运算
空间关系 intersect_check、containment_check NTS 拓扑判断
格式转换 coordinate_transform GDAL CRS 坐标转换
属性操作 field_calculator、null_value_filler 自研递归下降表达式解析器
质检规则 attribute_completeness_checker、geometry_validity_checker QC 模式双路输出
一个值得展开的设计是质检算子的双路输出模式。同为 geometry_validity_checker，在普通模式下输出"通过检查的要素集"，在 QC 模式（_qc_mode = true）下输出 IssueRecord 列表。这意味着同一个算子无需为分析和质检分别编写两套；框架在算子执行前根据方案配置注入 _qc_mode 参数，算子内部据此决定返回对象。这种设计避免了算子逻辑的重复，也保持了对下游的透明性。
3.2 字段计算器：为什么自研表达式引擎？
field_calculator 需要支持三种表达式语义：
字符串插值：“area: {area} ㎡” → 将 {area} 替换为要素的属性值
裸字段引用：{population} → 直接取属性值
算术运算：{a} * {b} / 100 → 先替换字段值，再计算表达式
最初考虑过引入第三方表达式引擎（如 NCalc），但引入一个完整表达式库只为支持 + - * / 四种运算符，显然是杀鸡用牛刀。最终实现了一个约 120 行的递归下降解析器：
expression → term ((‘+’ | ‘-’) term)*
term → factor (('’ | ‘/’) factor)
factor → ‘(’ expression ‘)’ | ‘-’ factor | number
这个解析器支持括号、负数、四则运算和除零检测，并且通过 SemaphoreSlim 确保字段替换在多线程环境下的正确性——在代码审查阶段发现了一个关键 bug：字段名 {a} 和 {ab} 的替换顺序问题。如果先匹配 {a}，{ab} 会被错误替换成 2b（假设 a=2）。解决方法是将字段引用按长度降序排序后再替换，确保长的字段名先被匹配。
3.3 适配器模式：数据源的统一抽象
GIS 数据源形态多样——PostGIS 数据库、Shapefile 文件、GeoJSON 文件、内存数据集……如果每个算子都需要关心"数据从哪来"的具体细节，算子代码将充满平台相关的判断逻辑。
public interface IFeatureSource : IAsyncDisposable
{
FeatureSourceMetadata Metadata { get; }
Envelope BoundingBox { get; }
ISpatialReference SpatialReference { get; }
Task GetFeatureCountAsync();
IAsyncEnumerable GetFeaturesAsync(
Envelope? boundingBox = null,
string? filterExpression = null,
CancellationToken cancellationToken = default);
}
IFeatureSource 将数据读取统一为流式接口（IAsyncEnumerable），这对内存友好——一个 PostGIS 表可能有百万级要素，全部加载到内存会直接 OOM。流式读取让框架能够逐要素处理，内存占用可控。
同样，IFeatureSink 将数据写入也统一为三步协议：
public interface IFeatureSink : IAsyncDisposable
{
Task InitializeAsync(OutputSchema schema, CancellationToken ct);
Task WriteAsync(IFeature feature, CancellationToken ct);
Task CompleteAsync(CancellationToken ct);
}
这种设计让算子的输出目标完全可配置——同一个缓冲区分析的输出，既可以写到 GeoJSON 文件用于可视化验证，也可以写入 PostGIS 数据库用于后续分析，只需修改方案中的 OutputBinding 即可，算子代码无需任何改动。
3.4 插件系统：AssemblyLoadContext 实现依赖隔离
除了 9 个内置算子，框架支持通过 DLL 动态加载第三方算子。这里采用了 .NET 的 AssemblyLoadContext（ALC）机制：
private sealed class PluginLoadContext : AssemblyLoadContext
{
private readonly AssemblyDependencyResolver _resolver;
public string DllPath { get; }
public Assembly Assembly { get; private set; }
public PluginLoadContext(string dllPath) : base(isCollectible: true) { /*...*/ } protected override Assembly? Load(AssemblyName name) { var path = _resolver.ResolveAssemblyToPath(name); return path is not null ? LoadFromAssemblyPath(path) : null; }}
关键设计选择：
isCollectible: true：允许插件程序集被 GC 回收，支持热卸载后重新加载。
AssemblyDependencyResolver：自动解析插件的依赖项（NuGet 包等），无需手动管理。
Unload() + Unregister()：卸载插件时同步从算子池中移除所有注册的算子 ID，防止出现幽灵引用。
四、调度引擎：DAG 拓扑排序与失败策略
4.1 依赖关系建模
方案中每个分析项（AnalysisItem）通过 Inputs 声明其依赖：
{
“id”: “buffer-result”,
“operatorId”: “buffer”,
“inputs”: {
“source”: {
“type”: “Upstream”,
“sourceId”: “clip-result”,
“outputKey”: “output”
}
}
}
绑定类型有三种：
External：从外部数据源读取
Upstream：依赖上游分析项的结果
SubPlan：依赖子方案输出（接口已定义，将在后续版本中实现）
调度引擎在方案验证阶段就构建 DAG，通过 DFS 三色标记法检测循环依赖（检查 back edge）。通过验证后，使用 Kahn 算法进行拓扑排序：
// Kahn 算法核心逻辑
while (queue.Count > 0)
{
var node = queue.Dequeue();
ordered.Add(itemMap[node]);
foreach (var neighbor in adj[node]) { inDegree[neighbor]--; if (inDegree[neighbor] == 0) queue.Enqueue(neighbor); }}
排序结果的 IsComplete 标志位指示是否所有节点都成功入队——如果存在循环依赖，入队数量会少于总节点数，此时框架拒绝执行并报错。
4.2 失败策略的两种模式
框架支持两种失败策略，由方案配置决定：
StopOnAny（默认）：任一分析项失败，立即终止整个方案。尚未执行的分析项被标记为"已跳过"，并在最终统计中呈现。
ContinueIndependent：失败项的下游依赖被跳过，但不影响不相关分支的执行。调度引擎通过检查 HasFailedUpstream() 来判定某个分析项是否应该跳过。
// ContinueIndependent 模式下的跳过逻辑
if (plan.ExecutionPolicy.FailurePolicy == FailurePolicy.ContinueIndependent
&& HasFailedUpstream(item, failedItemIds))
{
itemStats.Add(new PerItemStats { ItemId = item.Id, SkippedCount = 1 });
continue;
}
这种设计意味着方案中的失败行为完全由配置控制，执行引擎不需要也不应该自行决定"遇到失败怎么办"。
4.3 并发控制与结果缓存
当前版本采用串行调度器，但已为并行调度预留了基础设施：
GlobalConcurrencyController：基于 SemaphoreSlim 的并发槽位控制，限制同时执行的分析项数量
ResultCache：基于 ConcurrentDictionary 的中间结果缓存，用于上游结果向下游传递
Per-key 锁：通过 ConcurrentDictionary<string, SemaphoreSlim> 实现，避免重复计算时使用全局锁造成不必要的性能损失
五、方案管理：21 条校验规则与版本控制
5.1 两阶段校验
方案校验器（PlanValidator）采用两阶段验证：
第一轮：Schema 校验（规则 1-14）——不依赖算子池，始终执行。
必填字段检查（plan.Id、plan.Name、plan.Version）
语义版本号格式校验（^\d+.\d+.\d+$）
分析项 ID 唯一性、算子 ID 不可为空
输入绑定 SourceId 完整性
执行策略参数合法性（MaxRetries >= 0、Timeout > 0、MaxParallelism >= 1 等）
DAG 循环依赖检测
第二轮：业务规则校验（规则 15-21）——仅在算子池存在时执行。
算子是否存在（通过 operatorPool.GetById() 查找）
上游依赖引用的分析项是否确实存在
参数约束验证（数值范围、正则模式、允许值列表）
非最终分析项是否配置了中间输出
子方案引用完整性
5.2 版本管理
每次保存方案时，PlanManager.SaveAsync() 自动执行 patch 版本号递增（1.0.0 → 1.0.1），并先备份旧版本（通过 IPlanVersionManager.BackupAsync()）。这种设计确保了：
可追溯：每次修改都有版本记录
可回滚：备份文件是完整的 JSON，可直接恢复
原子性：备份成功后才覆盖当前版本，中途失败不会损坏现有数据
六、GIS 技术栈选型：GDAL 与 NTS 的双轨设计
这是整个框架中最为核心的技术选型决策。
6.1 为什么需要两个 GIS 库？
场景 选择 原因
数据读写（Shapefile、PostGIS、GDB 等） GDAL/OGR C++ 内核，原生支持数十种格式
坐标转换（EPSG:4326 → EPSG:3857） GDAL/OGR 内置 PROJ 转换引擎，无需额外依赖
大数据场景 GDAL/OGR C++ 内核性能优势
轻量空间计算（相交判断、包含判断） NTS 纯 .NET，调用无跨语言开销
几何有效性检查 NTS IsValidOp 直接可用
纯 .NET 方案（如 NTS + ProjNet）虽然能避免 C++ 依赖的部署复杂度，但在格式支持和定位精度方面存在差距。GDAL 是 GIS 领域事实上的底层标准，其 Java/.NET 接口本质上都是对 C++ 核心的封装。
两者的分工很明确：GDAL 负责重量级的 I/O 和转换，NTS 负责轻量级的内存计算。算子内部通过统一的 WKT 格式进行数据交换：
GDAL Feature → WKT (via WktConverter) → 算子处理 → WKT → GDAL Feature
6.2 资源管理的关键教训
在代码审查阶段发现了一个严重问题：所有 FeatureSource 的 DisposeAsync 方法都没有释放底层的 GDAL/OGR 原生资源句柄。GDAL 的资源不在 .NET GC 的管理范围内，必须手动释放。修复方案是在每个适配器的 DisposeAsync 中显式调用 OguLayer 的 Dispose()，并使用 SemaphoreSlim 保护并发访问。
这也促成了一个全局约定：所有 IFeatureSource 实现必须正确实现 IAsyncDisposable，执行完毕后由调度引擎的 finally 块统一清理。
七、质量评分算法设计
质检报告需要输出一个总体质量评分。评分算法的设计需要在"简单直观"和"反映真实质量"之间取平衡。最终采用加权通过率的方式：
总体评分 = Σ(权重_i × 通过率_i) / Σ(权重_i) × 100
其中:
通过率_i = max(0, 1 - 错误数_i / 总问题数_i)
每个质检规则（对应一个分析项）单独计算通过率
通过率只惩罚 Error 级别的问题，Warning 和 Info 不降分
支持通过方案配置为不同规则设置不同权重
规则级别的 PassRate 也一并输出，便于定位具体哪个规则拖低了整体分数
var passRate = totalIssues > 0
? Math.Max(0, 1.0 - (double)errorIssues / Math.Max(totalIssues, 1))
: 1.0;
totalWeightedScore += weight * passRate;
八、实践中的坑与教训
以下是在开发与代码审查过程中发现和修复的关键问题，它们揭示了并发编程中一些细微但致命的陷阱。
8.1 ResultCache 的竞态条件
问题：ResultCache.ClearAsync() 在遍历 _cache.Values 释放 IAsyncDisposable 资源的同时，另一个线程可能正在 GetOrComputeAsync 中计算新的缓存项。ClearAsync 遍历的是快照，新计算出的条目可能不会被清理，从而泄漏资源。
教训：并发集合的遍历操作（foreach 遍历 ConcurrentDictionary.Values）不是原子的。在清理操作和写入操作之间需要信号量同步。
8.2 ExecutionContext 的可变共享状态
问题：ExecutionContext.CurrentItemId 最初是可变的 string 属性。在并行调度场景下，多个线程可能同时读取/修改该字段，导致日志中记录的 CurrentItemId 指向错误的分析项。
修复：改为 init-only 属性，在 SerialScheduler 中为每个分析项的每次执行创建新的 ExecutionContext 实例，确保不可变性。
8.3 字段计算器的名称冲突
问题：字段替换使用 Regex.Replace(“{…}”, …) 时，{a} 可能在 {ab} 之前被匹配，导致 {ab} 的占位符被破坏。
修复：使用正则 {(\w+)} 提取所有字段引用，按字段名长度降序排序后再依次替换，确保长名字段优先匹配。
8.4 全局异常处理器初始化时序
问题：ExceptionHandler.ConfigureGlobalHandler() 在 DI 容器构建之前就被调用，而 Serilog 的配置在 DI 容器构建之后。这意味着框架启动初期的全局异常（如配置加载失败）不会被结构化日志系统捕获。
修复：将全局异常处理器从构造函数中移出，延迟到 DI 容器完全构建后再注册，并在处理器中添加对日志系统不可用时的降级处理（回退到 Console.Error）。
九、架构演进的预留设计
作为框架的初始版本，已经在多处为未来的扩展预留了接口和配置空间：
预留能力 当前状态 后续规划
并行调度 串行执行，但 GlobalConcurrencyController 已就绪 Kahn 层级内并行执行
子方案嵌套 BindingType.SubPlan 已定义，执行时抛 NotSupportedException 递归展开子方案 DAG
数据分区 EnablePartitioning + PartitionCount 配置已支持 按空间范围分区并行处理
算子版本锁定 OperatorVersion 字段已定义 多版本算子共存
进程隔离 AssemblyLoadContext 已实现 扩展到独立进程以支持异构语言运行时
这种"预留而不实现"的设计哲学，确保了当前版本的代码量不会膨胀，同时后续开发不必打破已建立的接口契约。
十、总结
构建一个 GIS 数据引擎，本质上是在做一个"编排层"——它不直接产生业务价值，它的价值来自于让产生业务价值的算子能够被正确地组合、调度和执行。这要求框架设计者对"什么属于框架"和"什么属于算子"有清晰的边界意识。
