compliance/docs/Well_Data_Integration_Guide.md

井数据集成指南

🎯 概述

本文档介绍了DMS合规性测试工具中新增的井数据集成功能。该功能能够在测试开始前自动获取真实的井和井筒数据，并在测试过程中使用这些真实值替换模拟数据，确保测试的准确性和真实性。

🔧 功能特性

核心功能

• 自动数据获取: 在测试开始前从指定API获取真实的井和井筒数据
• 智能字段识别: 自动识别井相关字段（wellId、wellboreId、wellCommonName等）
• 数据增强: 在生成测试数据时自动使用真实值替换模拟值
• 缓存机制: 缓存获取的数据，避免重复请求
• 错误处理: 当井数据获取失败时，自动回退到模拟数据

支持的字段

• wellId - 井ID（严格匹配字段名）
• wellboreId - 井筒ID（严格匹配字段名）
• wellCommonName - 井通用名称（严格匹配字段名）

注意: 字段名称严格按照DMS接口规范，不支持变体命名（如well_id、WELL_ID等）

🏗️ 架构设计

组件结构

WellDataManager (井数据管理器)
├── 数据获取模块
│   ├── fetch_well_data() - 获取井基本信息
│   └── fetch_wellbore_data() - 获取井筒基本信息
├── 数据缓存模块
│   ├── well_data[] - 井数据缓存
│   └── wellbore_data[] - 井筒数据缓存
└── 数据增强模块
    ├── is_well_related_field() - 字段识别
    ├── get_well_value_for_field() - 值获取
    └── enhance_data_with_well_values() - 数据增强

集成点

1. APITestOrchestrator: 在初始化时创建井数据管理器
2. DataGenerator: 在生成测试数据时使用井数据增强
3. 测试执行流程: 在测试开始前初始化井数据

🚀 使用方法

自动使用（推荐）

井数据功能默认启用，无需额外配置：

# 命令行使用
python run_api_tests.py \
  --dms ./assets/doc/dms/domain.json \
  --base-url https://www.dev.ideas.cnpc \
  --ignore-ssl

# Web界面使用
# 通过Web界面上传DMS配置文件即可自动使用

手动控制

可以通过配置参数控制井数据功能：

# 在代码中禁用井数据功能
orchestrator = APITestOrchestrator(
    base_url="https://www.dev.ideas.cnpc",
    enable_well_data=False  # 禁用井数据功能
)

API端点配置

井数据管理器使用以下API端点获取数据：

# 井基本信息API
POST /api/dms/well_kd_wellbore_ideas01/v1/cd_well/1.0.0
Content-Type: application/json
Body: {}

# 井筒基本信息API  
POST /api/dms/well_kd_wellbore_ideas01/v1/cd_wellbore/1.0.0
Content-Type: application/json
Body: {}

📊 工作流程

1. 初始化阶段

graph TD
    A[测试开始] --> B[创建井数据管理器]
    B --> C[调用井数据API]
    C --> D{API调用成功?}
    D -->|是| E[缓存井数据]
    D -->|否| F[记录警告，使用模拟数据]
    E --> G[开始测试执行]
    F --> G

2. 数据生成阶段

graph TD
    A[生成测试数据] --> B{是否为井相关字段?}
    B -->|是| C[从井数据缓存获取真实值]
    B -->|否| D[使用原有生成逻辑]
    C --> E{获取成功?}
    E -->|是| F[使用真实值]
    E -->|否| G[使用模拟值]
    D --> H[返回生成的数据]
    F --> H
    G --> H

🧪 测试验证

运行测试脚本

# 测试井数据管理器功能
python test_well_data_manager.py

预期输出

2025-08-19 10:00:00 - INFO - 开始测试井数据管理器...
2025-08-19 10:00:01 - INFO - 成功获取 43078 条井基本信息数据
2025-08-19 10:00:02 - INFO - 成功获取 18015 条井筒基本信息数据
2025-08-19 10:00:02 - INFO - ✅ 井数据初始化成功
2025-08-19 10:00:02 - INFO - 📊 井数据摘要: {'well_count': 43078, 'wellbore_count': 18015, ...}

验证真实数据使用

在测试报告中查看API调用详情，确认使用了真实的井ID和名称：

{
  "request_body": {
    "wellId": "HB00019975",  // 真实井ID
    "wellCommonName": "郑4-106",  // 真实井名称
    "wellboreId": "WEBHHB100083169"  // 真实井筒ID
  }
}

🔍 故障排除

常见问题

1. 井数据获取失败

症状: 日志显示"井数据初始化失败" 原因:

• 网络连接问题
• API端点不可访问
• SSL证书验证失败

解决方案:

# 确保使用--ignore-ssl参数
python run_api_tests.py --dms ./assets/doc/dms/domain.json --ignore-ssl

# 检查网络连接
curl -k -X POST https://www.dev.ideas.cnpc/api/dms/well_kd_wellbore_ideas01/v1/cd_well/1.0.0

2. 井数据未被使用

症状: 测试仍使用模拟数据 原因:

• 井数据管理器未正确初始化
• 字段名称不匹配

解决方案:

• 检查日志中的井数据初始化信息
• 确认字段名称符合支持的格式

3. 性能问题

症状: 测试启动缓慢 原因: 井数据获取耗时较长

解决方案:

• 井数据只在测试开始时获取一次
• 考虑实现数据缓存到文件

📈 性能影响

初始化开销

• 井数据获取: ~2-5秒（取决于网络状况）
• 内存占用: ~10-20MB（缓存数据）
• 后续测试: 无额外开销

优化建议

1. 网络优化: 确保测试环境与DMS服务网络连接良好
2. 缓存策略: 未来可考虑将井数据缓存到本地文件
3. 按需加载: 可根据测试需求选择性获取井数据

🔮 未来扩展

计划功能

1. 数据缓存持久化: 将井数据缓存到本地文件，减少重复获取
2. 更多字段支持: 支持更多井相关字段的真实数据替换
3. 数据验证: 增加井数据的有效性验证
4. 配置化: 支持通过配置文件自定义井数据API端点

扩展示例

# 未来可能的配置方式
well_config = {
    "endpoints": {
        "well": "/api/dms/well_kd_wellbore_ideas01/v1/cd_well/1.0.0",
        "wellbore": "/api/dms/well_kd_wellbore_ideas01/v1/cd_wellbore/1.0.0"
    },
    "cache": {
        "enabled": True,
        "file_path": "./well_data_cache.json",
        "ttl": 3600  # 缓存有效期（秒）
    },
    "fields": {
        "well_id_fields": ["wellId", "well_id", "WELL_ID"],
        "well_name_fields": ["wellCommonName", "well_name", "WELL_NAME"]
    }
}

📝 总结

井数据集成功能为DMS合规性测试工具提供了更真实、更准确的测试数据支持。通过自动获取和使用真实的井相关数据，显著提高了测试的可靠性和业务相关性。该功能设计为自动启用，对现有测试流程影响最小，同时提供了灵活的配置选项以满足不同的测试需求。