# 链接列表接口测试文档

## 接口概览

**接口地址**: `GET /api/link/list`

**功能描述**: 分页查询用户生成的链接列表，支持按状态、批次ID等条件过滤和排序

## 请求参数

### URL参数

| 参数名 | 类型 | 必填 | 默认值 | 说明 | 示例 |
|-------|------|------|--------|------|------|
| page | Integer | 否 | 1 | 页码，从1开始 | 1 |
| pageSize | Integer | 否 | 20 | 每页大小（1-100） | 20 |
| status | String | 否 | - | 链接状态过滤 | NEW |
| batchId | Long | 否 | - | 批次ID过滤 | 123 |
| isExpired | Boolean | 否 | - | 是否过期过滤 | false |
| sortBy | String | 否 | createdAt | 排序字段 | createdAt |
| sortDir | String | 否 | DESC | 排序方向 | DESC |

### 状态值说明

- `NEW` - 新建
- `USING` - 使用中
- `LOGGED_IN` - 已登录
- `REFUNDED` - 已退款
- `EXPIRED` - 已过期

### 排序字段说明

- `createdAt` - 创建时间
- `updatedAt` - 更新时间
- `expireAt` - 过期时间

## 响应格式

```json
{
    "items": [
        {
            "codeNo": "ABC12345",
            "batchId": 123,
            "status": "NEW",
            "statusDesc": "新建",
            "expireAt": "2024-01-15 16:30:00",
            "isExpired": false,
            "remainingSeconds": 7200,
            "quantity": 50,
            "times": 5,
            "totalPoints": 250,
            "region": null,
            "machineId": null,
            "loginAt": null,
            "createdAt": "2024-01-15 12:00:00",
            "updatedAt": "2024-01-15 12:00:00"
        }
    ],
    "total": 150,
    "page": 1,
    "pageSize": 20,
    "totalPages": 8,
    "hasNext": true,
    "hasPrev": false
}
```

## 测试用例

### 1. 基本分页查询

```bash
# 查询第一页，每页20条
curl -X GET "http://localhost:18080/api/link/list?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"
```

**预期结果**:
- 返回最新的20条链接记录
- 按创建时间倒序排列
- 包含完整的分页信息

### 2. 按状态过滤

```bash
# 查询所有新建状态的链接
curl -X GET "http://localhost:18080/api/link/list?status=NEW" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"
```

**预期结果**:
- 只返回状态为NEW的链接
- 其他字段正常显示

### 3. 按批次ID过滤

```bash
# 查询指定批次的所有链接
curl -X GET "http://localhost:18080/api/link/list?batchId=123" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"
```

**预期结果**:
- 只返回指定批次的链接
- 显示该批次的所有链接状态

### 4. 按过期状态过滤

```bash
# 查询未过期的链接
curl -X GET "http://localhost:18080/api/link/list?isExpired=false" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

# 查询已过期的链接
curl -X GET "http://localhost:18080/api/link/list?isExpired=true" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"
```

**预期结果**:
- isExpired=false: 只返回未过期的链接
- isExpired=true: 只返回已过期的链接

### 5. 排序测试

```bash
# 按过期时间升序排列
curl -X GET "http://localhost:18080/api/link/list?sortBy=expireAt&sortDir=ASC" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

# 按更新时间降序排列
curl -X GET "http://localhost:18080/api/link/list?sortBy=updatedAt&sortDir=DESC" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"
```

**预期结果**:
- 按指定字段和方向正确排序
- 数据顺序符合预期

### 6. 组合条件查询

```bash
# 查询未过期的新建状态链接，按过期时间升序
curl -X GET "http://localhost:18080/api/link/list?status=NEW&isExpired=false&sortBy=expireAt&sortDir=ASC&page=1&pageSize=10" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"
```

**预期结果**:
- 同时满足多个条件的链接
- 正确的排序和分页

### 7. 大页码测试

```bash
# 查询第100页
curl -X GET "http://localhost:18080/api/link/list?page=100&pageSize=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"
```

**预期结果**:
- 如果数据不足，返回空数组
- 分页信息正确显示

### 8. 边界值测试

```bash
# 最小页码和页大小
curl -X GET "http://localhost:18080/api/link/list?page=1&pageSize=1" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

# 最大页大小
curl -X GET "http://localhost:18080/api/link/list?page=1&pageSize=100" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"
```

**预期结果**:
- pageSize=1: 只返回1条记录
- pageSize=100: 返回最多100条记录

## 错误测试

### 1. 无效参数测试

```bash
# 无效的页码
curl -X GET "http://localhost:18080/api/link/list?page=0" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

# 页大小超出限制
curl -X GET "http://localhost:18080/api/link/list?pageSize=101" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

# 无效的排序字段
curl -X GET "http://localhost:18080/api/link/list?sortBy=invalidField" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"

# 无效的排序方向
curl -X GET "http://localhost:18080/api/link/list?sortDir=INVALID" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"
```

**预期结果**:
- 参数验证失败，返回400错误
- 或者使用默认值处理

### 2. 认证失败测试

```bash
# 无JWT令牌
curl -X GET "http://localhost:18080/api/link/list" \
  -H "Accept: application/json"

# 无效JWT令牌
curl -X GET "http://localhost:18080/api/link/list" \
  -H "Authorization: Bearer INVALID_TOKEN" \
  -H "Accept: application/json"
```

