# 链接状态接口测试文档

## 接口概览

新增了三个接口用于前端获取链接状态信息：

1. **获取链接状态** - `GET /api/link/{codeNo}/status`
2. **检查链接是否存在** - `GET /api/link/{codeNo}/exists`
3. **检查链接是否有效** - `GET /api/link/{codeNo}/valid`

## 测试步骤

### 1. 准备工作

首先需要生成一个链接用于测试：

```bash
# 1. 登录获取JWT令牌
curl -X POST http://localhost:18080/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your_username",
    "password": "your_password"
  }'
```

从响应中获取JWT令牌，后续请求都需要在Header中带上：
```bash
Authorization: Bearer eyJhbGciOiJIUzI1NiJ9...
```

### 2. 生成测试链接

```bash
# 2. 生成链接
curl -X POST http://localhost:18080/api/link/generate \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "times": 5,
    "linkCount": 2
  }'
```

响应示例：
```json
{
    "batchId": 123,
    "deductPoints": 250,
    "expireAt": "2024-01-15T16:30:00",
    "codeNos": ["ABC12345", "DEF67890"]
}
```

记录其中一个 `codeNo`，比如 `ABC12345`，用于后续测试。

### 3. 测试获取链接状态接口

```bash
# 3. 获取链接状态
curl -X GET http://localhost:18080/api/link/ABC12345/status \
  -H "Accept: application/json"
```

**预期响应：**
```json
{
    "codeNo": "ABC12345",
    "batchId": 123,
    "status": "NEW",
    "statusDesc": "新建",
    "expireAt": "2024-01-15T16:30:00",
    "isExpired": false,
    "remainingSeconds": 7200,
    "quantity": 50,
    "times": 5,
    "totalPoints": 250,
    "region": null,
    "machineId": null,
    "loginAt": null,
    "createdAt": "2024-01-15T12:00:00",
    "updatedAt": "2024-01-15T12:00:00"
}
```

### 4. 测试检查链接是否存在接口

```bash
# 4. 检查链接是否存在
curl -X GET http://localhost:18080/api/link/ABC12345/exists \
  -H "Accept: application/json"
```

**预期响应：** `true`

### 5. 测试检查链接是否有效接口

```bash
# 5. 检查链接是否有效
curl -X GET http://localhost:18080/api/link/ABC12345/valid \
  -H "Accept: application/json"
```

**预期响应：** `true`

### 6. 测试错误情况

#### 6.1 测试不存在的链接

```bash
# 测试不存在的链接
curl -X GET http://localhost:18080/api/link/INVALID123/status \
  -H "Accept: application/json"
```

**预期响应：**
```json
{
    "timestamp": "2024-01-15T12:00:00.000+00:00",
    "status": 400,
    "error": "Bad Request",
    "message": "链接不存在: INVALID123",
    "path": "/api/link/INVALID123/status"
}
```

#### 6.2 测试空链接编号

```bash
# 测试空链接编号
curl -X GET http://localhost:18080/api/link//status \
  -H "Accept: application/json"
```

**预期响应：** 404 Not Found

## 状态值说明

### 链接状态 (status)
- `NEW` - 新建，未开始使用
- `USING` - 使用中，正在执行任务
- `LOGGED_IN` - 已登录，任务完成
- `REFUNDED` - 已退款
- `EXPIRED` - 已过期

### 区域 (region)
- `Q` - Q区
- `V` - V区
- `null` - 未分配区域

## 测试数据验证

### 1. 数值计算验证
- `totalPoints` = `quantity` × `times`
- `remainingSeconds` 应该大于0（如果未过期）
- `isExpired` 应该与当前时间和 `expireAt` 一致

### 2. 状态一致性验证
- 如果 `status` 是 `EXPIRED`，那么 `isExpired` 应该是 `true`
- 如果 `status` 是 `LOGGED_IN`，那么 `loginAt` 不应该为 `null`

### 3. 时间验证
- `createdAt` ≤ `updatedAt`
- `expireAt` > `createdAt`
- 如果 `loginAt` 不为空，那么 `loginAt` ≥ `createdAt`

## 性能测试

### 1. 响应时间测试
```bash
# 使用time命令测试响应时间
time curl -X GET http://localhost:18080/api/link/ABC12345/status
```

### 2. 并发测试
```bash
# 使用ab工具进行并发测试
ab -n 100 -c 10 http://localhost:18080/api/link/ABC12345/status
```

## 错误处理测试

### 1. 数据库连接异常
模拟数据库连接失败的情况，验证错误处理。

### 2. 网络超时
模拟网络延迟，验证超时处理。

### 3. 内存不足
模拟内存不足情况，验证系统稳定性。

## 安全测试

### 1. 权限验证
```bash
# 不带JWT令牌访问（应该被拦截）
curl -X GET http://localhost:18080/api/link/ABC12345/status
```

### 2. SQL注入防护
```bash
# 测试SQL注入
curl -X GET "http://localhost:18080/api/link/ABC12345'; DROP TABLE link_task; --/status"
```

### 3. XSS防护
```bash
# 测试XSS攻击
curl -X GET "http://localhost:18080/api/link/<script>alert('xss')</script>/status"
```

## 测试报告模板

### 测试结果记录

| 测试项目 | 测试结果 | 响应时间 | 备注 |
|---------|---------|---------|------|
| 获取链接状态 | ✅ 通过 | 45ms | 正常 |
| 检查链接存在 | ✅ 通过 | 23ms | 正常 |
| 检查链接有效 | ✅ 通过 | 28ms | 正常 |
| 错误处理 | ✅ 通过 | 15ms | 正常 |
| 性能测试 | ✅ 通过 | 平均35ms | 满足要求 |

### 问题记录

| 问题描述 | 严重程度 | 状态 | 备注 |
|---------|---------|------|------|
| 无 | - | - | - |

### 建议改进

1. 可以考虑添加缓存机制，减少数据库查询
2. 可以添加链接访问统计功能
3. 可以考虑添加链接状态变更通知功能

## 自动化测试

### 使用Postman Collection

可以创建Postman Collection来自动化测试这些接口：

1. 创建环境变量存储JWT令牌和链接编号
2. 设置测试脚本验证响应数据
3. 使用Postman Runner批量执行测试

### 使用JUnit测试

```java
@SpringBootTest
@AutoConfigureTestDatabase
class LinkStatusControllerTest {
    
    @Test
    void testGetLinkStatus() {
        // 测试获取链接状态
    }
    
    @Test
    void testLinkNotExists() {
        // 测试链接不存在的情况
    }
}
```

## 总结

这些接口为前端提供了完整的链接状态查询功能，支持：

1. **完整的状态信息** - 包括任务详情、过期时间、奖励点数等
2. **实时状态计算** - 自动计算是否过期、剩余时间等
3. **友好的错误处理** - 提供清晰的错误信息和状态码
4. **高性能查询** - 使用响应式编程，支持高并发访问

前端可以根据这些接口实现丰富的用户界面，提供良好的用户体验。