# 前端队列状态 API 接口文档

## 概述

本文档说明队列状态查询的 API 接口，前端可以通过这些接口获取队列统计信息和文档排队位置。

**重要更新 (2026-01-29)**：
- `documents` 字段现在从**数据库**查询，而不是 Redis metrics
- 即使 Worker 未启动，也能正确显示等待处理的文档数量
- 新增 `waiting_ids` 和 `processing_details` 字段

---

## 接口 1：查询队列整体状态

**用途**：获取全局队列统计信息（排队数、处理数）

**请求**：
```http
GET /api/v2/system/queue/status
Authorization: Bearer <your_jwt_token>
```

**响应**：
```json
{
  "success": true,
  "timestamp": "2026-01-28T16:45:00.123456",
  "queue": {
    "pending_tasks": 5,
    "processing_tasks": 2,
    "available_slots": 2,
    "max_concurrent": 4
  },
  "documents": {
    "waiting": 3,
    "waiting_ids": [101, 102, 103],
    "processing": 2,
    "processing_ids": [123, 456],
    "processing_details": [
      {"id": 123, "status": "Cutting"},
      {"id": 456, "status": "Extractioning"}
    ]
  }
}
```

**响应字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 请求是否成功 |
| `timestamp` | string | 查询时间 |
| `queue.pending_tasks` | number | Celery 队列中等待的任务数 |
| `queue.processing_tasks` | number | 正在处理的任务数（通过并发许可统计） |
| `queue.available_slots` | number | 可用的处理槽位 |
| `queue.max_concurrent` | number | 最大并发数 |
| `documents.waiting` | number | **等待处理的文档数**（数据库 status='Queued'） |
| `documents.waiting_ids` | number[] | **等待中的文档ID列表** |
| `documents.processing` | number | **正在处理的文档数**（数据库 status in ['Cutting', 'Extractioning', 'Evaluationing']） |
| `documents.processing_ids` | number[] | 正在处理的文档ID列表 |
| `documents.processing_details` | object[] | **处理中文档的详细状态** |

**数据来源说明**：

| 字段 | 数据来源 | 说明 |
|------|----------|------|
| `queue.*` | Redis | 从 Celery 队列和并发控制器获取 |
| `documents.*` | PostgreSQL | 从数据库 documents 表查询 |

> ⚠️ **注意**：即使 Worker 未启动，`documents.waiting` 也会正确显示等待处理的文档数量。

---

## 接口 2：查询单个文档位置

**用途**：查询指定文档在队列中的位置、预估等待时间、以及细分处理状态

**请求**：
```http
GET /api/v2/system/queue/position/{document_id}
Authorization: Bearer <your_jwt_token>
```

**响应示例 - 排队中**：
```json
{
  "success": true,
  "document_id": 456,
  "status": "Queued",
  "position": 3,
  "ahead_count": 2,
  "total_in_queue": 5,
  "estimated_wait_minutes": 4,
  "message": "文档在队列中排第 3 位，前面有 2 个文档"
}
```

**响应示例 - OCR 识别中**：
```json
{
  "success": true,
  "document_id": 123,
  "status": "Cutting",
  "position": 0,
  "ahead_count": 0,
  "message": "OCR 识别中"
}
```

**响应示例 - AI 分析中**：
```json
{
  "success": true,
  "document_id": 123,
  "status": "Extractioning",
  "position": 0,
  "ahead_count": 0,
  "message": "AI 分析中"
}
```

**响应示例 - 规则检查中**：
```json
{
  "success": true,
  "document_id": 123,
  "status": "Evaluationing",
  "position": 0,
  "ahead_count": 0,
  "message": "规则检查中"
}
```

**响应示例 - 处理完成**：
```json
{
  "success": true,
  "document_id": 789,
  "status": "Processed",
  "position": null,
  "ahead_count": 0,
  "message": "文档处理完成"
}
```

**响应示例 - 处理失败**：
```json
{
  "success": true,
  "document_id": 789,
  "status": "Failed",
  "position": null,
  "ahead_count": 0,
  "message": "文档处理失败"
}
```

**响应字段说明**：

| 字段 | 类型 | 说明 |
|------|------|------|
| `success` | boolean | 请求是否成功 |
| `document_id` | number | 文档ID |
| `status` | string | **细分状态**（见下表） |
| `position` | number | 在队列中的位置（从1开始，处理中或完成时为0或null） |
| `ahead_count` | number | 前面排队的文档数 |
| `total_in_queue` | number | 队列中的总文档数（仅排队时返回） |
| `estimated_wait_minutes` | number | 预估等待时间（分钟，仅排队时返回） |
| `message` | string | 状态描述 |

**status 字段可能的值**：

