init

2026-04-10 13:47:53 +08:00
commit 8c78c0f920
61 changed files with 30343 additions and 0 deletions
--- a/docs/content/32-xian-shi-jian-cha-jie-guo.md
+++ b/docs/content/32-xian-shi-jian-cha-jie-guo.md
@@ -0,0 +1,678 @@
+显示检查结果是数据质量验证流程的最后一步，通过可视化界面呈现检查记录中记录的所有问题，帮助用户快速定位、分析和修复数据缺陷。通过 `ShowCheckOutput()` 方法，系统将内存中的检查记录转换为直观的检查结果窗口，提供交互式的问题浏览和定位功能。
+
+Sources: [PySSCheck.py](PySSCheck.py#L120-L120)
+
+## 核心功能概述
+
+`ShowCheckOutput()` 是 CheckFunForPY 类提供的关键方法，用于在系统界面中弹出一个独立的检查结果查看窗口。该窗口以表格或列表形式展示所有检查记录，支持按检查组、检查项进行分类展示，并提供空间定位功能，点击某条记录即可自动缩放地图到问题发生的位置。
+
+该方法的设计遵循**最小调用原则**，无需任何参数即可完成完整的显示操作，系统会自动读取当前 CheckFunForPY 实例中的所有检查记录并渲染到界面。这种设计降低了使用门槛，使得在检查完成后只需一行代码即可呈现结果。
+
+```mermaid
+graph TB
+    subgraph "检查脚本执行流程"
+        A[创建 CheckFunForPY 实例] --> B[执行数据检查逻辑]
+        B --> C[调用 AddCheckRecord 记录问题]
+        C --> D[检查完成]
+    end
+    
+    subgraph "结果显示阶段"
+        D --> E[调用 ShowCheckOutput]
+        E --> F[读取内存中的检查记录集合]
+        F --> G[生成检查结果窗口]
+        G --> H[用户交互浏览问题]
+        H --> I[点击定位到地图]
+    end
+    
+    style E fill:#e1f5ff
+    style G fill:#fff4e1
+    style I fill:#d4edda
+```
+
+Sources: [PySSCheck.py](PySSCheck.py#L120-L120)
+
+## 基础使用方法
+
+### 方法签名
+
+`ShowCheckOutput()` 方法的签名非常简洁：
+
+```python
+def ShowCheckOutput(self):
+```
+
+- **返回值**: 无明确文档说明返回值类型，从调用方代码推断为布尔值或无返回
+- **参数**: 无需任何参数
+- **异常**: 调用失败时可能抛出异常，建议在 try-except 结构中调用
+
+### 最简示例
+
+以下是使用 ShowCheckOutput 的最简示例，展示了典型的检查-记录-显示流程：
+
+```python
+from sunvpy.PySSCheck import CheckFunForPY
+
+# 创建检查记录管理实例
+check_fun = CheckFunForPY()
+
+# ... 执行检查逻辑，调用 AddCheckRecord 添加问题记录 ...
+check_fun.AddCheckRecord(
+    group="拓扑检查",
+    check="重叠检查",
+    checkmodel=1,
+    description="建筑物A与建筑物B存在重叠",
+    x=123456.78, y=345678.90, z=0.0,
+    objtype=3,
+    geoids="1001,1002",
+    noteids=""
+)
+
+# 显示检查结果
+check_fun.ShowCheckOutput()
+```
+
+执行上述代码后，系统会弹出一个检查结果窗口，显示所有已添加的检查记录。
+
+Sources: [PySSCheck.py](PySSCheck.py#L113-L120)
+
+## 检查结果窗口界面
+
+### 窗口结构
+
+检查结果窗口通常包含以下主要区域：
+
+| 区域 | 功能 | 说明 |
+|------|------|------|
+| **记录列表区** | 显示所有检查记录的摘要信息 | 包括组名、检查项、描述、位置等 |
+| **详情面板** | 显示当前选中记录的完整信息 | 展示所有字段的详细值 |
+| **工具栏** | 提供常用操作按钮 | 定位、刷新、导出等功能 |
+| **统计信息** | 显示问题统计概览 | 按组分类统计问题数量 |
+
+### 记录显示内容
+
+每条检查记录在窗口中显示以下核心信息：
+
+- **检查组**: 用于逻辑分组，如"拓扑检查"、"属性检查"
+- **检查项**: 标识具体检查类型，如"重叠检查"、"名称缺失"
+- **问题描述**: 简要描述发现的问题
+- **位置坐标**: 问题发生的 X、Y、Z 坐标
+- **关联对象**: 涉及的地物 ID 和注记 ID 列表
+
+### 交互功能
+
+检查结果窗口支持多种交互操作，提升问题处理的效率：
+
+```mermaid
+flowchart LR
+    A[检查结果窗口] --> B[点击记录]
+    B --> C[显示详情]
+    C --> D{需要定位?}
+    D -->|是| E[地图自动缩放至问题位置]
+    D -->|否| F[继续浏览其他记录]
+    E --> F
+    
+    F --> G{需要修复?}
+    G -->|是| H[切换到地图编辑视图]
+    H --> I[修改问题对象]
+    I --> J[返回检查窗口]
+    J --> F
+    
+    G -->|否| F
+    
+    F --> K{所有问题处理完毕?}
+    K -->|否| F
+    K -->|是| L[关闭窗口]
+    
+    style B fill:#e1f5ff
+    style E fill:#fff4e1
+    style I fill:#d4edda
+```
+
+Sources: [PySSCheck.py](PySSCheck.py#L120-L120)
+
+## 完整工作流程示例
+
+以下是一个完整的检查流程示例，从准备检查到显示结果的全部步骤：
+
+```python
+from sunvpy import SSProcess
+from sunvpy.PySSCheck import CheckFunForPY
+
+def run_topology_check():
+    """执行拓扑检查并显示结果"""
+    
+    # 步骤1: 初始化检查记录管理器
+    check_fun = CheckFunForPY()
+    check_fun.ClearCheckRecord()  # 清空之前的记录
+    
+    print("开始拓扑检查...")
+    
+    # 步骤2: 设置选择条件
+    SSProcess.clearSelection()
+    SSProcess.clearSelectCondition()
+    SSProcess.setSelectCondition("SSObj_Type", "==", "3")  # 面对象
+    SSProcess.selectFilter()
+    
+    # 步骤3: 遍历选择集并检查
+    count = SSProcess.getSelGeoCount()
+    issue_count = 0
+    
+    for i in range(count):
+        geo_id = SSProcess.getSelGeoValue(i, "SSObj_ID")
+        obj_type = int(SSProcess.getSelGeoValue(i, "SSObj_Type"))
+        
+        # 获取对象位置（使用第一个点坐标）
+        x = float(SSProcess.getSelGeoValue(i, "SSObj_X"))
+        y = float(SSProcess.getSelGeoValue(i, "SSObj_Y"))
+        z = 0.0
+        
+        # 模拟检查逻辑：每10个对象记录一个重叠问题
+        if i % 10 == 0:
+            check_fun.AddCheckRecord(
+                group="拓扑检查",
+                check="重叠检查",
+                checkmodel=1,
+                description=f"面对象 {geo_id} 存在空间重叠",
+                x=x, y=y, z=z,
+                objtype=obj_type,
+                geoids=str(geo_id),
+                noteids=""
+            )
+            issue_count += 1
+    
+    # 步骤4: 输出统计信息
+    total_count = check_fun.GetCheckRecordCount()
+    print(f"检查完成，共发现 {total_count} 个拓扑问题")
+    
+    # 步骤5: 显示检查结果
+    if total_count > 0:
+        print("正在打开检查结果窗口...")
+        check_fun.ShowCheckOutput()
+    else:
+        print("未发现问题，无需显示结果")
+    
+    return total_count
+
+# 执行检查
+if __name__ == "__main__":
+    result_count = run_topology_check()
+```
+
+该示例展示了**分阶段检查**的工作流程：初始化、查询、遍历、记录、统计、显示。通过在每个阶段输出日志，便于追踪检查进度和结果。
+
+Sources: [PySSCheck.py](PySSCheck.py#L113-L125)
+
+## 多类型检查结果展示
+
+在实际项目中，常常需要同时执行多种类型的检查，并在一个窗口中统一展示。ShowCheckOutput 方法支持混合显示不同组和检查项的记录。
+
+### 混合检查示例
+
+```python
+from sunvpy.PySSCheck import CheckFunForPY
+from sunvpy import SSProcess
+
+def run_comprehensive_check():
+    """执行综合检查：拓扑+属性"""
+    
+    check_fun = CheckFunForPY()
+    check_fun.ClearCheckRecord()
+    
+    # ===== 检查1: 拓扑重叠 =====
+    SSProcess.clearSelection()
+    SSProcess.clearSelectCondition()
+    SSProcess.setSelectCondition("SSObj_Type", "==", "3")
+    SSProcess.selectFilter()
+    
+    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"))
+        obj_type = int(SSProcess.getSelGeoValue(i, "SSObj_Type"))
+        
+        if i % 10 == 0:  # 模拟重叠检测
+            check_fun.AddCheckRecord(
+                group="拓扑检查",
+                check="重叠检查",
+                checkmodel=1,
+                description=f"对象 {geo_id} 重叠",
+                x=x, y=y, z=0.0,
+                objtype=obj_type,
+                geoids=str(geo_id),
+                noteids=""
+            )
+    
+    # ===== 检查2: 属性完整性 =====
+    SSProcess.clearSelection()
+    SSProcess.clearSelectCondition()
+    SSProcess.setSelectCondition("SSObj_Name", "==", "")
+    SSProcess.selectFilter()
+    
+    count = SSProcess.getSelGeoCount()
+    for i in range(min(20, count)):  # 限制数量
+        geo_id = SSProcess.getSelGeoValue(i, "SSObj_ID")
+        x = float(SSProcess.getSelGeoValue(i, "SSObj_X"))
+        y = float(SSProcess.getSelGeoValue(i, "SSObj_Y"))
+        obj_type = int(SSProcess.getSelGeoValue(i, "SSObj_Type"))
+        
+        check_fun.AddCheckRecord(
+            group="属性检查",
+            check="名称缺失",
+            checkmodel=2,
+            description=f"对象 {geo_id} 缺少名称属性",
+            x=x, y=y, z=0.0,
+            objtype=obj_type,
+            geoids=str(geo_id),
+            noteids=""
+        )
+    
+    # 统计各类问题数量
+    total_count = check_fun.GetCheckRecordCount()
+    print(f"\n检查完成，总计 {total_count} 个问题:")
+    
+    # 按组统计
+    groups = {}
+    for i in range(total_count):
+        fields = "group"
+        values = ""
+        check_fun.GetCheckRecordValue(i, fields, values)
+        
+        if values:
+            group_name = values.strip()
+            groups[group_name] = groups.get(group_name, 0) + 1
+    
+    for group, count in groups.items():
+        print(f"  {group}: {count} 个")
+    
+    # 显示结果
+    if total_count > 0:
+        check_fun.ShowCheckOutput()
+    
+    return total_count
+
+# 执行综合检查
+run_comprehensive_check()
+```
+
+在检查结果窗口中，不同组的记录通常会以分组形式展示，方便用户按问题类型进行分类浏览和定位。
+
+Sources: [PySSCheck.py](PySSCheck.py#L113-L125)
+
+## 显示前的准备工作
+
+在调用 ShowCheckOutput 之前，建议进行以下准备工作，确保显示结果的完整性和准确性。
+
+### 记录数量检查
+
+在显示前检查记录数量，避免显示空窗口：
+
+```python
+# 获取记录数量
+count = check_fun.GetCheckRecordCount()
+
+if count == 0:
+    print("未发现问题，无需显示检查结果")
+else:
+    print(f"发现 {count} 个问题，正在打开检查结果窗口...")
+    check_fun.ShowCheckOutput()
+```
+
+### 记录有效性验证
+
+确保所有记录的字段数据完整，避免显示异常：
+
+```python
+def validate_records(check_fun):
+    """验证检查记录的完整性"""
+    count = check_fun.GetCheckRecordCount()
+    valid_count = 0
+    invalid_count = 0
+    
+    for i in range(count):
+        fields = "group,check,description,x,y,geoids"
+        values = ""
+        
+        check_fun.GetCheckRecordValue(i, fields, values)
+        
+        # 简单验证：values 不应为空
+        if values and "," in values:
+            valid_count += 1
+        else:
+            invalid_count += 1
+            print(f"警告：记录 {i} 数据不完整: {values}")
+    
+    print(f"验证完成：有效记录 {valid_count} 条，无效记录 {invalid_count} 条")
+    return invalid_count == 0
+
+# 使用验证
+if validate_records(check_fun):
+    check_fun.ShowCheckOutput()
+else:
+    print("存在无效记录，建议检查数据后再显示")
+```
+
+### 保存后显示
+
+通常建议先保存检查记录，再显示结果，确保数据不会因系统异常而丢失：
+
+```python
+# 完整流程：保存 → 统计 → 显示
+print("正在保存检查记录...")
+check_fun.SaveCheckRecord()
+
+count = check_fun.GetCheckRecordCount()
+print(f"已保存 {count} 条检查记录")
+
+if count > 0:
+    check_fun.ShowCheckOutput()
+```
+
+Sources: [PySSCheck.py](PySSCheck.py#L108-L125)
+
+## 高级应用场景
+
+### 批量检查后的结果展示
+
+在自动化批量检查场景中，可能需要积累多次检查的结果后统一显示：
+
+```python
+from sunvpy.PySSCheck import CheckFunForPY
+
+def batch_check_and_show(layers):
+    """批量检查多个图层并统一显示结果"""
+    
+    check_fun = CheckFunForPY()
+    check_fun.ClearCheckRecord()
+    
+    total_issues = 0
+    
+    for layer_name in layers:
+        print(f"\n检查图层: {layer_name}")
+        
+        # 执行针对该图层的检查逻辑
+        # ... 检查代码 ...
+        
+        # 模拟：添加一些检查记录
+        check_fun.AddCheckRecord(
+            group="拓扑检查",
+            check="图层检查",
+            checkmodel=1,
+            description=f"图层 {layer_name} 中的问题",
+            x=0.0, y=0.0, z=0.0,
+            objtype=3,
+            geoids="1001",
+            noteids=""
+        )
+        total_issues += 1
+    
+    print(f"\n批量检查完成，共发现 {total_issues} 个问题")
+    
+    # 统一显示所有结果
+    check_fun.ShowCheckOutput()
+
+# 批量检查多个图层
+layers_to_check = ["建筑", "道路", "水系"]
+batch_check_and_show(layers_to_check)
+```
+
+### 历史对比显示
+
+在质量追踪场景中，可以加载历史记录并与当前结果对比：
+
+```python
+from sunvpy.PySSCheck import CheckFunForPY
+
+def compare_and_show_results():
+    """对比历史记录并显示当前结果"""
+    
+    check_fun = CheckFunForPY()
+    
+    # 1. 加载历史记录
+    check_fun.LoadCheckRecord()
+    old_count = check_fun.GetCheckRecordCount()
+    print(f"历史记录: {old_count} 个问题")
+    
+    # 2. 执行新的检查
+    check_fun.ClearCheckRecord()
+    # ... 新的检查逻辑 ...
+    
+    # 模拟：添加新记录
+    check_fun.AddCheckRecord(
+        group="拓扑检查",
+        check="重叠检查",
+        checkmodel=1,
+        description="新的重叠问题",
+        x=0.0, y=0.0, z=0.0,
+        objtype=3,
+        geoids="1001",
+        noteids=""
+    )
+    
+    new_count = check_fun.GetCheckRecordCount()
+    print(f"当前检查: {new_count} 个问题")
+    print(f"质量改进: {old_count - new_count} 个问题已修复")
+    
+    # 3. 显示当前结果
+    check_fun.ShowCheckOutput()
+
+compare_and_show_results()
+```
+
+Sources: [PySSCheck.py](PySSCheck.py#L108-L120)
+
+## 常见问题与解决方案
+
+### 窗口无法显示
+
+如果调用 ShowCheckOutput 后没有弹出窗口，可能的原因和解决方法：
+
+| 原因 | 解决方法 |
+|------|----------|
+| 检查记录为空 | 检查 `GetCheckRecordCount()` 返回值，确保有记录 |
+| 系统界面未初始化 | 确保在 SunvStation 主界面中调用，而非后台脚本 |
+| 窗口已打开 | 检查是否已有检查结果窗口处于打开状态 |
+
+```python
+# 安全显示方案
+def safe_show_output(check_fun):
+    try:
+        count = check_fun.GetCheckRecordCount()
+        if count > 0:
+            print(f"显示 {count} 条检查记录...")
+            check_fun.ShowCheckOutput()
+        else:
+            print("无检查记录可显示")
+    except Exception as e:
+        print(f"显示检查结果失败: {e}")
+
+safe_show_output(check_fun)
+```
+
+### 大量记录显示缓慢
+
+当检查记录数量超过 1000 条时，显示窗口可能加载较慢。建议：
+
+1. **分批显示**：只显示前 100 条，其他通过导出文件查看
+2. **优化描述**：简化 description 字段的内容
+3. **使用保存替代**：对于大量记录，使用 `SaveCheckRecord()` 保存到文件，而非显示窗口
+
+```python
+# 大量记录的处理策略
+def handle_large_results(check_fun, max_display=100):
+    count = check_fun.GetCheckRecordCount()
+    
+    if count > max_display:
+        print(f"记录数量过多 ({count} 条)，将保存到文件")
+        check_fun.SaveCheckRecord()
+        
+        # 只显示前 max_display 条的摘要
+        print(f"\n前 {max_display} 条记录摘要:")
+        for i in range(min(max_display, count)):
+            fields = "group,check,description"
+            values = ""
+            check_fun.GetCheckRecordValue(i, fields, values)
+            print(f"  {values}")
+    else:
+        check_fun.ShowCheckOutput()
+
+handle_large_results(check_fun, max_display=100)
+```
+
+### 空间定位不准确
+
+如果点击记录后地图未正确缩放到问题位置，检查以下几点：
+
+1. **坐标值是否正确**：确保 AddCheckRecord 时传入的 x、y、z 坐标有效
+2. **坐标系统一致性**：检查对象坐标与地图坐标系统是否一致
+3. **对象是否可见**：确认问题对象的图层处于可见状态
+
+```python
+# 确保坐标信息准确
+def get_valid_coordinates(process, geo_index):
+    """获取有效的坐标信息"""
+    try:
+        x = float(process.getSelGeoValue(geo_index, "SSObj_X"))
+        y = float(process.getSelGeoValue(geo_index, "SSObj_Y"))
+        z = float(process.getSelGeoValue(geo_index, "SSObj_Z"))
+        
+        # 验证坐标有效性
+        if abs(x) > 1e10 or abs(y) > 1e10:
+            print(f"警告：坐标值异常 ({x}, {y})，使用默认值")
+            return 0.0, 0.0, 0.0
+        
+        return x, y, z
+    except Exception as e:
+        print(f"获取坐标失败: {e}")
+        return 0.0, 0.0, 0.0
+
+# 使用示例
+x, y, z = get_valid_coordinates(SSProcess, i)
+check_fun.AddCheckRecord(..., x=x, y=y, z=z, ...)
+```
+
+Sources: [PySSCheck.py](PySSCheck.py#L113-L125)
+
+## 最佳实践总结
+
+### 显示时机建议
+
+```mermaid
+flowchart LR
+    A[检查流程开始] --> B[执行检查逻辑]
+    B --> C[调用 AddCheckRecord 记录问题]
+    C --> D{检查完成?}
+    D -->|否| B
+    D -->|是| E[调用 GetCheckRecordCount 统计]
+    E --> F{数量 > 0?}
+    F -->|否| G[输出无问题提示]
+    F -->|是| H[调用 SaveCheckRecord 保存]
+    H --> I[调用 ShowCheckOutput 显示]
+    I --> J[用户交互处理问题]
+    
+    style E fill:#e1f5ff
+    style H fill:#fff4e1
+    style I fill:#d4edda
+```
+
+推荐的标准流程：**检查 → 统计 → 保存 → 显示**
+
+1. 检查完成后统计记录数量
+2. 如有记录，先保存确保数据安全
+3. 最后显示结果窗口供用户交互
+
+### 代码模板
+
+以下是一个推荐的代码模板，适用于大多数检查场景：
+
+```python
+from sunvpy import SSProcess
+from sunvpy.PySSCheck import CheckFunForPY
+
+def standard_check_workflow(check_name, check_logic_func):
+    """标准的检查工作流程模板"""
+    
+    # 1. 初始化
+    check_fun = CheckFunForPY()
+    check_fun.ClearCheckRecord()
+    
+    print(f"开始执行: {check_name}")
+    
+    # 2. 执行检查逻辑
+    try:
+        check_logic_func(check_fun)
+    except Exception as e:
+        print(f"检查执行失败: {e}")
+        return -1
+    
+    # 3. 统计结果
+    count = check_fun.GetCheckRecordCount()
+    print(f"{check_name} 完成，发现 {count} 个问题")
+    
+    # 4. 处理结果
+    if count > 0:
+        # 保存记录
+        print("正在保存检查记录...")
+        try:
+            check_fun.SaveCheckRecord()
+            print("保存成功")
+        except Exception as e:
+            print(f"保存失败: {e}")
+        
+        # 显示结果
+        print("正在打开检查结果窗口...")
+        try:
+            check_fun.ShowCheckOutput()
+        except Exception as e:
+            print(f"显示失败: {e}")
+    else:
+        print("未发现问题，数据质量良好")
+    
+    return count
+
+# 使用示例
+def my_check_logic(check_fun):
+    """自定义检查逻辑"""
+    SSProcess.clearSelection()
+    SSProcess.clearSelectCondition()
+    SSProcess.setSelectCondition("SSObj_Type", "==", "3")
+    SSProcess.selectFilter()
+    
+    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"))
+        obj_type = int(SSProcess.getSelGeoValue(i, "SSObj_Type"))
+        
+        # ... 实际检查逻辑 ...
+        
+        # 示例：记录问题
+        check_fun.AddCheckRecord(
+            group="示例检查",
+            check="示例项",
+            checkmodel=1,
+            description=f"示例问题 {geo_id}",
+            x=x, y=y, z=0.0,
+            objtype=obj_type,
+            geoids=str(geo_id),
+            noteids=""
+        )
+
+# 执行检查
+standard_check_workflow("示例拓扑检查", my_check_logic)
+```
+
+该模板封装了完整的检查流程，包括错误处理和日志输出，可作为各种检查脚本的基础框架。
+
+Sources: [PySSCheck.py](PySSCheck.py#L108-L125)
+
+## 学习路径建议
+
+掌握显示检查结果功能后，建议按照以下路径继续深入学习：
+
+1. **[添加与加载检查记录](31-tian-jia-yu-jia-zai-jian-cha-ji-lu)** - 深入了解检查记录的添加、加载和持久化机制，掌握记录的生命周期管理
+2. **[自定义检查规则](33-zi-ding-yi-jian-cha-gui-ze)** - 学习如何构建复杂的数据检查逻辑，自定义检查规则以适应特定的业务需求
+3. **[清除与初始化选择集](11-qing-chu-yu-chu-shi-hua-xuan-ze-ji)** - 了解如何高效地设置和操作选择集，为数据检查提供准确的数据范围
+
+通过系统学习这些内容，您将能够构建完整的数据质量控制和问题追踪系统，实现从检查发现、问题定位到修复验证的闭环管理。