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

2026-09-12 14:25:25 +08:00
commit 39af400fc8
472 changed files with 36277 additions and 0 deletions
@@ -0,0 +1,37 @@
+# Checklist
+
+## 后端验证
+
+- [x] air_quality 应用目录结构完整（`__init__.py`, `apps.py`, `views.py`, `urls.py`, `tests.py`, `admin.py`, `models.py`, `migrations/__init__.py`）
+- [x] `AirQualityView` 类正确实现 GET 和 POST 方法
+- [x] 地理编码逻辑正确调用 Open-Meteo Geocoding API
+- [x] 空气质量数据正确解析（包含 pm2_5, pm10, ozone, nitrogen_dioxide, sulphur_dioxide, carbon_monoxide, air_quality_level）
+- [x] 参数校验：`city` 为空时返回 400
+- [x] 城市不存在时返回 404
+- [x] 第三方API超时/异常时返回 502/503
+- [x] Swagger 文档装饰器正确配置（tags, operation_summary, parameters, responses）
+- [x] URL 路由注册正确（`/api/air-quality/`）
+- [x] `INSTALLED_APPS` 包含 `air_quality`
+- [x] 响应格式遵循 `{code, message, data}` 标准
+
+## 前端验证
+
+- [x] `AQIDetails.tsx` 桌面端页面正确渲染
+- [x] `AQIDetailsMobile.tsx` 移动端页面正确渲染
+- [x] `AQIDetails.css` 样式文件存在且与设计系统一致
+- [x] Hero 区域显示页面标题和描述
+- [x] "文档" 标签显示：接口描述、请求参数表、响应示例、错误码
+- [x] "测试" 标签显示：URL输入框、发送按钮、响应结果区域
+- [x] 发送请求功能正确调用 `/api/air-quality/` 后端API
+- [x] 响应结果正确显示（状态码、耗时、响应体）
+- [x] 错误处理正确（网络错误、参数错误等）
+- [x] 路由 `/api/air-quality-details` 正确注册
+- [x] i18n 翻译在所有支持的语言中完整
+
+## 集成验证
+
+- [x] 后端API可通过 `curl` 或 Postman 正常访问
+- [x] Swagger UI (`/swagger/`) 显示空气质量API文档
+- [x] 前端页面可通过浏览器正常访问
+- [x] 前端测试功能可正确调用后端并显示结果
+- [x] 移动端响应式布局正常
@@ -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
+
+无移除的功能。
@@ -0,0 +1,49 @@
+# Tasks
+
+## 后端实现
+
+- [x] Task 1: 创建 air_quality Django应用
+  - [x] SubTask 1.1: 创建 `air_quality/` 目录结构（`__init__.py`, `apps.py`, `views.py`, `urls.py`, `tests.py`, `admin.py`, `models.py`, `migrations/`）
+  - [x] SubTask 1.2: 配置 `apps.py` 应用元数据
+
+- [x] Task 2: 实现空气质量查询API视图
+  - [x] SubTask 2.1: 实现 `AirQualityView` 类（GET和POST方法）
+  - [x] SubTask 2.2: 实现城市名称地理编码（复用 Open-Meteo Geocoding API）
+  - [x] SubTask 2.3: 调用 Open-Meteo 空气质量API获取数据
+  - [x] SubTask 2.4: 解析并格式化AQI数据（PM2.5, PM10, O3, NO2, SO2, CO, 等级）
+  - [x] SubTask 2.5: 添加参数校验和错误处理
+  - [x] SubTask 2.6: 添加Swagger文档装饰器
+
+- [x] Task 3: 注册URL路由和应用
+  - [x] SubTask 3.1: 配置 `air_quality/urls.py` 路由
+  - [x] SubTask 3.2: 在 `api/urls.py` 中添加 `path('air-quality/', include('air_quality.urls'))`
+  - [x] SubTask 3.3: 在 `settings.py` 的 `INSTALLED_APPS` 中添加 `air_quality`
+
+## 前端实现
+
+- [x] Task 4: 创建AQIDetails页面组件
+  - [x] SubTask 4.1: 创建 `pages/AQIDetails/` 目录
+  - [x] SubTask 4.2: 实现 `AQIDetails.tsx` 桌面端页面（Hero + Tabs + 文档 + 测试）
+  - [x] SubTask 4.3: 实现 `AQIDetailsMobile.tsx` 移动端页面
+  - [x] SubTask 4.4: 创建 `AQIDetails.css` 样式文件（复用ApiDetail设计风格）
+
+- [x] Task 5: 添加路由和翻译
+  - [x] SubTask 5.1: 在 `App.tsx` 中添加 `/api/air-quality-details` 路由
+  - [x] SubTask 5.2: 在 `locales/zh.json` 中添加中文翻译键
+  - [x] SubTask 5.3: 在 `locales/en.json` 中添加英文翻译键
+  - [x] SubTask 5.4: 在 `locales/ja.json`, `locales/ko.json`, `locales/zh-TW.json`, `locales/ru.json` 中添加翻译
+
+## 集成与验证
+
+- [x] Task 6: 端到端测试
+  - [x] SubTask 6.1: 验证后端API可通过 `/api/air-quality/?city=北京` 访问
+  - [x] SubTask 6.2: 验证Swagger文档包含新API
+  - [x] SubTask 6.3: 验证前端页面可通过 `/api/air-quality-details` 访问
+  - [x] SubTask 6.4: 验证前端测试功能可正确调用后端API
+
+# Task Dependencies
+
+- Task 2 依赖 Task 1（需要先创建应用结构）
+- Task 3 依赖 Task 2（需要先实现视图）
+- Task 5 依赖 Task 4（需要先实现页面）
+- Task 6 依赖 Task 3 和 Task 5（需要前后端都完成）