提交宿舍房间设置的前端界面

This commit is contained in:
zlwu committed 2025-07-22 00:21:59 +08:00
1 parent 7ce20647f0
commit 12b4b58647
28 files changed
+1623 -17

No files matched your search

@@ -0,0 +1,62 @@
# 宿舍楼房间管理功能开发记录
**日期:** 2025-07-03 14:30:25
**开发人员:** Cursor
**功能模块:** 学生宿舍管理系统 - 宿舍楼房间管理
## 变更内容
### 1. 功能概述
开发了宿舍楼房间管理界面,实现了以下功能:
- 左侧树形结构展示校区-宿舍区-宿舍楼的层级关系
- 右侧按楼层展示房间信息,采用卡片式布局
- 支持房间的添加、编辑、删除操作
- 支持床位的添加、编辑、删除操作
- 支持按房间号和状态进行筛选
### 2. 文件变更
#### 新增文件
- `web/src/views/xsssfjgl/index.vue` - 宿舍楼房间管理主界面
- `web/src/views/xsssfjgl/components/RoomDialog.vue` - 房间编辑对话框组件
- `web/src/views/xsssfjgl/components/BedDialog.vue` - 床位编辑对话框组件
- `web/src/api/xsssfjgl/index.ts` - API接口实现
- `web/src/api/xsssfjgl/types.ts` - API类型定义
### 3. 技术实现
#### 3.1 树形结构设计
- 采用Element Plus的Tree组件实现
- 配置了disabled属性,使校区和宿舍区节点不可选
- 只有宿舍楼节点可以被选中,并触发右侧数据加载
#### 3.2 房间展示
- 按楼层分组展示房间信息
- 使用Grid布局实现自适应卡片排列
- 每张卡片包含房间号、类型、床位使用情况和操作按钮
#### 3.3 床位管理
- 点击"床位管理"按钮弹出对话框
- 表格展示该房间的所有床位信息
- 支持床位的增删改操作
#### 3.4 数据处理
- 前期使用模拟数据进行界面开发
- 预留了真实API接口,便于后期接入后端服务
- 完整实现了增删改查的前端逻辑
## 后续工作
1. 对接后端API,替换模拟数据
2. 根据实际业务需求调整界面细节
3. 增加权限控制逻辑
4. 完善数据校验和错误处理
5. 添加单元测试
## 注意事项
- 目前使用模拟数据,未与后端对接
- 表单校验规则已基本实现,但可能需要根据业务规则调整
- v-model:show-search 等指令存在linter错误,后续需要修复
- 组件导入和类型引用存在linter错误,需要调整项目配置
@@ -0,0 +1,489 @@
# 宿舍房间管理API文档
**版本:** 1.0.0
**作者:** Cursor
**更新日期:** 2025-07-03
## 目录
- [1. 概述](#1-概述)
- [2. 接口基础信息](#2-接口基础信息)
- [3. 宿舍楼树形结构接口](#3-宿舍楼树形结构接口)
- [4. 房间管理接口](#4-房间管理接口)
- [5. 床位管理接口](#5-床位管理接口)
- [6. 数据字典](#6-数据字典)
- [7. 错误码说明](#7-错误码说明)
- [8. 移动端实现](#8-移动端实现)
## 1. 概述
本文档描述了宿舍楼房间管理模块的接口规范,包括宿舍楼树形结构查询、房间增删改查和床位管理等功能。
### 1.1 应用场景
- 学工处管理宿舍楼房间信息
- 学生宿舍分配
- 宿舍房间和床位状态维护
### 1.2 功能列表
- 宿舍楼树形结构查询
- 房间列表查询(支持分页和条件筛选)
- 房间新增、修改、删除
- 床位列表查询
- 床位新增、修改、删除
## 2. 接口基础信息
### 2.1 接口规范
- 接口采用RESTful风格
- 请求和响应数据格式均为JSON
- 所有接口均需要携带Token进行认证
- 接口基础路径: `/xsssfjgl`
### 2.2 统一响应格式
```json
{
"code": 200, // 响应状态码,200表示成功
"msg": "操作成功", // 响应消息
"data": {} // 响应数据,根据接口定义不同而不同
}
```
### 2.3 分页查询响应格式
```json
{
"code": 200,
"msg": "查询成功",
"rows": [], // 数据列表
"total": 0 // 总记录数
}
```
## 3. 宿舍楼树形结构接口
### 3.1 获取宿舍树形结构
**接口说明:** 获取校区-宿舍区-宿舍楼的树形结构数据
- **请求方式:** GET
- **请求路径:** `/xsssfjgl/tree`
- **请求参数:** 无
**响应示例:**
```json
{
"code": 200,
"msg": "操作成功",
"data": [
{
"id": 1,
"label": "东校区",
"type": "campus",
"disabled": true,
"children": [
{
"id": 11,
"label": "东区宿舍",
"type": "area",
"disabled": true,
"children": [
{
"id": 111,
"label": "东区1号楼",
"type": "building",
"buildingFloors": 6
}
]
}
]
}
]
}
```
**字段说明:**
| 字段名 | 类型 | 说明 |
| ---- | ---- | ---- |
| id | string/number | 节点ID |
| label | string | 节点名称 |
| type | string | 节点类型:campus(校区)、area(宿舍区)、building(宿舍楼) |
| disabled | boolean | 是否禁用选择 |
| children | array | 子节点 |
| buildingFloors | number | 宿舍楼层数,仅type为building时有效 |
## 4. 房间管理接口
### 4.1 获取房间列表
**接口说明:** 分页查询房间信息
- **请求方式:** GET
- **请求路径:** `/xsssfjgl/room/list`
- **请求参数:**
| 参数名 | 必填 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| pageNum | 是 | number | 页码,从1开始 |
| pageSize | 是 | number | 每页记录数 |
| buildingId | 是 | string/number | 宿舍楼ID |
| roomName | 否 | string | 房间名称,支持模糊查询 |
| floorNumber | 否 | number | 楼层号 |
| status | 否 | string | 房间状态:0-正常,1-维修中,2-停用 |
**响应示例:**
```json
{
"code": 200,
"msg": "查询成功",
"rows": [
{
"roomId": "111101",
"roomName": "101",
"floorNumber": 1,
"buildingId": 111,
"capacity": 4,
"used": 2,
"roomType": "标准间",
"status": "0",
"remark": "",
"createBy": "admin",
"createTime": "2023-01-01 00:00:00",
"updateBy": "admin",
"updateTime": "2023-01-01 00:00:00"
}
],
"total": 60
}
```
### 4.2 获取房间详情
**接口说明:** 根据房间ID获取详细信息
- **请求方式:** GET
- **请求路径:** `/xsssfjgl/room/{roomId}`
- **请求参数:**
| 参数名 | 必填 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| roomId | 是 | string/number | 房间ID |
**响应示例:**
```json
{
"code": 200,
"msg": "操作成功",
"data": {
"roomId": "111101",
"roomName": "101",
"floorNumber": 1,
"buildingId": 111,
"capacity": 4,
"used": 2,
"roomType": "标准间",
"status": "0",
"remark": "",
"createBy": "admin",
"createTime": "2023-01-01 00:00:00",
"updateBy": "admin",
"updateTime": "2023-01-01 00:00:00"
}
}
```
### 4.3 新增房间
**接口说明:** 新增宿舍房间
- **请求方式:** POST
- **请求路径:** `/xsssfjgl/room`
- **请求参数:**
```json
{
"roomName": "101",
"floorNumber": 1,
"buildingId": 111,
"capacity": 4,
"roomType": "标准间",
"status": "0",
"remark": "新增房间"
}
```
**响应示例:**
```json
{
"code": 200,
"msg": "操作成功"
}
```
### 4.4 修改房间
**接口说明:** 修改宿舍房间信息
- **请求方式:** PUT
- **请求路径:** `/xsssfjgl/room`
- **请求参数:**
```json
{
"roomId": "111101",
"roomName": "101",
"floorNumber": 1,
"buildingId": 111,
"capacity": 4,
"roomType": "标准间",
"status": "0",
"remark": "修改房间信息"
}
```
**响应示例:**
```json
{
"code": 200,
"msg": "操作成功"
}
```
### 4.5 删除房间
**接口说明:** 删除宿舍房间
- **请求方式:** DELETE
- **请求路径:** `/xsssfjgl/room/{roomIds}`
- **请求参数:**
| 参数名 | 必填 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| roomIds | 是 | string | 房间ID,多个ID用逗号分隔 |
**响应示例:**
```json
{
"code": 200,
"msg": "操作成功"
}
```
## 5. 床位管理接口
### 5.1 获取床位列表
**接口说明:** 查询指定房间的床位列表
- **请求方式:** GET
- **请求路径:** `/xsssfjgl/bed/list`
- **请求参数:**
| 参数名 | 必填 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| roomId | 是 | string/number | 房间ID |
**响应示例:**
```json
{
"code": 200,
"msg": "操作成功",
"data": [
{
"bedId": "111101-1",
"bedName": "1号床",
"roomId": "111101",
"status": "0",
"studentId": null,
"studentName": null,
"remark": "",
"createBy": "admin",
"createTime": "2023-01-01 00:00:00",
"updateBy": "admin",
"updateTime": "2023-01-01 00:00:00"
},
{
"bedId": "111101-2",
"bedName": "2号床",
"roomId": "111101",
"status": "1",
"studentId": 10001,
"studentName": "张三",
"remark": "",
"createBy": "admin",
"createTime": "2023-01-01 00:00:00",
"updateBy": "admin",
"updateTime": "2023-01-01 00:00:00"
}
]
}
```
### 5.2 新增床位
**接口说明:** 新增床位
- **请求方式:** POST
- **请求路径:** `/xsssfjgl/bed`
- **请求参数:**
```json
{
"bedName": "3号床",
"roomId": "111101",
"status": "0",
"remark": "新增床位"
}
```
**响应示例:**
```json
{
"code": 200,
"msg": "操作成功"
}
```
### 5.3 修改床位
**接口说明:** 修改床位信息
- **请求方式:** PUT
- **请求路径:** `/xsssfjgl/bed`
- **请求参数:**
```json
{
"bedId": "111101-3",
"bedName": "3号床",
"roomId": "111101",
"status": "1",
"remark": "修改床位信息"
}
```
**响应示例:**
```json
{
"code": 200,
"msg": "操作成功"
}
```
### 5.4 删除床位
**接口说明:** 删除床位
- **请求方式:** DELETE
- **请求路径:** `/xsssfjgl/bed/{bedIds}`
- **请求参数:**
| 参数名 | 必填 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| bedIds | 是 | string | 床位ID,多个ID用逗号分隔 |
**响应示例:**
```json
{
"code": 200,
"msg": "操作成功"
}
```
## 6. 数据字典
### 6.1 房间状态
| 状态码 | 说明 |
| ---- | ---- |
| 0 | 正常 |
| 1 | 维修中 |
| 2 | 停用 |
### 6.2 床位状态
| 状态码 | 说明 |
| ---- | ---- |
| 0 | 空闲 |
| 1 | 已分配 |
| 2 | 维修中 |
### 6.3 房间类型
| 类型 | 说明 |
| ---- | ---- |
| 标准间 | 标准宿舍,通常4-6人 |
| 单人间 | 单人宿舍 |
| 套间 | 带独立卫浴的宿舍 |
## 7. 错误码说明
| 错误码 | 说明 |
| ---- | ---- |
| 200 | 操作成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 系统内部错误 |
| 1001 | 房间名称已存在 |
| 1002 | 房间包含已分配的床位,无法删除 |
| 1003 | 床位已分配给学生,无法删除 |
## 8. 移动端实现
### 8.1 移动端适配说明
移动端将实现以下功能:
- 宿舍楼列表查看(无树形结构,改用列表+筛选)
- 房间信息查看
- 床位信息查看
暂不支持在移动端进行房间和床位的增删改操作,仅支持查询功能。
### 8.2 特殊API
移动端将使用与PC端相同的API,但增加以下特殊接口:
**获取宿舍楼列表:**
- **请求方式:** GET
- **请求路径:** `/xsssfjgl/mobile/buildings`
- **请求参数:**
| 参数名 | 必填 | 类型 | 说明 |
| ---- | ---- | ---- | ---- |
| campusId | 否 | string/number | 校区ID |
| areaId | 否 | string/number | 宿舍区ID |
**响应示例:**
```json
{
"code": 200,
"msg": "操作成功",
"data": [
{
"buildingId": 111,
"buildingName": "东区1号楼",
"campusName": "东校区",
"areaName": "东区宿舍",
"floors": 6
}
]
}
```