# 短链接生成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
无