# GasFlux Web API 端点参考

## 概述

GasFlux Web API 是一个基于 Flask 的 RESTful API，用于上传数据文件、执行气体通量分析处理，并下载处理结果。

**基础信息:**
- **基础 URL**: `http://localhost:5000`
- **认证**: 无需认证
- **数据格式**: JSON
- **文件大小限制**: 100MB
- **支持的文件类型**: `.xlsx`, `.xls`, `.yaml`, `.yml`

---

## 🔍 监控和健康检查

### 1. 获取健康状态
**端点**: `GET /health`

**描述**: 获取 API 的健康状态、系统信息和性能指标。

**响应示例** (200):
```json
{
  "code": 200,
  "message": "健康检查完成",
  "data": {
    "status": "healthy",
    "version": "1.0.0",
    "timestamp": 1705257600.123,
    "uptime": "2h 30m 15s",
    "storage": {
      "uploads_writable": true,
      "outputs_writable": true
    },
    "tasks": {
      "active_count": 2,
      "total_tracked": 15,
      "total_processed": 13,
      "success_rate_percent": 92.31
    },
    "performance": {
      "requests_per_second": 0.08,
      "avg_response_time_ms": 234.56,
      "error_rate_percent": 1.5
    }
  }
}
```

**响应示例** (503):
```json
{
  "code": 503,
  "message": "服务不可用",
  "data": {
    "status": "degraded",
    "version": "1.0.0",
    "timestamp": 1705257600.123,
    "uptime": "1h 30m 45s",
    "storage": {
      "uploads_writable": true,
      "outputs_writable": true
    },
    "tasks": {
      "active_count": 0,
      "total_tracked": 5,
      "total_processed": 3,
      "success_rate_percent": 60.0
    },
    "performance": {
      "requests_per_second": 0.12,
      "avg_response_time_ms": 145.67,
      "error_rate_percent": 50.0
    },
    "issues": [
      "错误率过高 (50.0%)",
      "活跃任务数量过多 (25)"
    ]
  }
}
```

**状态码**:
- `200`: API 健康
- `503`: API 不健康

---

### 2. 获取系统统计信息
**端点**: `GET /stats`

**描述**: 获取详细的 API 统计信息、性能指标和系统监控数据。

**响应示例** (200):
```json
{
  "code": 200,
  "message": "统计信息获取成功",
  "data": {
    "summary": {
      "uptime_seconds": 3600.5,
      "uptime_formatted": "1h 0m 0s",
      "requests_total": 150,
      "requests_per_second": 0.04,
      "error_rate_percent": 2.0,
      "active_tasks": 1
    },
    "requests": {
      "by_method": {
        "GET": 120,
        "POST": 30
      },
      "by_status": {
        "200": 145,
        "400": 3,
        "500": 2
      },
      "top_endpoints": {
        "/task/abc123": 45,
        "/health": 30,
        "/": 25
      }
    },
    "tasks": {
      "total_created": 25,
      "total_completed": 20,
      "total_failed": 2,
      "success_rate_percent": 90.91,
      "by_status": {
        "pending": 1,
        "processing": 1,
        "completed": 20,
        "failed": 2
      }
    },
    "performance": {
      "avg_response_time_ms": 245.67,
      "max_response_time_ms": 1250.34,
      "min_response_time_ms": 12.45
    },
    "system": {
      "memory_usage_percent": 45.2,
      "memory_used_gb": 7.3,
      "memory_total_gb": 16.0,
      "disk_usage_percent": 23.1,
      "disk_used_gb": 46.8,
      "disk_total_gb": 203.2
    },
    "recent_tasks": [
      {
        "task_id": "abc123-def456",
        "status": "completed",
        "age_seconds": 45.2,
        "message": "处理完成成功"
      }
    ]
  }
}
```

**状态码**:
- `200`: 成功

---

### 3. 重置统计信息
**端点**: `POST /stats/reset`

**描述**: 重置所有 API 统计数据（管理员功能）。

**响应示例** (200):
```json
{
  "code": 200,
  "message": "统计信息重置成功",
  "data": {
    "timestamp": 1705257600.123
  }
}
```

**状态码**:
- `200`: 成功

---

### 4. 获取配置信息
**端点**: `GET /config`

**描述**: 获取当前应用配置信息和支持的环境变量。

