70 lines
2.5 KiB
Markdown
70 lines
2.5 KiB
Markdown
# 实时天气查询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` 模拟逻辑
|