vscode-workbench/.trae/specs/real-time-weather-api/spec.md

实时天气查询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 模拟逻辑