**响应示例** (200):
```json
{
  "code": 200,
  "message": "配置信息获取成功",
  "data": {
    "configuration": {
      "host": "0.0.0.0",
      "port": 5000,
      "debug": false,
      "base_dir": "/app",
      "upload_folder": "/app/web_api_data/uploads",
      "output_folder": "/app/web_api_data/outputs",
      "max_content_length": 104857600,
      "log_level": "INFO",
      "log_file": "logs/gasflux_api.log",
      "cors_origins": ["*"],
      "task_cleanup_interval": 3600,
      "max_task_age": 86400,
      "threads": 8,
      "connection_limit": 100,
      "channel_timeout": 300
    },
    "environment_variables": {
      "supported": [
        "GASFLUX_HOST", "GASFLUX_PORT", "GASFLUX_DEBUG",
        "GASFLUX_UPLOAD_FOLDER", "GASFLUX_OUTPUT_FOLDER",
        "GASFLUX_MAX_CONTENT_LENGTH", "GASFLUX_LOG_LEVEL",
        "GASFLUX_LOG_FILE", "GASFLUX_CORS_ORIGINS",
        "GASFLUX_TASK_CLEANUP_INTERVAL", "GASFLUX_MAX_TASK_AGE",
        "GASFLUX_THREADS", "GASFLUX_CONNECTION_LIMIT",
        "GASFLUX_CHANNEL_TIMEOUT"
      ],
      "current_values": {
        "GASFLUX_HOST": "0.0.0.0",
        "GASFLUX_PORT": "5000",
        "GASFLUX_DEBUG": "false"
      }
    }
  }
}
```

**状态码**:
- `200`: 成功

---

## 📤 文件上传和管理

### 5. 文件上传和处理
**端点**: `POST /upload`

**描述**: 上传数据文件并启动异步处理任务。

**请求参数** (multipart/form-data):
- `file` (必需): 数据文件 (.xlsx 或 .xls 格式)
- `config` (可选): 配置文件 (.yaml 或 .yml 格式)

**响应示例** (202):
```json
{
  "code": 202,
  "message": "任务已接受并加入处理队列",
  "data": {
    "status": "accepted",
    "job_id": "abc123-def456-ghi789",
    "task_status_url": "/task/abc123-def456-ghi789"
  }
}
```

**错误响应示例** (400):
```json
{
  "code": 400,
  "message": "无效的数据文件类型。只允许 .xlsx 和 .xls 格式。",
  "data": {}
}
```

**错误响应示例** (413):
```json
{
  "code": 413,
  "message": "文件过大。最大尺寸为 100MB。",
  "data": {}
}
```

**状态码**:
- `202`: 任务已接受
- `400`: 请求参数错误
- `413`: 文件过大

---

## 📊 任务管理和监控

### 6. 分页查询任务列表
**端点**: `GET /tasks`

**描述**: 分页查询所有任务，支持按状态过滤、排序和分页。返回体为前端友好的瘦身结构：仅包含任务状态信息；当任务已完成时会包含 `downloads` 直达下载链接。

**查询参数**:
- `page` (可选): 页码 (默认: 1)
- `page_size` (可选): 每页任务数量 (默认: 20, 最大: 100)
- `sort_by` (可选): 排序字段 ('created_at', 'updated_at', 'status') (默认: 'updated_at')
- `sort_order` (可选): 排序顺序 ('asc', 'desc') (默认: 'desc')
- `status` (可选): 按任务状态过滤，支持多个状态用逗号分隔

**响应示例** (200):
```json
{
  "code": 200,
  "message": "任务列表查询成功",
  "data": {
    "tasks": [
      {
        "task_id": "abc123-def456-ghi789",
        "status": "completed",
        "message": "Processing completed successfully",
        "updated_at": 1705257700.456,
        "downloads": {
          "data_xlsx": "/download/abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
          "report_ch4": "/download/abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
          "report_co2": "/download/abc123-def456-ghi789/08_34_01_5m.processed_co2_report.html",
          "config": "/download/abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
          "metadata": "/download/abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json"
        }
      },
      {
        "task_id": "xyz789-abc123-def456",
        "status": "processing",
        "message": "正在进行数据分析...",
        "updated_at": 1705257650.321
      }
    ],
    "total": 25,
    "page": 1,
    "page_size": 20,
    "total_pages": 2,
    "has_next": true,
    "has_prev": false
  }
}
```

**状态码**:
- `200`: 成功
- `400`: 参数无效

---

### 7. 获取任务池统计信息
**端点**: `GET /tasks/stats`

**描述**: 获取任务池的统计信息，包括各状态任务数量、活跃任务数等。

**响应示例** (200):
```json
{
  "code": 200,
  "message": "任务池统计信息查询成功",
  "data": {
    "total_tasks": 25,
    "status_counts": {
      "pending": 3,
      "processing": 2,
      "completed": 18,
      "failed": 2
    },
    "active_tasks": 2,
    "queued_tasks": 3,
    "completed_tasks": 18,
    "failed_tasks": 2
  }
}
```

**状态码**:
- `200`: 成功

---

