DM-ROW 接口文档

Appearance

通用功能模块 ​

**本文引用的文件** - [assign.vue](file://app/devicemate-app/modules/common/assign.vue) - [repair.vue](file://app/devicemate-app/modules/common/repair.vue) - [history.vue](file://app/devicemate-app/modules/common/history.vue) - [common.js（Vuex）](file://app/devicemate-app/store/modules/common.js) - [dictMixins.js](file://app/devicemate-app/utils/dictMixins.js) - [common.js（工具函数）](file://app/devicemate-app/utils/common.js) - [localstorage.js](file://app/devicemate-app/utils/localstorage.js) - [userMixins.js](file://app/devicemate-app/utils/userMixins.js) - [baseForm.vue](file://app/devicemate-app/components/dd-form/baseForm.vue) - [index.js（store入口）](file://app/devicemate-app/store/index.js) - [index.js（modules聚合）](file://app/devicemate-app/store/modules/index.js) - [index.js（配置）](file://app/devicemate-app/config/index.js) - [pages.json](file://app/devicemate-app/pages.json) - [apply.vue（维护申请）](file://app/devicemate-app/modules/maintain/apply.vue) - [apply.vue（维修申请）](file://app/devicemate-app/modules/repair/apply.vue) - [execute.vue（巡检执行）](file://app/devicemate-app/modules/inspectTasks/execute.vue)

目录 ​

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

简介 ​

本文件面向“通用功能模块”的开发与使用，覆盖以下通用业务能力：

  • 工单指派：支持按部门查询用户并选择执行人，提交后联动后端更新工单执行人。
  • 关键维修：填写紧急度、缺陷数量/比例、问题描述、上传异常图片，保存至维修工单。
  • 历史记录：登记异常项，关联到对应工单来源，便于后续追溯。

同时，文档阐述通用模块的复用机制（组件封装、数据共享、状态管理）、与各业务模块的集成方式（数据传递、事件通信、状态同步），并给出开发规范、最佳实践与扩展指南，帮助开发者快速理解与使用这些通用功能。

项目结构 ​

通用功能模块位于前端工程的模块化目录下，采用“按功能域划分”的组织方式：

  • 通用页面：modules/common 下的 assign、repair、history 三个页面，分别对应工单指派、关键维修、历史记录。
  • 状态管理：store/modules/common.js 提供公共状态与动作，统一承载 assignUrl、history、repair 等跨页面数据。
  • 工具与混入：utils 下的 dictMixins、localstorage、userMixins 提供字典、本地存储、用户权限等通用能力；components/dd-form/baseForm.vue 提供通用表单渲染与校验能力。
  • 集成入口：pages.json 中声明了通用页面的导航标题与导航栏按钮等样式；store/index.js 与 store/modules/index.js 组织全局状态。

图表来源

章节来源

核心组件 ​

  • 工单指派（assign.vue）
    • 功能：搜索并选择执行人，提交后调用后端接口更新工单执行人。
    • 关键点：使用Vuex状态 assignUrl 传递目标工单URL与参数；选择后仅允许单选；提交时从选中用户填充执行人信息。
  • 关键维修（repair.vue）
    • 功能：填写紧急度、缺陷数量/比例、问题描述、上传异常图片，保存至维修工单。
    • 关键点：通过字典混入获取紧急度字典；上传组件配置请求头与上传地址；提交时合并表单与Vuex中的repair数据。
  • 历史记录（history.vue）
    • 功能：登记异常项，关联到来源工单与来源类型。
    • 关键点：提交时携带 deviceNo、itemSourceOrderNo、itemSourceType 等上下文信息；上传组件用于异常图片。
  • 通用表单（baseForm.vue）
    • 功能：通用表单渲染、字典选择、日期/时间选择、图片上传、审批流程可视化与提交。
    • 关键点：支持多种输入类型与必填校验；上传前检查未完成上传任务；提供审批弹窗与意见输入。
  • 状态管理（store/modules/common.js）
    • 功能：集中管理 assignUrl、history、repair 等跨页面共享数据；提供 setAssignUrl、setHistory、setRepair 等动作。
  • 工具与混入
    • 字典混入（dictMixins.js）：统一获取字典列表与根据值获取名称。
    • 本地存储（localstorage.js）：封装本地缓存读写。
    • 用户混入（userMixins.js）：权限判断、菜单展示、角色信息加载、默认工厂设置等。

章节来源

架构总览 ​

通用功能模块通过“页面 + 状态管理 + 工具/混入 + 通用组件”的分层设计实现高内聚低耦合：

  • 页面层：assign、repair、history 各自负责单一业务场景。
  • 状态管理层：common 模块集中存放跨页面共享数据，避免重复请求与状态漂移。
  • 工具/混入层：字典、本地存储、用户权限等能力下沉，提升复用性。
  • 通用组件层：baseForm 提供统一表单体验与校验，减少重复开发。

图表来源

详细组件分析 ​

工单指派（assign.vue） ​

  • 数据流
    • 页面加载时调用部门用户接口，渲染用户列表。
    • 用户点击选择后，仅保留一个选中项。
    • 导航栏提交时，读取 assignUrl（来自Vuex），拼接执行人信息后提交。
  • 关键实现要点
    • 使用Vuex映射 assignUrl，保证不同业务场景可注入不同的URL与参数。
    • 选择逻辑为单选，避免多选导致的歧义。
    • 提交成功后返回上一页，保持一致的交互体验。

图表来源

章节来源

关键维修（repair.vue） ​

  • 数据流
    • 页面加载时获取字典列表（如紧急度）。
    • 用户填写表单字段，支持上传异常图片。
    • 导航栏提交时，合并表单数据与Vuex中的repair对象，调用保存接口。
  • 关键实现要点
    • 通过字典混入统一获取字典，避免重复请求。
    • 上传组件配置请求头（含Token与语言），确保鉴权与国际化。
    • 表单字段与上传文件列表统一管理，提交时一并发送。

图表来源

章节来源

历史记录（history.vue） ​

  • 数据流
    • 页面加载时从Vuex读取历史上下文（如工单号、设备号、来源类型）。
    • 用户填写异常项名称，提交时携带上下文信息。
  • 关键实现要点
    • 通过Vuex共享上下文，避免重复传参。
    • 上传组件用于异常图片，提交时与异常项一起保存。

图表来源

章节来源

通用表单（baseForm.vue） ​

  • 数据流
    • 接收 formConfig，动态渲染表单项（输入、选择、日期、时间、上传）。
    • 支持字典选择与自定义数据源；上传前检查未完成上传任务；提交时触发外部事件。
  • 关键实现要点
    • 通过混入获取字典，支持直接传入静态列表或远程字典码。
    • 上传组件自动管理文件列表与上传进度，提交时合并附件。
    • 提供审批弹窗与意见输入，满足审批流程场景。

图表来源

章节来源

与业务模块的集成方式 ​

  • 与“维护/巡检/维修”模块的协作
    • 通用页面通过Vuex注入上下文（如 assignUrl、repair、history），业务模块在跳转前设置对应上下文。
    • 例如：巡检执行页面在详情加载完成后，将当前工单状态写入公共状态，控制页面按钮与标题栏按钮的显示。
  • 与“物料申请”模块的协作
    • 维护/维修申请页面在加载时读取业务上下文，结合通用页面的字典与上传能力，完成物料申请与提交。
  • 与“用户权限/菜单”模块的协作
    • 通过用户混入计算菜单可见性与跳转逻辑，保障页面访问权限。

图表来源

章节来源

依赖分析 ​

  • 组件耦合与内聚
    • 通用页面与Vuex强耦合，但通过统一命名空间与动作降低耦合度。
    • 通用页面与工具/混入弱耦合，通过mixins引入，提升内聚性。
    • 通用表单作为独立组件，被多个页面复用，形成高内聚低耦合。
  • 外部依赖
    • HTTP请求封装于 config/request.js（通过 $http 访问），统一鉴权与拦截。
    • 国际化与主题样式由 uView UI 与全局样式提供。
  • 循环依赖
    • 当前结构未发现循环依赖；若新增页面，应避免在Vuex中互相依赖。

图表来源

章节来源

性能考虑 ​

  • 请求去重与缓存
    • 字典列表建议在进入页面前缓存，避免重复请求；可在字典混入中增加本地缓存策略。
  • 上传优化
    • 通用表单在上传过程中禁用提交按钮，减少无效请求；建议在上传失败时提供重试与错误提示。
  • 渲染优化
    • 通用页面使用虚拟滚动与懒加载（如 mescroll-uni）提升长列表性能。
  • 状态同步
    • 通过Vuex集中管理跨页面状态，避免频繁跨页面传参带来的性能损耗。

故障排查指南 ​

  • 提交失败
    • 检查 assignUrl 是否正确设置；确认后端接口返回状态码与提示。
    • 关键维修/历史记录页面需确认上传组件是否完成上传再提交。
  • 字典未显示
    • 确认字典混入已正确调用；检查网络请求与返回格式。
  • 权限与菜单
    • 使用用户混入的权限判断方法，确认当前用户是否有访问该页面的权限。
  • 本地存储
    • 使用 localstorage 封装的读写方法，确认键名与数据结构一致。

章节来源

结论 ​

通用功能模块以“页面 + 状态管理 + 工具/混入 + 通用组件”为核心，实现了工单指派、关键维修、历史记录等通用业务的高复用与低耦合。通过Vuex集中管理跨页面上下文，配合字典与上传等通用能力，显著降低了业务重复开发成本。建议在后续扩展中继续坚持“分层清晰、职责单一”的原则，并在字典缓存、上传优化、权限控制等方面持续改进。

附录 ​

  • 开发规范与最佳实践
    • 页面命名：通用页面统一置于 modules/common，便于识别与复用。
    • 状态管理：跨页面共享数据统一放入 common 模块，避免分散在各业务模块。
    • 混入使用：将通用逻辑抽象为混入，减少重复代码。
    • 接口调用：统一通过 $http 访问，确保鉴权与拦截一致。
    • 错误处理：每个异步请求均需处理返回状态与错误提示。
  • 使用示例与扩展指南
    • 工单指派：在业务模块中设置 assignUrl，然后跳转到通用页面。
    • 关键维修：在业务模块中设置 repair 上下文，然后跳转到通用页面。
    • 历史记录：在业务模块中设置 history 上下文，然后跳转到通用页面。
    • 通用表单：在业务模块中组装 formConfig，传入 baseForm 即可渲染。

章节来源