vscode-workbench/.trae/specs/ip-location-api/spec.md

IP定位API Spec

Why

当前系统已有基础的IP信息获取接口，但仅返回请求头中的IP地址，无法提供地理位置信息。需要实现完整的IP定位功能，支持根据IP地址获取国家、城市、ISP等详细信息，并提供友好的前端展示界面。

What Changes

• 增强后端 GetIPDataView，集成免费的IP地理定位服务（ip-api.com）
• 支持自动获取客户端IP和指定IP查询
• 添加Redis缓存机制，避免频繁请求外部API
• 创建前端IP定位工具页面，提供交互式查询界面
• 更新API文档页面，展示IP定位接口详情
• 添加国际化支持

Impact

• Affected specs: API接口、工具页面
• Affected code:
  • chunyu_project/api/views/GetIPDataView.py
  • chunyu_project/api/urls.py
  • chunyu_project_react/src/pages/Tools/Tools.tsx
  • chunyu_project_react/src/pages/ApiDetail/ApiDetail.tsx
  • chunyu_project_react/src/utils/request.ts
  • 新增: chunyu_project_react/src/pages/IPLocation/IPLocation.tsx

ADDED Requirements

Requirement: IP定位API增强

系统SHALL提供增强的IP定位API，支持根据IP地址获取地理位置信息。

Scenario: 自动获取客户端IP信息

• WHEN 用户调用GET /api/getIpData/ 不带参数
• THEN 系统自动获取客户端IP并返回地理位置信息（国家、城市、ISP、经纬度等）

Scenario: 查询指定IP地址

• WHEN 用户调用GET /api/getIpData/?ip=8.8.8.8
• THEN 系统返回指定IP的地理位置信息

Scenario: 缓存机制生效

• WHEN 同一IP地址在缓存有效期内被多次查询
• THEN 系统从Redis缓存返回结果，不调用外部API

Requirement: IP定位前端页面

系统SHALL提供IP定位工具的前端页面，支持交互式查询。

Scenario: 自动查询当前IP

• WHEN 用户访问IP定位页面
• THEN 页面自动加载并显示当前客户端IP的地理位置信息

Scenario: 查询指定IP

• WHEN 用户在输入框中输入IP地址并点击查询
• THEN 页面显示该IP的详细信息，包括地图位置标记

MODIFIED Requirements

Requirement: API文档页面

现有的API文档页面SHALL展示IP定位接口的完整文档。

Scenario: API文档展示

• WHEN 用户访问API文档页面
• THEN IP定位接口的参数、响应示例、错误码等信息应当正确展示

Requirement: 工具列表页面

工具列表页面SHALL包含IP定位工具的入口卡片。

Scenario: 工具卡片展示

• WHEN 用户访问工具列表页面
• THEN 显示IP定位工具卡片，点击可跳转到IP定位页面

REMOVED Requirements

无