项目初始化

This commit is contained in:
kron
2026-04-07 16:15:59 +08:00
commit 852e522695
97 changed files with 3137 additions and 0 deletions

View File

@@ -0,0 +1,47 @@
# 后台 API 说明
## 1. 定位
作为平台统一业务中台,服务微信小程序、商户后台和管理后台,承载核心业务逻辑与数据处理。
## 2. 建议领域模块
- 用户与认证
- 商户与资质审核
- 赛事管理
- 报名与订单
- 支付与退款
- 成绩与排名
- 消息通知
- 报表统计
## 3. 设计要求
- 业务规则集中管理,避免前端自行判断核心状态。
- 接口需保证幂等、权限隔离、日志审计。
- 与第三方平台交互需封装统一适配层。
## 4. 相关细分文档
### 4.1 架构与设计
- `领域模块划分.md`
- `认证与鉴权方案.md`
- `数据库表设计草案.md`
- `状态机设计建议.md`
- `缓存与异步任务设计.md`
- `第三方集成清单.md`
### 4.2 接口清单
- `接口清单规划.md`
- `字段级接口清单模板.md`
- `登录鉴权接口字段清单.md`
- `用户报名相关接口字段清单.md`
- `商户赛事管理接口字段清单.md`
- `平台审核与运营接口字段清单.md`
- `支付退款接口字段清单.md`
- `成绩与排名接口字段清单.md`
- `消息通知接口字段清单.md`
- `结算对账接口字段清单.md`
- `文件上传接口字段清单.md`
- `字典与配置接口字段清单.md`
## 5. 待确认项
- 是否采用单体 + 模块化架构,还是服务拆分。
- 是否使用统一网关、统一鉴权、统一日志链路。

View File

@@ -0,0 +1,53 @@
# 商户赛事管理接口字段清单
## 1. 创建赛事
- 接口路径:`POST /api/merchant/events`
- 功能说明:商户创建赛事草稿。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| eventName | string | 是 | 赛事名称 |
| eventCover | string | 是 | 封面图 |
| eventIntro | string | 是 | 简介 |
| location | string | 是 | 比赛地点 |
| startTime | string | 是 | 开赛时间 |
| endTime | string | 是 | 结束时间 |
| signupStartTime | string | 是 | 报名开始时间 |
| signupEndTime | string | 是 | 报名截止时间 |
| refundRule | string | 是 | 退款规则 |
| groupConfigList | array | 是 | 组别配置 |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| eventId | string | 新创建的赛事ID |
| eventStatus | string | 当前状态,通常为草稿 |
## 2. 提交赛事审核
- 接口路径:`POST /api/merchant/events/{eventId}/submit-review`
- 功能说明:将赛事从草稿提交为待审核。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| eventId | string | 是 | 赛事ID |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| eventId | string | 赛事ID |
| reviewStatus | string | 待审核 |
## 3. 查询报名列表
- 接口路径:`GET /api/merchant/signups`
- 功能说明:查询本商户下赛事的报名记录。
### 查询参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| eventId | string | 否 | 赛事ID |
| groupId | string | 否 | 组别ID |
| signupStatus | string | 否 | 报名状态 |
| payStatus | string | 否 | 支付状态 |
| keyword | string | 否 | 姓名/手机号搜索 |

View File

@@ -0,0 +1,20 @@
# 字典与配置接口字段清单
## 1. 获取基础字典
- 接口路径:`GET /api/common/dictionaries`
- 功能说明:获取组别、弓种、状态等前端通用枚举配置。
### 查询参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| dictType | string | 否 | 指定字典类型 |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| dictType | string | 字典类型 |
| items | array | 字典项列表 |
## 2. 获取平台配置
- 接口路径:`GET /api/common/configs`
- 功能说明:获取前端启动所需平台配置,如客服电话、隐私协议链接等。

View File