| 状态值 | 说明 | 进度 | 建议显示 |
|--------|------|------|----------|
| `Queued` | 排队中 | 0% | 显示排队位置和预估时间 |
| `Cutting` | OCR 识别中 | 33% | 显示进度条 + "正在识别文档..." |
| `Extractioning` | AI 分析中 | 66% | 显示进度条 + "正在分析内容..." |
| `Evaluationing` | 规则检查中 | 90% | 显示进度条 + "正在检查规则..." |
| `Processed` | 处理完成 | 100% | 显示完成提示，可跳转查看结果 |
| `Failed` | 处理失败 | - | 显示错误提示，可查看详情 |

---

## 文档状态流转图

```
上传文档
    │
    ▼
┌─────────┐
│ Queued  │ ← 文档初始状态（等待 Worker 处理）
└────┬────┘
     │ Worker 开始处理
     ▼
┌─────────┐
│ Cutting │ ← OCR 识别阶段
└────┬────┘
     │
     ▼
┌──────────────┐
│Extractioning │ ← AI 分析阶段
└──────┬───────┘
       │
       ▼
┌──────────────┐
│Evaluationing │ ← 规则检查阶段
└──────┬───────┘
       │
       ├────────────┐
       ▼            ▼
┌──────────┐  ┌────────┐
│Processed │  │ Failed │
└──────────┘  └────────┘
```

---

## 前端集成建议

### 1. 上传后立即显示队列状态

```javascript
// 上传文档后
const uploadResult = await uploadDocument(file);
const documentId = uploadResult.result.id;

// 立即查询队列状态
const position = await api.get(`/system/queue/position/${documentId}`);
if (position.status === 'Queued') {
  showNotification(`文档已加入队列，前面有 ${position.ahead_count} 个文档`);
}
```

### 2. 轮询文档处理状态

```javascript
const pollDocumentStatus = async (documentId) => {
  const poll = async () => {
    const result = await api.get(`/system/queue/position/${documentId}`);

    switch (result.status) {
      case 'Queued':
        updateProgress(0, `排队中，前面还有 ${result.ahead_count} 个文档`);
        break;
      case 'Cutting':
        updateProgress(33, 'OCR 识别中...');
        break;
      case 'Extractioning':
        updateProgress(66, 'AI 分析中...');
        break;
      case 'Evaluationing':
        updateProgress(90, '规则检查中...');
        break;
      case 'Processed':
        updateProgress(100, '处理完成');
        return result; // 停止轮询
      case 'Failed':
        showError('处理失败');
        return result; // 停止轮询
    }

    // 继续轮询
    setTimeout(poll, 5000);
  };

  return poll();
};
```

### 3. 显示全局队列状态

```javascript
// 在页面顶部或侧边栏显示队列状态
const QueueStatusBadge = () => {
  const [status, setStatus] = useState(null);

  useEffect(() => {
    const fetchStatus = async () => {
      const data = await api.get('/system/queue/status');
      setStatus(data);
    };

    fetchStatus();
    const interval = setInterval(fetchStatus, 10000); // 每 10 秒刷新

    return () => clearInterval(interval);
  }, []);

  if (!status) return null;

  return (
    <div className="queue-status">
      <span>等待: {status.documents.waiting}</span>
      <span>处理中: {status.documents.processing}</span>
    </div>
  );
};
```

---

## 轮询建议

| 场景 | 推荐间隔 | 说明 |
|------|----------|------|
| 队列整体状态 | 10 秒 | 用于全局状态显示 |
| 单个文档位置 | 5 秒 | 用于进度跟踪 |
| 文档排队中 | 5 秒 | 显示排队位置变化 |
| 文档处理中 | 3 秒 | 更频繁更新进度 |

**停止轮询条件**：当 `status` 变为 `Processed` 或 `Failed` 时停止轮询

---

## 错误响应

所有接口在发生错误时返回：

```json
{
  "detail": "错误描述信息"
}
```

**HTTP 状态码**：
- `200` - 成功
- `401` - 未授权（Token 无效或过期）
- `500` - 服务器内部错误

---

## 常见问题

### Q1: 为什么 `queue.pending_tasks` 和 `documents.waiting` 数量不一致？

**A**:
- `queue.pending_tasks` 统计的是 Celery 队列中的**任务数**
- `documents.waiting` 统计的是数据库中 `status='Queued'` 的**文档数**
- 一个文档可能对应多个任务，或者有些任务不是文档处理任务

### Q2: Worker 未启动时会显示什么？

**A**:
- `queue.pending_tasks` 会显示队列中等待的任务数
- `documents.waiting` 会正确显示等待处理的文档数（从数据库查询）
- `queue.processing_tasks` 和 `documents.processing` 为 0

### Q3: 如何判断系统是否正常运行？

**A**:
- 如果 `documents.waiting > 0` 但 `queue.processing_tasks == 0` 且持续较长时间，可能 Worker 未启动
- 正常情况下，应该有文档在处理（`processing > 0`）或所有文档已处理完（`waiting == 0`）