# 接口约定与返回规范

## 1. 目标
统一前后端接口风格，降低多端协作成本，并为后续生成 OpenAPI 文档提供基础约束。

## 2. 通用约定
- 协议：HTTPS
- 数据格式：`application/json`
- 时间字段：统一使用 ISO 8601 或毫秒时间戳（待最终确定）
- 分页参数建议：`page`、`pageSize`

## 3. 推荐返回结构
```json
{
  "code": 0,
  "message": "success",
  "data": {},
  "requestId": "string"
}
```

## 4. 错误码建议
| code | 含义 |
| --- | --- |
| 0 | 成功 |
| 40001 | 参数错误 |
| 40101 | 未登录或登录失效 |
| 40301 | 无权限访问 |
| 40401 | 资源不存在 |
| 40901 | 状态冲突 |
| 50001 | 系统异常 |

## 5. 接口分类建议
- 用户端接口：登录、赛事列表、赛事详情、报名、支付、我的报名、成绩查询
- 商户端接口：商户资料、赛事管理、报名管理、成绩录入、数据导出
- 管理端接口：商户审核、赛事审核、用户管理、报表统计

## 6. 设计要求
- 所有写接口必须记录操作人。
- 支付回调、退款回调类接口必须保证幂等。
- 涉及列表查询的接口需明确筛选条件和排序规则。