ygtx_worklog/docs/diagrams/GxtEquipment功能描述和接口描述.md

GxtEquipmentController 设备管理功能描述和接口描述

一、功能概述

GxtEquipmentController 是一个用于设备管理的 RESTful 控制器，主要用于管理风机设备信息。它提供了完整的设备管理功能，包括设备的增删改查、数据导入导出、品牌机型筛选、维保中心场站筛选等功能。

该控制器主要涉及以下几个核心业务场景：

1. 设备信息的查询、新增、修改、删除
2. 设备数据的导入和导出
3. 品牌、机型、维保中心、场站等筛选条件的获取
4. 设备唯一性校验（根据风机编号、维保中心和场站判断）
5. 数据权限控制

二、核心功能详解

1. 设备信息管理

• 提供设备信息的增删改查功能
• 支持按条件查询设备列表
• 支持分页查询和数据导出
• 支持设备信息的导入和导出

2. 设备唯一性校验

• 在新增和修改设备时，系统会根据风机编号、维保中心和场站三个字段组合判断设备唯一性
• 如果存在相同设备，则不允许新增或提示冲突

3. 筛选条件管理

• 提供品牌列表获取（去重）
• 提供根据品牌获取机型列表（去重）
• 提供维保中心列表获取（去重）
• 提供根据维保中心获取场站列表（去重）
• 提供所有机型列表获取（去重）

4. 数据导入导出

• 支持设备数据的Excel导入，可选择是否支持更新已有数据
• 支持设备数据的Excel导出，可选择导出字段
• 提供导入模板下载功能

5. 数据权限控制

• 基于用户角色的数据范围进行自定义权限控制
• 支持多种数据权限模式：全部数据、自定义数据、部门数据、部门及以下数据、仅本人数据

三、接口详细描述

1. 查询设备管理列表

• 接口地址: /gxt/equipment/list
• 请求方法: GET
• 功能描述: 查询设备管理列表，支持分页和条件查询
• 请求参数:
  • GxtEquipment 对象（包含查询条件）
• 返回结果: TableDataInfo（分页数据）

2. 驾驶舱获取设备数据筛选树状图

• 接口地址: /gxt/equipment/listAll
• 请求方法: GET
• 功能描述: 获取所有设备数据，用于驾驶舱筛选树状图展示
• 请求参数:
  • GxtEquipment 对象（包含查询条件）
• 返回结果: TableDataInfo（完整数据列表）

3. 获取所有品牌列表（去重）

• 接口地址: /gxt/equipment/brands
• 请求方法: GET
• 功能描述: 获取所有品牌列表，去除重复项并按字母排序
• 请求参数: 无
• 返回结果: AjaxResult（包含品牌列表）

4. 根据品牌获取机型列表（去重）

• 接口地址: /gxt/equipment/models/{brand}
• 请求方法: GET
• 功能描述: 根据指定品牌获取对应的机型列表，去除重复项并按字母排序
• 请求参数:
  • brand (String): 品牌名称（路径参数）
• 返回结果: AjaxResult（包含机型列表）

5. 获取所有维保中心列表（去重）

• 接口地址: /gxt/equipment/maintenanceCenters
• 请求方法: GET
• 功能描述: 获取所有维保中心列表，去除重复项并按字母排序
• 请求参数: 无
• 返回结果: AjaxResult（包含维保中心列表）

6. 根据维保中心获取场站列表（去重）

• 接口地址: /gxt/equipment/stations/{maintenanceCenter}
• 请求方法: GET
• 功能描述: 根据指定维保中心获取对应的场站列表，去除重复项并按字母排序
• 请求参数:
  • maintenanceCenter (String): 维保中心名称（路径参数）
• 返回结果: AjaxResult（包含场站列表）

7. 获取所有机型列表（去重）

• 接口地址: /gxt/equipment/models
• 请求方法: GET
• 功能描述: 获取所有机型列表，去除重复项并按字母排序
• 请求参数: 无
• 返回结果: AjaxResult（包含机型列表）

8. 导出设备管理列表