**预期结果**:
- 返回401未授权错误
- 不返回任何数据

## 性能测试

### 1. 响应时间测试

```bash
# 测试响应时间
time curl -X GET "http://localhost:18080/api/link/list?page=1&pageSize=20" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Accept: application/json"
```

**性能要求**:
- 响应时间 < 100ms（正常数据量）
- 响应时间 < 500ms（大数据量）

### 2. 并发测试

```bash
# 使用ab工具进行并发测试
ab -n 100 -c 10 -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  "http://localhost:18080/api/link/list?page=1&pageSize=20"
```

**性能要求**:
- 支持至少10个并发用户
- 无明显性能衰减

## 数据验证

### 1. 分页计算验证

检查以下字段的计算是否正确：
- `totalPages` = Math.ceil(total / pageSize)
- `hasNext` = (page * pageSize < total)
- `hasPrev` = (page > 1)

### 2. 时间计算验证

检查以下时间字段：
- `isExpired` 与当前时间和 `expireAt` 的比较
- `remainingSeconds` 的计算精度
- 时间格式是否正确

### 3. 数据一致性验证

- 批次信息与链接任务的关联是否正确
- `totalPoints` = `quantity` × `times`
- 状态描述与状态码的对应关系

## 测试数据准备

### 1. 创建测试批次

```bash
# 生成多个批次的链接用于测试
curl -X POST http://localhost:18080/api/link/generate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "times": 5,
    "linkCount": 10
  }'
```

### 2. 模拟不同状态

为了测试过滤功能，需要有不同状态的链接：
- 保持一些链接为NEW状态
- 将一些链接设置为USING状态
- 让一些链接过期（修改expire_at时间）

## 自动化测试脚本

### JavaScript (Node.js)

```javascript
const axios = require('axios');

async function testLinkList() {
    const baseURL = 'http://localhost:18080';
    const token = 'YOUR_JWT_TOKEN';
    
    const config = {
        headers: {
            'Authorization': `Bearer ${token}`,
            'Accept': 'application/json'
        }
    };
    
    try {
        // 测试基本分页
        console.log('测试基本分页...');
        const response = await axios.get(`${baseURL}/api/link/list?page=1&pageSize=5`, config);
        console.log('响应:', response.data);
        
        // 验证分页信息
        const { total, page, pageSize, totalPages, hasNext, hasPrev } = response.data;
        console.log(`总数: ${total}, 当前页: ${page}, 总页数: ${totalPages}`);
        console.log(`有下一页: ${hasNext}, 有上一页: ${hasPrev}`);
        
        // 测试状态过滤
        console.log('测试状态过滤...');
        const statusResponse = await axios.get(`${baseURL}/api/link/list?status=NEW`, config);
        console.log('NEW状态链接数:', statusResponse.data.items.length);
        
    } catch (error) {
        console.error('测试失败:', error.response?.data || error.message);
    }
}

testLinkList();
```

### Python

```python
import requests
import json

def test_link_list():
    base_url = 'http://localhost:18080'
    token = 'YOUR_JWT_TOKEN'
    
    headers = {
        'Authorization': f'Bearer {token}',
        'Accept': 'application/json'
    }
    
    try:
        # 测试基本分页
        print('测试基本分页...')
        response = requests.get(f'{base_url}/api/link/list?page=1&pageSize=5', headers=headers)
        response.raise_for_status()
        
        data = response.json()
        print(f'总数: {data["total"]}, 当前页: {data["page"]}, 总页数: {data["totalPages"]}')
        
        # 测试状态过滤
        print('测试状态过滤...')
        status_response = requests.get(f'{base_url}/api/link/list?status=NEW', headers=headers)
        status_response.raise_for_status()
        
        print(f'NEW状态链接数: {len(status_response.json()["items"])}')
        
    except requests.exceptions.RequestException as e:
        print(f'测试失败: {e}')

if __name__ == '__main__':
    test_link_list()
```

## 测试报告模板

| 测试项目 | 测试结果 | 响应时间 | 备注 |
|---------|---------|---------|------|
| 基本分页查询 | ✅ 通过 | 45ms | 正常 |
| 状态过滤 | ✅ 通过 | 38ms | 正常 |
| 批次ID过滤 | ✅ 通过 | 42ms | 正常 |
| 过期状态过滤 | ✅ 通过 | 40ms | 正常 |
| 排序功能 | ✅ 通过 | 46ms | 正常 |
| 组合条件查询 | ✅ 通过 | 52ms | 正常 |
| 参数验证 | ✅ 通过 | 15ms | 正常 |
| 认证检查 | ✅ 通过 | 12ms | 正常 |
| 性能测试 | ✅ 通过 | 平均43ms | 满足要求 |

## 总结

链接列表接口提供了完整的分页查询功能，支持：

1. **灵活的分页** - 支持自定义页码和页大小
2. **多条件过滤** - 按状态、批次、过期状态等过滤
3. **多字段排序** - 支持按创建时间、更新时间、过期时间排序
4. **丰富的数据** - 包含链接状态、奖励信息、时间信息等
5. **良好的性能** - 使用数据库索引，支持高并发查询
6. **完善的错误处理** - 参数验证、认证检查等

该接口为前端提供了完整的链接管理功能，用户可以方便地查看和管理自己生成的所有链接。