@@ -0,0 +1,32 @@
# 字段级接口清单模板
## 1. 使用方式
后续每个接口都建议按以下格式补齐,补完后即可直接交给 agent 编写 Controller、DTO、Service 和测试。
## 2. 模板
### 接口名称
- 接口路径:
- 请求方法:
- 使用端:用户端 / 商户端 / 管理端
- 功能说明:
- 权限要求:
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| | | | |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| | | |
### 错误码
| code | 场景 | 说明 |
| --- | --- | --- |
| | | |
### 备注
- 幂等要求:
- 状态变更:
- 日志要求:

View File

@@ -0,0 +1,59 @@
# 平台审核与运营接口字段清单
## 1. 商户审核列表
- 接口路径:`GET /api/admin/merchant-reviews`
- 功能说明:查询待审核或已审核的商户入驻记录。
### 查询参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| reviewStatus | string | 否 | 审核状态 |
| keyword | string | 否 | 商户名称/联系人 |
| page | number | 否 | 页码 |
| pageSize | number | 否 | 每页大小 |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| merchantId | string | 商户ID |
| merchantName | string | 商户名称 |
| contactName | string | 联系人 |
| reviewStatus | string | 审核状态 |
| submitTime | string | 提交时间 |
## 2. 审核商户入驻
- 接口路径:`POST /api/admin/merchant-reviews/{merchantId}/decision`
- 功能说明:审核通过或驳回商户入驻。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| merchantId | string | 是 | 商户ID |
| reviewResult | string | 是 | approve/reject |
| rejectReason | string | 驳回时必填 | 驳回原因 |
| internalRemark | string | 否 | 内部备注 |
## 3. 赛事审核操作
- 接口路径:`POST /api/admin/event-reviews/{eventId}/decision`
- 功能说明:审核赛事发布申请。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| eventId | string | 是 | 赛事ID |
| reviewResult | string | 是 | approve/reject |
| rejectReason | string | 驳回时必填 | 驳回原因 |
| riskTagList | array | 否 | 风险标签列表 |
## 4. 报表概览接口
- 接口路径:`GET /api/admin/dashboard/overview`
- 功能说明:获取平台运营关键指标。
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| totalMerchantCount | number | 商户总数 |
| totalEventCount | number | 赛事总数 |
| totalSignupCount | number | 报名总数 |
| totalPaidAmount | number | 支付总金额 |
| totalRefundAmount | number | 退款总金额 |

View File

@@ -0,0 +1,46 @@
# 成绩与排名接口字段清单
## 1. 商户录入成绩
- 接口路径:`POST /api/merchant/results/import`
- 功能说明:批量导入或提交成绩。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| eventId | string | 是 | 赛事ID |
| groupId | string | 是 | 组别ID |
| resultList | array | 是 | 成绩列表 |
## 2. 发布成绩
- 接口路径:`POST /api/merchant/results/publish`
- 功能说明:发布成绩并生成用户可见排名。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| eventId | string | 是 | 赛事ID |
| groupId | string | 否 | 指定组别 |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| publishStatus | string | 发布结果 |
| publishedCount | number | 发布记录数 |
## 3. 用户查询成绩
- 接口路径:`GET /api/user/results`
- 功能说明:查询用户自己的成绩与排名。
### 查询参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| eventId | string | 否 | 赛事ID |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| eventName | string | 赛事名称 |
| groupName | string | 组别 |
| totalScore | number | 总成绩 |
| rank | number | 排名 |
| resultStatus | string | 成绩状态 |

View File

@@ -0,0 +1,26 @@
# 接口清单规划
## 1. 用户端接口
- 登录 / 刷新 token
- 赛事列表 / 赛事详情
- 提交报名 / 查询我的报名
- 创建支付 / 查询支付结果
- 查询成绩 / 查询通知
## 2. 商户端接口
- 商户资料查询与更新
- 提交入驻申请
- 创建赛事 / 编辑赛事 / 提交审核
- 查询报名列表 / 核销签到
- 录入成绩 / 发布成绩
## 3. 管理端接口
- 商户审核列表 / 审核详情 / 审核操作
- 赛事审核列表 / 审核详情 / 审核操作
- 订单查询 / 退款复核
- 报表统计接口
## 4. 规划原则
- 先按业务域分组,再细化到接口级别。
- 接口命名保持统一风格。
- 所有写接口需带操作人上下文。

