compliance/docs/Single_Page_Mode_Guide.md

# 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条记录，而不会继续获取后续页面！