303 lines
7.8 KiB
Markdown
303 lines
7.8 KiB
Markdown
# 赛事规程 API 设计文档
|
||
|
||
## 接口说明
|
||
|
||
### 获取赛事规程
|
||
**接口地址**: `/martial/competition/rules`
|
||
**请求方式**: `GET`
|
||
**接口描述**: 获取指定赛事的规程信息，包括附件和章节内容
|
||
|
||
---
|
||
|
||
## 请求参数
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| competitionId | String/Number | 是 | 赛事ID |
|
||
|
||
**请求示例**:
|
||
```javascript
|
||
GET /martial/competition/rules?competitionId=123
|
||
```
|
||
|
||
---
|
||
|
||
## 返回数据结构
|
||
|
||
### 成功响应
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"competitionId": "123",
|
||
"competitionName": "2025年郑州武术大赛",
|
||
|
||
// 附件列表（可选）
|
||
"attachments": [
|
||
{
|
||
"id": "1",
|
||
"name": "2025年郑州武术大赛规程.pdf",
|
||
"fileName": "2025年郑州武术大赛规程.pdf",
|
||
"url": "https://example.com/files/rules.pdf",
|
||
"fileUrl": "https://example.com/files/rules.pdf",
|
||
"size": 2621440, // 文件大小（字节）
|
||
"fileSize": 2621440,
|
||
"fileType": "pdf",
|
||
"uploadTime": "2025-01-15 10:30:00"
|
||
},
|
||
{
|
||
"id": "2",
|
||
"name": "参赛报名表.docx",
|
||
"fileName": "参赛报名表.docx",
|
||
"url": "https://example.com/files/form.docx",
|
||
"fileUrl": "https://example.com/files/form.docx",
|
||
"size": 159744,
|
||
"fileSize": 159744,
|
||
"fileType": "docx",
|
||
"uploadTime": "2025-01-15 10:35:00"
|
||
}
|
||
],
|
||
|
||
// 规程章节内容（可选）
|
||
"chapters": [
|
||
{
|
||
"id": "1",
|
||
"chapterNumber": "第一章",
|
||
"number": "第一章",
|
||
"title": "总则",
|
||
"name": "总则",
|
||
"order": 1,
|
||
"contents": [
|
||
"1.1 本次比赛遵循国际武术联合会竞赛规则。",
|
||
"1.2 所有参赛选手必须持有效证件参赛。",
|
||
"1.3 参赛选手须服从裁判判决，不得有违规行为。"
|
||
],
|
||
"items": [
|
||
"1.1 本次比赛遵循国际武术联合会竞赛规则。",
|
||
"1.2 所有参赛选手必须持有效证件参赛。",
|
||
"1.3 参赛选手须服从裁判判决，不得有违规行为。"
|
||
]
|
||
},
|
||
{
|
||
"id": "2",
|
||
"chapterNumber": "第二章",
|
||
"number": "第二章",
|
||
"title": "参赛资格",
|
||
"name": "参赛资格",
|
||
"order": 2,
|
||
"contents": [
|
||
"2.1 参赛选手年龄须在18-45周岁之间。",
|
||
"2.2 参赛选手须持有武术等级证书或相关证明。",
|
||
"2.3 参赛选手须通过健康检查，身体状况良好。"
|
||
]
|
||
},
|
||
{
|
||
"id": "3",
|
||
"chapterNumber": "第三章",
|
||
"number": "第三章",
|
||
"title": "比赛规则",
|
||
"name": "比赛规则",
|
||
"order": 3,
|
||
"contents": [
|
||
"3.1 比赛采用单败淘汰制。",
|
||
"3.2 每场比赛时间为3分钟，分3局进行。",
|
||
"3.3 得分规则按照国际标准执行。"
|
||
]
|
||
},
|
||
{
|
||
"id": "4",
|
||
"chapterNumber": "第四章",
|
||
"number": "第四章",
|
||
"title": "奖项设置",
|
||
"name": "奖项设置",
|
||
"order": 4,
|
||
"contents": [
|
||
"4.1 各组别设金、银、铜牌各一枚。",
|
||
"4.2 设最佳表现奖、体育道德风尚奖等特别奖项。",
|
||
"4.3 所有参赛选手均可获得参赛证书。"
|
||
]
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 字段说明
|
||
|
||
### attachments（附件列表）
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | String | 是 | 附件ID |
|
||
| name / fileName | String | 是 | 文件名称 |
|
||
| url / fileUrl | String | 是 | 文件下载地址（完整URL） |
|
||
| size / fileSize | Number | 否 | 文件大小（字节） |
|
||
| fileType | String | 否 | 文件类型（pdf/doc/docx/xls/xlsx等） |
|
||
| uploadTime | String | 否 | 上传时间 |
|
||
|
||
**支持的文件类型**:
|
||
- PDF文档: `.pdf`
|
||
- Word文档: `.doc`, `.docx`
|
||
- Excel表格: `.xls`, `.xlsx`
|
||
- PowerPoint: `.ppt`, `.pptx`
|
||
- 文本文件: `.txt`
|
||
- 压缩包: `.zip`, `.rar`
|
||
|
||
### chapters（规程章节）
|
||
|
||
| 字段名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| id | String | 是 | 章节ID |
|
||
| chapterNumber / number | String | 是 | 章节编号（如"第一章"） |
|
||
| title / name | String | 是 | 章节标题 |
|
||
| order | Number | 否 | 排序序号 |
|
||
| contents / items | Array<String> | 是 | 章节内容列表 |
|
||
|
||
---
|
||
|
||
## 数据灵活性说明
|
||
|
||
前端代码已做兼容处理，支持以下字段别名：
|
||
|
||
**附件字段别名**:
|
||
- `name` 或 `fileName` → 文件名
|
||
- `url` 或 `fileUrl` → 文件地址
|
||
- `size` 或 `fileSize` → 文件大小
|
||
|
||
**章节字段别名**:
|
||
- `chapterNumber` 或 `number` → 章节编号
|
||
- `title` 或 `name` → 章节标题
|
||
- `contents` 或 `items` → 内容列表
|
||
|
||
---
|
||
|
||
## 业务规则
|
||
|
||
1. **附件和章节可选**: `attachments` 和 `chapters` 都是可选的，可以只返回其中一个或两个都返回
|
||
2. **空数据处理**: 如果两者都为空或不存在，前端会显示"暂无规程信息"
|
||
3. **文件下载**: 附件URL必须是可直接下载的完整地址
|
||
4. **章节排序**: 建议按 `order` 字段排序，如无该字段则按数组顺序展示
|
||
5. **内容格式**: 章节内容建议使用数组形式，每个元素为一条规则
|
||
|
||
---
|
||
|
||
## 错误响应
|
||
|
||
```json
|
||
{
|
||
"code": 404,
|
||
"message": "赛事规程不存在",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
```json
|
||
{
|
||
"code": 500,
|
||
"message": "服务器错误",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 前端实现说明
|
||
|
||
### 页面路径
|
||
`pages/event-rules/event-rules.vue`
|
||
|
||
### 主要功能
|
||
1. **附件下载**: 点击附件卡片可下载并打开文件
|
||
2. **章节展开**: 点击章节标题可展开/收起内容
|
||
3. **空状态**: 无数据时显示友好提示
|
||
4. **降级处理**: API失败时使用模拟数据
|
||
|
||
### 调用示例
|
||
```javascript
|
||
import competitionAPI from '@/api/competition.js'
|
||
|
||
// 获取规程数据
|
||
const res = await competitionAPI.getCompetitionRules(competitionId)
|
||
```
|
||
|
||
---
|
||
|
||
## 后端开发建议
|
||
|
||
### 数据库表设计参考
|
||
|
||
**赛事规程附件表** (`competition_rules_attachment`)
|
||
```sql
|
||
CREATE TABLE competition_rules_attachment (
|
||
id VARCHAR(32) PRIMARY KEY,
|
||
competition_id VARCHAR(32) NOT NULL,
|
||
file_name VARCHAR(255) NOT NULL,
|
||
file_url VARCHAR(500) NOT NULL,
|
||
file_size BIGINT,
|
||
file_type VARCHAR(20),
|
||
upload_time DATETIME,
|
||
INDEX idx_competition_id (competition_id)
|
||
);
|
||
```
|
||
|
||
**赛事规程章节表** (`competition_rules_chapter`)
|
||
```sql
|
||
CREATE TABLE competition_rules_chapter (
|
||
id VARCHAR(32) PRIMARY KEY,
|
||
competition_id VARCHAR(32) NOT NULL,
|
||
chapter_number VARCHAR(50) NOT NULL,
|
||
title VARCHAR(200) NOT NULL,
|
||
order_num INT DEFAULT 0,
|
||
INDEX idx_competition_id (competition_id)
|
||
);
|
||
```
|
||
|
||
**赛事规程内容表** (`competition_rules_content`)
|
||
```sql
|
||
CREATE TABLE competition_rules_content (
|
||
id VARCHAR(32) PRIMARY KEY,
|
||
chapter_id VARCHAR(32) NOT NULL,
|
||
content TEXT NOT NULL,
|
||
order_num INT DEFAULT 0,
|
||
INDEX idx_chapter_id (chapter_id)
|
||
);
|
||
```
|
||
|
||
---
|
||
|
||
## 管理后台功能需求
|
||
|
||
为了支持规程的上传和管理，建议后台提供以下功能：
|
||
|
||
1. **附件管理**
|
||
- 上传附件（支持多文件上传）
|
||
- 删除附件
|
||
- 预览附件
|
||
- 附件排序
|
||
|
||
2. **章节管理**
|
||
- 添加章节
|
||
- 编辑章节标题
|
||
- 删除章节
|
||
- 章节排序
|
||
- 添加/编辑/删除章节内容
|
||
|
||
3. **富文本编辑器**（可选）
|
||
- 支持富文本格式的规程内容编辑
|
||
- 支持图片上传
|
||
- 支持表格编辑
|
||
|
||
---
|
||
|
||
## 注意事项
|
||
|
||
1. **文件存储**: 建议使用OSS等云存储服务存储附件
|
||
2. **文件大小限制**: 建议单个文件不超过50MB
|
||
3. **文件类型限制**: 仅允许上传文档类文件，禁止可执行文件
|
||
4. **访问权限**: 附件URL建议设置有效期或访问权限控制
|
||
5. **CDN加速**: 建议为附件URL配置CDN加速下载
|