DM-ROW 接口文档

Appearance

开发指南 ​

**本文档引用的文件** - [AGENTS.md](file://AGENTS.md) - [lemes-business-devicemate/AGENTS.md](file://lemes-cloud/lemes-business-devicemate/AGENTS.md) - [lemes-business-devicemate/pom.xml](file://lemes-cloud/lemes-business-devicemate/pom.xml) - [lemes-auth/pom.xml](file://lemes-cloud/lemes-auth/pom.xml) - [lemes-gateway/pom.xml](file://lemes-cloud/lemes-gateway/pom.xml) - [lemes-web/README.md](file://dm/lemes-web/README.md) - [front end/AGENTS.md](file://docs/front end/dm/AGENTS.md) - [lemes-web/package.json](file://dm/lemes-web/package.json) - [lemes-web/.eslintrc.js](file://dm/lemes-web/.eslintrc.js) - [lemes-web/vue.config.js](file://dm/lemes-web/vue.config.js) - [devops/AGENTS.md](file://lemes-cloud/src/devops/AGENTS.md) - [lemes-web/src/views/devicemate/README.md](file://dm/lemes-web/src/views/devicemate/README.md) - [devicemate-app/README.md](file://app/devicemate-app/README.md) - [devicemate-app/package.json](file://app/devicemate-app/package.json)

目录 ​

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

简介 ​

本开发指南面向 DeviceMate 项目开发团队，覆盖前后端混合工作区的开发环境搭建、IDE 配置、代码规范、Git 工作流与分支管理、代码评审流程、项目结构与命名约定、新功能开发流程、测试与文档规范、调试与性能优化、以及常见问题解决。本指南以仓库内的 AGENTS.md 与关键配置文件为依据，确保团队遵循统一标准，提升交付质量与效率。

项目结构 ​

DeviceMate 工作区为混合结构，包含后端 Java 微服务（lemes-cloud）、前端 Vue 2 应用（docs/front end/dm/lemes-web）以及文档与资料区（docs/）。根目录 AGENTS.md 明确划分了职责边界与命令入口，避免将整个工作区当作单一构建单元。

图表来源

章节来源

核心组件 ​

  • 后端微服务聚合层：lemes-business-devicemate 聚合 dm-common、dm-device、dm-store、dm-workflow 四个业务域，每个域包含 common 与 server 子模块，端口默认 8040~8043。
  • 前端应用：lemes-web 为 Vue 2 + ElementUI 单页应用，使用 Webpack 构建，支持 ESLint、Jest 单测与 husky/lint-staged 提交前校验。
  • DevOps 交付：src/devops/ 提供 Dockerfile、docker-compose、Jenkins 公共脚本、K8s 服务清单与控制台模板，用于本地与环境部署。
  • 移动端应用：app/devicemate-app 为 uniapp 项目，支持多端打包。

章节来源

架构总览 ​

DeviceMate 采用前后端分离架构：前端通过网关访问后端微服务，认证服务负责 OAuth2 授权与鉴权，业务域服务提供设备、仓储、流程等能力。

图表来源

详细组件分析 ​

后端微服务域与模块边界 ​

  • dm-common：用户/角色/权限/组织/配置/文件等公共能力。
  • dm-device：设备台账、维护计划、点检/巡检、维修工单。
  • dm-store：库存、出入库、借还、胶水场景。
  • dm-workflow：Flowable 表单、任务、流程 API。
  • 端口约定：common=8040、device=8041、store=8042、workflow=8043。
  • Nacos 占位符：@nacos.addr@、@nacos.namespace@、@nacos.group@。

图表来源

章节来源

前端工程与构建配置 ​

  • 入口：lemes-web/src/main.js。
  • 路由、状态、国际化：router/、store/、lang/。
  • 开发端口：9527；代理配置指向后端 API。
  • Lint：ESLint 规则集中于 .eslintrc.js；husky + lint-staged 提交前修复。
  • 测试：Jest 配置指向 tests/unit；当前代码树未发现实体 tests/ 目录，需先核对再创建。
  • 打包：生产环境启用 gzip、runtime inline、chunk split。

图表来源

章节来源

DevOps 交付与部署 ​

  • Dockerfile：Spring Boot 分层镜像。
  • docker-compose：多套 yml、脚本、环境文件，支持本地与环境部署。
  • K8s：service/base、expose-port、job、console 模板等。
  • Jenkins：共享脚本与流水线配置。
  • 混淆：Allatori 资产。

图表来源

章节来源

移动端应用（uniapp） ​

  • 项目描述：支持 H5、安卓、苹果、小程序多端打包。
  • 依赖：jsencrypt、sockjs-client、vue-i18n 等。
  • 注意：当前仓库未提供 uniapp 的 IDE 配置与构建脚本细节，建议在本地按 uniapp 官方流程配置。

章节来源

依赖分析 ​

  • 后端依赖：Swagger、EasyPOI、Redisson、Hystrix、Validation 等业务层依赖在聚合 POM 中声明。
  • 前端依赖：axios、element-ui、echarts、vue、vuex、vue-router 等；husky/lint-staged、Jest、Webpack 插件等开发工具。
  • Nacos 占位符：各业务模块依赖 Nacos 配置占位符，需在启动前正确配置。

图表来源

章节来源

性能考虑 ​

  • 前端
    • 生产环境启用 gzip 压缩与 runtime inline，减少首屏加载与运行时体积。
    • SplitChunks 拆分第三方库、ElementUI 与公共组件，提升缓存命中与并行加载。
    • 图片资源阈值控制与 url-loader/fallback 策略，平衡 base64 与请求开销。
    • 开发环境使用 HardSource 缓存与多进程 loader，缩短热更时间。
  • 后端
    • 依赖 Redisson、Hystrix 等增强稳定性与降级能力。
    • Nacos 配置占位符需正确注入，避免运行期配置缺失导致性能退化。
  • 移动端
    • 按需引入加密与通信库，避免打包体积膨胀。
    • 多端构建前进行资源裁剪与压缩。

章节来源

故障排查指南 ​

  • 前端
    • 开发端口 9527 无法访问：检查 .env.development 是否正确配置 VUE_APP_LEMES_API；确认 devServer.proxy 配置与后端连通性。
    • ESLint 报错：执行 npm run lint 或 pre-commit 自动修复；必要时在本地禁用规则前评估风险。
    • 测试未执行：确认 tests/unit 目录存在且命名符合 Jest 配置；使用 npm run test:ci 进行本地近似 CI 校验。
  • 后端
    • 依赖缺失：先初始化子模块，再执行 Maven 构建；确认 Nacos/Redis/数据库前置条件满足。
    • 端口冲突：根据业务域默认端口（8040~8043）调整本地运行端口或关闭占用进程。
  • DevOps
    • compose/k8s/Jenkins 同时改动：先明确目标环境层级（本地脚本、K8s base、expose-port、job、console template），避免跨层级误改。
  • 移动端
    • 多端打包失败：检查 uniapp 依赖与平台 SDK 版本匹配；按 uniapp 官方流程配置 IDE。

章节来源

结论 ​

本指南基于仓库内的 AGENTS.md 与关键配置文件，为 DeviceMate 项目提供了从环境搭建到交付运维的全链路开发规范。团队应严格遵循：后端按域与 common/server 边界开发、前端按路由/状态/国际化组织代码、DevOps 仅在明确需求下改动、移动端按 uniapp 官方流程配置。通过统一的 Git 工作流、代码规范与测试流程，确保高质量交付。

附录 ​

开发环境搭建与 IDE 配置 ​

  • 后端（Java + Maven）
    • 初始化子模块与依赖：按 lemes-business-devicemate/AGENTS.md 与 lemes-cloud/README.md 指引执行。
    • IDE 建议：IntelliJ IDEA 导入 lemes-cloud 为 Maven 工程；按模块选择运行 dm-common/device/store/workflow 的 Application。
  • 前端（Vue 2 + ElementUI）
    • Node 版本：>=8.9；推荐 >=16.14 使用 pnpm；详见 lemes-web/README.md 与 docs/front end/AGENTS.md。
    • IDE 建议：VS Code 安装 ESLint、Vetur 插件；启用 EditorConfig；prettier 与 ESLint 冲突时以 ESLint 为主。
  • 移动端（uniapp）
    • IDE 建议：HBuilderX 或 VS Code + uniapp 插件；按 uniapp 官方流程配置平台 SDK。

章节来源

Git 工作流与分支管理 ​

  • 根目录 AGENTS.md 明确：lemes-cloud 与 docs/front end/dm/lemes-web 各自为独立 git 仓库，不可将整个工作区当作单一仓库操作。
  • 建议分支模型
    • develop：日常开发分支
    • feature/<name>：功能开发
    • fix/<name>：缺陷修复
    • release/<version>：预发布
    • hotfix/<name>：紧急线上修复
  • 提交规范
    • 语义化提交：feat/fix/docs/chore/style/refactor/test/build/ci
    • 限制单次提交粒度，配合小步快跑与频繁合并

章节来源

代码规范与审查流程 ​

  • 前端
    • ESLint 规则：见 .eslintrc.js；husky + lint-staged 提交前修复；禁止在未评估风险前提下放宽规则。
    • Vue 组件命名：PascalCase；属性换行策略与最大属性数见 .eslintrc.js。
    • 生产环境禁止 debugger；console 使用需谨慎。
  • 后端
    • 依赖与配置：按 lemes-business-devicemate/pom.xml 与各模块 bootstrap.yml/application.yml 注入 Nacos 占位符。
    • 测试：优先单模块 compile/目标测试，大改动再联动构建。
  • 代码审查
    • PR 必须包含变更说明、测试用例与风险评估；Reviewers 至少 1 人；CI 通过后再合并。

章节来源

新功能开发流程 ​

  • 需求评审：明确业务域归属（common/device/store/workflow），评估影响范围。
  • 设计与建模：后端定义接口/实体/Mapper/Service/Controller，前端设计路由/状态/国际化。
  • 开发与自测：按模块边界开发，执行 npm run test:ci（前端）与 mvn test（后端）。
  • 文档：更新 views/devicemate/README.md 与相关文档；补充变更日志。
  • 提交与评审：按 Git 工作流提交，触发 CI，Reviewers 审查后合并。

章节来源

测试要求与文档规范 ​

  • 前端
    • Jest：测试文件命名与位置需符合 jest.config.js；当前代码树未发现实体 tests/ 目录，新增前先核对。
    • 本地 CI：npm run test:ci 联合 lint 与单测。
  • 后端
    • 单模块测试：mvn -pl lemes-service-dm-device -am test；大改动再联动构建。
    • 集成测试：依赖 Redis/Nacos/DB 的测试需确保前置条件满足。
  • 文档
    • views/devicemate/README.md：记录页面与功能说明；变更时同步更新。

章节来源

调试技巧与性能优化建议 ​

  • 前端
    • devServer 代理：确认 /lemes-api 代理与后端连通；必要时在代理 headers 注入 dev-ip。
    • 生产性能：gzip、runtime inline、SplitChunks；图片阈值与 loader 策略。
  • 后端
    • 稳定性：Redisson、Hystrix；Nacos 占位符正确注入。
    • 日志：关注 logs/lemes-* 下的 debug 日志定位问题。
  • 移动端
    • 多端差异：逐平台验证；按 uniapp 官方流程配置 IDE 与平台 SDK。

章节来源