# 静态资源API设计文档
## 概述
本API提供对足球项目中静态资源的访问，包括球队可视化资源、球员图片和球队HTML数据文件。通过规则生成路径而非存储实际路径，简化了数据库结构。
## 模型设计
### Team（球队）
- `id`: 球队ID
- `name`: 球队名称
### Player（球员）
- `id`: 球员ID
- `name`: 球员名称
- `team`: 所属球队ID
- `team_name`: 所属球队名称（只读）
- `age`: 年龄
- `position`: 位置
- `nationality`: 国籍
### TeamVisual（球队可视化资源）
- `id`: 可视化资源ID
- `team`: 所属球队ID
- `team_name`: 所属球队名称（只读）
- `visual_files`: 可视化文件列表（动态生成）
### TeamPlayerImage（球员图片）
- `id`: 球员图片ID
- `team`: 所属球队ID
- `team_name`: 所属球队名称（只读）
- `player_name`: 球员名称
- `image_path`: 图片路径（动态生成）
### TeamDataHtml（球队HTML数据文件）
- `id`: HTML文件ID
- `team`: 所属球队ID
- `team_name`: 所属球队名称（只读）
- `html_path`: HTML文件路径（动态生成）
## 路径生成规则
### TeamVisual
每个球队有8个PNG文件和1个HTML文件，路径格式为：
```
static/team-visuals/{team_name}/{file_name}
```
### TeamPlayerImage
每个球员一张图片，路径格式为：
```
static/team_player_images/{team_name}/{player_name_with_underscores}.jpg
```
### TeamDataHtml
每个球队一个HTML文件，路径格式为：
```
static/team_data_html/{simplified_team_name}.html
```
其中简化球队名通过映射表生成：
- Arsenal → arsenal
- Manchester City → manchestercity
- 等等...
## API端点
### 球队相关
- `GET /api/v1/teams/` - 获取所有球队列表
- `GET /api/v1/teams/{id}/` - 获取特定球队信息
### 球员相关
- `GET /api/v1/players/` - 获取所有球员列表
- `GET /api/v1/players/{id}/` - 获取特定球员信息
### 球队可视化资源
- `GET /api/v1/team-visuals/` - 获取所有球队可视化资源列表
- `GET /api/v1/team-visuals/{id}/` - 获取特定球队的可视化资源信息
### 球员图片
- `GET /api/v1/team-player-images/` - 获取所有球员图片列表
- `GET /api/v1/team-player-images/{id}/` - 获取特定球员图片信息
### 球队HTML数据文件
- `GET /api/v1/team-data-html/` - 获取所有球队HTML数据文件列表
- `GET /api/v1/team-data-html/{id}/` - 获取特定球队的HTML数据文件信息
## 过滤和搜索
所有端点都支持以下过滤和搜索功能：
### 过滤
- `team={team_id}` - 按球队ID过滤
- `position={position}` - 按位置过滤（仅球员）
- `nationality={nationality}` - 按国籍过滤（仅球员）
### 搜索
- `search={query}` - 按名称搜索
- 球员端点：按球员名、球队名、位置、国籍搜索
- 球员图片端点：按球员名搜索
## 使用示例
### 获取球队列表
```bash
curl http://localhost:8000/api/v1/teams/
```
### 获取特定球队的所有球员
```bash
curl http://localhost:8000/api/v1/players/?team=1
```
### 获取球员图片路径
```bash
curl http://localhost:8000/api/v1/team-player-images/1/
```
返回示例：
```json
{
"id": 1,
"team": 1,
"team_name": "Arsenal",
"player_name": "Bukayo Saka",
"image_path": "static/team_player_images/Arsenal/Bukayo_Saka.jpg"
}
```
### 获取球队可视化文件列表
```bash
curl http://localhost:8000/api/v1/team-visuals/1/
```
返回示例：
```json
{
"id": 1,
"team": 1,
"team_name": "Arsenal",
"visual_files": [
{
"name": "age_distribution.png",
"file_path": "static/team-visuals/Arsenal/age_distribution.png"
},
// ... 其他文件
]
}
```