项目初始化

05-通用基础/接口约定与返回规范.md

@@ -0,0 +1,41 @@
+# 接口约定与返回规范
+
+## 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. 设计要求
+- 所有写接口必须记录操作人。
+- 支付回调、退款回调类接口必须保证幂等。
+- 涉及列表查询的接口需明确筛选条件和排序规则。