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

GxtUserScoreController 功能描述和接口描述

一、功能概述

GxtUserScoreController 是一个用于处理用户月度评分统计的 RESTful 控制器。它提供了完整的月度评分管理功能，包括查询、新增、修改、删除用户月度评分信息，以及处理复杂的月度工分汇总和评分提交功能。

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

1. 用户月度评分列表的查询和管理
2. 人员评分页面数据的获取和展示
3. 月度工分汇总数据的计算和展示
4. 统一提交人员评分页面的所有数据
5. 月度评分数据的导出功能

二、核心功能详解

1. 人员评分管理

• 提供用户月度评分的增删改查功能
• 支持按条件查询用户月度评分列表
• 支持分页查询和数据导出

2. 人员评分页面数据获取

• 根据类型(rtType)和月份周期(monthPeriod)获取相关人员评分数据
• 整合多个评分维度的数据，包括：
  • 系数与定检台数统计数据
  • 安全运行工单列表数据
  • 维保机组类型评分数据
  • 检修员得分列表数据
  • 维修员最终得分列表数据
  • 场站负责人评分列表数据

3. 月度工分汇总

• 根据类型、月份周期和部门ID获取月度工分汇总数据
• 支持根据ID获取特定的月度工分汇总信息
• 提供月度工分汇总列表数据获取功能

4. 评分数据提交

• 提供统一提交人员评分页面所有数据的功能
• 支持批量处理多种类型的评分数据
• 具备数据去重和更新机制

5. 辅助功能

• 获取汇总月份列表
• 数据导出功能

三、接口详细描述

1. 查询用户月度评分统计表列表

• 接口地址: /gxt/userscore/list
• 请求方法: GET
• 功能描述: 查询用户月度评分统计表列表，支持分页
• 请求参数:
  • GxtUserScore 对象（包含查询条件）
• 返回结果: TableDataInfo（分页数据）

2. 人员评分页面数据获取

• 接口地址: /gxt/userscore/getUserScoreInfo
• 请求方法: GET
• 功能描述: 获取人员评分页面数据，整合多个评分维度的数据
• 请求参数:
  • rtType (Integer): 类型
  • monthPeriod (String): 月份周期
• 返回结果: AjaxResult（包含各类评分数据列表）

3. 月度工分汇总页面数据获取

• 接口地址: /gxt/userscore/getScoreSummary
• 请求方法: GET
• 功能描述: 获取月度工分汇总页面数据
• 请求参数:
  • rtType (Integer): 类型
  • monthPeriod (String): 月份周期
  • deptId (Long): 部门ID
• 返回结果: AjaxResult（包含月度工分汇总数据）

4. 根据ID获取月度工分汇总

• 接口地址: /gxt/userscore/getScoreSummaryById
• 请求方法: GET
• 功能描述: 根据ID获取月度工分汇总信息
• 请求参数:
  • rtType (Integer): 类型
  • id (Long): ID
• 返回结果: AjaxResult（包含月度工分汇总数据）

5. 月度工分汇总列表数据获取

• 接口地址: /gxt/userscore/getMonthScoreList
• 请求方法: GET
• 功能描述: 获取月度工分汇总列表数据
• 请求参数:
  • SysDept 对象（包含查询条件）
• 返回结果: TableDataInfo（分页数据）

6. 统一提交月度工分汇总

• 接口地址: /gxt/userscore/submitMonthScore
• 请求方法: POST
• 功能描述: 提交月度工分汇总数据
• 请求参数:
  • GxtMonthScore 对象（包含月度工分汇总数据）
• 返回结果: AjaxResult（提交结果）

7. 获取汇总月份列表

• 接口地址: /gxt/userscore/getSummaryMonths
• 请求方法: GET
• 功能描述: 获取可汇总的月份列表
• 请求参数:
  • deptId (Long): 部门ID
• 返回结果: AjaxResult（包含月份字典列表）

8. 导出用户月度评分统计表列表

• 接口地址: /gxt/userscore/export
• 请求方法: POST
• 功能描述: 导出用户月度评分统计表数据到Excel
• 请求参数:
  • GxtUserScore 对象（包含导出条件）
• 返回结果: HttpServletResponse（Excel文件流）

9. 获取用户月度评分统计表详细信息

• 接口地址: /gxt/userscore/{id}
• 请求方法: GET
• 功能描述: 根据ID获取用户月度评分统计表详细信息
• 请求参数:
  • id (Long): 主键ID（路径参数）
• 返回结果: AjaxResult（包含GxtUserScore对象）

10. 新增用户月度评分统计表

• 接口地址: /gxt/userscore
• 请求方法: POST
• 功能描述: 新增用户月度评分统计表记录
• 请求参数:
  • GxtUserScore 对象（包含新增数据）
• 返回结果: AjaxResult（新增结果）

11. 修改用户月度评分统计表

• 接口地址: /gxt/userscore
• 请求方法: PUT
• 功能描述: 修改用户月度评分统计表记录
• 请求参数:
  • GxtUserScore 对象（包含修改数据）
• 返回结果: AjaxResult（修改结果）

12. 删除用户月度评分统计表

• 接口地址: /gxt/userscore/{ids}
• 请求方法: DELETE
• 功能描述: 删除用户月度评分统计表记录
• 请求参数:
  • ids (Long[]): 主键ID数组（路径参数）
• 返回结果: AjaxResult（删除结果）

13. 统一提交人员评分页面的所有数据

• 接口地址: /gxt/userscore/submitAllScores
• 请求方法: POST
• 功能描述: 统一提交人员评分页面的所有列表数据
• 请求参数:
  • GxtUserScoreSubmissionDTO 对象（包含所有评分数据）
• 返回结果: AjaxResult（提交结果）

四、数据处理逻辑

1. 数据提交处理逻辑

当提交评分数据时，系统会根据monthPeriod和userName查询是否存在记录：

• 如果存在记录，则更新第一条记录
• 如果不存在记录，则新增记录

2. 权限控制

系统通过configService获取"gxt.user.scorePage"配置来控制数据访问权限。

3. 数据完整性保障

在处理各类评分数据时，系统会确保数据的完整性和一致性，避免重复数据的产生。

五、异常处理

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

• 对于业务异常，返回相应的错误信息
• 对于系统异常，记录日志并返回通用错误提示
• 确保系统的稳定性和用户体验