pangu-user-platform/docs/02-技术方案/H5会员接口需求与技术方案.md

# 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` 模块，配置阿里云：

```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
```

#### 短信防刷配置（application.yml）

```yaml
h5:
  sms:
    # 是否启用短信发送（false时仅打印日志，用于测试）
    enabled: false
    # 验证码长度
    code-length: 6
    # 验证码有效期（分钟）
    code-expire-minutes: 5
    # 同一手机号发送间隔（秒）
    send-interval-seconds: 60
    # 同一手机号每日发送上限
    daily-limit-per-phone: 10
    # 同一IP每分钟发送上限
    minute-limit-per-ip: 5
    # 同一IP每日发送上限
    daily-limit-per-ip: 50
    # 黑名单封禁时长（分钟）
    blacklist-minutes: 30
    # 触发黑名单的验证失败次数
    blacklist-trigger-count: 5
    # 阿里云短信配置名称（对应sms.blends下的配置）
    sms-config-name: alibaba
    # 短信模板ID - 登录
    login-template-id: ''
    # 短信模板ID - 注册
    register-template-id: ''
```

#### 防刷策略

| 层级 | 策略 | 配置项 | 默认值 |
|------|------|--------|--------|
| 前置 | 图形验证码校验 | - | 必须 |
| 手机号 | 黑名单检查 | `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*