View File

@@ -0,0 +1,47 @@
# 支付退款接口字段清单
## 1. 创建支付单
- 接口路径:`POST /api/user/orders/{orderId}/pay`
- 功能说明:生成支付凭证,供小程序拉起支付。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| orderId | string | 是 | 订单ID |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| orderId | string | 订单ID |
| payParams | object | 支付参数对象 |
| payStatus | string | 当前支付状态 |
## 2. 发起退款申请
- 接口路径:`POST /api/user/refunds`
- 功能说明:用户发起退款申请。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| signupId | string | 是 | 报名单ID |
| reason | string | 是 | 退款原因 |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| refundId | string | 退款单ID |
| refundStatus | string | 当前退款状态 |
| refundAmount | number | 退款金额 |
## 3. 查询退款详情
- 接口路径:`GET /api/user/refunds/{refundId}`
- 功能说明:查看退款处理进度。
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| refundId | string | 退款单ID |
| refundStatus | string | 退款状态 |
| refundAmount | number | 退款金额 |
| reason | string | 退款原因 |
| processedAt | string | 处理时间 |

View File

@@ -0,0 +1,28 @@
# 数据库表设计草案
## 1. 文档目标
从关系型数据库角度,对核心业务表进行初步拆分,为后续建表和 ORM 设计提供依据。
## 2. 核心表建议
| 表名建议 | 用途 |
| --- | --- |
| users | 存储用户基础信息 |
| merchants | 商户主体信息 |
| merchant_audit_records | 商户审核记录 |
| events | 赛事主表 |
| event_groups | 赛事组别表 |
| signups | 报名单 |
| orders | 订单主表 |
| refunds | 退款单 |
| results | 成绩表 |
| notifications | 通知记录表 |
| admin_operation_logs | 管理后台操作日志 |
## 3. 设计建议
- 审核记录、操作日志建议独立存表。
- 订单与退款建议分表,便于幂等和对账。
- 状态字段建议使用枚举值,并补充状态说明表。
## 4. 待补充项
- 主键策略、索引设计、唯一约束。
- 分库分表或读写分离策略(如需要)。

View File

@@ -0,0 +1,23 @@
# 文件上传接口字段清单
## 1. 获取上传凭证
- 接口路径:`POST /api/common/upload-token`
- 功能说明:获取文件上传所需凭证或预签名地址。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| bizType | string | 是 | 业务类型,如 merchant_license/event_cover |
| fileName | string | 是 | 文件名 |
| contentType | string | 是 | 文件类型 |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| uploadUrl | string | 上传地址 |
| fileKey | string | 文件存储Key |
| expireAt | string | 过期时间 |
## 2. 上传完成回写
- 接口路径:`POST /api/common/upload-callback`
- 功能说明:记录文件上传完成后的元数据。

View File

@@ -0,0 +1,26 @@
# 消息通知接口字段清单
## 1. 查询通知列表
- 接口路径:`GET /api/user/notifications`
- 功能说明:获取当前用户通知列表。
### 查询参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| page | number | 否 | 页码 |
| pageSize | number | 否 | 每页大小 |
| readStatus | string | 否 | 已读/未读 |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| notificationId | string | 通知ID |
| title | string | 标题 |
| content | string | 内容摘要 |
| bizType | string | 业务类型 |
| readStatus | string | 已读状态 |
| createdAt | string | 创建时间 |
## 2. 标记已读
- 接口路径:`POST /api/user/notifications/{notificationId}/read`
- 功能说明:将通知标记为已读。

View File

