martial-mini/doc/赛事规程API设计.md

赛事规程 API 设计文档

接口说明

获取赛事规程

接口地址: /martial/competition/rules 请求方式: GET 接口描述: 获取指定赛事的规程信息，包括附件和章节内容

---

请求参数

参数名	类型	必填	说明
competitionId	String/Number	是	赛事ID

请求示例:

GET /martial/competition/rules?competitionId=123

---

返回数据结构

成功响应

{
  "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	是	章节内容列表

---

数据灵活性说明

前端代码已做兼容处理，支持以下字段别名：

附件字段别名:

• name 或 fileName → 文件名
• url 或 fileUrl → 文件地址
• size 或 fileSize → 文件大小

章节字段别名:

• chapterNumber 或 number → 章节编号
• title 或 name → 章节标题
• contents 或 items → 内容列表

---

业务规则

1. 附件和章节可选: attachments 和 chapters 都是可选的，可以只返回其中一个或两个都返回
2. 空数据处理: 如果两者都为空或不存在，前端会显示"暂无规程信息"
3. 文件下载: 附件URL必须是可直接下载的完整地址
4. 章节排序: 建议按 order 字段排序，如无该字段则按数组顺序展示
5. 内容格式: 章节内容建议使用数组形式，每个元素为一条规则

---

错误响应

{
  "code": 404,
  "message": "赛事规程不存在",
  "data": null
}

{
  "code": 500,
  "message": "服务器错误",
  "data": null
}

---

前端实现说明

页面路径

pages/event-rules/event-rules.vue

主要功能

1. 附件下载: 点击附件卡片可下载并打开文件
2. 章节展开: 点击章节标题可展开/收起内容
3. 空状态: 无数据时显示友好提示
4. 降级处理: API失败时使用模拟数据

调用示例

import competitionAPI from '@/api/competition.js'

// 获取规程数据
const res = await competitionAPI.getCompetitionRules(competitionId)

---

后端开发建议

数据库表设计参考

赛事规程附件表 (competition_rules_attachment)

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)

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)

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加速下载