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

2026-09-12 14:25:25 +08:00
commit 8242e730b4
482 changed files with 37029 additions and 0 deletions
@@ -0,0 +1,30 @@
+# Checklist
+
+## 后端开发
+- [x] weather应用已创建并注册到INSTALLED_APPS
+- [x] WeatherView类实现正确，支持GET/POST方法
+- [x] 参数验证逻辑正确（city必填，其他可选）
+- [x] 第三方天气API调用逻辑正确
+- [x] 响应数据格式符合前端期望
+- [x] 错误处理完善（参数错误、API不可用、城市不存在等）
+- [x] Swagger文档注解完整
+- [x] URL路由注册正确（/api/weather/）
+
+## 配置
+- [x] 和风天气API密钥已添加到settings
+- [x] 环境变量配置说明已添加（如.env.example）
+- [x] requests库已添加到requirements.txt
+
+## 前端开发
+- [x] ApiDetail.tsx中mock数据已移除
+- [x] handleSend函数调用真实API
+- [x] 错误状态显示正确
+- [x] loading状态正常工作
+- [x] 响应数据展示正确
+
+## 测试
+- [x] 后端API单元测试通过
+- [x] 使用curl测试接口正常
+- [x] 前端页面联调成功
+- [x] Swagger文档可访问并显示天气API
+- [x] 错误场景测试通过（空城市、无效城市等）
@@ -0,0 +1,69 @@
+# 实时天气查询API Spec
+
+## Why
+当前前端ApiDetail页面使用mock数据展示天气查询API，但后端没有实际实现。需要完成后端天气API开发，使前端能够调用真实的天气数据。
+
+## What Changes
+
+### 后端变更
+- 新增 `weather/` Django应用，实现天气查询API视图
+- 调用第三方天气API（使用和风天气API）
+- 添加Swagger文档支持
+- 注册URL路由
+
+### 前端变更
+- 修改 `ApiDetail.tsx` 中的 `handleSend` 函数，连接真实后端接口
+- 移除mock数据逻辑
+- 添加错误处理和加载状态
+
+### 配置变更
+- 添加和风天气API密钥到环境变量或Django settings
+- 添加第三方API请求库 `requests` 到 requirements
+
+## Impact
+- Affected specs: 无
+- Affected code:
+  - `chunyu_project/weather/` (新增)
+  - `chunyu_project/api/urls.py` (修改)
+  - `chunyu_project/settings.py` (修改)
+  - `chunyu_project_react/src/pages/ApiDetail/ApiDetail.tsx` (修改)
+  - `chunyu_project_react/src/pages/Tools/Tools.tsx` (可选修改)
+
+## ADDED Requirements
+
+### Requirement: 天气查询API
+The system SHALL provide a weather query API that returns real-time weather data for a given city.
+
+#### Scenario: 成功查询天气
+- **WHEN** 用户发送 GET 请求到 `/api/weather/`，携带 `city` 参数
+- **THEN** 系统返回 200 状态码及天气数据（温度、湿度、天气状况、风力、空气质量）
+
+#### Scenario: 缺少必填参数
+- **WHEN** 用户发送请求但未携带 `city` 参数
+- **THEN** 系统返回 400 状态码及错误提示
+
+#### Scenario: 第三方API不可用
+- **WHEN** 第三方天气服务暂时不可用
+- **THEN** 系统返回 503 状态码及友好错误提示
+
+### Requirement: API文档集成
+The weather API SHALL be automatically included in the Swagger API documentation.
+
+#### Scenario: Swagger文档显示
+- **WHEN** 管理员访问 `/swagger/` 或 `/api-docs/`
+- **THEN** 天气查询API出现在API文档列表中，包含参数说明和响应示例
+
+## MODIFIED Requirements
+
+### Requirement: ApiDetail页面真实请求
+The frontend ApiDetail page SHALL call the real backend API instead of using mock data.
+
+#### Scenario: 用户测试API
+- **WHEN** 用户在ApiDetail页面点击"发送请求"按钮
+- **THEN** 系统向 `/api/weather/` 发起真实请求并显示响应结果
+
+## REMOVED Requirements
+
+### Requirement: Mock天气数据
+**Reason**: 后端已实现真实API，不再需要前端mock数据
+**Migration**: 移除 `mockResponse` 和 `setTimeout` 模拟逻辑
@@ -0,0 +1,40 @@
+# Tasks
+
+- [x] Task 1: 创建后端weather应用骨架
+  - [x] 使用 `python manage.py startapp weather` 创建应用
+  - [x] 在 `settings.py` 中注册应用
+  - [x] 创建基本的视图文件和URL配置
+
+- [x] Task 2: 实现天气查询视图
+  - [x] 创建 `WeatherView` 类，支持GET和POST请求
+  - [x] 实现请求参数解析（city, unit, lang, days）
+  - [x] 实现第三方天气API调用逻辑
+  - [x] 实现错误处理和响应格式化
+  - [x] 添加Swagger文档注解
+
+- [x] Task 3: 配置第三方天气API
+  - [x] 在和风天气官网注册并获取API密钥
+  - [x] 在 `settings.py` 中添加 `WEATHER_API_KEY` 配置
+  - [x] 实现API请求和响应数据的转换映射
+
+- [x] Task 4: 注册URL路由
+  - [x] 在 `weather/urls.py` 中定义路由
+  - [x] 在 `api/urls.py` 中包含weather路由
+
+- [x] Task 5: 修改前端ApiDetail页面
+  - [x] 移除mock数据和模拟请求逻辑
+  - [x] 修改 `handleSend` 函数调用真实后端API
+  - [x] 添加请求错误处理和提示
+  - [x] 更新响应数据格式匹配真实API
+
+- [x] Task 6: 测试验证
+  - [x] 后端API单元测试
+  - [x] 使用curl/Postman测试接口
+  - [x] 前端页面联调测试
+
+# Task Dependencies
+- Task 2 依赖于 Task 1
+- Task 3 依赖于 Task 2
+- Task 4 依赖于 Task 2
+- Task 5 依赖于 Task 4
+- Task 6 依赖于 Task 5