DM-ROW 接口文档

Appearance

表单管理系统 ​

**本文引用的文件** - [baseForm.vue](file://app/devicemate-app/components/dd-form/baseForm.vue) - [form.vue](file://app/devicemate-app/pages/user/form.vue) - [dictMixins.js](file://app/devicemate-app/utils/dictMixins.js) - [request.js](file://app/devicemate-app/config/request.js) - [index.js](file://app/devicemate-app/config/index.js) - [PermissionController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-server/src/main/java/com/lenovo/lemes/service/dm/common/controller/PermissionController.java) - [SysUserServiceImpl.java](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/java/com/lenovo/lemes/service/common/server/service/impl/SysUserServiceImpl.java) - [SysUserMapper.xml](file://lemes-cloud/lemes-service-common/lemes-service-common-server/src/main/resources/mapper/SysUserMapper.xml) - [DataPermission.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/tools/annotation/DataPermission.java) - [UserVo2.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-common/lemes-service-dm-common-common/src/main/java/com/lenovo/lemes/service/dm/common/client/vo/outer/UserVo2.java) - [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)

目录 ​

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

简介 ​

本技术文档围绕 DeviceMate 表单管理系统，系统性阐述动态表单的设计与实现原理，涵盖字段类型、验证规则、布局管理、数据采集与存储、与业务数据的关联、渲染引擎与交互逻辑、设计器使用与样式定制、权限控制与数据安全、以及性能优化策略。文档以实际源码为依据，配合可视化图示帮助读者快速理解与落地实施。

项目结构 ​

前端采用基于 Vue 的小程序框架，核心表单组件位于 components/dd-form/baseForm.vue；页面级示例位于 pages/user/form.vue；通用请求封装与字典混入分别位于 config/request.js 与 utils/dictMixins.js；后端权限控制与用户体系位于 lemes-cloud 工程模块中。

图表来源

章节来源

核心组件 ​

  • 动态表单组件：负责根据配置渲染不同字段类型、绑定模型、处理交互、上传附件、计算禁用状态与按钮可用性。
  • 页面示例：展示如何声明表单配置、模型与提交处理。
  • 请求封装：统一处理鉴权头、国际化与时区、加载提示与错误提示。
  • 字典混入：提供字典拉取与名称解析能力，支持下拉选择。
  • 后端权限：控制器、服务与映射文件共同实现权限与数据权限控制。

章节来源

架构总览 ​

前端通过 baseForm.vue 组件接收 formConfig，内部根据字段类型渲染输入控件，维护 model 并在提交时回传给上层页面。上传组件与字典混入分别处理附件与下拉选项。后端通过权限控制器与用户服务实现权限校验与数据权限过滤。

图表来源

详细组件分析 ​

动态表单组件（baseForm.vue） ​

  • 设计要点
    • 通过 props 接收 formConfig，内部维护 model 与 props 列表，按类型渲染输入框、下拉、日期、时间、上传等控件。
    • 支持只读模式与可编辑模式切换，通过 calDisabled 控制。
    • 上传组件集成文件列表与上传头，提交前汇总 fileList。
    • 通过 emit 事件向上抛出 change/disabled/submit/approval 等，便于页面或上层容器联动。
  • 字段类型与布局
    • 类型：normal-input、select-input、calendar-input、time-input、upload-input。
    • 布局：label-position、label-width、align、autoHeight、maxlength 等。
  • 交互逻辑
    • 输入变更：inputChange 同步 model，并触发防抖检查禁用状态。
    • 下拉选择：changeSelectShow 拉取字典或自定义函数，selectChange 更新 model 并触发禁用检查。
    • 日期/时间：changeCalendarShow/changeTimeShow 打开弹窗，回调更新 model。
    • 上传：beforeUpload 使用 uni.uploadFile 逐个上传，维护 uploadSuccessCount，提交时校验。
    • 禁用计算：checkDisabled 综合必填与上传进度判断按钮可用性。
  • 数据流
    • model 作为数据载体，fileList 与 model 合并后通过 submit 事件返回。
    • 下载文件：downloadFile 调用 uni.downloadFile/uni.saveFile/uni.openDocument。

图表来源

章节来源

页面示例（form.vue） ​

  • 作用：演示如何声明 formConfig（字段、模型、必填、对齐、高度、最大长度、上传等），并在提交时接收数据。
  • 关键点：type='apply' 控制底部按钮显示；props 定义字段；model 初始化字段值与 fileList。

章节来源

字典混入（dictMixins.js） ​

  • 能力：统一拉取字典列表、根据 dictCode 与 value 解析名称。
  • 与表单联动：当字段配置包含 dictCode 时，组件通过 getDict 拉取并缓存到 item.list，供下拉选择使用。

章节来源

请求封装（request.js） ​

  • 统一处理：
    • 网络状态检测、加载提示、国际化头、工厂时区头。
    • 鉴权头拼接（Bearer Token），错误提示与 401 处理。
    • 过滤响应结构、统一返回 Promise。
  • 与上传：上传头携带 Authorization，用于后端鉴权。

章节来源

配置与密钥（index.js） ​

  • 提供公钥常量，可用于前端加密场景（如签名、校验等）。

章节来源

权限控制与数据安全 ​

  • 后端权限
    • 控制器：基于注解 @PreAuthorize 实现细粒度权限校验（如 user:permission:list/add）。
    • 用户服务：聚合菜单权限、生成用户权限集合。
    • SQL 映射：按权限编码查询用户列表，支撑权限下发与校验。
  • 数据权限
    • 注解：@DataPermission 用于标注字段级数据权限前缀与值。
    • VO：UserVo2 包含角色、部门、权限编码等字段，支撑权限判定。

图表来源

章节来源

与业务数据的关联 ​

  • 表单信息 DTO：FormInfoDTO 定义 formKey、读写权限等，用于后端识别与控制表单访问。
  • 页面示例中的 model：承载业务字段（如联系方式、时间、备注、附件列表），提交时与上传文件一并保存。

章节来源

依赖关系分析 ​

  • 组件耦合
    • baseForm.vue 依赖 request.js 进行网络请求，依赖 dictMixins.js 进行字典拉取。
    • 页面 form.vue 仅负责装配 formConfig，不直接参与复杂逻辑。
  • 外部依赖
    • uView UI 组件库用于表单项、上传、弹窗等。
    • 上传组件依赖 uni.uploadFile 与后端上传接口。
  • 后端依赖
    • 权限控制器与用户服务依赖数据库映射进行权限查询。

图表来源

章节来源

性能考量 ​

  • 上传性能
    • 逐个上传并维护 uploadSuccessCount，在提交时校验未完成的上传，避免并发问题。
    • 建议：分片上传、断点续传、上传队列限制。
  • 渲染性能
    • 使用 v-if/v-show 控制条件渲染，减少不必要的 DOM。
    • 防抖：inputChange 使用防抖降低频繁校验与重绘。
  • 网络性能
    • 统一设置超时与加载提示，避免长时间无反馈。
    • 国际化与时区头按需注入，减少无效请求。
  • 权限查询
    • 后端聚合权限并缓存常用权限集合，减少多次查询。

[本节为通用指导，无需特定文件引用]

故障排查指南 ​

  • 上传失败
    • 现象：上传完成后仍禁用或无法提交。
    • 排查：确认 beforeUpload 中 uploadSuccessCount 是否归零；检查 uni.uploadFile 成功回调与 complete 回调。
    • 参考路径：baseForm.vue:360-394，baseForm.vue:421-442
  • 下拉无数据
    • 现象：选择框显示“请选择”。
    • 排查：确认 dictCode 是否正确；若为自定义函数，确认返回格式；检查 getDict 返回结果。
    • 参考路径：baseForm.vue:275-310，dictMixins.js:10-20
  • 提交按钮不可用
    • 现象：存在必填字段未填或仍有上传任务。
    • 排查：检查 checkDisabled 的必填与上传计数逻辑。
    • 参考路径：baseForm.vue:421-442
  • 权限不足

章节来源

结论 ​

DeviceMate 表单系统通过组件化与配置驱动的方式实现了高扩展的动态表单能力。前端以 baseForm.vue 为核心，结合字典与上传能力，满足多类型字段与复杂交互；后端通过权限与数据权限注解保障安全可控。建议在生产环境中进一步完善上传策略、渲染优化与权限缓存，以获得更佳的用户体验与运行效率。

[本节为总结性内容，无需特定文件引用]

附录 ​

字段类型与配置清单 ​

  • normal-input：普通文本/数字/文本域，支持 inputType、align、autoHeight、maxlength、height、position 等。
  • select-input：下拉选择，支持 dictCode、自定义函数、本地 list。
  • calendar-input：日期选择，支持 maxDate、mode。
  • time-input：时间选择，支持 timeParams。
  • upload-input：文件上传，支持 maxCount、sourceType、sizeType。

章节来源

表单设计器使用指南（概念性说明） ​

  • 设计器职责：可视化配置字段、布局、校验与联动。
  • 建议流程：字段拖拽 → 属性面板配置 → 预览校验 → 导出配置对象 → 前端渲染。
  • 注意事项：字段唯一性、必填与长度限制、字典来源一致性、上传容量与格式限制。

[本节为概念性说明，无需特定文件引用]

样式定制方法（概念性说明） ​

  • 组件样式：通过 uView 组件属性（如 label-width、label-position、align）调整布局。
  • 自定义样式：在 baseForm.vue 的 scoped 样式中覆盖默认样式，注意作用域隔离。
  • 主题适配：统一在 uView 主题文件中调整颜色与字号，保持全局一致。

[本节为概念性说明，无需特定文件引用]