102 lines
3.9 KiB
Markdown
102 lines
3.9 KiB
Markdown
# 空气质量指数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
|
||
|
||
无移除的功能。
|