15 KiB
数据检查记录管理是 SunvStation 数据质量保证系统的核心组件，用于记录、追踪和管理数据验证过程中发现的各类问题。通过该机制，您可以系统地捕获检查结果、定位问题对象、记录问题描述，并支持后续的统计分析和问题修复工作。数据检查记录为数据生产流程提供了可追溯的质量控制能力。
Sources: PySSCheck.py
系统架构概览
数据检查记录管理基于 CheckFunForPY 类实现，该类通过 SWIG 封装技术连接 Python 业务逻辑与 C++ 核心检查引擎。在整个系统架构中，CheckFunForPY 位于接口层，与工作空间、地图管理等核心模块协同工作，形成完整的数据质量保障体系。
graph TB
subgraph "应用层 Python 业务逻辑"
Script[检查脚本]
end
subgraph "接口层 SWIG 封装"
CheckFun[CheckFunForPY<br/>检查记录管理类]
OtherMods[其他接口模块<br/>PySSCore, PySSMap等]
end
subgraph "实现层 C++ 核心库"
CheckDL[_PySSCheck.pyd<br/>检查引擎实现]
OtherDL[其他核心库<br/>_PySSCore.pyd等]
end
Script -->|实例化| CheckFun
Script -->|可能调用| OtherMods
CheckFun -->|调用| CheckDL
CheckFun -.->|协作| OtherMods
OtherMods --> OtherDL
style CheckFun fill:#e1f5ff
style CheckDL fill:#fff4e1
CheckFunForPY 类采用了 记录集管理模式，检查记录以集合形式在内存中维护，提供增删改查的完整操作。与 SSProcessManager 的单例模式不同，CheckFunForPY 需要显式实例化，这种设计允许同时维护多个独立的检查记录集合，适用于并行检查或分段检查等复杂场景。
Sources: PySSCheck.py
核心功能模块
数据检查记录管理包含六大核心功能模块，每个模块对应一组相关的方法，共同构成完整的检查记录生命周期管理能力。
记录生命周期管理
| 方法名称 | 功能说明 | 典型应用场景 |
|---|---|---|
AddCheckRecord() |
添加一条新的检查记录 | 数据验证脚本发现问题时记录 |
RemoveCheckRecord() |
删除指定的检查记录 | 误报修正或批量清理 |
GetCheckRecordCount() |
获取当前检查记录总数 | 统计分析、进度监控 |
ClearCheckRecord() |
清空所有检查记录 | 开始新一轮检查前初始化 |
记录的生命周期从添加开始，经过可能的删除操作，最终通过保存操作持久化。这种设计遵循最小状态原则，检查记录仅在内存中维护显式状态，避免隐式的后台同步操作。
Sources: PySSCheck.py
持久化与IO操作
| 方法名称 | 功能说明 | 操作目标 |
|---|---|---|
LoadCheckRecord() |
从文件加载历史检查记录 | 恢复之前保存的检查结果 |
SaveCheckRecord() |
将当前检查记录保存到文件 | 持久化存储检查结果 |
WriteCheckRecord() |
将检查记录写入系统输出 | 与系统检查模块集成 |
持久化操作支持检查结果的跨会话复用，您可以在不同时间点加载和比较检查结果，追踪数据质量的演变趋势。
Sources: PySSCheck.py
查询与访问
| 方法名称 | 功能说明 | 参数说明 |
|---|---|---|
GetCheckRecordValue() |
获取指定记录的字段值 | 支持批量获取多个字段 |
ShowCheckOutput() |
显示检查输出结果 | 在系统界面中呈现 |
查询方法提供了灵活的数据访问能力，支持按索引定位记录并提取特定字段，便于生成定制化的报告或进行深度分析。
Sources: PySSCheck.py
检查记录数据结构
每条检查记录包含丰富的元数据信息，用于完整描述检查发现的问题。理解这些字段的结构是有效使用检查记录功能的基础。
classDiagram
class CheckRecord {
+string group 检查组名
+string check 检查项名称
+int checkmodel 检查模式
+string description 问题描述
+float x 问题位置X坐标
+float y 问题位置Y坐标
+float z 问题位置Z坐标
+int objtype 对象类型
+string geoids 地物ID列表
+string noteids 注记ID列表
}
class CheckFunForPY {
+AddCheckRecord(group, check, ...)
+GetCheckRecordValue(index, fields, values)
+RemoveCheckRecord(group, check)
+GetCheckRecordCount()
+LoadCheckRecord()
+SaveCheckRecord()
}
CheckFunForPY "1" *-- "0..*" CheckRecord : 管理记录集合
检查记录采用坐标定位 + 对象关联的双重定位机制。通过 x、y、z 坐标可以直接定位问题发生的地理位置，通过 geoids 和 noteids 可以关联到具体的地物对象和注记对象，这种设计既支持空间定位，也支持对象级别的追踪修复。
Sources: PySSCheck.py
关键字段说明
| 字段名 | 数据类型 | 说明 | 示例值 |
|---|---|---|---|
group |
string | 检查组名称，用于分类管理 | "拓扑检查" |
check |
string | 检查项名称，标识具体检查类型 | "重叠检查" |
checkmodel |
int | 检查模式标识符 | 0 |
description |
string | 问题描述或错误详情 | "面对象与线对象存在重叠" |
x |
float | 问题位置X坐标 | 123456.78 |
y |
float | 问题位置Y坐标 | 345678.90 |
z |
float | 问题位置Z坐标（可选） | 0.0 |
objtype |
int | 问题对象类型 | 2（面对象） |
geoids |
string | 地物对象ID列表，逗号分隔 | "1001,1002,1003" |
noteids |
string | 注记对象ID列表，逗号分隔 | "2001,2002" |
Sources: PySSCheck.py
典型使用流程
数据检查记录管理遵循标准的 创建-操作-保存 流程。理解这个流程有助于编写结构清晰、逻辑严谨的检查脚本。
flowchart LR
A[开始数据检查任务] --> B[创建 CheckFunForPY 实例]
B --> C[执行数据检查逻辑]
C --> D{发现数据问题?}
D -->|否| C
D -->|是| E[调用 AddCheckRecord 记录问题]
E --> C
C --> F{检查流程完成?}
F -->|否| C
F -->|是| G[调用 GetCheckRecordCount 统计]
G --> H{需要显示结果?}
H -->|是| I[调用 ShowCheckOutput]
H -->|否| J[调用 SaveCheckRecord 保存]
I --> J
J --> K[检查记录管理完成]
该流程体现了渐进式积累的设计理念：检查记录在检查过程中逐步添加，最后统一处理显示和保存，这种方式避免了频繁的 I/O 操作，提升了大规模数据检查的性能。
Sources: PySSCheck.py
基础实例化
与 sunvpy 中其他需要显式实例化的类一样，使用 CheckFunForPY 首先需要创建实例。
from sunvpy.PySSCheck import CheckFunForPY
# 创建检查记录管理实例
check_fun = CheckFunForPY()
实例化后，check_fun 对象维护一个独立的检查记录集合，与其他实例或系统全局检查记录互不干扰。
Sources: PySSCheck.py
添加检查记录
添加检查记录是数据质量验证脚本的核心操作。以下示例展示了如何记录一个重叠检查问题：
# 检查到两个面对象重叠
group_name = "拓扑检查"
check_name = "重叠检查"
check_model = 0
desc = "建筑物A与建筑物B存在空间重叠"
x_pos = 123456.78
y_pos = 345678.90
z_pos = 0.0
obj_type = 2 # 面对象
geo_ids = "1001,1002" # 两个重叠对象的ID
note_ids = "" # 无注记对象
# 添加检查记录
check_fun.AddCheckRecord(
group_name, check_name, check_model, desc,
x_pos, y_pos, z_pos, obj_type, geo_ids, note_ids
)
在实际应用中，geoids 和 noteids 通常从当前选择集或遍历结果中提取，这需要与 SSProcessManager 的选择集功能配合使用。
Sources: PySSCheck.py
统计与查询
检查完成后，通常需要获取统计信息或详细记录，用于生成报告或进行后续分析。
# 获取检查记录总数
count = check_fun.GetCheckRecordCount()
print(f"共发现 {count} 个问题")
# 遍历检查记录
for i in range(count):
fields = "group,check,description,geoids"
values = ""
# 获取记录值（通过引用参数返回）
check_fun.GetCheckRecordValue(i, fields, values)
# values 包含所有请求字段的值，按逗号分隔
print(f"记录 {i}: {values}")
GetCheckRecordValue 方法采用 批量字段获取 的设计，一次调用可以获取多个字段，减少方法调用次数，提升性能。返回的 values 字符串按照 fields 参数中指定的字段顺序，以逗号分隔各个字段值。
Sources: PySSCheck.py
持久化与清理
检查记录的生命周期管理包括保存和清理操作，确保数据不会意外丢失或占用过多内存。
# 保存检查记录到文件
check_fun.SaveCheckRecord()
# 在系统界面中显示检查结果
check_fun.ShowCheckOutput()
# 清空检查记录，准备下一次检查
check_fun.ClearCheckRecord()
保存操作会将当前内存中的所有检查记录写入系统配置的默认位置，通常位于工作目录下的特定文件夹中。ShowCheckOutput 方法会触发系统内置的检查结果查看器，提供可视化的结果浏览界面。
Sources: PySSCheck.py
检查记录的高级应用
在实际的数据生产项目中，检查记录管理通常与其他 sunvpy 功能结合使用，形成完整的质量控制解决方案。
与选择集的协同
检查记录通常基于选择集操作的结果生成，以下是一个完整的检查流程示例：
from sunvpy import SSProcess
from sunvpy.PySSCheck import CheckFunForPY
# 1. 创建检查记录实例
check_fun = CheckFunForPY()
# 2. 设置选择条件，筛选可能存在问题的对象
SSProcess.clearSelection()
SSProcess.clearSelectCondition()
SSProcess.setSelectCondition("SSObj_LayerName", "==", "建筑")
SSProcess.setSelectCondition("<Overlap>", "==", "True")
# 3. 执行过滤查询
SSProcess.selectFilter()
# 4. 遍历选择集，记录问题
count = SSProcess.getSelGeoCount()
for i in range(count):
geo_id = SSProcess.getSelGeoValue(i, "SSObj_ID")
x = float(SSProcess.getSelGeoValue(i, "SSObj_X"))
y = float(SSProcess.getSelGeoValue(i, "SSObj_Y"))
layer_name = SSProcess.getSelGeoValue(i, "SSObj_LayerName")
# 添加检查记录
check_fun.AddCheckRecord(
group="拓扑检查",
check="重叠检查",
checkmodel=0,
description=f"图层 '{layer_name}' 中的地物存在重叠",
x=x, y=y, z=0.0,
objtype=2,
geoids=str(geo_id),
noteids=""
)
# 5. 保存并显示结果
print(f"检查完成，共发现 {check_fun.GetCheckRecordCount()} 个问题")
check_fun.SaveCheckRecord()
check_fun.ShowCheckOutput()
该示例展示了检查记录管理与选择集操作的典型协作模式，体现了查询-遍历-记录的三阶段处理流程。
Sources: ssprocess_mixins/selection_mixin.py
历史记录对比
通过 LoadCheckRecord 方法，可以加载历史检查记录进行对比分析，追踪数据质量的改进情况。
# 加载之前的检查记录
check_fun.LoadCheckRecord()
old_count = check_fun.GetCheckRecordCount()
print(f"历史记录中共有 {old_count} 个问题")
# 执行新的检查...
# ...检查逻辑...
# 清空历史记录，保存新的检查结果
check_fun.ClearCheckRecord()
# ...添加新的检查记录...
new_count = check_fun.GetCheckRecordCount()
print(f"本次检查发现 {new_count} 个问题")
print(f"数据质量改进: {old_count - new_count} 个问题已修复")
对比分析功能为数据生产质量评估提供了量化指标，是数据质量管理体系的重要组成部分。
Sources: PySSCheck.py
性能考虑与最佳实践
在大规模数据检查场景下，合理使用检查记录管理功能对于保证脚本性能至关重要。
批量操作优化
检查记录的添加操作相对轻量，但在数十万级别记录时仍需注意性能。建议采用分批保存策略：
BATCH_SIZE = 1000 # 每1000条记录保存一次
for i in range(total_checks):
# 执行检查并添加记录
check_fun.AddCheckRecord(...)
# 分批保存
if (i + 1) % BATCH_SIZE == 0:
check_fun.SaveCheckRecord()
check_fun.ClearCheckRecord() # 可选：清空后继续累积
# 保存剩余记录
if total_checks % BATCH_SIZE != 0:
check_fun.SaveCheckRecord()
这种策略可以有效控制内存使用，避免检查记录集合过大导致性能下降。
Sources: PySSCheck.py
记录内容优化
在记录量大的情况下，精简描述信息可以提升整体性能：
# 简洁描述（推荐）
desc = f"重叠|obj_{geo_id}|{layer_name}"
# 冗长描述（避免）
desc = f"在图层 '{layer_name}' 中，编码为 {geo_id} 的地物对象与其他对象存在空间重叠现象，需要进行进一步的空间关系分析和几何修正处理"
描述信息主要用于问题定位，过度详细的描述会占用额外的存储空间并影响后续查询性能。
Sources: PySSCheck.py
常见问题与故障排除
记录无法保存
如果 SaveCheckRecord 调用失败，通常是因为以下原因：
- 文件权限问题：确保脚本有写入输出目录的权限
- 路径不存在：检查系统配置的输出路径是否有效
- 磁盘空间不足：检查磁盘剩余空间
# 添加错误处理
try:
check_fun.SaveCheckRecord()
print("检查记录保存成功")
except Exception as e:
print(f"保存失败: {e}")
geoids 和 noteids 格式错误
这两个字段需要以逗号分隔的字符串形式提供，错误格式可能导致关联失败：
# 正确格式
geo_ids = "1001,1002,1003"
# 错误格式（会导致问题）
geo_ids = "1001; 1002; 1003" # 使用了分号
geo_ids = "[1001,1002]" # 使用了括号
GetCheckRecordValue 返回空值
当指定索引超出范围或字段名称不存在时，该方法可能返回空字符串。应始终进行有效性检查：
fields = "group,check,description"
values = ""
# 确保索引有效
if index < check_fun.GetCheckRecordCount():
check_fun.GetCheckRecordValue(index, fields, values)
if not values:
print(f"警告：记录 {index} 的数据不完整")
else:
print(f"错误：索引 {index} 超出范围")
Sources: PySSCheck.py
学习路径建议
数据检查记录管理是 SunvStation 数据质量保障体系的基础，掌握本页面的内容后，建议按照以下顺序深入学习：
- 添加与加载检查记录 - 详细了解 AddCheckRecord 和 LoadCheckRecord 的高级用法
- 显示检查结果 - 掌握 ShowCheckOutput 和结果可视化技巧
- 自定义检查规则 - 学习如何构建自定义的数据检查逻辑
通过系统学习这些内容，您将能够构建完整的数据质量控制和问题追踪系统。