feat: PLANNING体系首版（00路线图/02任务总表/03执行协议/I-03/I-04/registry42口径）+M1止血交付

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

@@ -0,0 +1,101 @@
+# 空气质量指数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
+
+无移除的功能。