381 lines
9.8 KiB
Markdown
381 lines
9.8 KiB
Markdown
# 院校模块（School）后台接口文档
|
||
|
||
> 适用范围：后台管理（CRUD / 导入导出 / 聚合详情）。
|
||
>
|
||
> 代码位置：`jeecg-module-system/jeecg-system-biz/src/main/java/org/jeecg/modules/school/controller/*`
|
||
|
||
## 1. 基础约定（JEECG-Boot）
|
||
|
||
### 1.1 基础地址
|
||
|
||
- 默认 `server.servlet.context-path` 为 `/jeecg-boot`
|
||
- 文档中接口地址以：`/jeecg-boot` + Controller 的 `@RequestMapping` 为准
|
||
|
||
示例：
|
||
|
||
- `GET /jeecg-boot/school/school/list`
|
||
|
||
### 1.2 认证
|
||
|
||
- 需要登录后调用（通常前端会在请求头携带 token）
|
||
- 权限控制使用 `@RequiresPermissions`（文档中会标注权限码）
|
||
|
||
### 1.3 统一返回结构
|
||
|
||
接口统一返回：`org.jeecg.common.api.vo.Result<T>`。
|
||
|
||
成功示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"message": "",
|
||
"code": 200,
|
||
"result": {},
|
||
"timestamp": 1700000000000
|
||
}
|
||
```
|
||
|
||
失败示例：
|
||
|
||
```json
|
||
{
|
||
"success": false,
|
||
"message": "未找到对应数据",
|
||
"code": 500,
|
||
"result": null,
|
||
"timestamp": 1700000000000
|
||
}
|
||
```
|
||
|
||
### 1.4 分页返回结构（MyBatis-Plus IPage）
|
||
|
||
分页接口 `result` 为 `IPage<T>`，常见字段示例：
|
||
|
||
```json
|
||
{
|
||
"success": true,
|
||
"code": 200,
|
||
"result": {
|
||
"records": [],
|
||
"total": 0,
|
||
"size": 10,
|
||
"current": 1,
|
||
"pages": 0
|
||
}
|
||
}
|
||
```
|
||
|
||
### 1.5 导入 / 导出
|
||
|
||
- 导出：`GET /exportXls`，返回 Excel 文件流
|
||
- 导入：`POST /importExcel`，`multipart/form-data`，上传字段名通常为 `file`
|
||
|
||
## 2. 数据表与字段说明（摘要）
|
||
|
||
> 下面仅列出接口当前代码中实体字段；若你按 `Task2_solution.md` 扩展了更多列，可继续在实体中补字段以支持后台维护。
|
||
|
||
### 2.1 学校主表（t_school）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | Long | 主键ID |
|
||
| mainCode | String | 学校编码（唯一） |
|
||
| mainName | String | 学校主名称（官方全称） |
|
||
| shortName | String | 学校简称 |
|
||
| schoolIcon | String | 院校图标（URL） |
|
||
| createBy/createTime | String/Date | 创建人/创建时间 |
|
||
| updateBy/updateTime | String/Date | 更新人/更新时间 |
|
||
|
||
### 2.2 学校详情（t_school_detail）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | Long | 主键ID |
|
||
| schoolId | Long | 学校ID |
|
||
| introduction | String | 学校简介（大文本） |
|
||
| address | String | 地址 |
|
||
| contact | String | 联系电话 |
|
||
| website | String | 官网 |
|
||
| updateTime | Date | 更新时间 |
|
||
|
||
### 2.3 学校名称（t_school_name）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | Long | 主键ID |
|
||
| schoolId | Long | 学校ID |
|
||
| name | String | 名称（别名/曾用名/英文名） |
|
||
| nameType | Integer | 名称类型：1官方全称/2曾用名/3别名/4英文名称 |
|
||
|
||
### 2.4 学校标签（t_school_tag）
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| id | Long | 主键ID |
|
||
| schoolId | Long | 学校ID |
|
||
| tagName | String | 标签名（985/211/双一流/…） |
|
||
|
||
### 2.5 学院 / 专业（Task2 扩展表）
|
||
|
||
- 学院：`t_school_college`
|
||
- 专业：`t_school_major`
|
||
- 专业标签：`t_school_major_tag`
|
||
|
||
### 2.6 校区 / 宿舍 / 媒体 / 招生计划（Task2 扩展表）
|
||
|
||
- 校区：`t_school_campus`
|
||
- 宿舍：`t_school_dorm`
|
||
- 媒体：`t_school_media`（biz_type + biz_id）
|
||
- 招生计划：`t_school_enroll_plan`
|
||
|
||
## 3. 接口清单
|
||
|
||
> 说明：所有 `/list` 接口均支持 `pageNo` / `pageSize` 分页。
|
||
>
|
||
> 对于使用 `QueryGenerator` 的 `/list`：可通过 query 参数传实体字段实现筛选（例如 `schoolId=1`、`majorName=计算机`）。
|
||
|
||
### 3.1 学校主表（SchoolController）
|
||
|
||
Base：`/jeecg-boot/school/school`
|
||
|
||
#### 3.1.1 分页列表（通用查询）
|
||
|
||
- Method: `GET`
|
||
- Path: `/list`
|
||
- 权限：无（如需权限可自行加 `@RequiresPermissions`）
|
||
- Query:
|
||
- `pageNo`：默认 1
|
||
- `pageSize`：默认 10
|
||
- 其他：`t_school` 对应字段（例如 `mainName`、`mainCode` 等）
|
||
|
||
#### 3.1.2 关键词搜索（编码/名称/简称/别名）
|
||
|
||
- Method: `GET`
|
||
- Path: `/search`
|
||
- 权限：无
|
||
- Query:
|
||
- `keyword`：可空
|
||
- `pageNo`、`pageSize`
|
||
|
||
#### 3.1.3 新增
|
||
|
||
- Method: `POST`
|
||
- Path: `/add`
|
||
- 权限：`school:school:add`
|
||
- Body(JSON)：
|
||
|
||
```json
|
||
{
|
||
"mainCode": "10001",
|
||
"mainName": "示例大学",
|
||
"shortName": "示大",
|
||
"schoolIcon": "https://example.com/icon.png"
|
||
}
|
||
```
|
||
|
||
#### 3.1.4 修改
|
||
|
||
- Method: `PUT` or `POST`
|
||
- Path: `/edit`
|
||
- 权限：`school:school:edit`
|
||
- Body(JSON)：必须包含 `id`
|
||
|
||
#### 3.1.5 删除
|
||
|
||
- Method: `DELETE`
|
||
- Path: `/delete`
|
||
- 权限：`school:school:delete`
|
||
- Query：`id`
|
||
|
||
#### 3.1.6 批量删除
|
||
|
||
- Method: `DELETE`
|
||
- Path: `/deleteBatch`
|
||
- 权限：`school:school:deleteBatch`
|
||
- Query：`ids`（逗号分隔 Long，例如：`1,2,3`）
|
||
|
||
#### 3.1.7 按ID查询
|
||
|
||
- Method: `GET`
|
||
- Path: `/queryById`
|
||
- Query：`id`
|
||
|
||
#### 3.1.8 全量聚合详情（按ID）
|
||
|
||
- Method: `GET`
|
||
- Path: `/fullById`
|
||
- Query：`id`
|
||
- 返回：`SchoolFullVO`（主表 + detail + names + tags + colleges/majors/...）
|
||
|
||
#### 3.1.9 全量聚合详情（按mainCode）
|
||
|
||
- Method: `GET`
|
||
- Path: `/fullByMainCode`
|
||
- Query：`mainCode`
|
||
|
||
#### 3.1.10 导出
|
||
|
||
- Method: `GET`
|
||
- Path: `/exportXls`
|
||
- 权限：`school:school:exportXls`
|
||
- Query：可带筛选条件（同 `/list`）
|
||
|
||
#### 3.1.11 导入
|
||
|
||
- Method: `POST`
|
||
- Path: `/importExcel`
|
||
- 权限：`school:school:importExcel`
|
||
- Form-Data：`file=@xxx.xlsx`
|
||
|
||
---
|
||
|
||
### 3.2 学校详情（SchoolDetailController）
|
||
|
||
Base：`/jeecg-boot/school/detail`
|
||
|
||
- `GET /list`（QueryGenerator）
|
||
- `POST /add`（权限：`school:detail:add`）
|
||
- `PUT|POST /edit`（权限：`school:detail:edit`）
|
||
- `DELETE /delete`（权限：`school:detail:delete`）
|
||
- `DELETE /deleteBatch`（权限：`school:detail:deleteBatch`）
|
||
- `GET /queryById`
|
||
- `GET /exportXls`（权限：`school:detail:exportXls`）
|
||
- `POST /importExcel`（权限：`school:detail:importExcel`）
|
||
|
||
---
|
||
|
||
### 3.3 学校名称（SchoolNameController）
|
||
|
||
Base：`/jeecg-boot/school/name`
|
||
|
||
- `GET /list`
|
||
- `POST /add`（权限：`school:name:add`）
|
||
- `PUT|POST /edit`（权限：`school:name:edit`）
|
||
- `DELETE /delete`（权限：`school:name:delete`）
|
||
- `DELETE /deleteBatch`（权限：`school:name:deleteBatch`）
|
||
- `GET /queryById`
|
||
- `GET /exportXls`（权限：`school:name:exportXls`）
|
||
- `POST /importExcel`（权限：`school:name:importExcel`）
|
||
|
||
---
|
||
|
||
### 3.4 学校标签（SchoolTagController）
|
||
|
||
Base：`/jeecg-boot/school/tag`
|
||
|
||
- `GET /list`
|
||
- `POST /add`（权限：`school:tag:add`）
|
||
- `PUT|POST /edit`（权限：`school:tag:edit`）
|
||
- `DELETE /delete`（权限：`school:tag:delete`）
|
||
- `DELETE /deleteBatch`（权限：`school:tag:deleteBatch`）
|
||
- `GET /queryById`
|
||
- `GET /exportXls`（权限：`school:tag:exportXls`）
|
||
- `POST /importExcel`（权限：`school:tag:importExcel`）
|
||
|
||
---
|
||
|
||
### 3.5 学院（SchoolCollegeController）
|
||
|
||
Base：`/jeecg-boot/school/college`
|
||
|
||
- `GET /list`
|
||
- `POST /add`（权限：`school:college:add`）
|
||
- `PUT|POST /edit`（权限：`school:college:edit`）
|
||
- `DELETE /delete`（权限：`school:college:delete`）
|
||
- `DELETE /deleteBatch`（权限：`school:college:deleteBatch`）
|
||
- `GET /queryById`
|
||
- `GET /exportXls`（权限：`school:college:exportXls`）
|
||
- `POST /importExcel`（权限：`school:college:importExcel`）
|
||
|
||
---
|
||
|
||
### 3.6 专业（SchoolMajorController）
|
||
|
||
Base：`/jeecg-boot/school/major`
|
||
|
||
- `GET /list`
|
||
- `POST /add`（权限：`school:major:add`）
|
||
- `PUT|POST /edit`（权限：`school:major:edit`）
|
||
- `DELETE /delete`（权限：`school:major:delete`）
|
||
- `DELETE /deleteBatch`（权限：`school:major:deleteBatch`）
|
||
- `GET /queryById`
|
||
- `GET /exportXls`（权限：`school:major:exportXls`）
|
||
- `POST /importExcel`（权限：`school:major:importExcel`）
|
||
|
||
---
|
||
|
||
### 3.7 专业标签（SchoolMajorTagController）
|
||
|
||
Base：`/jeecg-boot/school/majorTag`
|
||
|
||
- `GET /list`
|
||
- `POST /add`（权限：`school:majorTag:add`）
|
||
- `PUT|POST /edit`（权限：`school:majorTag:edit`）
|
||
- `DELETE /delete`（权限：`school:majorTag:delete`）
|
||
- `DELETE /deleteBatch`（权限：`school:majorTag:deleteBatch`）
|
||
- `GET /queryById`
|
||
- `GET /exportXls`（权限：`school:majorTag:exportXls`）
|
||
- `POST /importExcel`（权限：`school:majorTag:importExcel`）
|
||
|
||
---
|
||
|
||
### 3.8 校区（SchoolCampusController）
|
||
|
||
Base：`/jeecg-boot/school/campus`
|
||
|
||
- `GET /list`
|
||
- `POST /add`（权限：`school:campus:add`）
|
||
- `PUT|POST /edit`（权限：`school:campus:edit`）
|
||
- `DELETE /delete`（权限：`school:campus:delete`）
|
||
- `DELETE /deleteBatch`（权限：`school:campus:deleteBatch`）
|
||
- `GET /queryById`
|
||
- `GET /exportXls`（权限：`school:campus:exportXls`）
|
||
- `POST /importExcel`（权限：`school:campus:importExcel`）
|
||
|
||
---
|
||
|
||
### 3.9 宿舍（SchoolDormController）
|
||
|
||
Base：`/jeecg-boot/school/dorm`
|
||
|
||
- `GET /list`
|
||
- `POST /add`（权限：`school:dorm:add`）
|
||
- `PUT|POST /edit`（权限：`school:dorm:edit`）
|
||
- `DELETE /delete`（权限：`school:dorm:delete`）
|
||
- `DELETE /deleteBatch`（权限：`school:dorm:deleteBatch`）
|
||
- `GET /queryById`
|
||
- `GET /exportXls`（权限：`school:dorm:exportXls`）
|
||
- `POST /importExcel`（权限：`school:dorm:importExcel`）
|
||
|
||
---
|
||
|
||
### 3.10 媒体（SchoolMediaController）
|
||
|
||
Base：`/jeecg-boot/school/media`
|
||
|
||
- `GET /list`
|
||
- `POST /add`（权限：`school:media:add`）
|
||
- `PUT|POST /edit`（权限：`school:media:edit`）
|
||
- `DELETE /delete`（权限：`school:media:delete`）
|
||
- `DELETE /deleteBatch`（权限：`school:media:deleteBatch`）
|
||
- `GET /queryById`
|
||
- `GET /exportXls`（权限：`school:media:exportXls`）
|
||
- `POST /importExcel`（权限：`school:media:importExcel`）
|
||
|
||
---
|
||
|
||
### 3.11 招生计划（SchoolEnrollPlanController）
|
||
|
||
Base：`/jeecg-boot/school/enrollPlan`
|
||
|
||
- `GET /list`
|
||
- `POST /add`（权限：`school:enrollPlan:add`）
|
||
- `PUT|POST /edit`（权限：`school:enrollPlan:edit`）
|
||
- `DELETE /delete`（权限：`school:enrollPlan:delete`）
|
||
- `DELETE /deleteBatch`（权限：`school:enrollPlan:deleteBatch`）
|
||
- `GET /queryById`
|
||
- `GET /exportXls`（权限：`school:enrollPlan:exportXls`）
|
||
- `POST /importExcel`（权限：`school:enrollPlan:importExcel`）
|
||
|