# 赛事规程 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加速下载