fangxh2013
/
pangu-user-platform
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
pangu-user-platform/docs/04-接口文档/接口设计文档_v1.0.md

1032 lines
20 KiB
Markdown
Raw Normal View History

feat: 初始化盘古用户平台项目 - 添加项目文档（需求规格、系统设计、数据库设计、接口设计） - 添加前端项目pangu-ui（Vue3 + Element Plus + Mock） - 完成7个功能模块的前端页面开发 - 包含学校、会员、学生、应用、年级、班级、学科、区域管理
2026-01-31 16:48:20 +08:00
# 盘古用户平台 - 接口设计文档
---
| 文档信息 | 内容 |
|---------|------|
| **文档版本** | 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`
---
docs: 补充墨刀原型批注和示例数据到各文档 - 需求规格说明书：添加第8.3章墨刀批注汇总 - 全局注意事项（角色、部门管理、token） - 学校管理批注（挂载模式、软删除、必填规则） - 会员管理批注（登录方式、身份类型规则） - 学生管理批注（批量导入要求） - 应用管理批注（重置密钥、接口授权） - 区域管理批注（父级带入） - 示例数据（区域树、学校树） - 数据库设计文档：添加第4.6-4.9章示例数据 - 学校示例数据（武汉市第一中学等） - 会员示例数据 - 学生示例数据 - 应用示例数据（AI智慧平台） - 接口设计文档：添加第10章业务规则说明 - 学校管理规则（编码生成、挂载模式） - 会员管理规则（自动生成、身份类型） - 学生管理规则（批量导入） - 应用管理规则（密钥重置） - 区域管理规则 - README.md：添加原型批注要点和示例数据摘要
2026-01-31 16:58:18 +08:00
## 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 | 删除区域前检查是否有子级或被引用 |
---
feat: 初始化盘古用户平台项目 - 添加项目文档（需求规格、系统设计、数据库设计、接口设计） - 添加前端项目pangu-ui（Vue3 + Element Plus + Mock） - 完成7个功能模块的前端页面开发 - 包含学校、会员、学生、应用、年级、班级、学科、区域管理
2026-01-31 16:48:20 +08:00
*文档结束*