• 接口地址: /gxt/equipment/export
• 请求方法: POST
• 功能描述: 导出设备管理数据到Excel文件
• 请求参数:
  • GxtEquipment 对象（包含导出条件）
  • exportFields (String): 导出字段列表（可选）
• 返回结果: HttpServletResponse（Excel文件流）

9. 获取设备管理导出字段列表

• 接口地址: /gxt/equipment/exportFields
• 请求方法: GET
• 功能描述: 获取设备管理导出字段列表
• 请求参数: 无
• 返回结果: AjaxResult（包含导出字段信息）

10. 获取设备管理详细信息

• 接口地址: /gxt/equipment/{equipmentId}
• 请求方法: GET
• 功能描述: 根据设备ID获取设备详细信息
• 请求参数:
  • equipmentId (Long): 设备ID（路径参数）
• 返回结果: AjaxResult（包含GxtEquipment对象）

11. 新增设备管理

• 接口地址: /gxt/equipment
• 请求方法: POST
• 功能描述: 新增设备管理记录
• 请求参数:
  • GxtEquipment 对象（包含新增数据）
• 返回结果: AjaxResult（新增结果）

12. 修改设备管理

• 接口地址: /gxt/equipment
• 请求方法: PUT
• 功能描述: 修改设备管理记录
• 请求参数:
  • GxtEquipment 对象（包含修改数据）
• 返回结果: AjaxResult（修改结果）

13. 删除设备管理

• 接口地址: /gxt/equipment/{equipmentIds}
• 请求方法: DELETE
• 功能描述: 删除设备管理记录
• 请求参数:
  • equipmentIds (Long[]): 设备ID数组（路径参数）
• 返回结果: AjaxResult（删除结果）

14. 导入设备管理数据

• 接口地址: /gxt/equipment/importData
• 请求方法: POST
• 功能描述: 通过Excel文件导入设备管理数据
• 请求参数:
  • file (MultipartFile): 上传的Excel文件
  • updateSupport (Boolean): 是否支持更新已有数据
• 返回结果: AjaxResult（导入结果信息）

15. 下载设备管理导入模板

• 接口地址: /gxt/equipment/importTemplate
• 请求方法: POST
• 功能描述: 下载设备管理数据导入模板
• 请求参数: 无
• 返回结果: HttpServletResponse（Excel模板文件流）

四、数据处理逻辑

1. 设备唯一性校验

在新增和修改设备时，系统会根据以下三个字段的组合判断设备唯一性：

• equipmentCode（风机编号）
• maintenanceCenter（维保中心）
• station（场站）

如果存在相同组合的设备，则不允许新增或提示冲突。

2. 部门信息处理

在导入设备数据时，系统会自动根据维保中心和场站名称查找对应的部门信息，并设置相应的部门ID：

• maintenanceCenterId（维保中心ID）
• stationId（场站ID）

3. 责任人信息处理

在导入设备数据时，系统会根据责任人姓名查找对应的系统用户，如果找到唯一用户则自动设置责任人ID。

4. 数据权限控制

系统基于用户角色的数据范围进行自定义权限控制，支持以下几种数据权限模式：

• 全部数据权限：可查看所有设备数据
• 自定义数据权限：只能查看指定部门的设备数据
• 部门数据权限：只能查看本部门的设备数据
• 部门及以下数据权限：只能查看本部门及下属部门的设备数据
• 仅本人数据权限：只能查看自己负责的设备数据

五、异常处理

所有接口都具备完善的异常处理机制：

• 对于业务异常（如设备重复、数据验证失败等），返回相应的错误信息
• 对于系统异常，记录日志并返回通用错误提示
• 确保系统的稳定性和用户体验

六、导入导出功能说明

导入功能

1. 支持Excel文件导入设备数据
2. 可选择是否支持更新已有数据
3. 导入时会自动校验数据有效性
4. 导入时会自动处理部门信息和责任人信息
5. 提供详细的导入结果反馈

导出功能

1. 支持Excel文件导出设备数据
2. 可选择导出字段
3. 提供导出字段列表接口供前端使用