vscode-workbench/.trae/specs/air-quality-api/spec.md

空气质量指数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

无移除的功能。