cykj/hzdyjs
1
0 Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

提交代码

Browse Source
This commit is contained in:
zlwu committed 2025-07-21 20:15:31 +08:00
1 parent 225a268e32
commit 7ce20647f0
28 files changed
+1451 -420
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/变更管理/code-adjust-record-2025-07-20-zlwu.md
+68
View File
@@ -0,0 +1,68 @@
# 宿舍楼管理API树形结构开发记录
**时间**: 2025-07-20 15:30:00
**开发人员**: zlwu
**变更模块**: 宿舍管理 - 宿舍楼树形结构API
## 变更内容
### 1. 新增类文件
1. 新增 `BuildingTreeSelectVo.java` 类用于宿舍楼树形结构展示
- 支持校区-宿舍区-宿舍楼三级结构
- 标识节点类型和可选状态
### 2. API接口开发
1. 在 `XgDormBuildingController` 中新增 `/buildingTree` 接口:
- 获取完整的宿舍楼树形结构
- 校区和宿舍区节点设置为不可选(disabled=true)
- 宿舍楼节点设置为可选(disabled=false)
2. 在 `IXgDormBuildingService` 接口中添加 `getBuildingTreeData()` 方法
3. 在 `XgDormBuildingServiceImpl` 中实现树形数据构建逻辑:
- 查询所有校区、宿舍区和宿舍楼数据
- 构建三级层次结构
- 确保树中校区和宿舍区节点被标记为不可选
- 只有宿舍楼节点可以被选择
### 3. 数据表关联关系
- `xg_dorm_building` 通过 `campus_id` 关联 `xg_dorm_campus`
- `xg_dorm_building` 通过 `area_id` 关联 `xg_dorm_area`
- `xg_dorm_area` 通过 `campus_id` 关联 `xg_dorm_campus`
### 4. 前端实现
1. 在`web/src/api/sslxx/dormBuilding/types.ts`中添加`BuildingTreeSelectVo`接口定义:
- 定义了树形节点的属性类型
- 包含id、label、nodeType、disabled等核心字段
- 支持children属性用于嵌套结构
2. 在`web/src/api/sslxx/dormBuilding/index.ts`中添加`getBuildingTree`方法:
- 调用后端API获取树形结构数据
- 方法返回类型为`AxiosPromise<BuildingTreeSelectVo[]>`
3. 修改`ScopeDialog.vue`组件:
- 为宿舍楼类型(type="building")添加独立的树形选择器
- 移除原有的模拟数据，改用API获取真实数据
- 添加宿舍楼数据回显和解析逻辑
- 保留对校区和宿舍区的原有支持
## 技术实现
树形结构数据构建采用三步查询 + 组装的方式:
1. 首先查询所有校区数据
2. 查询所有宿舍区数据
3. 查询所有宿舍楼数据
4. 通过Stream API过滤和关联数据，构建多层嵌套结构
## 使用说明
1. 校区管理员授权时，使用普通多选下拉框
2. 宿舍区管理员授权时，使用以校区为父节点的两级树形结构
3. 宿舍楼管理员授权时，使用新开发的三级树形结构(校区-宿舍区-宿舍楼)
- 校区和宿舍区节点自动禁用，不可选择
- 只有宿舍楼节点可以选择
- 支持多选和折叠标签
docs/开发文档/API/API文档总览.md
+29 -170
View File
@@ -1,189 +1,48 @@
# API 文档总览
# API文档总览
## 📋 文档说明
本文件作为API文档的统一导航入口，提供项目中所有API文档的快速访问链接。
本文档是校园管理系统 API 接口的总览和导航页面。为了提高文档的可维护性和可读性，API 文档已按业务模块进行拆分。
## 认证登录
**拆分完成时间**: 2025-07-01
**拆分目的**: 按业务模块管理，便于维护和查找，减少单个文件过大的问题
- [用户认证登录API](./用户认证登录API.md) - 用户登录、获取用户信息等接口
---
## 学工管理模块
- [班干部管理API](班干部管理API.md)
- [宿舍管理员授权API](宿舍管理员授权API.md)
- [宿舍楼树形结构API](宿舍楼树形结构API.md) - 校区-宿舍区-宿舍楼三级树形结构数据
## 📊 API 文档架构
## 后勤管理
### 🔗 分模块 API 文档
### 场地管理
| 文档名称 | 文件路径 | 主要内容 | 适用场景 |
| ------------------------- | ----------------------------------------------- | ---------------------------------------------- | -------------------- |
| **📋 API 文档基础规范** | [API 文档基础规范.md](./API文档基础规范.md) | 请求头规范、响应格式、状态码、错误码、数据字典 | **所有开发人员必读** |
| **🔐 用户认证登录 API** | [用户认证登录 API.md](./用户认证登录API.md) | 用户登录、退出、验证码、用户信息、租户管理 | 认证相关开发 |
| **🛠️ 物业报修管理 API** | [物业报修管理 API.md](./物业报修管理API.md) | 维修分类、报修工单、进度跟踪、服务评价 | 物业报修功能开发 |
| **📊 后勤满意度调查 API** | [后勤满意度调查 API.md](./后勤满意度调查API.md) | 问卷管理、答题、题目管理、答题记录 | 满意度调查功能开发 |
| **🏢 场地预约管理 API** | [场地预约管理 API.md](./场地预约管理API.md) | 场地信息管理、预约申请、审批流程、冲突检查 | 场地预约功能开发 |
| **🎭 报告厅预约审核 API** | [报告厅预约审核 API.md](./报告厅预约审核API.md) | 审核建议生成、时间冲突检查、批量审核处理 | 报告厅审核功能开发 |
- [场地预约管理API](./场地预约管理API.md) - 场地信息管理、预约申请管理接口
- [报告厅预约审核API](./报告厅预约审核API.md) - 报告厅信息管理、预约审核接口
### 📝 阅读建议
### 物业管理
1. **首次阅读**: 先阅读 [API 文档基础规范.md](./API文档基础规范.md) 了解通用规范
2. **业务开发**: 根据开发的功能模块选择对应的 API 文档
3. **交叉引用**: 各模块文档间有交叉引用，便于快速查找相关接口
- [物业报修管理API](./物业报修管理API.md) - 报修工单管理、维修处理接口
---
### 满意度调查
## 🎯 快速导航
- [后勤满意度调查API](./后勤满意度调查API.md) - 问卷设计、答题管理接口
### 🔍 按功能查找接口
## 工作流管理
#### 🔐 用户认证相关
- [请假流程API](./请假流程API.md) - 请假申请、审批管理接口
- [用户登录](./用户认证登录API.md#用户登录) - AES+RSA 加密登录
- [退出登录](./用户认证登录API.md#退出登录) - 清除会话
- [获取验证码](./用户认证登录API.md#获取验证码) - 图形验证码
- [获取用户信息](./用户认证登录API.md#获取当前用户信息) - 用户详情和权限
- [租户管理](./用户认证登录API.md#租户管理) - 多租户支持
## 系统管理
#### 🛠️ 物业报修相关
- [菜单权限API](./菜单权限API.md) - 菜单配置、权限管理接口
- [用户管理API](./用户管理API.md) - 系统用户、角色、部门管理接口
- [维修分类管理](./物业报修管理API.md#维修分类管理) - 分类 CRUD 操作
- [报修工单管理](./物业报修管理API.md#报修工单管理) - 工单生命周期
- [工单进度跟踪](./物业报修管理API.md#获取工单进度列表) - 进度记录
- [服务评价](./物业报修管理API.md#服务评价管理) - 评价系统
## API基础规范
#### 📊 满意度调查相关
- [API文档基础规范](./API文档基础规范.md) - API接口设计规范、响应格式规范
- [问卷管理](./后勤满意度调查API.md#问卷基础管理) - 问卷 CRUD 操作
- [答题功能](./后勤满意度调查API.md#答题API) - 答题提交和查询
- [题目管理](./后勤满意度调查API.md#题目管理API) - 题目和选项
- [答题记录](./后勤满意度调查API.md#答题记录管理API) - 记录查询
## 更新记录
#### 🏢 场地预约相关
- [场地信息管理](./场地预约管理API.md#场地信息管理api) - 场地 CRUD 操作
- [场地预约申请](./场地预约管理API.md#场地预约管理api) - 预约提交和修改
- [预约审批](./场地预约管理API.md#审批场地预约) - 审批流程管理
- [时间冲突检查](./场地预约管理API.md#检查时间冲突) - 预约冲突检测
#### 🎭 报告厅审核相关
- [报告厅预约查询](./报告厅预约审核API.md#报告厅预约查询-api) - 预约列表和详情查询
- [时间冲突检查](./报告厅预约审核API.md#时间冲突检查-api) - 智能冲突检测
- [批量审核处理](./报告厅预约审核API.md#报告厅预约审核-api) - 批准/拒绝预约申请
- [审核建议生成](./报告厅预约审核API.md#时间冲突检查-api) - 基于冲突检查的智能建议
### 🔍 按开发阶段查找
#### 🚀 项目初期
1. [API 文档基础规范.md](./API文档基础规范.md) - 了解通用规范
2. [用户认证登录 API.md](./用户认证登录API.md) - 实现用户认证
3. 选择业务模块文档进行开发
#### 🛠️ 功能开发
- 根据具体功能模块查找对应 API 文档
- 参考接口示例和错误码说明
- 使用数据字典了解枚举值含义
#### 🧪 接口测试
- 参考各文档中的请求示例
- 使用提供的测试脚本
- 查看错误码说明进行问题排查
---
## 📋 通用信息
### 🔧 基础配置
- **基础路径**: `/api`
- **响应格式**: JSON
- **字符编码**: UTF-8
- **权限认证**: Sa-Token + JWT
- **版本**: v1.0
- **🌐 在线 API 文档**: [http://localhost:8080/swagger-ui/index.html](http://localhost:8080/swagger-ui/index.html) ⭐
### 📊 API 文档查看方式
1. **🌟 Swagger UI 在线文档** (推荐)
- **访问地址**: http://localhost:8080/swagger-ui/index.html
- **特点**: 可视化界面，支持在线测试，按模块分组
- **使用场景**: 接口调试、快速查看、在线测试
2. **📁 项目内置文档** (详细)
- **位置**: `docs/开发文档/API/`
- **特点**: 中文详细说明，业务逻辑解释，完整示例
- **使用场景**: 深入了解业务逻辑、开发参考
### 🔐 认证要求
所有需要认证的接口都必须在请求头中携带：
```json
{
"Authorization": "Bearer {access_token}",
"clientid": "e5cd7e4891bf95d1d19206ce24a7b32e",
"Content-Type": "application/json;charset=utf-8"
}
```
详细说明请参考：[API 文档基础规范.md](./API文档基础规范.md#请求头规范强制性)
### 📊 响应格式
- **分页列表**: TableDataInfo 格式 (total, rows, code, msg)
- **非分页接口**: R 类型格式 (code, msg, data)
- **错误响应**: 统一错误格式
详细说明请参考：[API 文档基础规范.md](./API文档基础规范.md#统一响应格式强制性)
---
## 🔄 文档维护
### 📝 更新规则
1. **基础规范变更**: 更新 [API 文档基础规范.md](./API文档基础规范.md)
2. **认证相关变更**: 更新 [用户认证登录 API.md](./用户认证登录API.md)
3. **物业报修变更**: 更新 [物业报修管理 API.md](./物业报修管理API.md)
4. **满意度调查变更**: 更新 [后勤满意度调查 API.md](./后勤满意度调查API.md)
5. **总览更新**: 根据需要更新本文档
### 🚨 强制要求
- **同步更新**: 代码变更时必须同步更新对应的 API 文档
- **向下兼容**: 新版本 API 必须考虑向下兼容性
- **版本记录**: 重大变更需要在相应文档中记录版本信息
---
## 📞 联系方式
如有 API 文档相关问题，请联系开发团队或查看项目仓库的 Issues。
---
## 📈 版本历史
### v2.0.0 (2025-07-01) - API 文档拆分重构
- 🔄 **重大架构调整**: API 文档按业务模块拆分
- 📋 **新增基础规范文档**: 统一管理通用规范
- 🔐 **独立认证 API 文档**: 用户认证登录专门文档
- 🛠️ **物业报修 API 文档**: 报修管理专门文档
- 📊 **满意度调查 API 文档**: 问卷答题专门文档
- 📝 **中文文件命名**: 便于快速识别和查找
- 🔗 **交叉引用系统**: 各文档间建立引用关系
- 📚 **总览导航**: 提供统一的文档入口
### v1.x.x (2025-01-26 及之前)
参考各个拆分文档中的版本历史记录。
---
**📝 维护**: API 文档总览和导航
**🔄 更新**: 2025-07-01
**📁 架构**: 4 个专门 API 文档 + 1 个总览文档
**🎯 目标**: 提供清晰的 API 文档导航和管理体系
- 2025-07-20：新增宿舍楼树形结构API文档
- 2025-07-20：新增宿舍管理员授权API文档
- 2025-07-15：新增场地预约管理API文档
- 2025-07-10：新增物业报修管理API文档
- 2025-07-01：重组API文档结构，创建统一导航入口
docs/开发文档/API/宿舍楼树形结构API.md
+174
View File
@@ -0,0 +1,174 @@
# 宿舍楼树形结构API文档
## 接口说明
本文档描述了获取宿舍楼树形结构数据的API接口，该接口返回校区-宿舍区-宿舍楼的三级树形结构，其中校区和宿舍区节点不可选，只有宿舍楼节点可以选择。
## 接口定义
### 获取宿舍楼树形结构
**请求URL**：`/sslxx/dormBuilding/buildingTree`
**请求方式**：`GET`
**权限标识**：`sslxx:dormBuilding:list`
**请求参数**：无
**响应示例**：
```json
{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": 1,
"label": "东校区",
"nodeType": "campus",
"disabled": true,
"children": [
{
"id": 101,
"label": "东区宿舍区",
"nodeType": "area",
"disabled": true,
"children": [
{
"id": 1001,
"label": "1号楼",
"nodeType": "building",
"disabled": false
},
{
"id": 1002,
"label": "2号楼",
"nodeType": "building",
"disabled": false
}
]
}
]
},
{
"id": 2,
"label": "西校区",
"nodeType": "campus",
"disabled": true,
"children": [
{
"id": 201,
"label": "西区宿舍区",
"nodeType": "area",
"disabled": true,
"children": [
{
"id": 2001,
"label": "3号楼",
"nodeType": "building",
"disabled": false
},
{
"id": 2002,
"label": "4号楼",
"nodeType": "building",
"disabled": false
}
]
}
]
}
]
}
```
## 数据结构
### BuildingTreeSelectVo
树形结构节点对象：
| 字段名 | 类型 | 描述 |
|------------|-------------------|----------------------------------------|
| id | Long | 节点ID |
| label | String | 节点名称 |
| nodeType | String | 节点类型：campus(校区)、area(宿舍区)、building(宿舍楼) |
| disabled | Boolean | 是否禁用选择 |
| children | List<BuildingTreeSelectVo> | 子节点列表 |
| createBy | Long | 创建者 |
| createTime | Date | 创建时间 |
| updateBy | Long | 更新者 |
| updateTime | Date | 更新时间 |
## 使用方法
### 前端使用示例
在Vue组件中使用该接口获取树形数据：
```typescript
import { getBuildingTree } from '@/api/sslxx/dormBuilding';
import type { BuildingTreeSelectVo } from '@/api/sslxx/dormBuilding/types';
// 在组件的setup函数中
const treeData = ref<BuildingTreeSelectVo[]>([]);
// 加载宿舍楼树形数据
const loadBuildingTree = async () => {
try {
const res = await getBuildingTree();
if (res && res.data) {
treeData.value = res.data;
}
} catch (error) {
console.error('加载宿舍楼树形数据失败:', error);
}
};
// 调用加载方法
loadBuildingTree();
```
### 使用el-tree-select组件展示
```html
<el-tree-select
v-model="selectedBuildings"
placeholder="请选择宿舍楼"
style="width: 100%"
clearable
filterable
multiple
collapse-tags
collapse-tags-tooltip
:data="treeData"
:props="{
children: 'children',
label: 'label',
disabled: 'disabled',
value: 'id'
}"
check-strictly
/>
```
## 特殊说明
1. 接口返回的树形结构中，校区和宿舍区节点已设置 `disabled=true`，前端无需额外处理即可实现只能选择宿舍楼节点的效果
2. 使用 `check-strictly=true` 可以确保树形选择器的选中状态不会级联影响父子节点
3. 该接口已支持管理员分配宿舍楼管理范围的业务需求
## 相关API接口
- [宿舍管理员授权API](./宿舍管理员授权API.md)
## 数据库关系
- `xg_dorm_building` 表通过 `campus_id` 字段关联 `xg_dorm_campus` 表
- `xg_dorm_building` 表通过 `area_id` 字段关联 `xg_dorm_area` 表
- `xg_dorm_area` 表通过 `campus_id` 字段关联 `xg_dorm_campus` 表
## 最后更新时间
2025-07-20
docs/开发文档/API/宿舍管理员授权API.md
+112
View File
@@ -0,0 +1,112 @@
# 宿舍管理员授权API文档
## 1. 接口总览
| 接口名称 | 请求方式 | 接口地址 | 接口描述 |
| ------- | ------- | ------- | ------- |
| 获取宿舍区树形结构 | GET | /ssqxx/dormArea/tree | 获取以校区为根节点、宿舍区为子节点的树形结构数据 |
## 2. 权限要求
- 查询宿舍区树形结构：`ssqxx:dormArea:query`
## 3. 接口详情
### 3.1 获取宿舍区树形结构
#### 接口说明
该接口用于获取宿舍区的树形结构数据，以校区为根节点，宿舍区为子节点。前端可以使用该接口实现树形下拉选择，实现宿舍管理员授权范围选择功能。
#### 请求URL
```
GET /ssqxx/dormArea/tree
```
#### 请求参数
无
#### 响应参数
| 参数名 | 类型 | 说明 |
| ------ | ---- | ---- |
| code | Integer | 状态码，200表示成功 |
| msg | String | 提示信息 |
| data | Array | 数据内容 |
| data[i].id | Long | 节点ID |
| data[i].label | String | 节点名称 |
| data[i].type | String | 节点类型（campus：校区，area：宿舍区） |
| data[i].disabled | Boolean | 是否禁用选择（校区节点为true，宿舍区节点为false） |
| data[i].children | Array | 子节点，结构同父节点 |
#### 响应示例
```json
{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": 1,
"label": "东校区",
"type": "campus",
"disabled": true,
"children": [
{
"id": 101,
"label": "1号宿舍区",
"type": "area",
"disabled": false,
"children": []
},
{
"id": 102,
"label": "2号宿舍区",
"type": "area",
"disabled": false,
"children": []
}
]
},
{
"id": 2,
"label": "西校区",
"type": "campus",
"disabled": true,
"children": [
{
"id": 201,
"label": "3号宿舍区",
"type": "area",
"disabled": false,
"children": []
}
]
}
]
}
```
## 4. 使用说明
### 前端使用方式
1. 调用树形结构接口获取宿舍区树形数据
2. 使用树形选择组件展示数据，设置不可选择校区节点（根据disabled属性）
3. 用户只能选择宿舍区节点，不能选择校区节点
4. 支持多选宿舍区节点
### 数据说明
- 树形结构中，校区为第一级节点，宿舍区为第二级节点
- 校区节点的disabled属性为true，表示不可选择
- 宿舍区节点的disabled属性为false，表示可以选择
- 通过type字段可以区分节点类型：campus为校区，area为宿舍区
## 5. 实现细节
- 宿舍区数据存放在xg_dorm_area表中，校区数据存放在xg_dorm_campus表中
- xg_dorm_area表中campus_id字段关联xg_dorm_campus表的id字段
- 树形数据的构建逻辑是：先查询所有校区，再查询所有宿舍区，然后根据关联关系构建树形结构