H5 会员管理接口需求与技术方案
作者：湖北新华业务中台研发团队
创建时间：2026-02-02
版本：v1.0
一、需求概述
为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接口模块
│ ├── 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 模块，配置阿里云：
sms:
blends:
alibaba:
supplier: alibaba
access-key-id: ${ALIYUN_SMS_ACCESS_KEY}
access-key-secret: ${ALIYUN_SMS_ACCESS_SECRET}
signature: 盘古教育
template-id: SMS_XXXXXX
短信验证码逻辑：
- 校验图形验证码
- 频率限制（60秒内不可重发）
- 生成6位数字验证码，5分钟有效
- 存入Redis：
h5:sms:{phone}:{type}
- 调用阿里云API发送
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