DM-ROW 接口文档

Appearance

表单管理 ​

**本文档引用的文件** - [FormInfoDTO.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/entity/dto/FormInfoDTO.java) - [QryFormInfoResp.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-common/src/main/java/com/lenovo/lemes/service/dm/workflow/entity/outer/QryFormInfoResp.java) - [FormController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-server/src/main/java/com/lenovo/lemes/service/dm/workflow/controller/FormController.java) - [McsFormService.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-server/src/main/java/com/lenovo/lemes/service/dm/workflow/service/McsFormService.java) - [FlowFormService.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-server/src/main/java/com/lenovo/lemes/service/dm/workflow/service/FlowFormService.java) - [FlowFormServiceImpl.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-workflow/lemes-service-dm-workflow-server/src/main/java/com/lenovo/lemes/service/dm/workflow/service/impl/FlowFormServiceImpl.java) - [baseForm.vue](file://app/devicemate-app/components/dd-form/baseForm.vue) - [u-form.vue](file://app/devicemate-app/uview-ui/components/u-form/u-form.vue) - [apply.vue（维修）](file://app/devicemate-app/modules/repair/apply.vue) - [apply.vue（保养）](file://app/devicemate-app/modules/maintain/apply.vue) - [assign.vue（指派）](file://app/devicemate-app/modules/common/assign.vue)

目录 ​

  1. 简介
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能考虑
  8. 故障排查指南
  9. 结论
  10. 附录

简介 ​

本技术文档围绕“表单管理”主题，系统梳理后端工作流表单的数据模型与接口能力，以及前端表单组件与业务页面的协作机制。重点覆盖以下方面：

  • 工作流表单的设计与查询接口：FormInfoDTO、QryFormInfoResp 的职责与使用场景
  • 表单与业务数据的关联：字段映射、数据绑定、表单验证
  • 表单管理 API 的完整规范：查询表单信息、获取表单数据、提交表单
  • 不同类型表单的应用场景：设备维护表单、维修申请表单、审批/指派表单
  • 最佳实践：表单设计原则、数据验证策略、用户体验优化

项目结构 ​

本项目采用前后端分离架构，表单管理涉及后端工作流模块与前端应用模块：

  • 后端（工作流服务）：提供表单信息查询接口，封装 Flowable 表单属性，输出 DTO/响应对象
  • 前端（应用）：提供通用表单组件 baseForm.vue，结合 u-form 组件完成字段渲染、校验与提交；业务页面（维修、保养、指派等）基于该组件实现具体表单

图表来源

章节来源

核心组件 ​

  • 数据模型
    • FormInfoDTO：后端工作流返回的表单信息载体，包含表单 key 与读写权限标识
    • QryFormInfoResp：对外查询响应对象，用于 API 返回给前端
  • 接口层
    • FormController：提供 GET /form/getFormInfo，按流程实例与任务 ID 查询表单信息
  • 服务层
    • McsFormService：抽象表单信息服务，提供按实例/任务查询表单信息与表单信息映射
    • FlowFormService：对接 Flowable 引擎，获取任务表单属性
    • FlowFormServiceImpl：实现 FlowFormService，封装异常处理与错误码
  • 前端组件
    • baseForm.vue：通用表单渲染与交互组件，支持输入、选择、日期时间、上传、审核等
    • u-form.vue：表单容器，提供校验、重置、错误提示等能力

章节来源

架构总览 ​

后端通过工作流引擎获取任务表单属性，转换为统一的 DTO/响应对象，前端以 baseForm.vue 为核心渲染表单，业务页面通过 HTTP 请求与后端交互。

图表来源

详细组件分析 ​

数据模型与实体类 ​

  • FormInfoDTO
    • 字段：formKey（表单键）、isRead（是否可读）、isWrite（是否可写）
    • 用途：承载工作流引擎返回的表单元信息，供前端判断渲染与交互行为
  • QryFormInfoResp
    • 字段：formKey、isRead、isWrite
    • 用途：作为 API 查询响应对象，统一对外输出

图表来源

章节来源

表单查询接口 ​

  • 接口定义
    • 方法：GET
    • 路径：/form/getFormInfo
    • 参数：processInstanceId（流程实例 ID）、taskId（任务 ID）
    • 返回：ResultData<List<QryFormInfoResp>>
  • 控制器职责
    • FormController 调用 McsFormService 获取表单信息，并通过工具类复制为响应对象列表
  • 服务链路
    • McsFormService -> FlowFormService -> FlowFormServiceImpl -> Flowable 引擎
    • FlowFormServiceImpl 在获取任务表单属性失败时抛出带错误码的服务异常

图表来源

章节来源

前端表单组件与渲染 ​

  • baseForm.vue
    • 功能：渲染表单项（输入、选择、日期、时间、上传）、处理用户交互、生成提交数据、控制按钮可用性
    • 关键点：
      • 通过 u-form 绑定 model，逐项渲染并支持必填校验
      • 支持下拉选择、日历、时间选择、文件上传、审核弹窗等
      • 上传文件前缀与鉴权头由组件内部拼装
      • 通过 emit 事件向上抛出提交数据与状态变化
  • u-form.vue
    • 功能：表单容器，提供校验、重置、错误提示等能力
    • 关键点：validate 方法遍历子项执行校验，支持 toast 提示

图表来源

章节来源

业务场景与表单应用 ​

设备维护表单（保养） ​

  • 页面路径：modules/maintain/apply.vue
  • 场景要点：
    • 加载保养标准明细，按物料类型（耗材/工具）映射到表单数据
    • 用户填写使用数量、产线、仓库等字段，提交至保养工单接口
    • 输入校验：数量不能为空、不能小于 1、不能为小数
  • 数据绑定与提交：
    • 将页面数据映射为后端期望的参数结构，POST 提交

图表来源

章节来源

维修申请表单 ​

  • 页面路径：modules/repair/apply.vue
  • 场景要点：
    • 根据设备编号加载主设备详情，映射备件/易耗品清单
    • 用户填写使用数量、仓库等字段，提交至维修工单接口
    • 输入校验：数量不能为空、不能小于 1、不能为小数
  • 数据绑定与提交：
    • 将页面数据映射为后端期望的参数结构，POST 提交

图表来源

章节来源

审批/指派表单 ​

  • 组件：baseForm.vue
  • 场景要点：
    • 支持审核弹窗，选择“通过/不通过”，并可填写意见
    • 上传附件与图片，支持下载查看
    • 通过 emit 事件向上抛出审核参数，由父级处理后续流程
  • 交互逻辑：
    • 审核按钮触发弹窗，确认后 emit 审核类型与意见

图表来源

章节来源

指派任务 ​

  • 页面路径：modules/common/assign.vue
  • 场景要点：
    • 展示部门用户列表，支持搜索
    • 选择执行人后，调用指派接口更新任务执行人
  • 数据绑定与提交：
    • 将选中用户的 userNo/name 作为参数提交

图表来源

章节来源

依赖关系分析 ​

  • 后端依赖链
    • FormController 依赖 McsFormService
    • McsFormService 依赖 FlowFormService
    • FlowFormService 由 FlowFormServiceImpl 实现，调用 Flowable 引擎
  • 前端依赖链
    • 业务页面依赖 baseForm.vue
    • baseForm.vue 依赖 u-form.vue 与各类 UI 组件（u-upload、u-calendar、u-picker 等）

图表来源

章节来源

性能考虑 ​

  • 表单渲染
    • 大量表单项时建议按需渲染与懒加载，避免一次性渲染过多节点
  • 文件上传
    • 上传并发控制与进度反馈，避免阻塞 UI；上传未完成时禁用提交按钮
  • 校验策略
    • 前端即时校验与防抖，后端必做二次校验，减少无效请求
  • 接口调用
    • 合理缓存查询结果（如字典、枚举），减少重复请求

故障排查指南 ​

  • 表单查询失败
    • 现象：调用 /form/getFormInfo 抛出异常或返回空
    • 排查：确认 taskId 是否存在、流程实例是否正确、Flowable 引擎连接状态
    • 参考：FlowFormServiceImpl 中对不存在任务的异常处理
  • 表单提交失败
    • 现象：提交后无响应或报错
    • 排查：检查 baseForm.vue 的上传计数与必填项校验、业务接口参数映射
  • 审核弹窗无响应
    • 现象：点击审核按钮无弹窗或无法提交
    • 排查：确认 emit('approval') 事件是否被父组件接收，弹窗状态是否正确

章节来源

结论 ​

本表单管理体系以工作流引擎为核心，通过统一的 DTO/响应对象与前端通用组件实现跨业务场景的一致体验。后端提供稳定的表单查询接口，前端以 baseForm.vue 为基础，结合业务页面完成复杂表单的渲染与提交。建议在实际落地中遵循本文最佳实践，持续优化用户体验与系统稳定性。

附录 ​

  • API 规范摘要
    • GET /form/getFormInfo
      • 参数：processInstanceId（流程实例 ID）、taskId（任务 ID）
      • 返回：ResultData<List<QryFormInfoResp>>
  • 业务接口参考
    • POST /dm-device/maintenanceWorkOrders/applyFor（保养申请）
    • POST /dm-device/repairWorkOrders/applyFor（维修申请）
    • POST /...（指派接口，携带 excutorNo/excutorName）

章节来源