H5 会员管理接口需求与技术方案
作者：pangu
创建时间：2026-02-02
更新时间：2026-02-04
版本：v1.2
一、需求概述
为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.1.7 微信扫码登录
2.1.7.1 获取微信扫码登录二维码
| 项目 |
说明 |
| 接口 |
GET /h5/auth/wechat/qrcode |
| 返回 |
qrcodeUrl（二维码URL）、ticket（二维码凭证）、expireSeconds（有效期秒数） |
| 有效期 |
默认5分钟 |
2.1.7.2 查询微信扫码状态
| 项目 |
说明 |
| 接口 |
GET /h5/auth/wechat/status/{ticket} |
| 返回 |
status（waiting/scanned/confirmed/expired）、tempCode（确认后返回） |
| 轮询建议 |
每2秒查询一次 |
2.1.7.3 微信扫码登录
| 项目 |
说明 |
| 接口 |
POST /h5/auth/wechat/login |
| 请求参数 |
ticket（二维码凭证）、tempCode（临时登录码） |
| 返回 |
needBindPhone=false时返回Token；needBindPhone=true时返回bindToken需绑定手机号 |
2.1.7.4 发送微信绑定手机号短信验证码
| 项目 |
说明 |
| 接口 |
POST /h5/auth/wechat/sms/send |
| 请求参数 |
phone（手机号）、captchaCode（图形验证码）、uuid |
| 业务场景 |
微信首次登录时绑定手机号 |
2.1.7.5 微信登录绑定手机号
| 项目 |
说明 |
| 接口 |
POST /h5/auth/wechat/bindPhone |
| 请求参数 |
bindToken、phone、smsCode、captchaCode、uuid |
| 业务逻辑 |
手机号已存在则绑定到现有账号，否则创建新会员 |
| 返回 |
accessToken、refreshToken |
2.1.7.6 微信回调处理
| 项目 |
说明 |
| 接口 |
GET /h5/auth/wechat/callback |
| 请求参数 |
code（微信授权码）、state（即ticket） |
| 业务场景 |
前端回调页面收到微信code后调用 |
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、memberCode、phone（脱敏）、nickname、avatar、gender、birthday、registerTime、educations（教育身份列表）、students（绑定学生列表） |
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/educations |
| 请求参数 |
schoolId（学校）、schoolGradeId（年级）、schoolClassId（班级）、subjectId（学科） |
| 业务逻辑 |
添加一条教育身份记录，支持多条 |
2.5.2 获取教育身份列表
| 项目 |
说明 |
| 接口 |
GET /h5/member/educations |
| 返回 |
教育身份列表（每条包含：educationId、学校、年级、班级、学科名称及ID、是否默认） |
2.5.3 修改教育身份
| 项目 |
说明 |
| 接口 |
PUT /h5/member/educations/{educationId} |
| 请求参数 |
schoolId（学校）、schoolGradeId（年级）、schoolClassId（班级）、subjectId（学科） |
| 业务逻辑 |
修改指定教育身份的信息 |
2.5.4 删除教育身份
| 项目 |
说明 |
| 接口 |
DELETE /h5/member/educations/{educationId} |
| 业务逻辑 |
删除指定的教育身份记录 |
2.5.5 设置默认教育身份
| 项目 |
说明 |
| 接口 |
PUT /h5/member/educations/{educationId}/default |
| 业务逻辑 |
将指定教育身份设为默认，其他教育身份自动取消默认状态 |
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 操作日志
2.8.1 获取操作日志列表
| 项目 |
说明 |
| 接口 |
GET /h5/member/logs |
| 请求参数 |
pageNum（页码，默认1）、pageSize（每页条数，默认10） |
| 返回 |
分页的操作日志列表（操作类型、操作内容、操作时间、IP地址等） |
| 业务场景 |
用户查看自己的操作记录 |
2.9 接口规范
| 规范项 |
说明 |
| 认证方式 |
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/pangu-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 # 绑定学生
│ │ ├── WechatLoginDto.java # 微信登录
│ │ └── WechatBindPhoneDto.java # 微信绑定手机号
│ └── vo/ # 响应VO
│ ├── H5LoginVo.java # 登录响应
│ ├── H5CaptchaVo.java # 验证码响应
│ ├── H5MemberInfoVo.java # 会员信息（含教育身份列表）
│ ├── H5EducationVo.java # 教育身份
│ ├── H5StudentVo.java # 学生信息
│ ├── H5MemberLogVo.java # 操作日志
│ ├── WechatQrcodeVo.java # 微信二维码
│ ├── WechatStatusVo.java # 微信扫码状态
│ └── WechatLoginVo.java # 微信登录响应
3.2 接口路径规划
| 模块 |
路径前缀 |
认证要求 |
| 认证接口 |
/h5/auth/* |
无需认证 |
| 微信登录 |
/h5/auth/wechat/* |
无需认证 |
| 会员接口 |
/h5/member/* |
需要Token |
| 教育身份 |
/h5/member/educations/* |
需要Token |
| 学生管理 |
/h5/member/student/* |
需要Token |
| 操作日志 |
/h5/member/logs |
需要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），集成阿里云短信服务。
阿里云账号信息
| 配置项 |
值 |
说明 |
| AccessKey ID |
LTAI5tQLorTxf9Fzzh93pfGN |
阿里云访问密钥 |
| AccessKey Secret |
NhBZGwac5vvWg60R0Y4UndTsKK4zuh |
阿里云密钥 |
| Endpoint |
dysmsapi.aliyuncs.com |
短信API地址 |
| 签名 |
湖北新华教育服务平台 |
短信签名（已审核通过） |
短信模板
| 模板用途 |
模板ID |
模板内容 |
| 登录验证码 |
SMS_461020580 |
【湖北新华教育服务平台】您正在申请登录，验证码为：${code} |
| 注册验证码 |
SMS_473140005 |
【湖北新华教育服务平台】您正在申请注册，验证码为：${code} |
| 重置密码 |
SMS_473130008 |
用于忘记密码（备用） |
阿里云配置（application-dev.yml）
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）
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次 |
验证码发送流程
- 校验图形验证码
- 检查手机号是否在黑名单
- 检查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, WechatLoginDto, WechatBindPhoneDto |
| 2 |
VO类 |
H5LoginVo, H5CaptchaVo, H5MemberInfoVo, H5EducationVo, H5StudentVo, H5MemberLogVo, WechatQrcodeVo, WechatStatusVo, WechatLoginVo |
| 3 |
认证服务 |
H5AuthService, H5AuthServiceImpl（含微信登录） |
| 4 |
会员服务 |
H5MemberService, H5MemberServiceImpl（含多教育身份、操作日志） |
| 5 |
Controller |
H5AuthController（含微信登录）, H5MemberController（含多教育身份）, H5BaseDataController |
| 6 |
安全配置 |
SecurityConfig（添加放行规则） |
| 7 |
短信配置 |
application-dev.yml |
| 8 |
微信配置 |
微信开放平台AppID、AppSecret配置 |
最后更新: 2026-02-03