@@ -0,0 +1,23 @@
# 状态机设计建议
## 1. 目标
为后台 API 的状态流转实现提供统一设计建议,避免不同模块各自维护状态导致混乱。
## 2. 建议纳入状态机管理的对象
- 商户入驻状态
- 赛事状态
- 报名单状态
- 订单状态
- 退款单状态
- 成绩发布状态
## 3. 设计原则
- 状态变化必须由明确事件触发。
- 非法状态跳转应统一拦截。
- 每次状态变化需要记录操作人、时间、原因。
- 尽量避免前端拼凑状态逻辑。
## 4. 实现建议
- 在领域服务层集中处理状态变更。
- 为关键状态机编写转移表与单元测试。
- 支持审计日志和状态回溯。

View File

@@ -0,0 +1,64 @@
# 用户报名相关接口字段清单
## 1. 获取赛事详情
- 接口路径:`GET /api/user/events/{eventId}`
- 功能说明:获取赛事详情页所需数据。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| eventId | string | 是 | 赛事ID |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| eventId | string | 赛事ID |
| eventName | string | 赛事名称 |
| eventCover | string | 封面图 |
| eventStatus | string | 赛事状态 |
| signupStartTime | string | 报名开始时间 |
| signupEndTime | string | 报名截止时间 |
| groupList | array | 组别列表 |
| location | string | 比赛地点 |
| ruleSummary | string | 规则摘要 |
| noticeText | string | 参赛须知 |
## 2. 提交报名
- 接口路径:`POST /api/user/signups`
- 功能说明:提交报名信息并生成待支付订单。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| eventId | string | 是 | 赛事ID |
| groupId | string | 是 | 组别ID |
| participantName | string | 是 | 报名人姓名 |
| participantPhone | string | 是 | 联系电话 |
| gender | string | 否 | 性别 |
| birthday | string | 否 | 出生日期 |
| remark | string | 否 | 备注 |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| signupId | string | 报名单ID |
| orderId | string | 待支付订单ID |
| amount | number | 支付金额 |
| payStatus | string | 支付状态 |
## 3. 查询我的报名列表
- 接口路径:`GET /api/user/signups`
- 功能说明:获取用户个人报名记录。
### 查询参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| page | number | 否 | 页码 |
| pageSize | number | 否 | 每页数量 |
| signupStatus | string | 否 | 报名状态 |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| list | array | 报名记录列表 |
| total | number | 总数 |

View File

@@ -0,0 +1,39 @@
# 登录鉴权接口字段清单
## 1. 用户微信登录
- 接口路径:`POST /api/auth/wechat-login`
- 功能说明:用户通过微信授权登录并获取 token。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| code | string | 是 | 微信登录 code |
| encryptedData | string | 否 | 加密用户信息 |
| iv | string | 否 | 解密向量 |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| token | string | 登录态 token |
| refreshToken | string | 刷新 token |
| userId | string | 用户ID |
| isPhoneBound | boolean | 是否已绑定手机号 |
## 2. 商户/平台账号登录
- 接口路径:`POST /api/auth/password-login`
- 功能说明:商户后台或管理后台账号密码登录。
### 请求参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| account | string | 是 | 登录账号 |
| password | string | 是 | 登录密码 |
| loginType | string | 是 | merchant/admin |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| token | string | 登录态 token |
| refreshToken | string | 刷新 token |
| roleList | array | 角色列表 |
| userInfo | object | 用户信息 |

View File

@@ -0,0 +1,18 @@
# 第三方集成清单
## 1. 文档目标
列出平台建设过程中可能涉及的第三方服务,为接口封装和运维准备提供依据。
## 2. 建议集成项
| 能力 | 服务示例 | 用途 |
| --- | --- | --- |
| 微信登录 | 微信开放能力 | 用户身份获取 |
| 微信支付 | 微信支付 | 报名支付与退款 |
| 对象存储 | OSS/COS/S3 类服务 | 上传资质、赛事封面、附件 |
| 短信服务 | 第三方短信平台 | 验证码、关键通知 |
| 日志监控 | APM / 日志平台 | 告警、排障、审计 |
## 3. 集成原则
- 第三方调用统一封装适配层。
- 凭据通过环境变量或密钥系统管理。
- 调用失败要有重试、告警和兜底。

