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. 校验手机号未注册
2. 校验验证码
3. 创建会员账号
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. 创建学生记录
2. 关联当前会员
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接口放行规则：
// H5公开接口（无需认证）
.excludePathPatterns(
"/h5/auth/**", // 登录/注册/验证码
"/h5/base/**" // 基础数据
)
3.4 短信服务（阿里云）
复用现有 sms4j 模块（版本 3.3.5），集成阿里云短信服务。
阿里云准备工作
| 步骤 |
操作 |
说明 |
| 1 |
开通短信服务 |
阿里云短信控制台 |
| 2 |
创建 AccessKey |
建议使用 RAM 子账号，仅授予 AliyunDysmsFullAccess 权限 |
| 3 |
申请短信签名 |
签名管理 → 添加签名，审核通过后使用 |
| 4 |
申请短信模板 |
模板管理 → 添加模板，需包含 ${code} 变量 |
短信模板示例：
验证码为${code}，${minutes}分钟内有效，请勿泄露给他人。
阿里云配置（application-dev.yml）
sms:
config-type: yaml
restricted: true
minute-max: 1
account-max: 30
blends:
# 配置名称 "alibaba" 与 h5.sms.sms-config-name 对应
alibaba:
supplier: alibaba
# AccessKey ID（阿里云控制台 - AccessKey管理）
access-key-id: ${ALIYUN_SMS_ACCESS_KEY:您的AccessKeyId}
# AccessKey Secret
access-key-secret: ${ALIYUN_SMS_ACCESS_SECRET:您的AccessKeySecret}
# 短信签名（需审核通过）
signature: ${ALIYUN_SMS_SIGNATURE:您的短信签名}
H5短信配置（application.yml）
h5:
sms:
# ---------- 基础配置 ----------
# 是否真正发送短信（false时仅打印日志，用于开发测试）
enabled: false
# 阿里云短信配置名称
sms-config-name: alibaba
# ---------- 短信模板配置 ----------
# 登录验证码模板ID（阿里云控制台申请）
login-template-id: ${ALIYUN_SMS_LOGIN_TEMPLATE:SMS_XXXXXX}
# 注册验证码模板ID
register-template-id: ${ALIYUN_SMS_REGISTER_TEMPLATE:SMS_XXXXXX}
# ---------- 验证码配置 ----------
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
环境变量配置（推荐）
生产环境建议使用环境变量，避免密钥泄露：
# 阿里云短信配置
export ALIYUN_SMS_ACCESS_KEY=LTAI5tXXXXXXXXXXXXXX
export ALIYUN_SMS_ACCESS_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
export ALIYUN_SMS_SIGNATURE=盘古教育
export ALIYUN_SMS_LOGIN_TEMPLATE=SMS_123456789
export ALIYUN_SMS_REGISTER_TEMPLATE=SMS_987654321
防刷策略
| 层级 |
策略 |
配置项 |
默认值 |
| 前置 |
图形验证码校验 |
- |
必须 |
| 手机号 |
黑名单检查 |
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次 |
验证码发送流程
- 校验图形验证码
- 检查手机号是否在黑名单
- 检查IP是否在黑名单
- 检查发送间隔（60秒）
- 检查手机号每日上限
- 检查IP每分钟上限
- 检查IP每日上限
- 业务校验（注册：手机号未注册；登录：手机号已注册）
- 生成验证码并存入Redis
- 更新各项计数器
- 调用阿里云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