项目初始化

05-通用基础/README.md

@@ -0,0 +1,10 @@
+# 通用基础
+
+本目录存放跨端共用的系统基础说明文档。
+
+## 包含内容
+- `系统架构总览.md`
+- `开发规范与协作约定.md`
+- `角色与权限矩阵.md`
+- `核心数据模型草案.md`
+- `接口约定与返回规范.md`

05-通用基础/开发规范与协作约定.md

@@ -0,0 +1,26 @@
+# 开发规范与协作约定
+
+## 1. 文档目标
+统一后续多人协作、agent 执行、代码提交和文档补充的方式，减少返工与沟通成本。
+
+## 2. 命名规范建议
+- 文档：采用中文 + 编号方式命名。
+- API：统一使用资源化命名风格。
+- 数据库字段：统一小写下划线风格（建议）。
+- 状态值：优先使用枚举常量，避免散落 magic value。
+
+## 3. 分支与提交建议
+- 需求变更应有对应文档更新。
+- commit message 建议使用中文并带类型前缀，例如：`feat:`、`fix:`、`docs:`、`refactor:`。
+- 接口变更需同步更新接口文档与前端调用说明。
+
+## 4. 协作约定
+- 先补文档，再拆任务，再开发。
+- 核心业务规则必须在文档中确认后再编码。
+- 重要状态流转和异常处理需有测试覆盖。
+
+## 5. 适合交给 agent 的任务类型
+- 页面脚手架与模块初始化
+- API 路由和 DTO 生成
+- 数据表初稿与接口联调
+- 单元测试与接口测试补齐

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

05-通用基础/核心数据模型草案.md

@@ -0,0 +1,82 @@
+# 核心数据模型草案
+
+## 1. 目标
+梳理核心业务对象，便于后续设计数据库表结构、接口字段和前端页面模型。
+
+## 2. 核心实体
+
+### 2.1 用户 User
+- userId
+- nickname
+- avatar
+- phone
+- status
+- createdAt
+
+### 2.2 商户 Merchant
+- merchantId
+- merchantName
+- contactName
+- contactPhone
+- licenseNo
+- reviewStatus
+- settledAt
+
+### 2.3 赛事 Event
+- eventId
+- merchantId
+- eventName
+- eventStatus
+- location
+- startTime
+- endTime
+- signupStartTime
+- signupEndTime
+- refundRule
+
+### 2.4 组别 EventGroup
+- groupId
+- eventId
+- groupName
+- capacity
+- price
+- ruleSummary
+
+### 2.5 报名单 Signup
+- signupId
+- userId
+- eventId
+- groupId
+- signupStatus
+- orderId
+- checkinStatus
+
+### 2.6 订单 Order
+- orderId
+- bizType
+- bizId
+- amount
+- payStatus
+- paidAt
+- refundStatus
+
+### 2.7 成绩 Result
+- resultId
+- eventId
+- userId
+- score
+- rank
+- resultStatus
+- publishedAt
+
+## 3. 关系说明
+- 一个商户可以有多个赛事。
+- 一个赛事可以有多个组别。
+- 一个用户可在不同赛事下拥有多条报名记录。
+- 一条报名记录通常对应一个订单。
+- 一个赛事结束后会产生多条成绩记录。
+
+## 4. 待确认项
+- 是否需要单独建“队伍/团体”实体。
+- 是否支持多人一单。
+- 是否支持分轮成绩与最终成绩分开存储。

05-通用基础/系统架构总览.md

@@ -0,0 +1,35 @@
+# 系统架构总览
+
+## 1. 文档目标
+说明射箭赛事平台四个代码工程之间的职责分工、调用关系与边界，作为后续系统设计和开发拆分依据。
+
+## 2. 四个工程的定位
+| 工程 | 面向对象 | 核心职责 |
+| --- | --- | --- |
+| 微信小程序 | 参赛用户 | 浏览赛事、报名支付、查看通知与成绩 |
+| 商户后台 | 赛事主办方 | 维护赛事、处理报名、录入成绩、查看数据 |
+| 管理后台 | 平台运营 | 审核商户、审核赛事、风控治理、报表统计 |
+| 后台 API 服务 | 全部客户端 | 提供统一业务接口、权限控制、订单支付、成绩与消息能力 |
+
+## 3. 推荐逻辑架构
+- 展示层：微信小程序、商户后台、管理后台
+- 接口层：统一后台 API
+- 领域层：用户、商户、赛事、报名、订单、成绩、通知、审核
+- 基础设施层：数据库、缓存、对象存储、消息通知、支付能力
+
+## 4. 系统交互关系
+1. 用户通过微信小程序调用后台 API 完成登录、报名、支付。
+2. 商户后台调用后台 API 完成赛事管理、报名管理、成绩录入。
+3. 管理后台调用后台 API 完成审核、运营配置、数据查询。
+4. 后台 API 对接微信登录、微信支付、短信/订阅消息等第三方能力。
+
+## 5. 设计原则
+- 业务规则统一收敛在后台 API，避免多端逻辑分叉。
+- 商户与平台的权限边界必须清晰隔离。
+- 接口设计优先稳定、可扩展、可审计。
+- 文档命名与术语优先统一，便于 agent 自动续写。
+
+## 6. 当前待定项
+- 前端框架与后端语言尚未确定。
+- 是否采用单体架构还是模块化服务架构待后续决策。
+- 消息通知、对象存储、日志平台的具体选型待确认。

05-通用基础/角色与权限矩阵.md

@@ -0,0 +1,31 @@
+# 角色与权限矩阵
+
+## 1. 目标
+统一定义各角色在系统中的可见范围与可执行操作，避免前后端权限理解不一致。
+
+## 2. 角色定义
+| 角色 | 所属端 | 说明 |
+| --- | --- | --- |
+| 普通用户 | 微信小程序 | 参赛者、报名者 |
+| 商户管理员 | 商户后台 | 商户主账号，拥有本机构全部管理权限 |
+| 商户子账号 | 商户后台 | 受限账号，可按模块授权 |
+| 平台审核员 | 管理后台 | 审核商户和赛事 |
+| 平台运营管理员 | 管理后台 | 负责配置、报表、异常处理 |
+
+## 3. 权限矩阵
+| 功能 | 用户 | 商户管理员 | 商户子账号 | 平台审核员 | 平台运营管理员 |
+| --- | --- | --- | --- | --- | --- |
+| 浏览赛事 | ✅ | ✅ | ✅ | ✅ | ✅ |
+| 提交报名 | ✅ | ❌ | ❌ | ❌ | ❌ |
+| 创建赛事 | ❌ | ✅ | 可授权 | ❌ | ❌ |
+| 编辑赛事 | ❌ | ✅ | 可授权 | ❌ | ❌ |
+| 提交赛事审核 | ❌ | ✅ | 可授权 | ❌ | ❌ |
+| 审核赛事 | ❌ | ❌ | ❌ | ✅ | ✅ |
+| 审核商户入驻 | ❌ | ❌ | ❌ | ✅ | ✅ |
+| 录入成绩 | ❌ | ✅ | 可授权 | ❌ | ❌ |
+| 查看平台总报表 | ❌ | ❌ | ❌ | 可查看部分 | ✅ |
+
+## 4. 原则
+- 商户只能访问本机构相关数据。
+- 平台角色具备跨商户管理能力，但需留痕。
+- 高风险操作需具备二次确认与日志审计。