vscode-workbench/.trae/specs/short-url-api/spec.md

短链接生成API Spec

Why

当前系统缺少短链接生成功能，用户无法将长URL转换为便于分享的短链接。需要开发短链接生成API后端及前端API详情页，提供链接缩短、自定义短码、过期设置和点击统计能力。

What Changes

后端变更

• 新增 shorturl/ Django应用，实现短链接生成和管理API
• 使用自增ID+Base62编码生成短码，支持自定义短码
• 数据模型存储：短码、原始URL、自定义短码、过期时间、创建者、点击次数
• 支持链接过期和访问次数统计
• 添加Swagger文档支持
• 注册URL路由 /api/shorturl/

前端变更

• 新增 ShortUrlDetail 页面，提供API文档和在线测试功能
• 包含API文档标签页和在线测试标签页
• 支持输入长URL、自定义短码、设置过期时间
• 显示生成的短链接和二维码
• 添加路由配置

Impact

• Affected specs: 无
• Affected code:
  • chunyu_project/shorturl/ (新增Django应用)
  • chunyu_project/api/urls.py (修改，添加shorturl路由)
  • chunyu_project_react/src/pages/ShortUrlDetail/ (新增)
  • chunyu_project_react/src/utils/request.ts (修改，添加shorturl API)
  • chunyu_project_react/src/App.tsx (修改，添加路由)

ADDED Requirements

Requirement: 短链接生成API

系统SHALL提供短链接生成API，支持将长URL转换为短链接。

Scenario: 成功生成短链接

• WHEN 用户发送 POST 请求到 /api/shorturl/shorten/，携带有效的 url 参数
• THEN 系统返回 200 状态码及生成的短链接信息（短码、短链接URL、原始URL、过期时间）

Scenario: 自定义短码

• WHEN 用户发送 POST 请求时携带 custom_code 参数
• THEN 系统使用用户指定的短码，若已被占用则返回 409 冲突错误

Scenario: 设置过期时间

• WHEN 用户发送 POST 请求时携带 expire_days 参数
• THEN 系统记录该短链接的过期时间

Scenario: URL格式校验

• WHEN 用户发送 POST 请求时携带无效的URL格式
• THEN 系统返回 400 错误提示

Scenario: 短码已存在

• WHEN 用户自定义的短码已被其他链接使用
• THEN 系统返回 409 错误及提示信息

Requirement: 短链接解析API

系统SHALL提供短链接解析API，支持通过短码获取原始URL信息。

Scenario: 查询短链接信息

• WHEN 用户发送 GET 请求到 /api/shorturl/info/<code>/
• THEN 系统返回该短码对应的原始URL、创建时间、点击次数、过期时间

Scenario: 短码不存在

• WHEN 用户查询不存在的短码
• THEN 系统返回 404 错误

Requirement: 短链接重定向

系统SHALL提供短链接重定向功能。

Scenario: 访问有效短链接

• WHEN 用户访问 /s/<code>/
• THEN 系统将用户重定向到原始URL，并将点击次数加1

Scenario: 短链接已过期

• WHEN 用户访问已过期的短链接
• THEN 系统返回 410 Gone 错误页面

Requirement: 链接列表API

系统SHALL提供用户创建的短链接列表查询API。

Scenario: 查询链接列表

• WHEN 已登录用户发送 GET 请求到 /api/shorturl/list/
• THEN 系统返回当前用户创建的所有短链接列表（分页）

Scenario: 匿名用户查询

• WHEN 未登录用户发送 GET 请求到 /api/shorturl/list/
• THEN 系统返回 401 错误，提示需要登录

Requirement: 前端API详情页

系统SHALL提供短链接生成API的前端详情页。

Scenario: 查看API文档

• WHEN 用户访问短链接API详情页
• THEN 系统显示API接口文档，包含请求参数、响应示例、错误码说明

Scenario: 在线生成短链接

• WHEN 用户在测试页面输入长URL和可选参数，点击生成
• THEN 系统向 /api/shorturl/shorten/ 发起真实请求并显示生成的短链接

Scenario: 复制短链接

• WHEN 用户点击复制按钮
• THEN 生成的短链接被复制到剪贴板

Requirement: API文档集成

短链接API SHALL自动集成到Swagger API文档中。

Scenario: Swagger文档显示

• WHEN 管理员访问 /swagger/
• THEN 短链接API出现在API文档列表中

MODIFIED Requirements

Requirement: 前端路由

前端路由SHALL包含新的短链接详情页路由。

Scenario: 访问短链接详情页

• WHEN 用户访问 /shorturl-detail
• THEN 系统显示短链接生成API详情页

REMOVED Requirements

无