17 KiB

Raw Blame History

盘古用户平台 - 接口设计文档

文档信息	内容
文档版本	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 响应规范

统一响应格式

{
    "code": 200,
    "msg": "操作成功",
    "data": {}
}

分页响应格式

{
    "code": 200,
    "msg": "查询成功",
    "total": 100,
    "rows": []
}

1.3 错误码定义

错误码	说明
200	成功
400	请求参数错误
401	未登录或Token过期
403	无权限访问
404	资源不存在
500	服务器内部错误

2. 认证接口

2.1 后台登录

接口地址：POST /api/login

请求参数

{
    "username": "admin",
    "password": "admin123",
    "code": "1234",
    "uuid": "xxx-xxx-xxx"
}

参数	类型	必填	说明
username	string	是	用户名
password	string	是	密码
code	string	是	验证码
uuid	string	是	验证码唯一标识

响应结果

{
    "code": 200,
    "msg": "操作成功",
    "token": "eyJhbGciOiJIUzUxMiJ9..."
}

2.2 获取验证码

接口地址：GET /api/captchaImage

响应结果

{
    "code": 200,
    "msg": "操作成功",
    "img": "data:image/png;base64,...",
    "uuid": "xxx-xxx-xxx"
}

2.3 会员登录（验证码）

接口地址：POST /app/login/sms

请求参数

{
    "phone": "13812345678",
    "code": "123456"
}

参数	类型	必填	说明
phone	string	是	手机号
code	string	是	短信验证码

响应结果

{
    "code": 200,
    "msg": "登录成功",
    "data": {
        "token": "eyJhbGciOiJIUzUxMiJ9...",
        "memberId": 1,
        "memberCode": "JS123456789",
        "phone": "138****5678",
        "nickname": "用户昵称",
        "avatar": "https://...",
        "identityType": "1"
    }
}

2.4 发送短信验证码

接口地址：POST /app/sms/send

请求参数

{
    "phone": "13812345678",
    "type": "login"
}

参数	类型	必填	说明
phone	string	是	手机号
type	string	是	验证码类型：login/register

响应结果

{
    "code": 200,
    "msg": "验证码已发送"
}

2.5 会员登录（密码）

接口地址：POST /app/login/password

请求参数

{
    "phone": "13812345678",
    "password": "123456"
}

2.6 会员登录（微信）

接口地址：POST /app/login/wechat

请求参数

{
    "code": "wx_login_code"
}

参数	类型	必填	说明
code	string	是	微信登录code

3. 学校管理接口

3.1 查询学校树

接口地址：GET /api/school/tree

请求参数

参数	类型	必填	说明
regionId	long	否	区域ID

响应结果

{
    "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	是	每页条数

响应结果

{
    "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

请求参数

{
    "schoolName": "武汉市第一中学",
    "schoolType": "02",
    "regionId": 111,
    "address": "武昌区xxx路xxx号",
    "contactPerson": "张老师",
    "contactPhone": "13812345678",
    "status": "0"
}

3.4 修改学校

接口地址：PUT /api/school

请求参数

{
    "schoolId": 1,
    "schoolName": "武汉市第一中学",
    "schoolType": "02",
    "regionId": 111,
    "status": "0"
}

3.5 删除学校

接口地址：DELETE /api/school/{schoolId}

3.6 为学校挂载年级

接口地址：POST /api/school/bindGrades

请求参数

{
    "schoolId": 1,
    "gradeIds": [7, 8, 9]
}

3.7 为年级挂载班级

接口地址：POST /api/school/bindClasses

请求参数

{
    "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	是	每页条数

响应结果

{
    "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}

响应结果

{
    "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

请求参数

{
    "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}

响应结果

{
    "code": 200,
    "msg": "密码重置成功",
    "data": {
        "password": "abc123"
    }
}

4.7 绑定学生

接口地址：POST /api/member/bindStudent

请求参数

{
    "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	是	每页条数

响应结果

{
    "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

请求参数

{
    "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文件

响应结果

{
    "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}

响应结果

{
    "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

请求参数

{
    "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}

响应结果

{
    "code": 200,
    "msg": "密钥重置成功",
    "data": {
        "appSecret": "a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
    }
}

6.7 获取API接口列表

接口地址：GET /api/application/apiList

响应结果

{
    "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

响应结果

{
    "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

请求参数

{
    "nickname": "新昵称",
    "avatar": "https://...",
    "gender": "1"
}

9.3 修改密码

接口地址：PUT /app/member/updatePwd

请求参数

{
    "oldPassword": "123456",
    "newPassword": "654321"
}

9.4 获取我的学生列表

接口地址：GET /app/student/myList

9.5 获取学校列表

接口地址：GET /app/school/list

9.6 获取区域树

接口地址：GET /app/region/tree

文档结束

17 KiB Raw Blame History Unescape Escape

盘古用户平台 - 接口设计文档

1. 接口规范

1.1 请求规范

1.2 响应规范

1.3 错误码定义

2. 认证接口

2.1 后台登录

2.2 获取验证码

2.3 会员登录（验证码）

2.4 发送短信验证码

2.5 会员登录（密码）

2.6 会员登录（微信）

3. 学校管理接口

3.1 查询学校树

3.2 查询学校列表

3.3 新增学校

3.4 修改学校

3.5 删除学校

3.6 为学校挂载年级

3.7 为年级挂载班级

4. 会员管理接口

4.1 查询会员列表

4.2 获取会员详情

4.3 新增会员

4.4 修改会员

4.5 删除会员

4.6 重置密码

4.7 绑定学生

4.8 解绑学生

5. 学生管理接口

5.1 查询学生列表

5.2 获取学生详情

5.3 新增学生

5.4 修改学生

5.5 删除学生

5.6 批量导入学生

5.7 下载导入模板

6. 应用管理接口

6.1 查询应用列表

6.2 获取应用详情

6.3 新增应用

6.4 修改应用

6.5 删除应用

6.6 重置密钥

6.7 获取API接口列表

7. 基础数据接口

7.1 区域管理

获取区域树

新增区域

修改区域

删除区域

7.2 年级管理

查询年级列表

新增年级

修改年级

删除年级

7.3 班级管理

查询班级列表

新增班级

修改班级

删除班级

7.4 学科管理

查询学科列表

新增学科

修改学科

删除学科

8. 开放API接口

8.1 签名规则

8.2 查询学生列表

8.3 查询学校列表

8.4 查询年级列表

8.5 查询班级列表

8.6 查询区域树

8.7 查询会员列表

9. 移动端接口

9.1 获取当前用户信息

9.2 修改个人信息

9.3 修改密码

9.4 获取我的学生列表

17 KiB

Raw Blame History