# GasFlux 项目说明文档

## 项目概述

GasFlux 是一个基于 Flask 的气体通量分析 Web API 系统，专门用于处理无人机或飞行器采集的气体浓度数据，支持 CO₂、CH₄ 等温室气体通量的计算。

## 核心功能

### 🧪 数据处理
- **数据预处理**: Excel/CSV 文件解析，数据验证和清洗
- **背景校正**: 集成 FastChrom 算法的智能背景扣除
- **空间插值**: 克里金插值算法，支持多种半变异函数模型
- **通量计算**: 基于质量平衡法的气体通量计算

### 🌐 Web API 服务
- **RESTful API**: 完整的 HTTP API 接口
- **异步处理**: 支持大文件后台处理
- **实时监控**: 任务状态实时查询和进度跟踪
- **文件管理**: 自动上传、处理和下载管理

### 🔐 安全与认证
- **API 密钥认证**: 安全的密钥管理系统
- **权限控制**: 支持不同范围的 API 访问权限
- **引导密钥**: 初始管理员密钥配置

### 🧹 自动维护
- **任务清理**: 自动清理过期任务和文件
- **存储管理**: 智能的磁盘空间管理
- **日志记录**: 完整的操作日志和性能监控

## 技术架构

### 后端技术栈
- **框架**: Flask (Python Web 框架)
- **数据库**: SQLite (任务状态和配置存储)
- **部署**: Waitress (生产环境 WSGI 服务器)
- **认证**: 自定义 API 密钥系统

### 数据处理引擎
- **核心算法**: GasFlux 气体通量分析引擎
- **数据格式**: Excel, CSV, YAML 配置
- **输出格式**: CSV 数据, HTML 报告, PNG 图表

### 前端界面
- **Web 界面**: 内置 HTML/CSS/JavaScript 控制台
- **API 客户端**: 支持 cURL, Python requests 等
- **实时更新**: WebSocket 风格的任务状态轮询

## 快速开始

### 1. 环境准备
```bash
# Python 3.8+ 环境
python --version

# 安装依赖
pip install -r requirements.txt
```

### 2. 配置系统
```bash
# 编辑配置文件
notepad gasflux.ini

# 创建初始 API 密钥
python create_api_key.py
```

### 3. 启动服务
```bash
# 启动 Web API 服务
python -m src.gasflux.app

# 服务启动后访问: http://localhost:5001
```

### 4. 使用 API
```bash
# 上传处理文件
curl -X POST \
  -H "X-API-Key: your-api-key" \
  -F "file=@data.xlsx" \
  http://localhost:5001/upload
```

## 配置文件说明

### gasflux.ini (主配置文件)
```ini
[server]
host = 0.0.0.0
port = 5001
debug = false

[paths]
uploads = ./web_api_data/uploads
outputs = ./web_api_data/outputs

[cleanup]
task_cleanup_interval = 30
successful_task_cleanup_age = 60
failed_task_cleanup_age = 60
janitor_dry_run = false

[security]
admin_bootstrap_key = bootstrap_key_2024
```

### gasflux_config.yaml (处理配置)
```yaml
output_dir: ./output
gases:
  ch4: [1.5, 10.0]
  co2: [300, 500]
strategies:
  background: "algorithm"
  spatial: "curtain"
  interpolation: "kriging"
```

## API 接口列表

### 核心接口
- `POST /upload` - 文件上传和处理
- `GET /task/{task_id}` - 查询任务状态
- `GET /download/{path}` - 文件下载
- `GET /health` - 系统健康检查

### 管理接口
- `POST /api-keys` - 创建 API 密钥
- `GET /api-keys` - 列出 API 密钥
- `DELETE /api-keys/{key_id}` - 撤销 API 密钥

### 监控接口
- `GET /stats` - 系统统计信息
- `GET /config` - 配置信息查询

## 部署选项

### 开发环境
```bash
# 直接运行
python -m src.gasflux.app
```

### 生产环境 (Waitress)
```bash
# 使用 Waitress 服务器
python server_waitress.py
```

### Docker 部署
```bash
# 构建 Docker 镜像
docker build -t gasflux .

# 运行容器
docker run -p 5001:5001 gasflux
```

## 目录结构

```
gasflux-develop/
├── src/gasflux/              # 核心源码
│   ├── app.py               # Flask 应用主文件
│   ├── auth.py              # 认证模块
│   ├── db.py                # 数据库模块
│   ├── janitor.py           # 自动清理模块
│   └── blueprints/          # API 蓝图
├── gasflux.ini              # 主配置文件
├── create_api_key.py        # API 密钥创建工具
├── requirements.txt         # Python 依赖
├── web_api_data/            # 数据目录
│   ├── uploads/            # 上传文件
│   └── outputs/            # 输出文件
└── logs/                   # 日志文件
```

## 常见问题

### Q: 如何创建 API 密钥？
A: 运行 `python create_api_key.py`，按照提示输入描述信息。

### Q: 如何查看任务处理状态？
A: 使用 `GET /task/{task_id}` 接口，或在 Web 界面中查看。

### Q: 如何修改清理策略？
A: 编辑 `gasflux.ini` 中的 `[cleanup]` 部分配置。

### Q: 系统支持哪些气体？
A: 目前支持 CO₂、CH₄ 等主要温室气体，可在配置中扩展。

## 技术支持

- **项目主页**: [GitHub Repository]
- **文档**: [API_DOCUMENTATION.md](API_DOCUMENTATION.md)
- **配置指南**: [CONFIG_README.md](CONFIG_README.md)
- **部署指南**: [WAITRESS_DEPLOYMENT.md](WAITRESS_DEPLOYMENT.md)

## 版本信息

- **当前版本**: v0.2.1
- **Python 版本**: 3.8+
- **许可证**: AGPL v3.0