1032 lines
20 KiB
Markdown
1032 lines
20 KiB
Markdown
# 盘古用户平台 - 接口设计文档
|
||
|
||
---
|
||
|
||
| 文档信息 | 内容 |
|
||
|---------|------|
|
||
| **文档版本** | V1.0 |
|
||
| **项目名称** | 盘古用户平台（Pangu User Platform） |
|
||
| **编写团队** | pangu |
|
||
| **创建日期** | 2026-01-31 |
|
||
| **接口基础路径** | `/api` (管理端) `/app` (移动端) `/open` (开放API) |
|
||
|
||
---
|
||
|
||
## 1. 接口规范
|
||
|
||
### 1.1 请求规范
|
||
|
||
**请求头（Header）**
|
||
|
||
| Header | 必填 | 说明 |
|
||
|--------|:----:|------|
|
||
| Authorization | 是 | Bearer {token}，登录接口除外 |
|
||
| Content-Type | 是 | application/json |
|
||
|
||
**请求方法**
|
||
|
||
| 方法 | 用途 |
|
||
|-----|------|
|
||
| GET | 查询数据 |
|
||
| POST | 新增数据 |
|
||
| PUT | 修改数据 |
|
||
| DELETE | 删除数据 |
|
||
|
||
### 1.2 响应规范
|
||
|
||
**统一响应格式**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
**分页响应格式**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"total": 100,
|
||
"rows": []
|
||
}
|
||
```
|
||
|
||
### 1.3 错误码定义
|
||
|
||
| 错误码 | 说明 |
|
||
|-------|------|
|
||
| 200 | 成功 |
|
||
| 400 | 请求参数错误 |
|
||
| 401 | 未登录或Token过期 |
|
||
| 403 | 无权限访问 |
|
||
| 404 | 资源不存在 |
|
||
| 500 | 服务器内部错误 |
|
||
|
||
---
|
||
|
||
## 2. 认证接口
|
||
|
||
### 2.1 后台登录
|
||
|
||
**接口地址**：`POST /api/login`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"username": "admin",
|
||
"password": "admin123",
|
||
"code": "1234",
|
||
"uuid": "xxx-xxx-xxx"
|
||
}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| username | string | 是 | 用户名 |
|
||
| password | string | 是 | 密码 |
|
||
| code | string | 是 | 验证码 |
|
||
| uuid | string | 是 | 验证码唯一标识 |
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"token": "eyJhbGciOiJIUzUxMiJ9..."
|
||
}
|
||
```
|
||
|
||
### 2.2 获取验证码
|
||
|
||
**接口地址**：`GET /api/captchaImage`
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "操作成功",
|
||
"img": "data:image/png;base64,...",
|
||
"uuid": "xxx-xxx-xxx"
|
||
}
|
||
```
|
||
|
||
### 2.3 会员登录（验证码）
|
||
|
||
**接口地址**：`POST /app/login/sms`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"phone": "13812345678",
|
||
"code": "123456"
|
||
}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| phone | string | 是 | 手机号 |
|
||
| code | string | 是 | 短信验证码 |
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "登录成功",
|
||
"data": {
|
||
"token": "eyJhbGciOiJIUzUxMiJ9...",
|
||
"memberId": 1,
|
||
"memberCode": "JS123456789",
|
||
"phone": "138****5678",
|
||
"nickname": "用户昵称",
|
||
"avatar": "https://...",
|
||
"identityType": "1"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 2.4 发送短信验证码
|
||
|
||
**接口地址**：`POST /app/sms/send`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"phone": "13812345678",
|
||
"type": "login"
|
||
}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| phone | string | 是 | 手机号 |
|
||
| type | string | 是 | 验证码类型：login/register |
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "验证码已发送"
|
||
}
|
||
```
|
||
|
||
### 2.5 会员登录（密码）
|
||
|
||
**接口地址**：`POST /app/login/password`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"phone": "13812345678",
|
||
"password": "123456"
|
||
}
|
||
```
|
||
|
||
### 2.6 会员登录（微信）
|
||
|
||
**接口地址**：`POST /app/login/wechat`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"code": "wx_login_code"
|
||
}
|
||
```
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| code | string | 是 | 微信登录code |
|
||
|
||
---
|
||
|
||
## 3. 学校管理接口
|
||
|
||
### 3.1 查询学校树
|
||
|
||
**接口地址**：`GET /api/school/tree`
|
||
|
||
**请求参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| regionId | long | 否 | 区域ID |
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": [
|
||
{
|
||
"schoolId": 1,
|
||
"schoolCode": "SCH001",
|
||
"schoolName": "武汉市第一中学",
|
||
"regionPath": "湖北省-武汉市-武昌区",
|
||
"children": [
|
||
{
|
||
"id": 1,
|
||
"gradeId": 7,
|
||
"gradeName": "七年级",
|
||
"children": [
|
||
{
|
||
"id": 1,
|
||
"classId": 1,
|
||
"className": "1班"
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 3.2 查询学校列表
|
||
|
||
**接口地址**：`GET /api/school/list`
|
||
|
||
**请求参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| schoolName | string | 否 | 学校名称（模糊查询）|
|
||
| regionId | long | 否 | 区域ID |
|
||
| status | string | 否 | 状态 |
|
||
| pageNum | int | 是 | 页码 |
|
||
| pageSize | int | 是 | 每页条数 |
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"total": 100,
|
||
"rows": [
|
||
{
|
||
"schoolId": 1,
|
||
"schoolCode": "SCH001",
|
||
"schoolName": "武汉市第一中学",
|
||
"schoolType": "02",
|
||
"regionId": 111,
|
||
"regionPath": "湖北省-武汉市-武昌区",
|
||
"status": "0",
|
||
"createTime": "2026-01-01 10:00:00",
|
||
"createBy": "admin"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 3.3 新增学校
|
||
|
||
**接口地址**：`POST /api/school`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"schoolName": "武汉市第一中学",
|
||
"schoolType": "02",
|
||
"regionId": 111,
|
||
"address": "武昌区xxx路xxx号",
|
||
"contactPerson": "张老师",
|
||
"contactPhone": "13812345678",
|
||
"status": "0"
|
||
}
|
||
```
|
||
|
||
### 3.4 修改学校
|
||
|
||
**接口地址**：`PUT /api/school`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"schoolId": 1,
|
||
"schoolName": "武汉市第一中学",
|
||
"schoolType": "02",
|
||
"regionId": 111,
|
||
"status": "0"
|
||
}
|
||
```
|
||
|
||
### 3.5 删除学校
|
||
|
||
**接口地址**：`DELETE /api/school/{schoolId}`
|
||
|
||
### 3.6 为学校挂载年级
|
||
|
||
**接口地址**：`POST /api/school/bindGrades`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"schoolId": 1,
|
||
"gradeIds": [7, 8, 9]
|
||
}
|
||
```
|
||
|
||
### 3.7 为年级挂载班级
|
||
|
||
**接口地址**：`POST /api/school/bindClasses`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"schoolGradeId": 1,
|
||
"classIds": [1, 2, 3]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 会员管理接口
|
||
|
||
### 4.1 查询会员列表
|
||
|
||
**接口地址**：`GET /api/member/list`
|
||
|
||
**请求参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| phone | string | 否 | 手机号 |
|
||
| nickname | string | 否 | 昵称 |
|
||
| identityType | string | 否 | 身份类型（1家长 2教师）|
|
||
| status | string | 否 | 状态 |
|
||
| beginTime | string | 否 | 注册开始时间 |
|
||
| endTime | string | 否 | 注册结束时间 |
|
||
| pageNum | int | 是 | 页码 |
|
||
| pageSize | int | 是 | 每页条数 |
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"total": 100,
|
||
"rows": [
|
||
{
|
||
"memberId": 1,
|
||
"memberCode": "JS123456789",
|
||
"phone": "138****5678",
|
||
"nickname": "用户昵称",
|
||
"gender": "1",
|
||
"birthday": "1990-01-01",
|
||
"identityType": "1",
|
||
"registerSource": "1",
|
||
"registerTime": "2026-01-01 10:00:00",
|
||
"status": "0"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 4.2 获取会员详情
|
||
|
||
**接口地址**：`GET /api/member/{memberId}`
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"memberId": 1,
|
||
"memberCode": "JS123456789",
|
||
"phone": "13812345678",
|
||
"nickname": "用户昵称",
|
||
"gender": "1",
|
||
"birthday": "1990-01-01",
|
||
"identityType": "2",
|
||
"regionId": 111,
|
||
"schoolId": 1,
|
||
"schoolGradeId": 1,
|
||
"schoolClassId": 1,
|
||
"students": [
|
||
{
|
||
"studentId": 1,
|
||
"studentName": "张三",
|
||
"studentNo": "2026001",
|
||
"schoolName": "武汉市第一中学",
|
||
"gradeName": "七年级",
|
||
"className": "1班"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.3 新增会员
|
||
|
||
**接口地址**：`POST /api/member`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"phone": "13812345678",
|
||
"nickname": "用户昵称",
|
||
"gender": "1",
|
||
"birthday": "1990-01-01",
|
||
"identityType": "2",
|
||
"regionId": 111,
|
||
"schoolId": 1,
|
||
"schoolGradeId": 1,
|
||
"schoolClassId": 1,
|
||
"status": "0"
|
||
}
|
||
```
|
||
|
||
### 4.4 修改会员
|
||
|
||
**接口地址**：`PUT /api/member`
|
||
|
||
### 4.5 删除会员
|
||
|
||
**接口地址**：`DELETE /api/member/{memberId}`
|
||
|
||
### 4.6 重置密码
|
||
|
||
**接口地址**：`PUT /api/member/resetPwd/{memberId}`
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "密码重置成功",
|
||
"data": {
|
||
"password": "abc123"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4.7 绑定学生
|
||
|
||
**接口地址**：`POST /api/member/bindStudent`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"memberId": 1,
|
||
"studentId": 1
|
||
}
|
||
```
|
||
|
||
### 4.8 解绑学生
|
||
|
||
**接口地址**：`DELETE /api/member/unbindStudent/{memberId}/{studentId}`
|
||
|
||
---
|
||
|
||
## 5. 学生管理接口
|
||
|
||
### 5.1 查询学生列表
|
||
|
||
**接口地址**：`GET /api/student/list`
|
||
|
||
**请求参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| studentName | string | 否 | 学生姓名 |
|
||
| studentNo | string | 否 | 学号 |
|
||
| gender | string | 否 | 性别 |
|
||
| schoolId | long | 否 | 学校ID |
|
||
| schoolGradeId | long | 否 | 学校年级ID |
|
||
| schoolClassId | long | 否 | 学校班级ID |
|
||
| subjectId | long | 否 | 学科ID |
|
||
| memberPhone | string | 否 | 归属用户手机号 |
|
||
| pageNum | int | 是 | 页码 |
|
||
| pageSize | int | 是 | 每页条数 |
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"total": 100,
|
||
"rows": [
|
||
{
|
||
"studentId": 1,
|
||
"studentName": "张三",
|
||
"studentNo": "2026001",
|
||
"gender": "1",
|
||
"birthday": "2015-01",
|
||
"regionPath": "湖北省-武汉市-武昌区",
|
||
"schoolName": "武汉市第一中学",
|
||
"gradeName": "七年级",
|
||
"className": "1班",
|
||
"subjectName": "语文",
|
||
"memberNickname": "张三爸爸",
|
||
"memberPhone": "138****5678"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 5.2 获取学生详情
|
||
|
||
**接口地址**：`GET /api/student/{studentId}`
|
||
|
||
### 5.3 新增学生
|
||
|
||
**接口地址**：`POST /api/student`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"studentName": "张三",
|
||
"studentNo": "2026001",
|
||
"gender": "1",
|
||
"birthday": "2015-01",
|
||
"regionId": 111,
|
||
"schoolId": 1,
|
||
"schoolGradeId": 1,
|
||
"schoolClassId": 1,
|
||
"subjectId": 1,
|
||
"memberId": 1
|
||
}
|
||
```
|
||
|
||
### 5.4 修改学生
|
||
|
||
**接口地址**：`PUT /api/student`
|
||
|
||
### 5.5 删除学生
|
||
|
||
**接口地址**：`DELETE /api/student/{studentId}`
|
||
|
||
### 5.6 批量导入学生
|
||
|
||
**接口地址**：`POST /api/student/import`
|
||
|
||
**请求方式**：`multipart/form-data`
|
||
|
||
**请求参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| file | file | 是 | Excel文件 |
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "导入成功",
|
||
"data": {
|
||
"successCount": 98,
|
||
"failCount": 2,
|
||
"failList": [
|
||
{"row": 5, "reason": "学号已存在"},
|
||
{"row": 10, "reason": "学校信息不匹配"}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 5.7 下载导入模板
|
||
|
||
**接口地址**：`GET /api/student/template`
|
||
|
||
**响应**：Excel文件下载
|
||
|
||
---
|
||
|
||
## 6. 应用管理接口
|
||
|
||
### 6.1 查询应用列表
|
||
|
||
**接口地址**：`GET /api/application/list`
|
||
|
||
**请求参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| appName | string | 否 | 应用名称 |
|
||
| appCode | string | 否 | 应用编码 |
|
||
| status | string | 否 | 状态 |
|
||
| pageNum | int | 是 | 页码 |
|
||
| pageSize | int | 是 | 每页条数 |
|
||
|
||
### 6.2 获取应用详情
|
||
|
||
**接口地址**：`GET /api/application/{appId}`
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"appId": 1,
|
||
"appCode": "YY000001",
|
||
"appName": "AI智慧平台",
|
||
"appSecret": "********************************",
|
||
"status": "0",
|
||
"apis": [
|
||
{
|
||
"apiCode": "STUDENT_LIST",
|
||
"apiName": "查询学生信息",
|
||
"apiPath": "/open/student/list"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.3 新增应用
|
||
|
||
**接口地址**：`POST /api/application`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"appName": "AI智慧平台",
|
||
"appDesc": "AI教育智慧平台",
|
||
"contactPerson": "张经理",
|
||
"contactPhone": "13812345678",
|
||
"status": "0",
|
||
"apiCodes": ["STUDENT_LIST", "SCHOOL_LIST", "GRADE_LIST"]
|
||
}
|
||
```
|
||
|
||
### 6.4 修改应用
|
||
|
||
**接口地址**：`PUT /api/application`
|
||
|
||
### 6.5 删除应用
|
||
|
||
**接口地址**：`DELETE /api/application/{appId}`
|
||
|
||
### 6.6 重置密钥
|
||
|
||
**接口地址**：`PUT /api/application/resetSecret/{appId}`
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "密钥重置成功",
|
||
"data": {
|
||
"appSecret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.7 获取API接口列表
|
||
|
||
**接口地址**：`GET /api/application/apiList`
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": [
|
||
{
|
||
"apiCode": "STUDENT_LIST",
|
||
"apiName": "查询学生信息",
|
||
"apiPath": "/open/student/list",
|
||
"apiMethod": "GET"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 7. 基础数据接口
|
||
|
||
### 7.1 区域管理
|
||
|
||
#### 获取区域树
|
||
|
||
**接口地址**：`GET /api/region/tree`
|
||
|
||
#### 新增区域
|
||
|
||
**接口地址**：`POST /api/region`
|
||
|
||
#### 修改区域
|
||
|
||
**接口地址**：`PUT /api/region`
|
||
|
||
#### 删除区域
|
||
|
||
**接口地址**：`DELETE /api/region/{regionId}`
|
||
|
||
### 7.2 年级管理
|
||
|
||
#### 查询年级列表
|
||
|
||
**接口地址**：`GET /api/grade/list`
|
||
|
||
#### 新增年级
|
||
|
||
**接口地址**：`POST /api/grade`
|
||
|
||
#### 修改年级
|
||
|
||
**接口地址**：`PUT /api/grade`
|
||
|
||
#### 删除年级
|
||
|
||
**接口地址**：`DELETE /api/grade/{gradeId}`
|
||
|
||
### 7.3 班级管理
|
||
|
||
#### 查询班级列表
|
||
|
||
**接口地址**：`GET /api/class/list`
|
||
|
||
#### 新增班级
|
||
|
||
**接口地址**：`POST /api/class`
|
||
|
||
#### 修改班级
|
||
|
||
**接口地址**：`PUT /api/class`
|
||
|
||
#### 删除班级
|
||
|
||
**接口地址**：`DELETE /api/class/{classId}`
|
||
|
||
### 7.4 学科管理
|
||
|
||
#### 查询学科列表
|
||
|
||
**接口地址**：`GET /api/subject/list`
|
||
|
||
#### 新增学科
|
||
|
||
**接口地址**：`POST /api/subject`
|
||
|
||
#### 修改学科
|
||
|
||
**接口地址**：`PUT /api/subject`
|
||
|
||
#### 删除学科
|
||
|
||
**接口地址**：`DELETE /api/subject/{subjectId}`
|
||
|
||
---
|
||
|
||
## 8. 开放API接口
|
||
|
||
> 供第三方应用调用，需要AppId + AppSecret签名认证
|
||
|
||
### 8.1 签名规则
|
||
|
||
**请求头**
|
||
|
||
| Header | 必填 | 说明 |
|
||
|--------|:----:|------|
|
||
| X-App-Id | 是 | 应用编码 |
|
||
| X-Timestamp | 是 | 时间戳（毫秒）|
|
||
| X-Sign | 是 | 签名 |
|
||
|
||
**签名算法**
|
||
|
||
```
|
||
1. 将所有请求参数按参数名ASCII升序排序
|
||
2. 拼接成 key1=value1&key2=value2 格式
|
||
3. 末尾追加 &appSecret=xxx
|
||
4. 对整个字符串进行MD5加密（32位大写）
|
||
```
|
||
|
||
**示例**
|
||
|
||
```
|
||
请求参数：pageNum=1&pageSize=10&schoolId=1
|
||
拼接后：pageNum=1&pageSize=10&schoolId=1&appSecret=abc123
|
||
MD5签名：E5D7C6B5A4F3E2D1C0B9A8F7E6D5C4B3
|
||
```
|
||
|
||
### 8.2 查询学生列表
|
||
|
||
**接口地址**：`GET /open/student/list`
|
||
|
||
**请求参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| schoolId | long | 否 | 学校ID |
|
||
| gradeId | long | 否 | 年级ID |
|
||
| classId | long | 否 | 班级ID |
|
||
| pageNum | int | 是 | 页码 |
|
||
| pageSize | int | 是 | 每页条数 |
|
||
|
||
### 8.3 查询学校列表
|
||
|
||
**接口地址**：`GET /open/school/list`
|
||
|
||
**请求参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| regionId | long | 否 | 区域ID |
|
||
| pageNum | int | 是 | 页码 |
|
||
| pageSize | int | 是 | 每页条数 |
|
||
|
||
### 8.4 查询年级列表
|
||
|
||
**接口地址**：`GET /open/grade/list`
|
||
|
||
### 8.5 查询班级列表
|
||
|
||
**接口地址**：`GET /open/class/list`
|
||
|
||
### 8.6 查询区域树
|
||
|
||
**接口地址**：`GET /open/region/tree`
|
||
|
||
### 8.7 查询会员列表
|
||
|
||
**接口地址**：`GET /open/member/list`
|
||
|
||
**请求参数**
|
||
|
||
| 参数 | 类型 | 必填 | 说明 |
|
||
|-----|------|:----:|------|
|
||
| phone | string | 否 | 手机号 |
|
||
| schoolId | long | 否 | 学校ID |
|
||
| pageNum | int | 是 | 页码 |
|
||
| pageSize | int | 是 | 每页条数 |
|
||
|
||
---
|
||
|
||
## 9. 移动端接口
|
||
|
||
### 9.1 获取当前用户信息
|
||
|
||
**接口地址**：`GET /app/member/info`
|
||
|
||
**响应结果**
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"msg": "查询成功",
|
||
"data": {
|
||
"memberId": 1,
|
||
"memberCode": "JS123456789",
|
||
"phone": "138****5678",
|
||
"nickname": "用户昵称",
|
||
"avatar": "https://...",
|
||
"gender": "1",
|
||
"identityType": "1",
|
||
"students": [
|
||
{
|
||
"studentId": 1,
|
||
"studentName": "张三",
|
||
"schoolName": "武汉市第一中学",
|
||
"gradeName": "七年级",
|
||
"className": "1班"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 9.2 修改个人信息
|
||
|
||
**接口地址**：`PUT /app/member/info`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"nickname": "新昵称",
|
||
"avatar": "https://...",
|
||
"gender": "1"
|
||
}
|
||
```
|
||
|
||
### 9.3 修改密码
|
||
|
||
**接口地址**：`PUT /app/member/updatePwd`
|
||
|
||
**请求参数**
|
||
|
||
```json
|
||
{
|
||
"oldPassword": "123456",
|
||
"newPassword": "654321"
|
||
}
|
||
```
|
||
|
||
### 9.4 获取我的学生列表
|
||
|
||
**接口地址**：`GET /app/student/myList`
|
||
|
||
### 9.5 获取学校列表
|
||
|
||
**接口地址**：`GET /app/school/list`
|
||
|
||
### 9.6 获取区域树
|
||
|
||
**接口地址**：`GET /app/region/tree`
|
||
|
||
---
|
||
|
||
## 10. 业务规则说明
|
||
|
||
> 以下业务规则来源于墨刀原型批注，接口开发时需遵守
|
||
|
||
### 10.1 学校管理
|
||
|
||
| 规则编号 | 规则描述 |
|
||
|:------:|--------|
|
||
| SCH-01 | 学校编码自动生成，格式：SCH + 年份 + 4位序号 |
|
||
| SCH-02 | 新增学校时所属地区从列表页选择的区域层级树带入，也可手动调整 |
|
||
| SCH-03 | 所属地区/学校编码/学校名称为必填 |
|
||
| SCH-04 | 学校下新增年级为选择挂载模式，非新建年级，支持多选 |
|
||
| SCH-05 | 年级下新增班级为选择挂载模式，非新建班级，支持多选 |
|
||
| SCH-06 | 删除时检查是否有子级或被学生信息引用，有则不允许删除 |
|
||
| SCH-07 | 所有删除操作均为软删除 |
|
||
|
||
### 10.2 会员管理
|
||
|
||
| 规则编号 | 规则描述 |
|
||
|:------:|--------|
|
||
| MEM-01 | 会员编号自动生成，格式：JS + 时间戳 |
|
||
| MEM-02 | 昵称未填写时自动生成 |
|
||
| MEM-03 | 出生日期和性别为选填 |
|
||
| MEM-04 | 身份类型为"教师"时，必须填写区域/学校/年级/班级 |
|
||
| MEM-05 | 身份类型为"教师"时，只能绑定同校学生 |
|
||
| MEM-06 | 身份类型为"家长"时，不显示区域信息，可绑定任意学生 |
|
||
| MEM-07 | 重置密码后弹窗显示新密码，提供复制功能 |
|
||
| MEM-08 | 删除会员需popconfirm确认，如绑定学生则不允许删除 |
|
||
| MEM-09 | 禁用会员后无法登录任何端 |
|
||
| MEM-10 | 支持三种登录方式：手机号+验证码、手机号+密码、微信登录 |
|
||
|
||
### 10.3 学生管理
|
||
|
||
| 规则编号 | 规则描述 |
|
||
|:------:|--------|
|
||
| STU-01 | 学号不允许重复，可为空 |
|
||
| STU-02 | 出生日期和性别可为空 |
|
||
| STU-03 | 学校信息（区域/学校/年级/班级）为必填 |
|
||
| STU-04 | 学生必须归属于某个会员 |
|
||
|
||
**批量导入规则：**
|
||
|
||
| 规则编号 | 规则描述 |
|
||
|:------:|--------|
|
||
| IMP-01 | 模板字段：姓名(必填)、学号(必填)、用户手机号(必填)、区域(必填)、学校(必填)、年级(必填)、班级(必填)、性别(选填)、出生年月(选填) |
|
||
| IMP-02 | 导入时校验必填字段和区域/学校/年级/班级数据一致性 |
|
||
| IMP-03 | 用户手机号已存在则挂载到已有用户 |
|
||
| IMP-04 | 用户手机号不存在则自动创建家长用户，初始密码：123456 |
|
||
|
||
### 10.4 应用管理
|
||
|
||
| 规则编号 | 规则描述 |
|
||
|:------:|--------|
|
||
| APP-01 | 应用编码自动生成，格式：YY + 6位序号 |
|
||
| APP-02 | 应用密钥（AppSecret）自动生成，32位随机字符串 |
|
||
| APP-03 | 重置密钥后弹窗显示新密钥，提供复制功能 |
|
||
| APP-04 | 删除应用需popconfirm确认 |
|
||
| APP-05 | 禁用应用后无法调用任何API |
|
||
|
||
### 10.5 区域管理
|
||
|
||
| 规则编号 | 规则描述 |
|
||
|:------:|--------|
|
||
| REG-01 | 区域名称必填 |
|
||
| REG-02 | 区域编码自动生成 |
|
||
| REG-03 | 新增下级时默认所属父级为选择的区域 |
|
||
| REG-04 | 删除区域前检查是否有子级或被引用 |
|
||
|
||
---
|
||
|
||
*文档结束*
|