add 真实well数据覆盖

2025-08-19 17:03:32 +08:00
parent fc2b64ccc4
commit 4875a68f1c
10 changed files with 950 additions and 8 deletions
@@ -0,0 +1,253 @@
+# DMS分页功能 - 单页模式使用指南
+
+## 🎯 问题解决
+
+您遇到的问题是：设置 `page_size=1` 时，系统仍然会获取所有页面的数据，而不是只获取第1页的1条记录。
+
+**原因**: 原来的逻辑是用指定的分页大小去获取**所有可用的数据**，这是为了完整测试设计的。
+
+**解决方案**: 新增 `fetch_all_pages` 参数来控制获取模式。
+
+## 🔧 新增参数
+
+### `fetch_all_pages` 参数
+
+- **类型**: `boolean`
+- **默认值**: `true`
+- **作用**: 控制分页获取模式
+
+| 值 | 模式 | 行为 |
+|---|------|------|
+| `true` | 全页模式 | 用指定分页大小获取所有数据（原行为） |
+| `false` | 单页模式 | 只获取指定页面的数据 |
+
+## 📊 使用场景对比
+
+### 1. 单页模式 (`fetch_all_pages=false`)
+
+**适用场景**:
+- 快速测试少量API
+- 内存受限环境
+- 断点续传
+- 分批处理大数据集
+
+**示例**: 只获取第3页的5条记录
+```json
+{
+  "page_size": 5,
+  "page_no": 3,
+  "fetch_all_pages": false
+}
+```
+
+**结果**: 只会发送1个请求，获取5条记录
+
+### 2. 全页模式 (`fetch_all_pages=true`)
+
+**适用场景**:
+- 完整的合规性测试
+- 生成完整报告
+- 一次性处理所有API
+
+**示例**: 用1000的分页大小获取所有数据
+```json
+{
+  "page_size": 1000,
+  "page_no": 1,
+  "fetch_all_pages": true
+}
+```
+
+**结果**: 会发送多个请求，直到获取所有数据
+
+## 🚀 使用方法
+
+### 1. 命令行工具
+
+**单页模式**:
+```bash
+python run_api_tests.py \
+  --dms ./assets/doc/dms/domain.json \
+  --base-url https://www.dev.ideas.cnpc \
+  --page-size 5 \
+  --page-no 3 \
+  --fetch-single-page \
+  --ignore-ssl
+```
+
+**全页模式**:
+```bash
+python run_api_tests.py \
+  --dms ./assets/doc/dms/domain.json \
+  --base-url https://www.dev.ideas.cnpc \
+  --page-size 1000 \
+  --page-no 1 \
+  --ignore-ssl
+```
+
+### 2. FastAPI服务器
+
+**单页模式**:
+```bash
+curl -X POST http://localhost:5051/run \
+  -H "Content-Type: application/json" \
+  -d '{
+    "dms": "./assets/doc/dms/domain.json",
+    "base_url": "https://www.dev.ideas.cnpc",
+    "page_size": 5,
+    "page_no": 3,
+    "fetch_all_pages": false,
+    "ignore_ssl": true
+  }'
+```
+
+**全页模式**:
+```bash
+curl -X POST http://localhost:5051/run \
+  -H "Content-Type: application/json" \
+  -d '{
+    "dms": "./assets/doc/dms/domain.json",
+    "base_url": "https://www.dev.ideas.cnpc",
+    "page_size": 1000,
+    "page_no": 1,
+    "fetch_all_pages": true,
+    "ignore_ssl": true
+  }'
+```
+
+## 📈 日志输出对比
+
+### 单页模式日志
+```
+Fetching SINGLE page (page_size=5, page_no=3)
+Fetching page 3 from: https://api.example.com/schema?pageNo=3&pageSize=5
+Fetched 5 records from page 3, total: 5
+Single page mode: fetched 5 records from page 3
+```
+
+### 全页模式日志
+```
+Fetching ALL API pages with pagination (page_size=1000, starting from page 1)
+Fetching page 1 from: https://api.example.com/schema?pageNo=1&pageSize=1000
+Fetched 1000 records from page 1, total: 1000
+Fetching page 2 from: https://api.example.com/schema?pageNo=2&pageSize=1000
+Fetched 523 records from page 2, total: 1523
+Reached end of data. Total records: 1523
+```
+
+## 🔍 分页信息返回
+
+### 单页模式返回
+```json
+{
+  "pagination": {
+    "page_size": 5,
+    "page_no_start": 3,
+    "total_pages": 0,
+    "total_records": 0,
+    "pages_fetched": 1,
+    "current_page": 3,
+    "fetch_all_pages": false
+  }
+}
+```
+
+### 全页模式返回
+```json
+{
+  "pagination": {
+    "page_size": 1000,
+    "page_no_start": 1,
+    "total_pages": 2,
+    "total_records": 1523,
+    "pages_fetched": 2,
+    "current_page": 2,
+    "fetch_all_pages": true
+  }
+}
+```
+
+## 💡 实际应用示例
+
+### 场景1: 快速验证系统
+```bash
+# 只测试前5个API
+python run_api_tests.py \
+  --dms ./domain.json \
+  --base-url https://api.test.com \
+  --page-size 5 \
+  --page-no 1 \
+  --fetch-single-page
+```
+
+### 场景2: 内存受限环境分批处理
+```bash
+# 第一批：处理第1-50个API
+python run_api_tests.py \
+  --dms ./domain.json \
+  --base-url https://api.test.com \
+  --page-size 50 \
+  --page-no 1 \
+  --fetch-single-page
+
+# 第二批：处理第51-100个API
+python run_api_tests.py \
+  --dms ./domain.json \
+  --base-url https://api.test.com \
+  --page-size 50 \
+  --page-no 2 \
+  --fetch-single-page
+```
+
+### 场景3: 断点续传
+```bash
+# 从第10页继续（假设前面已经处理了9页）
+python run_api_tests.py \
+  --dms ./domain.json \
+  --base-url https://api.test.com \
+  --page-size 100 \
+  --page-no 10 \
+  --fetch-single-page
+```
+
+### 场景4: 完整测试
+```bash
+# 一次性测试所有API
+python run_api_tests.py \
+  --dms ./domain.json \
+  --base-url https://api.test.com \
+  --page-size 1000 \
+  --page-no 1
+  # 不加 --fetch-single-page，默认为全页模式
+```
+
+## 🧪 测试验证
+
+运行测试脚本验证功能：
+```bash
+python test_single_page.py
+```
+
+测试内容：
+1. 单页模式 - 只获取第1页的1条记录
+2. 单页模式 - 获取第3页的5条记录  
+3. 全页模式对比 - 获取所有数据
+
+## 📝 总结
+
+现在您可以：
+
+1. **精确控制数据获取**
+   - 单页模式：只获取指定页面
+   - 全页模式：获取所有数据
+
+2. **灵活的使用场景**
+   - 快速测试：`page_size=5, fetch_all_pages=false`
+   - 分批处理：`page_size=50, page_no=N, fetch_all_pages=false`
+   - 完整测试：`page_size=1000, fetch_all_pages=true`
+
+3. **清晰的日志反馈**
+   - 明确显示当前模式
+   - 详细的分页统计信息
+
+这样就完全解决了您遇到的问题：当您设置 `page_size=1` 和 `fetch_all_pages=false` 时，系统只会获取第1页的1条记录，而不会继续获取后续页面！
@@ -0,0 +1,224 @@
+# 井数据集成指南
+
+## 🎯 概述
+
+本文档介绍了DMS合规性测试工具中新增的井数据集成功能。该功能能够在测试开始前自动获取真实的井和井筒数据，并在测试过程中使用这些真实值替换模拟数据，确保测试的准确性和真实性。
+
+## 🔧 功能特性
+
+### 核心功能
+- **自动数据获取**: 在测试开始前从指定API获取真实的井和井筒数据
+- **智能字段识别**: 自动识别井相关字段（wellId、wellboreId、wellCommonName等）
+- **数据增强**: 在生成测试数据时自动使用真实值替换模拟值
+- **缓存机制**: 缓存获取的数据，避免重复请求
+- **错误处理**: 当井数据获取失败时，自动回退到模拟数据
+
+### 支持的字段
+- `wellId` / `well_id` - 井ID
+- `wellboreId` / `wellbore_id` - 井筒ID  
+- `wellCommonName` / `well_common_name` - 井通用名称
+- `wellboreCommonName` / `wellbore_common_name` - 井筒通用名称
+
+## 🏗️ 架构设计
+
+### 组件结构
+```
+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. **测试执行流程**: 在测试开始前初始化井数据
+
+## 🚀 使用方法
+
+### 自动使用（推荐）
+井数据功能默认启用，无需额外配置：
+
+```bash
+# 命令行使用
+python run_api_tests.py \
+  --dms ./assets/doc/dms/domain.json \
+  --base-url https://www.dev.ideas.cnpc \
+  --ignore-ssl
+
+# Web界面使用
+# 通过Web界面上传DMS配置文件即可自动使用
+```
+
+### 手动控制
+可以通过配置参数控制井数据功能：
+
+```python
+# 在代码中禁用井数据功能
+orchestrator = APITestOrchestrator(
+    base_url="https://www.dev.ideas.cnpc",
+    enable_well_data=False  # 禁用井数据功能
+)
+```
+
+### API端点配置
+井数据管理器使用以下API端点获取数据：
+
+```python
+# 井基本信息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. 初始化阶段
+```mermaid
+graph TD
+    A[测试开始] --> B[创建井数据管理器]
+    B --> C[调用井数据API]
+    C --> D{API调用成功?}
+    D -->|是| E[缓存井数据]
+    D -->|否| F[记录警告，使用模拟数据]
+    E --> G[开始测试执行]
+    F --> G
+```
+
+### 2. 数据生成阶段
+```mermaid
+graph TD
+    A[生成测试数据] --> B{是否为井相关字段?}
+    B -->|是| C[从井数据缓存获取真实值]
+    B -->|否| D[使用原有生成逻辑]
+    C --> E{获取成功?}
+    E -->|是| F[使用真实值]
+    E -->|否| G[使用模拟值]
+    D --> H[返回生成的数据]
+    F --> H
+    G --> H
+```
+
+## 🧪 测试验证
+
+### 运行测试脚本
+```bash
+# 测试井数据管理器功能
+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和名称：
+
+```json
+{
+  "request_body": {
+    "wellId": "HB00019975",  // 真实井ID
+    "wellCommonName": "郑4-106",  // 真实井名称
+    "wellboreId": "WEBHHB100083169"  // 真实井筒ID
+  }
+}
+```
+
+## 🔍 故障排除
+
+### 常见问题
+
+#### 1. 井数据获取失败
+**症状**: 日志显示"井数据初始化失败"
+**原因**: 
+- 网络连接问题
+- API端点不可访问
+- SSL证书验证失败
+
+**解决方案**:
+```bash
+# 确保使用--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端点
+
+### 扩展示例
+```python
+# 未来可能的配置方式
+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合规性测试工具提供了更真实、更准确的测试数据支持。通过自动获取和使用真实的井相关数据，显著提高了测试的可靠性和业务相关性。该功能设计为自动启用，对现有测试流程影响最小，同时提供了灵活的配置选项以满足不同的测试需求。