# RTSP视频流管理系统 API 文档

## 基础信息
- **基础URL**: `http://localhost:8080`
- **数据格式**: JSON
- **编码**: UTF-8

## API 端点

### 1. 视频管理

#### 1.1 列出所有视频
```
GET /api/videos
```

**响应示例**:
```json
{
  "count": 10,
  "videos": [
    {
      "filename": "test_stream1.mp4",
      "full_path": "./output/20251011_082130/test_stream1.mp4",
      "timestamp_dir": "20251011_082130",
      "file_size": 787456,
      "created_time": "2025-10-11 08:21:45",
      "stream_index": "1"
    }
  ]
}
```

#### 1.2 列出指定时间戳目录的视频
```
GET /api/videos/{timestamp}
```

**路径参数**:
- `timestamp`: 时间戳目录名，例如 `20251011_082130`

---

### 2. 时间戳目录管理

#### 2.1 列出所有时间戳目录
```
GET /api/timestamps
```

**响应示例**:
```json
{
  "count": 5,
  "timestamps": [
    {
      "timestamp": "20251011_082130",
      "video_count": 2,
      "total_size": 5748992
    }
  ]
}
```

#### 2.2 删除时间戳目录
```
DELETE /api/timestamp/{timestamp}
```

**路径参数**:
- `timestamp`: 要删除的时间戳目录名

**响应示例**:
```json
{
  "success": true,
  "path": "./output/20251011_082130",
  "message": "目录删除成功"
}
```

---

### 3. 轮询报告管理 🆕

#### 3.1 列出所有轮询报告
```
GET /api/reports
```

**响应示例**:
```json
{
  "count": 8,
  "reports": [
    {
      "timestamp": "20251011_082130",
      "has_report": true,
      "summary": {
        "total_streams": 2,
        "successful_streams": 2,
        "failed_streams": 0,
        "cancelled_streams": 0,
        "total_bytes": 0,
        "total_frames": 950,
        "success_rate": 1.0,
        "average_duration": 18.0,
        "earliest_start": "2025-10-11 08:21:30",
        "latest_end": "2025-10-11 08:21:50"
      },
      "generated_at": "2025-10-11 08:21:50"
    }
  ]
}
```

**字段说明**:
- `total_streams`: 总流数
- `successful_streams`: 成功拉取的流数量
- `failed_streams`: 失败的流数量
- `cancelled_streams`: 取消的流数量
- `success_rate`: 成功率 (0.0-1.0)
- `total_frames`: 总接收帧数
- `average_duration`: 平均持续时间（秒）

#### 3.2 获取指定时间戳的轮询报告
```
GET /api/report/{timestamp}
```

**路径参数**:
- `timestamp`: 时间戳目录名

**响应示例**:
```json
{
  "report_generated_at": "2025-10-11 08:21:50",
  "config": {
    "global_config": {
      "total_poll_duration_seconds": 60,
      "max_concurrent_streams": 2,
      "output_directory": "./output/20251011_082130"
    },
    "streams": [...]
  },
  "scheduler_stats": {
    "total_tasks": 2,
    "completed_tasks": 2,
    "failed_tasks": 0,
    "cancelled_tasks": 0
  },
  "streams": [
    {
      "stream_index": 1,
      "rtsp_url": "rtsp://example.com/stream1",
      "output_file": "./output/20251011_082130/test_stream2.mp4",
      "status": "完成",
      "start_time": "2025-10-11 08:21:30",
      "end_time": "2025-10-11 08:21:50",
      "bytes_received": 0,
      "frames_received": 549,
      "duration_seconds": 20,
      "error_message": "",
      "actual_duration_seconds": 20
    }
  ],
  "summary": {
    "total_streams": 2,
    "successful_streams": 2,
    "failed_streams": 0,
    "total_frames": 950,
    "success_rate": 1.0
  }
}
```

**流状态说明**:
- `完成`: 流成功拉取
- `失败`: 流拉取失败（会有error_message）
- `取消`: 流被取消

---

### 4. 视频文件操作

#### 4.1 删除视频文件
```
DELETE /api/video?path={path}
```

**查询参数**:
- `path`: 视频文件的完整路径

**响应示例**:
```json
{
  "success": true,
  "path": "./output/20251011_082130/test_stream1.mp4",
  "message": "文件删除成功"
}
```

#### 4.2 播放/下载视频
```
GET /videos/{timestamp}/{filename}
```

**路径参数**:
- `timestamp`: 时间戳目录名
- `filename`: 视频文件名

**功能**: 直接返回视频文件流，支持浏览器播放和下载

---

## Web 界面

### 主页
```
GET /
```
系统主页，提供快速导航

### 视频管理界面
```
GET /manager
```
完整的视频和报告管理界面，包括：
- 时间戳目录浏览
- 所有视频列表
- **轮询报告查看** 🆕
- 视频播放功能
- 文件删除功能

---

## 错误响应

所有错误响应遵循以下格式：

```json
{
  "error": "错误类型",
  "message": "详细错误信息"
}
```

**常见HTTP状态码**:
- `200 OK`: 请求成功
- `400 Bad Request`: 请求参数错误
- `403 Forbidden`: 权限不足
- `404 Not Found`: 资源不存在
- `500 Internal Server Error`: 服务器内部错误

---

## 使用示例

### curl 示例

#### 获取所有轮询报告
```bash
curl http://localhost:8080/api/reports
```

#### 获取特定报告详情
```bash
curl http://localhost:8080/api/report/20251011_082130
```

#### 删除视频文件
```bash
curl -X DELETE "http://localhost:8080/api/video?path=./output/20251011_082130/test_stream1.mp4"
```

### JavaScript 示例

```javascript
// 获取所有报告
async function loadReports() {
  const response = await fetch('http://localhost:8080/api/reports');
  const data = await response.json();
  console.log(`共有 ${data.count} 个报告`);
  return data.reports;
}

// 获取特定报告
async function getReport(timestamp) {
  const response = await fetch(`http://localhost:8080/api/report/${timestamp}`);
  const report = await response.json();
  return report;
}
```

---

## 注意事项

1. **CORS支持**: API支持跨域请求
2. **文件路径安全**: 删除操作会检查文件路径，只能删除output目录下的文件
3. **视频播放**: 支持HTTP Range请求，可以拖动播放进度
4. **轮询报告**: 每次任务执行都会生成独立的JSON报告文件
5. **失败流展示**: 报告中包含所有流的状态，包括失败和未拉取成功的流

## 更新日志

### v1.1.0 (2025-10-11)
- ✨ 新增轮询报告API (`/api/reports`, `/api/report/{timestamp}`)
- ✨ Web界面新增"轮询报告"选项卡
- ✨ 报告展示包含成功和失败的流信息
- 🔧 优化API文档和错误处理