# 空气质量指数API Spec

## Why
当前已有实时天气查询API，空气质量是与天气相关的重要环境数据。需要实现独立的空气质量指数API后端，提供AQI、PM2.5、PM10等关键空气污染物数据，并在前端提供API详情文档和测试页面。

## What Changes

### 后端变更
- 新增 `air_quality/` Django应用，实现空气质量查询API视图
- 使用 Open-Meteo 免费空气质量API（无需API Key）
- 添加Swagger文档支持，遵循现有 `weather` 应用模式
- 注册URL路由到 `api/urls.py`
- 响应格式与天气API保持一致：`{code, message, data}`

### 前端变更
- 新增 `AQIDetails` 页面（含桌面端和移动端），展示API文档和在线测试功能
- 页面结构复用 `ApiDetail` 组件模式（Hero区域 + Tabs文档/测试）
- 添加路由注册
- 添加i18n翻译键

### 数据变更
- 无数据库表变更（纯第三方API代理，无需持久化）

## Impact
- Affected specs: `real-time-weather-api`（参考其模式）
- Affected code:
  - `chunyu_project/air_quality/`（新增Django应用）
  - `chunyu_project/api/urls.py`（修改，添加路由）
  - `chunyu_project/settings.py`（修改，注册应用）
  - `chunyu_project_react/src/pages/AQIDetails/`（新增页面）
  - `chunyu_project_react/src/pages/AQIDetails/AQIDetailsMobile.tsx`（新增移动端）
  - `chunyu_project_react/src/App.tsx`（修改，添加路由）
  - `chunyu_project_react/src/locales/*.json`（修改，添加翻译）
  - `chunyu_project_react/src/pages/ApiDocs/ApiDocs.tsx`（可选，更新API列表）

## ADDED Requirements

### Requirement: 空气质量查询API
The system SHALL provide an air quality query API that returns current air quality data for a given city.

#### Scenario: 成功查询空气质量
- **WHEN** 用户发送 GET 请求到 `/api/air-quality/`，携带 `city` 参数
- **THEN** 系统返回 200 状态码及空气质量数据（AQI指数、PM2.5、PM10、O3、NO2、SO2、CO、空气质量等级）

#### Scenario: 缺少必填参数
- **WHEN** 用户发送请求但未携带 `city` 参数
- **THEN** 系统返回 400 状态码及错误提示

#### Scenario: 城市不存在
- **WHEN** 用户请求的城市名称无法解析为地理坐标
- **THEN** 系统返回 404 状态码及友好错误提示

#### Scenario: 第三方API不可用
- **WHEN** Open-Meteo 服务暂时不可用或超时
- **THEN** 系统返回 502/503 状态码及友好错误提示

#### Scenario: 支持语言参数
- **WHEN** 用户携带 `lang` 参数（zh_cn 或 en）
- **THEN** 系统返回对应语言的空气质量等级描述

### Requirement: API文档集成
The air quality API SHALL be automatically included in the Swagger API documentation.

#### Scenario: Swagger文档显示
- **WHEN** 管理员访问 `/swagger/`
- **THEN** 空气质量查询API出现在API文档列表中，包含参数说明和响应示例

### Requirement: 前端API详情页面
The system SHALL provide a frontend API documentation and testing page for the air quality API.

#### Scenario: 页面访问
- **WHEN** 用户访问 `/api/air-quality-details`
- **THEN** 显示空气质量API详情页面，包含文档标签和测试标签

#### Scenario: API文档展示
- **WHEN** 用户切换到"文档"标签
- **THEN** 显示接口描述、请求参数表、响应示例、错误码说明

#### Scenario: 在线测试
- **WHEN** 用户在"测试"标签中输入城市名并点击发送
- **THEN** 向 `/api/air-quality/` 发起真实请求并显示响应结果

## MODIFIED Requirements

### Requirement: API路由注册
The main `api/urls.py` SHALL include the air quality API routes.

#### Scenario: 路由注册
- **WHEN** Django启动
- **THEN** `/api/air-quality/` 路由正确映射到 AirQualityView

### Requirement: Django应用注册
The `INSTALLED_APPS` SHALL include the new air quality app.

#### Scenario: 应用注册
- **WHEN** Django启动
- **THEN** `air_quality` 应用被正确加载

## REMOVED Requirements

无移除的功能。