397 lines
13 KiB
Markdown
397 lines
13 KiB
Markdown
# H5 会员管理接口需求与技术方案
|
||
|
||
> 作者：湖北新华业务中台研发团队
|
||
> 创建时间：2026-02-02
|
||
> 版本：v1.1
|
||
|
||
---
|
||
|
||
## 一、需求概述
|
||
|
||
为H5前端提供会员管理相关接口，包括认证、注册、个人信息管理、教育身份管理、学生绑定等功能。
|
||
|
||
---
|
||
|
||
## 二、接口需求设计
|
||
|
||
### 2.1 认证模块（OAuth 2.0）
|
||
|
||
#### 2.1.1 密码登录
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /h5/auth/login/password` |
|
||
| **请求参数** | phone（手机号）、password（密码）、captchaCode（图形验证码）、uuid（验证码标识）、rememberMe（记住我） |
|
||
| **返回** | accessToken、refreshToken、expiresIn、会员基本信息 |
|
||
|
||
#### 2.1.2 短信验证码登录
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /h5/auth/login/sms` |
|
||
| **请求参数** | phone（手机号）、smsCode（短信验证码）、captchaCode（图形验证码）、uuid |
|
||
| **短信平台** | **阿里云短信服务** |
|
||
| **返回** | accessToken、refreshToken、expiresIn、会员基本信息 |
|
||
|
||
#### 2.1.3 获取图形验证码
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `GET /h5/auth/captcha` |
|
||
| **返回** | uuid、captchaImg（Base64图片） |
|
||
|
||
#### 2.1.4 发送短信验证码（阿里云）
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /h5/auth/sms/send` |
|
||
| **请求参数** | phone、captchaCode、uuid、type（login/register） |
|
||
| **短信平台** | **阿里云短信服务** |
|
||
| **返回** | 发送结果、倒计时秒数（60秒） |
|
||
|
||
#### 2.1.5 刷新Token
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /h5/auth/refresh` |
|
||
| **请求参数** | refreshToken |
|
||
| **返回** | 新的 accessToken、refreshToken |
|
||
|
||
#### 2.1.6 退出登录
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /h5/auth/logout` |
|
||
|
||
---
|
||
|
||
### 2.2 注册模块
|
||
|
||
#### 2.2.1 注册 - 提交基本信息
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /h5/auth/register` |
|
||
| **请求参数** | phone、smsCode、captchaCode、uuid、password |
|
||
| **短信平台** | **阿里云短信服务** |
|
||
| **业务逻辑** | 1. 校验手机号未注册<br>2. 校验验证码<br>3. 创建会员账号<br>4. 自动登录返回Token |
|
||
| **返回** | accessToken、refreshToken、memberId |
|
||
|
||
#### 2.2.2 完善身份信息（可选）
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /h5/member/identity` |
|
||
| **请求参数** | identityType（parent/teacher） |
|
||
|
||
---
|
||
|
||
### 2.3 会员信息模块
|
||
|
||
#### 2.3.1 获取当前会员信息
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `GET /h5/member/info` |
|
||
| **返回** | memberId、phone（脱敏）、nickname、avatar、gender、birthday、registerTime、identityType、教育信息、绑定学生列表 |
|
||
|
||
#### 2.3.2 修改会员基本信息
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `PUT /h5/member/info` |
|
||
| **可修改字段** | nickname（昵称）、gender（性别）、birthday（生日） |
|
||
| **备注** | 手机号不可修改 |
|
||
|
||
---
|
||
|
||
### 2.4 密码管理
|
||
|
||
#### 2.4.1 修改密码
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `PUT /h5/member/password` |
|
||
| **请求参数** | oldPassword（当前密码）、newPassword（新密码）、confirmPassword（确认新密码） |
|
||
| **校验** | 新密码至少6位，包含字母、数字或符号 |
|
||
|
||
---
|
||
|
||
### 2.5 教育身份管理（教师身份）
|
||
|
||
#### 2.5.1 添加/修改教育身份
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /h5/member/education` |
|
||
| **请求参数** | schoolId（学校）、schoolGradeId（年级）、schoolClassId（班级）、subjectId（学科） |
|
||
| **业务逻辑** | 设置会员身份为"教师"，关联学校班级学科信息 |
|
||
|
||
#### 2.5.2 获取教育身份信息
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `GET /h5/member/education` |
|
||
| **返回** | 学校、年级、班级、学科名称及ID |
|
||
|
||
#### 2.5.3 删除教育身份
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `DELETE /h5/member/education` |
|
||
|
||
---
|
||
|
||
### 2.6 绑定学生管理（家长/教师均可）
|
||
|
||
#### 2.6.1 绑定学生
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `POST /h5/member/student` |
|
||
| **请求参数** | studentName（学生姓名）、studentNo（学号）、birthday（出生日期）、gender（性别）、regionId（地区）、schoolId、schoolGradeId、schoolClassId |
|
||
| **业务逻辑** | 1. 创建学生记录<br>2. 关联当前会员<br>3. **家长和教师身份均可绑定学生** |
|
||
|
||
#### 2.6.2 获取绑定的学生列表
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `GET /h5/member/students` |
|
||
| **返回** | 学生列表（含学校、年级、班级名称） |
|
||
|
||
#### 2.6.3 修改学生信息
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `PUT /h5/member/student/{studentId}` |
|
||
| **请求参数** | 同绑定学生 |
|
||
|
||
#### 2.6.4 解绑学生
|
||
| 项目 | 说明 |
|
||
|------|------|
|
||
| **接口** | `DELETE /h5/member/student/{studentId}` |
|
||
|
||
---
|
||
|
||
### 2.7 基础数据接口（公开）
|
||
|
||
| 接口 | 说明 |
|
||
|------|------|
|
||
| `GET /h5/base/regions` | 获取区域树（省市区） |
|
||
| `GET /h5/base/schools?regionId=xxx` | 根据区域获取学校列表 |
|
||
| `GET /h5/base/grades?schoolId=xxx` | 根据学校获取年级列表 |
|
||
| `GET /h5/base/classes?schoolGradeId=xxx` | 根据年级获取班级列表 |
|
||
| `GET /h5/base/subjects` | 获取学科列表 |
|
||
|
||
---
|
||
|
||
### 2.8 接口规范
|
||
|
||
| 规范项 | 说明 |
|
||
|------|------|
|
||
| **认证方式** | OAuth 2.0 Bearer Token，Header: `Authorization: Bearer {accessToken}` |
|
||
| **Token有效期** | accessToken: 2小时，refreshToken: 7天（记住我30天） |
|
||
| **响应格式** | `{ code: 200, msg: "success", data: {...} }` |
|
||
| **错误码** | 401-未认证，403-无权限，10001-验证码错误，10002-密码错误，10003-手机号已注册 |
|
||
| **短信服务** | 阿里云短信 |
|
||
|
||
---
|
||
|
||
## 三、技术方案
|
||
|
||
### 3.1 项目结构设计
|
||
|
||
在 `pangu-business` 模块下新建 `h5` 包：
|
||
|
||
```
|
||
backend/ruoyi-modules/pangu-business/src/main/java/org/dromara/pangu/
|
||
├── h5/ # H5接口模块
|
||
│ ├── config/
|
||
│ │ └── H5SmsProperties.java # 短信防刷配置类
|
||
│ ├── controller/
|
||
│ │ ├── H5AuthController.java # 认证接口
|
||
│ │ ├── H5MemberController.java # 会员信息接口
|
||
│ │ └── H5BaseDataController.java # 基础数据接口
|
||
│ ├── service/
|
||
│ │ ├── H5AuthService.java # 认证服务接口
|
||
│ │ ├── impl/
|
||
│ │ │ └── H5AuthServiceImpl.java # 认证服务实现
|
||
│ │ ├── H5MemberService.java # 会员服务接口
|
||
│ │ └── impl/
|
||
│ │ └── H5MemberServiceImpl.java # 会员服务实现
|
||
│ └── domain/
|
||
│ ├── dto/ # 请求DTO
|
||
│ │ ├── H5PasswordLoginDto.java # 密码登录
|
||
│ │ ├── H5SmsLoginDto.java # 短信登录
|
||
│ │ ├── H5RegisterDto.java # 注册
|
||
│ │ ├── H5SmsSendDto.java # 发送短信
|
||
│ │ ├── H5MemberUpdateDto.java # 会员信息修改
|
||
│ │ ├── H5PasswordUpdateDto.java # 密码修改
|
||
│ │ ├── H5EducationDto.java # 教育身份
|
||
│ │ └── H5StudentBindDto.java # 绑定学生
|
||
│ └── vo/ # 响应VO
|
||
│ ├── H5LoginVo.java # 登录响应
|
||
│ ├── H5CaptchaVo.java # 验证码响应
|
||
│ ├── H5MemberInfoVo.java # 会员信息
|
||
│ ├── H5EducationVo.java # 教育身份
|
||
│ └── H5StudentVo.java # 学生信息
|
||
```
|
||
|
||
### 3.2 接口路径规划
|
||
|
||
| 模块 | 路径前缀 | 认证要求 |
|
||
|------|---------|---------|
|
||
| 认证接口 | `/h5/auth/*` | 无需认证 |
|
||
| 会员接口 | `/h5/member/*` | 需要Token |
|
||
| 基础数据 | `/h5/base/*` | 无需认证 |
|
||
|
||
### 3.3 认证方案（Sa-Token）
|
||
|
||
#### Token 策略
|
||
|
||
| 配置项 | 值 | 说明 |
|
||
|--------|-----|------|
|
||
| Token 存储 | Redis | 支持分布式 |
|
||
| accessToken 有效期 | 2小时 | 常规访问 |
|
||
| refreshToken 有效期 | 7天/30天 | 记住我时30天 |
|
||
| Token 传递方式 | Header | `Authorization: Bearer {token}` |
|
||
| 设备类型 | h5 | 区分多端登录 |
|
||
|
||
#### 安全配置
|
||
|
||
在 `SecurityConfig.java` 中添加H5接口放行规则：
|
||
|
||
```java
|
||
// H5公开接口（无需认证）
|
||
.excludePathPatterns(
|
||
"/h5/auth/**", // 登录/注册/验证码
|
||
"/h5/base/**" // 基础数据
|
||
)
|
||
```
|
||
|
||
### 3.4 短信服务（阿里云）
|
||
|
||
复用现有 `sms4j` 模块（版本 3.3.5），集成阿里云短信服务。
|
||
|
||
#### 阿里云账号信息
|
||
|
||
| 配置项 | 值 | 说明 |
|
||
|--------|-----|------|
|
||
| AccessKey ID | `LTAI5tQLorTxf9Fzzh93pfGN` | 阿里云访问密钥 |
|
||
| AccessKey Secret | `NhBZGwac5vvWg60R0Y4UndTsKK4zuh` | 阿里云密钥 |
|
||
| Endpoint | `dysmsapi.aliyuncs.com` | 短信API地址 |
|
||
| 签名 | `湖北新华教育服务平台` | 短信签名（已审核通过） |
|
||
|
||
#### 短信模板
|
||
|
||
| 模板用途 | 模板ID | 模板内容 |
|
||
|----------|--------|----------|
|
||
| 登录验证码 | `SMS_461020580` | 【湖北新华教育服务平台】您正在申请登录，验证码为：${code} |
|
||
| 注册验证码 | `SMS_473140005` | 【湖北新华教育服务平台】您正在申请注册，验证码为：${code} |
|
||
| 重置密码 | `SMS_473130008` | 用于忘记密码（备用） |
|
||
|
||
#### 阿里云配置（application-dev.yml）
|
||
|
||
```yaml
|
||
sms:
|
||
config-type: yaml
|
||
restricted: true
|
||
minute-max: 1
|
||
account-max: 30
|
||
blends:
|
||
alibaba:
|
||
supplier: alibaba
|
||
access-key-id: LTAI5tQLorTxf9Fzzh93pfGN
|
||
access-key-secret: NhBZGwac5vvWg60R0Y4UndTsKK4zuh
|
||
signature: 湖北新华教育服务平台
|
||
```
|
||
|
||
#### H5短信配置（application.yml）
|
||
|
||
```yaml
|
||
h5:
|
||
sms:
|
||
# 是否真正发送短信（开发测试设false，生产设true）
|
||
enabled: true
|
||
sms-config-name: alibaba
|
||
|
||
# 短信模板ID
|
||
login-template-id: SMS_461020580
|
||
register-template-id: SMS_473140005
|
||
|
||
# 验证码配置
|
||
code-length: 6
|
||
code-expire-minutes: 5
|
||
|
||
# 防刷策略
|
||
send-interval-seconds: 60
|
||
daily-limit-per-phone: 10
|
||
minute-limit-per-ip: 5
|
||
daily-limit-per-ip: 50
|
||
blacklist-minutes: 30
|
||
blacklist-trigger-count: 5
|
||
```
|
||
|
||
#### 防刷策略
|
||
|
||
| 层级 | 策略 | 配置项 | 默认值 |
|
||
|------|------|--------|--------|
|
||
| 前置 | 图形验证码校验 | - | 必须 |
|
||
| 手机号 | 黑名单检查 | `blacklist-minutes` | 30分钟 |
|
||
| 手机号 | 发送间隔限制 | `send-interval-seconds` | 60秒 |
|
||
| 手机号 | 每日发送上限 | `daily-limit-per-phone` | 10条 |
|
||
| IP | 黑名单检查 | `blacklist-minutes` | 30分钟 |
|
||
| IP | 每分钟发送上限 | `minute-limit-per-ip` | 5条 |
|
||
| IP | 每日发送上限 | `daily-limit-per-ip` | 50条 |
|
||
| 验证 | 连续失败自动封禁 | `blacklist-trigger-count` | 5次 |
|
||
|
||
#### 验证码发送流程
|
||
|
||
1. 校验图形验证码
|
||
2. 检查手机号是否在黑名单
|
||
3. 检查IP是否在黑名单
|
||
4. 检查发送间隔（60秒）
|
||
5. 检查手机号每日上限
|
||
6. 检查IP每分钟上限
|
||
7. 检查IP每日上限
|
||
8. 业务校验（注册：手机号未注册；登录：手机号已注册）
|
||
9. 生成验证码并存入Redis
|
||
10. 更新各项计数器
|
||
11. 调用阿里云API发送（测试模式仅打印日志）
|
||
|
||
#### Redis Key 设计
|
||
|
||
| Key | 说明 | TTL |
|
||
|-----|------|-----|
|
||
| `h5:sms:code:{type}:{phone}` | 验证码 | 5分钟 |
|
||
| `h5:sms:daily:phone:{date}:{phone}` | 手机号每日计数 | 1天 |
|
||
| `h5:sms:minute:ip:{ip}` | IP每分钟计数 | 1分钟 |
|
||
| `h5:sms:daily:ip:{date}:{ip}` | IP每日计数 | 1天 |
|
||
| `h5:sms:blacklist:phone:{phone}` | 手机号黑名单 | 30分钟 |
|
||
| `h5:sms:blacklist:ip:{ip}` | IP黑名单 | 30分钟 |
|
||
| `h5:sms:fail:{phone}` | 验证失败计数 | 5分钟 |
|
||
|
||
### 3.5 数据库设计
|
||
|
||
复用现有表结构，无需新增表：
|
||
- `pg_member` - 会员表
|
||
- `pg_student` - 学生表
|
||
- `pg_school` / `pg_school_grade` / `pg_school_class` - 学校相关
|
||
- `pg_region` - 区域表
|
||
- `pg_subject` - 学科表
|
||
|
||
### 3.6 依赖关系
|
||
|
||
```
|
||
H5 Controller
|
||
↓
|
||
H5 Service（新建）
|
||
↓
|
||
复用现有 Service/Mapper
|
||
├── IPgMemberService
|
||
├── IPgStudentService
|
||
├── IPgSchoolService
|
||
└── 基础数据 Service
|
||
```
|
||
|
||
---
|
||
|
||
## 四、开发清单
|
||
|
||
| 序号 | 内容 | 文件 |
|
||
|------|------|------|
|
||
| 1 | DTO类 | H5PasswordLoginDto, H5SmsLoginDto, H5RegisterDto, H5SmsSendDto, H5MemberUpdateDto, H5PasswordUpdateDto, H5EducationDto, H5StudentBindDto |
|
||
| 2 | VO类 | H5LoginVo, H5CaptchaVo, H5MemberInfoVo, H5EducationVo, H5StudentVo |
|
||
| 3 | 认证服务 | H5AuthService, H5AuthServiceImpl |
|
||
| 4 | 会员服务 | H5MemberService, H5MemberServiceImpl |
|
||
| 5 | Controller | H5AuthController, H5MemberController, H5BaseDataController |
|
||
| 6 | 安全配置 | SecurityConfig（添加放行规则） |
|
||
| 7 | 短信配置 | application-dev.yml |
|
||
|
||
---
|
||
|
||
*最后更新: 2026-02-02*
|