### 8. 获取活跃任务列表
**端点**: `GET /tasks/active`

**描述**: 获取当前正在处理的任务列表（瘦身结构）。当列表中包含已完成任务时会附带 `downloads` 直达下载链接。

**响应示例** (200):
```json
{
  "code": 200,
  "message": "活跃任务查询成功",
  "data": {
    "active_tasks": [
      {
        "task_id": "abc123-def456-ghi789",
        "status": "processing",
        "message": "正在生成报告...",
        "updated_at": 1705257650.321
      },
      {
        "task_id": "completed-task-123",
        "status": "completed",
        "message": "Processing completed successfully",
        "updated_at": 1705257550.456,
        "downloads": {
          "data_xlsx": "/download/completed-task-123/processed_data.xlsx",
          "report_html": "/download/completed-task-123/data_report.html"
        }
      }
    ],
    "count": 2
  }
}
```

**状态码**:
- `200`: 成功

---

### 9. 获取队列任务列表
**端点**: `GET /tasks/queue`

**描述**: 获取等待处理的任务队列（瘦身结构）。当列表中包含已完成任务时会附带 `downloads` 直达下载链接。

**响应示例** (200):
```json
{
  "code": 200,
  "message": "队列任务查询成功",
  "data": {
    "queued_tasks": [
      {
        "task_id": "xyz789-abc123-def456",
        "status": "pending",
        "message": "等待处理",
        "updated_at": 1705257400.123
      },
      {
        "task_id": "completed-queued-task",
        "status": "completed",
        "message": "Processing completed successfully",
        "updated_at": 1705257450.321,
        "downloads": {
          "data_xlsx": "/download/completed-queued-task/processed_data.xlsx",
          "report_html": "/download/completed-queued-task/analysis_report.html"
        }
      }
    ],
    "count": 2,
    "queue_position_info": "任务按创建时间排序，较早的任务优先处理"
  }
}
```

**状态码**:
- `200`: 成功

---

### 10. 查询任务状态
**端点**: `GET /task/{task_id}`

**描述**: 查询异步处理任务的当前状态和进度信息。

**路径参数**:
- `task_id`: 任务 ID (UUID 格式)

**响应示例** - 处理中 (200):
```json
{
  "code": 200,
  "message": "任务查询成功",
  "data": {
    "task_id": "abc123-def456-ghi789",
    "status": "processing",
    "message": "GasFlux 分析完成，正在生成报告...",
    "updated_at": 1705257600.123
  }
}
```

**响应示例** - 处理完成 (200):
```json
{
  "code": 200,
  "message": "任务查询成功",
  "data": {
    "task_id": "abc123-def456-ghi789",
    "status": "completed",
    "message": "处理完成成功",
    "updated_at": 1705257600.123,
    "results": [
      {
        "name": "08_34_01_5m.processed_ch4_report.html",
        "rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
        "download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
        "size": 245760,
        "type": "report"
      },
      {
        "name": "08_34_01_5m.processed_data.xlsx",
        "rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
        "download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
        "size": 153600,
        "type": "data"
      },
      {
        "name": "08_34_01_5m.processed_config.yaml",
        "rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
        "download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
        "size": 2048,
        "type": "config"
      },
      {
        "name": "08_34_01_5m.processed_output_vars.json",
        "rel_path": "abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json",
        "download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json",
        "size": 4096,
        "type": "metadata"
      }
    ],
    "downloads": {
      "data_xlsx": "/download/abc123-def456-ghi789/08_34_01_5m.processed_data.xlsx",
      "report_ch4": "/download/abc123-def456-ghi789/08_34_01_5m.processed_ch4_report.html",
      "report_co2": "/download/abc123-def456-ghi789/08_34_01_5m.processed_co2_report.html",
      "config": "/download/abc123-def456-ghi789/08_34_01_5m.processed_config.yaml",
      "metadata": "/download/abc123-def456-ghi789/08_34_01_5m.processed_output_vars.json"
    }
  }
}
```

**响应示例** - 任务不存在 (404):
```json
{
  "code": 404,
  "message": "任务未找到",
  "data": {}
}
```

**状态码**:
- `200`: 成功
- `404`: 任务不存在

---

### 11. 更新任务状态
**端点**: `PUT /task/{task_id}`

**描述**: 更新任务的状态、信息或优先级。

**路径参数**:
- `task_id`: 任务 ID (UUID 格式)

**请求参数** (JSON):
- `status` (可选): 新的任务状态
- `message` (可选): 状态消息或错误描述
- `priority` (可选): 任务优先级 (normal/high/low)

