315 lines
10 KiB
Markdown
315 lines
10 KiB
Markdown
# 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. 校验手机号未注册<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接口模块
|
||
│ ├── 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` 模块，配置阿里云：
|
||
|
||
```yaml
|
||
sms:
|
||
blends:
|
||
alibaba:
|
||
supplier: alibaba
|
||
access-key-id: ${ALIYUN_SMS_ACCESS_KEY}
|
||
access-key-secret: ${ALIYUN_SMS_ACCESS_SECRET}
|
||
signature: 盘古教育
|
||
template-id: SMS_XXXXXX
|
||
```
|
||
|
||
短信验证码逻辑：
|
||
1. 校验图形验证码
|
||
2. 频率限制（60秒内不可重发）
|
||
3. 生成6位数字验证码，5分钟有效
|
||
4. 存入Redis：`h5:sms:{phone}:{type}`
|
||
5. 调用阿里云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*
|