AIGC/demo/POLLING_QUERY_IMPLEMENTATION.md

# 轮询查询功能实现说明

## 概述
系统已实现每2分钟执行一次的轮询查询功能，用于检查任务状态并更新完成/失败状态。

## 实现组件

### 1. 定时任务服务

#### TaskStatusPollingService.java
- **功能**: 每2分钟轮询查询任务状态
- **注解**: `@Scheduled(fixedRate = 120000)` (2分钟 = 120000毫秒)
- **方法**: `pollTaskStatuses()`
- **功能**:
  - 查找需要轮询的任务
  - 调用外部API查询状态
  - 更新任务状态（完成/失败/处理中）
  - 处理超时任务

#### TaskQueueScheduler.java
- **功能**: 任务队列调度器
- **注解**: `@Scheduled(fixedRate = 120000)` (2分钟)
- **方法**: `checkTaskStatuses()`
- **功能**:
  - 检查队列中的任务状态
  - 调用TaskQueueService.checkTaskStatuses()

#### PollingQueryService.java
- **功能**: 专门的轮询查询服务
- **注解**: `@Scheduled(fixedRate = 120000)` (2分钟)
- **方法**: `executePollingQuery()`
- **功能**:
  - 查询所有正在处理的任务
  - 逐个检查任务状态
  - 提供统计信息

### 2. 核心服务

#### TaskQueueService.java
- **方法**: `checkTaskStatuses()` - 检查队列中的任务状态
- **方法**: `checkTaskStatus(TaskQueue)` - 检查单个任务状态
- **功能**:
  - 查询外部API获取任务状态
  - 更新任务状态（完成/失败/超时）
  - 处理积分扣除和返还

### 3. 配置类

#### PollingConfig.java
- **功能**: 轮询查询配置
- **特性**:
  - 启用定时任务 `@EnableScheduling`
  - 自定义线程池执行定时任务
  - 确保每2分钟精确执行

### 4. 测试控制器

#### PollingTestController.java
- **路径**: `/api/polling/**`
- **接口**:
  - `GET /api/polling/stats` - 获取轮询统计信息
  - `POST /api/polling/trigger` - 手动触发轮询查询
  - `GET /api/polling/config` - 获取轮询配置信息

## 轮询查询流程

### 1. 定时触发
```
每2分钟 → TaskStatusPollingService.pollTaskStatuses()
每2分钟 → TaskQueueScheduler.checkTaskStatuses()
每2分钟 → PollingQueryService.executePollingQuery()
```

### 2. 查询逻辑
```
1. 查找需要轮询的任务
2. 调用外部API查询状态
3. 解析响应数据
4. 更新任务状态
5. 处理超时任务
6. 记录日志
```

### 3. 状态更新
- **完成**: `completed` 或 `success` → 扣除积分，创建用户作品
- **失败**: `failed` 或 `error` → 返还积分，记录错误
- **处理中**: `processing` 或 `pending` → 继续等待
- **超时**: 超过时间限制 → 标记为超时，返还积分

## 配置参数

### 定时任务间隔
- **固定间隔**: 120000毫秒 = 2分钟
- **注解**: `@Scheduled(fixedRate = 120000)`
- **线程池**: 2个线程执行定时任务

### 外部API配置
- **基础URL**: `http://116.62.4.26:8081`
- **API密钥**: `ak_5f13ec469e6047d5b8155c3cc91350e2`
- **超时设置**: 无限制（0秒）

## 日志记录

### 轮询查询日志
```
=== 开始执行任务状态轮询查询 (每2分钟) ===
找到 X 个需要轮询查询的任务
轮询任务: taskId=xxx, externalTaskId=xxx, status=xxx
外部API响应: {...}
任务状态更新: taskId=xxx, status=xxx, resultUrl=xxx
=== 任务状态轮询查询完成 ===
```

### 状态更新日志
```
任务完成: taskId=xxx
任务失败: taskId=xxx, 错误: xxx
任务继续处理中: taskId=xxx, 状态: xxx
任务超时: taskId=xxx
```

## 测试接口

### 获取统计信息
```bash
GET /api/polling/stats
```

### 手动触发轮询
```bash
POST /api/polling/trigger
```

### 获取配置信息
```bash
GET /api/polling/config
```

## 注意事项

1. **定时任务启用**: 确保主应用类有 `@EnableScheduling` 注解
2. **线程安全**: 使用事务管理确保数据一致性
3. **错误处理**: 单个任务失败不影响其他任务轮询
4. **超时处理**: 自动处理超时任务，返还用户积分
5. **日志记录**: 详细记录轮询过程和状态变化

## 总结

轮询查询功能已完整实现，包括：
- ✅ 每2分钟自动轮询查询
- ✅ 外部API状态查询
- ✅ 任务状态更新
- ✅ 积分管理
- ✅ 超时处理
- ✅ 详细日志记录
- ✅ 测试接口
- ✅ 统计信息

系统将自动每2分钟执行一次轮询查询，检查所有正在处理的任务状态，并更新相应的完成/失败状态。