View File

@@ -0,0 +1,25 @@
# 结算对账接口字段清单
## 1. 商户结算列表
- 接口路径:`GET /api/merchant/settlements`
- 功能说明:查询商户结算记录。
### 查询参数
| 字段 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| settlementStatus | string | 否 | 结算状态 |
| page | number | 否 | 页码 |
| pageSize | number | 否 | 每页数量 |
### 返回字段
| 字段 | 类型 | 说明 |
| --- | --- | --- |
| settlementId | string | 结算单ID |
| settlementAmount | number | 结算金额 |
| settlementStatus | string | 结算状态 |
| settlementPeriod | string | 结算周期 |
| createdAt | string | 创建时间 |
## 2. 平台对账结果查询
- 接口路径:`GET /api/admin/reconciliations`
- 功能说明:查询支付对账结果和差异记录。

View File

@@ -0,0 +1,21 @@
# 缓存与异步任务设计
## 1. 文档目标
为高频查询、消息发送、导出任务、支付补偿等场景提供技术设计建议。
## 2. 适合缓存的场景
- 热门赛事列表
- 基础字典与组别配置
- 已发布赛事详情(短期缓存)
## 3. 适合异步化的任务
- 通知消息发送
- 导出报名名单与成绩单
- 对账任务
- 支付/退款异常补偿任务
- 报表汇总任务
## 4. 设计原则
- 缓存必须有失效策略。
- 异步任务要具备幂等与重试机制。
- 失败任务需可追踪、可人工重放。

View File

@@ -0,0 +1,26 @@
# 认证与鉴权方案
## 1. 文档目标
统一描述用户、商户、平台三类身份的登录认证和接口鉴权方式。
## 2. 身份类型
| 身份 | 来源端 | 说明 |
| --- | --- | --- |
| 用户 | 微信小程序 | 通过微信登录获取身份 |
| 商户账号 | 商户后台 | 使用账号密码或验证码登录 |
| 平台账号 | 管理后台 | 平台内部账号登录 |
## 3. 鉴权建议
- 登录成功后签发统一 token。
- token 中需包含身份类型、用户ID、角色信息。
- 后端根据角色与资源进行权限校验。
- 高风险接口需二次校验或更严格的权限控制。
## 4. 安全要求
- token 失效与刷新机制要明确。
- 敏感操作要有审计日志。
- 管理后台和商户后台建议支持强密码策略或 MFA如后续需要
## 5. 待确认项
- 是否统一采用 JWT。
- 是否引入 RBAC 或更细粒度权限模型。

View File

@@ -0,0 +1,24 @@
# 领域模块划分
## 1. 目标
从领域模型角度拆分后台 API 的模块边界,方便后续按模块开发、测试和维护。
## 2. 推荐模块
| 模块 | 主要职责 |
| --- | --- |
| 认证与用户 | 登录鉴权、用户资料、token 管理 |
| 商户中心 | 商户资料、入驻审核、状态管理 |
| 赛事中心 | 赛事创建、组别配置、状态流转 |
| 报名中心 | 报名资格校验、报名记录管理 |
| 订单中心 | 订单创建、支付回调、关闭订单 |
| 退款中心 | 退款申请、退款回调、异常处理 |
| 成绩中心 | 成绩录入、排名计算、成绩发布 |
| 审核中心 | 商户审核、赛事审核、驳回原因管理 |
| 通知中心 | 站内消息、订阅消息、短信能力 |
| 报表中心 | 报名统计、交易统计、运营数据 |
## 3. 模块边界原则
- 订单与支付状态以订单中心为准。
- 赛事规则与状态流转以赛事中心为准。
- 审核动作统一经过审核中心留痕。
- 外部渠道适配统一收敛到基础设施层。