433 lines
15 KiB
Markdown
433 lines
15 KiB
Markdown
数据检查记录管理是 SunvStation 数据质量保证系统的核心组件，用于记录、追踪和管理数据验证过程中发现的各类问题。通过该机制，您可以系统地捕获检查结果、定位问题对象、记录问题描述，并支持后续的统计分析和问题修复工作。数据检查记录为数据生产流程提供了可追溯的质量控制能力。
|
||
|
||
Sources: [PySSCheck.py](PySSCheck.py#L101-L160)
|
||
|
||
## 系统架构概览
|
||
|
||
数据检查记录管理基于 **CheckFunForPY** 类实现，该类通过 SWIG 封装技术连接 Python 业务逻辑与 C++ 核心检查引擎。在整个系统架构中，CheckFunForPY 位于接口层，与工作空间、地图管理等核心模块协同工作，形成完整的数据质量保障体系。
|
||
|
||
```mermaid
|
||
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](PySSCheck.py#L101-L160)
|
||
|
||
## 核心功能模块
|
||
|
||
数据检查记录管理包含六大核心功能模块，每个模块对应一组相关的方法，共同构成完整的检查记录生命周期管理能力。
|
||
|
||
### 记录生命周期管理
|
||
|
||
| 方法名称 | 功能说明 | 典型应用场景 |
|
||
|---------|---------|------------|
|
||
| `AddCheckRecord()` | 添加一条新的检查记录 | 数据验证脚本发现问题时记录 |
|
||
| `RemoveCheckRecord()` | 删除指定的检查记录 | 误报修正或批量清理 |
|
||
| `GetCheckRecordCount()` | 获取当前检查记录总数 | 统计分析、进度监控 |
|
||
| `ClearCheckRecord()` | 清空所有检查记录 | 开始新一轮检查前初始化 |
|
||
|
||
记录的生命周期从添加开始，经过可能的删除操作，最终通过保存操作持久化。这种设计遵循**最小状态原则**，检查记录仅在内存中维护显式状态，避免隐式的后台同步操作。
|
||
|
||
Sources: [PySSCheck.py](PySSCheck.py#L114-L123)
|
||
|
||
### 持久化与IO操作
|
||
|
||
| 方法名称 | 功能说明 | 操作目标 |
|
||
|---------|---------|---------|
|
||
| `LoadCheckRecord()` | 从文件加载历史检查记录 | 恢复之前保存的检查结果 |
|
||
| `SaveCheckRecord()` | 将当前检查记录保存到文件 | 持久化存储检查结果 |
|
||
| `WriteCheckRecord()` | 将检查记录写入系统输出 | 与系统检查模块集成 |
|
||
|
||
持久化操作支持检查结果的跨会话复用，您可以在不同时间点加载和比较检查结果，追踪数据质量的演变趋势。
|
||
|
||
Sources: [PySSCheck.py](PySSCheck.py#L108-L110)
|
||
|
||
### 查询与访问
|
||
|
||
| 方法名称 | 功能说明 | 参数说明 |
|
||
|---------|---------|---------|
|
||
| `GetCheckRecordValue()` | 获取指定记录的字段值 | 支持批量获取多个字段 |
|
||
| `ShowCheckOutput()` | 显示检查输出结果 | 在系统界面中呈现 |
|
||
|
||
查询方法提供了灵活的数据访问能力，支持按索引定位记录并提取特定字段，便于生成定制化的报告或进行深度分析。
|
||
|
||
Sources: [PySSCheck.py](PySSCheck.py#L124-L125)
|
||
|
||
## 检查记录数据结构
|
||
|
||
每条检查记录包含丰富的元数据信息，用于完整描述检查发现的问题。理解这些字段的结构是有效使用检查记录功能的基础。
|
||
|
||
```mermaid
|
||
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](PySSCheck.py#L113-L114)
|
||
|
||
### 关键字段说明
|
||
|
||
| 字段名 | 数据类型 | 说明 | 示例值 |
|
||
|-------|---------|------|--------|
|
||
| `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](PySSCheck.py#L113-L114)
|
||
|
||
## 典型使用流程
|
||
|
||
数据检查记录管理遵循标准的 **创建-操作-保存** 流程。理解这个流程有助于编写结构清晰、逻辑严谨的检查脚本。
|
||
|
||
```mermaid
|
||
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](PySSCheck.py#L108-L125)
|
||
|
||
### 基础实例化
|
||
|
||
与 sunvpy 中其他需要显式实例化的类一样，使用 CheckFunForPY 首先需要创建实例。
|
||
|
||
```python
|
||
from sunvpy.PySSCheck import CheckFunForPY
|
||
|
||
# 创建检查记录管理实例
|
||
check_fun = CheckFunForPY()
|
||
```
|
||
|
||
实例化后，check_fun 对象维护一个独立的检查记录集合，与其他实例或系统全局检查记录互不干扰。
|
||
|
||
Sources: [PySSCheck.py](PySSCheck.py#L156-L158)
|
||
|
||
### 添加检查记录
|
||
|
||
添加检查记录是数据质量验证脚本的核心操作。以下示例展示了如何记录一个重叠检查问题：
|
||
|
||
```python
|
||
# 检查到两个面对象重叠
|
||
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](PySSCheck.py#L113-L114)
|
||
|
||
### 统计与查询
|
||
|
||
检查完成后，通常需要获取统计信息或详细记录，用于生成报告或进行后续分析。
|
||
|
||
```python
|
||
# 获取检查记录总数
|
||
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](PySSCheck.py#L124-L125)
|
||
|
||
### 持久化与清理
|
||
|
||
检查记录的生命周期管理包括保存和清理操作，确保数据不会意外丢失或占用过多内存。
|
||
|
||
```python
|
||
# 保存检查记录到文件
|
||
check_fun.SaveCheckRecord()
|
||
|
||
# 在系统界面中显示检查结果
|
||
check_fun.ShowCheckOutput()
|
||
|
||
# 清空检查记录，准备下一次检查
|
||
check_fun.ClearCheckRecord()
|
||
```
|
||
|
||
保存操作会将当前内存中的所有检查记录写入系统配置的默认位置，通常位于工作目录下的特定文件夹中。ShowCheckOutput 方法会触发系统内置的检查结果查看器，提供可视化的结果浏览界面。
|
||
|
||
Sources: [PySSCheck.py](PySSCheck.py#L108-L112)
|
||
|
||
## 检查记录的高级应用
|
||
|
||
在实际的数据生产项目中，检查记录管理通常与其他 sunvpy 功能结合使用，形成完整的质量控制解决方案。
|
||
|
||
### 与选择集的协同
|
||
|
||
检查记录通常基于选择集操作的结果生成，以下是一个完整的检查流程示例：
|
||
|
||
```python
|
||
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](ssprocess_mixins/selection_mixin.py#L29-L38)
|
||
|
||
### 历史记录对比
|
||
|
||
通过 LoadCheckRecord 方法，可以加载历史检查记录进行对比分析，追踪数据质量的改进情况。
|
||
|
||
```python
|
||
# 加载之前的检查记录
|
||
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](PySSCheck.py#L108-L110)
|
||
|
||
## 性能考虑与最佳实践
|
||
|
||
在大规模数据检查场景下，合理使用检查记录管理功能对于保证脚本性能至关重要。
|
||
|
||
### 批量操作优化
|
||
|
||
检查记录的添加操作相对轻量，但在数十万级别记录时仍需注意性能。建议采用**分批保存**策略：
|
||
|
||
```python
|
||
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](PySSCheck.py#L108-L114)
|
||
|
||
### 记录内容优化
|
||
|
||
在记录量大的情况下，精简描述信息可以提升整体性能：
|
||
|
||
```python
|
||
# 简洁描述（推荐）
|
||
desc = f"重叠|obj_{geo_id}|{layer_name}"
|
||
|
||
# 冗长描述（避免）
|
||
desc = f"在图层 '{layer_name}' 中，编码为 {geo_id} 的地物对象与其他对象存在空间重叠现象，需要进行进一步的空间关系分析和几何修正处理"
|
||
```
|
||
|
||
描述信息主要用于问题定位，过度详细的描述会占用额外的存储空间并影响后续查询性能。
|
||
|
||
Sources: [PySSCheck.py](PySSCheck.py#L113-L114)
|
||
|
||
## 常见问题与故障排除
|
||
|
||
### 记录无法保存
|
||
|
||
如果 SaveCheckRecord 调用失败，通常是因为以下原因：
|
||
|
||
1. **文件权限问题**：确保脚本有写入输出目录的权限
|
||
2. **路径不存在**：检查系统配置的输出路径是否有效
|
||
3. **磁盘空间不足**：检查磁盘剩余空间
|
||
|
||
```python
|
||
# 添加错误处理
|
||
try:
|
||
check_fun.SaveCheckRecord()
|
||
print("检查记录保存成功")
|
||
except Exception as e:
|
||
print(f"保存失败: {e}")
|
||
```
|
||
|
||
### geoids 和 noteids 格式错误
|
||
|
||
这两个字段需要以逗号分隔的字符串形式提供，错误格式可能导致关联失败：
|
||
|
||
```python
|
||
# 正确格式
|
||
geo_ids = "1001,1002,1003"
|
||
|
||
# 错误格式（会导致问题）
|
||
geo_ids = "1001; 1002; 1003" # 使用了分号
|
||
geo_ids = "[1001,1002]" # 使用了括号
|
||
```
|
||
|
||
### GetCheckRecordValue 返回空值
|
||
|
||
当指定索引超出范围或字段名称不存在时，该方法可能返回空字符串。应始终进行有效性检查：
|
||
|
||
```python
|
||
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](PySSCheck.py#L124-L125)
|
||
|
||
## 学习路径建议
|
||
|
||
数据检查记录管理是 SunvStation 数据质量保障体系的基础，掌握本页面的内容后，建议按照以下顺序深入学习：
|
||
|
||
1. **[添加与加载检查记录](31-tian-jia-yu-jia-zai-jian-cha-ji-lu)** - 详细了解 AddCheckRecord 和 LoadCheckRecord 的高级用法
|
||
2. **[显示检查结果](32-xian-shi-jian-cha-jie-guo)** - 掌握 ShowCheckOutput 和结果可视化技巧
|
||
3. **[自定义检查规则](33-zi-ding-yi-jian-cha-gui-ze)** - 学习如何构建自定义的数据检查逻辑
|
||
|
||
通过系统学习这些内容，您将能够构建完整的数据质量控制和问题追踪系统。 |