**响应示例** (200):
```json
{
  "code": 200,
  "message": "任务更新成功",
  "data": {
    "task_id": "abc123-def456-ghi789",
    "status": "updated",
    "task_info": {
      "status": "completed",
      "message": "手动标记为完成",
      "updated_at": 1705257600.123,
      "priority": "normal"
    }
  }
}
```

**错误响应示例** (404):
```json
{
  "code": 404,
  "message": "任务未找到",
  "data": {}
}
```

**错误响应示例** (400):
```json
{
  "code": 400,
  "message": "无效状态。必须是以下之一: pending, processing, completed, failed",
  "data": {}
}
```

**状态码**:
- `200`: 成功
- `400`: 无效请求
- `404`: 任务不存在

---

### 12. 删除任务
**端点**: `DELETE /task/{task_id}`

**描述**: 删除任务及其所有相关的文件和数据。

**路径参数**:
- `task_id`: 任务 ID (UUID 格式)

**响应示例** (200):
```json
{
  "code": 200,
  "message": "任务及相关文件删除成功",
  "data": {
    "task_id": "abc123-def456-ghi789",
    "status": "deleted",
    "details": {
      "folders_deleted": 1,
      "total_size_deleted": 307200,
      "task_status": "completed"
    }
  }
}
```

**错误响应示例** (404):
```json
{
  "code": 404,
  "message": "任务未找到",
  "data": {}
}
```

**错误响应示例** (409):
```json
{
  "code": 409,
  "message": "无法删除当前正在处理或等待处理的任务",
  "data": {
    "task_status": "processing"
  }
}
```

**状态码**:
- `200`: 成功
- `404`: 任务不存在
- `409`: 任务正在处理

---

## 📋 报告管理和查询

### 13. 分页查询已生成报告
**端点**: `GET /reports`

**描述**: 分页查询所有已生成的处理报告，支持排序和过滤。

**查询参数**:
- `page` (可选): 页码 (默认: 1)
- `per_page` (可选): 每页报告数量 (默认: 20, 最大: 100)
- `sort_by` (可选): 排序字段 (默认: created_at)
- `sort_order` (可选): 排序顺序 (默认: desc)
- `status` (可选): 按任务状态过滤

**响应示例** (200):
```json
{
  "code": 200,
  "message": "报告列表获取成功",
  "data": {
    "reports": [
      {
        "task_id": "abc123-def456-ghi789",
        "report_name": "08_34_01_5m",
        "status": "completed",
        "created_at": 1705257600.123,
        "file_count": 4,
        "total_size": 307200,
        "processing_time_seconds": 125.67,
        "main_report": {
          "name": "08_34_01_5m.processed_ch4_report.html",
          "size": 245760,
          "type": "report",
          "download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_ch4_report.html"
        },
        "all_files": [
          {
            "name": "08_34_01_5m.processed_ch4_report.html",
            "size": 245760,
            "type": "report",
            "download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_ch4_report.html"
          },
          {
            "name": "08_34_01_5m.processed_data.csv",
            "size": 153600,
            "type": "data",
            "download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_data.csv"
          },
          {
            "name": "08_34_01_5m.processed_config.yaml",
            "size": 2048,
            "type": "config",
            "download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_config.yaml"
          },
          {
            "name": "08_34_01_5m.processed_output_vars.json",
            "size": 4096,
            "type": "metadata",
            "download_url": "/download/abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run/08_34_01_5m.processed_output_vars.json"
          }
        ],
        "run_directory": "abc123-def456-ghi789/08_34_01_5m.processed/2026-01-14_10-33-29-961698_processing_run"
      }
    ],
    "pagination": {
      "page": 1,
      "per_page": 20,
      "total_reports": 45,
      "total_pages": 3,
      "has_next": true,
      "has_prev": false
    },
    "filters": {
      "sort_by": "created_at",
      "sort_order": "desc",
      "status": null
    }
  }
}
```

**错误响应示例** (400):
```json
{
  "code": 400,
  "message": "Invalid parameter: per_page must be between 1 and 100",
  "data": {}
}
```

**状态码**:
- `200`: 成功
- `400`: 参数无效

---

## 📁 文件下载

### 14. 下载处理结果
**端点**: `GET /download/{filename}`

**描述**: 下载处理后的结果文件，支持传入完整文件路径。

**路径参数**:
- `filename`: 文件的完整路径或相对路径 (包含任务ID)

**状态码**:
- `200`: 成功下载文件
- `403`: 访问被拒绝
- `404`: 文件不存在
- `400`: 路径不是文件

---

## 🌐 Web 界面

### 15. Web 管理界面
**端点**: `GET /`

**描述**: 访问用户友好的 Web 界面，支持文件上传、任务监控和结果下载。

**状态码**:
- `200`: 成功

---

*最后更新: 2026年1月29日*

*GasFlux Web API 版本: 1.0.0*