DM-ROW 接口文档

Appearance

个人借还与损坏管理 ​

**本文引用的文件** - [PersonalPartStoreDo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/entity/PersonalPartStoreDo.java) - [PersonalApplyBorrowOrdersDo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/entity/PersonalApplyBorrowOrdersDo.java) - [PersonalPartReturnOrdersDo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/entity/PersonalPartReturnOrdersDo.java) - [PersonalReportDamageOrdersDo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/entity/PersonalReportDamageOrdersDo.java) - [PersonalStoreService.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/service/PersonalStoreService.java) - [PersonalStoreController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/controller/PersonalStoreController.java) - [PersonalApplyBorrowOrdersController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/controller/PersonalApplyBorrowOrdersController.java) - [PersonalPartReturnOrdersController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/controller/PersonalPartReturnOrdersController.java) - [PersonalReportDamageOrdersController.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/controller/PersonalReportDamageOrdersController.java) - [PersonalStoreMapper.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/mapper/PersonalStoreMapper.java) - [PersonalApplyBorrowOrdersMapper.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/mapper/PersonalApplyBorrowOrdersMapper.java) - [PersonalPartReturnOrdersMapper.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/mapper/PersonalPartReturnOrdersMapper.java) - [PersonalReportDamageOrdersMapper.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-common/src/main/java/com/lenovo/lemes/service/dm/store/mapper/PersonalReportDamageOrdersMapper.java) - [PersonalStoreServiceImpl.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/service/impl/PersonalStoreServiceImpl.java) - [PersonalApplyBorrowOrdersServiceImpl.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/service/impl/PersonalApplyBorrowOrdersServiceImpl.java) - [PersonalPartReturnOrdersServiceImpl.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/service/impl/PersonalPartReturnOrdersServiceImpl.java) - [PersonalReportDamageOrdersServiceImpl.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/service/impl/PersonalReportDamageOrdersServiceImpl.java) - [PersonalStoreServerApplication.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/main/java/com/lenovo/lemes/service/dm/store/PersonalStoreServerApplication.java) - [PersonalStoreServerApplicationTests.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-store/lemes-service-dm-store-server/src/test/java/com/lenovo/lemes/service/dm/store/PersonalStoreServerApplicationTests.java) - [pages.json](file://app/devicemate-app/pages.json) - [apply.vue（维修模块）](file://app/devicemate-app/modules/repair/apply.vue) - [execute.vue（维修模块）](file://app/devicemate-app/modules/repair/execute.vue) - [spareParts.vue（维修模块）](file://app/devicemate-app/modules/repair/components/spareParts.vue) - [apply.vue（保养模块）](file://app/devicemate-app/modules/maintain/apply.vue) - [execute.vue（保养模块）](file://app/devicemate-app/modules/maintain/execute.vue) - [spareParts.vue（保养模块）](file://app/devicemate-app/modules/maintain/components/spareParts.vue) - [repair.js（Vuex模块）](file://app/devicemate-app/store/modules/repair.js) - [my.vue（用户中心）](file://app/devicemate-app/pages/user/my.vue)

目录 ​

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

引言 ​

本技术文档聚焦于“个人借还与损坏管理”模块，围绕以下关键实体展开：个人借出申请单 PersonalApplyBorrowOrdersDo、个人归还单 PersonalPartReturnOrdersDo、个人损坏报告 PersonalReportDamageOrdersDo，以及个人库存 PersonalPartStoreDo。文档从系统架构、业务流程、数据模型、接口设计、安全机制、性能与可维护性等方面进行深入解析，并结合前端页面与后端服务的交互，给出可操作的实践建议与排障指引。

项目结构 ​

该模块横跨前端应用与后端微服务两部分：

  • 前端应用（devicemate-app）：提供个人借还相关页面与交互逻辑，调用后端服务接口。
  • 后端服务（lemes-business-devicemate/lemes-service-dm-store）：提供个人库存与借还损坏相关的核心业务能力，包含实体、Mapper、Service、Controller 层。

图表来源

章节来源

核心组件 ​

本模块的核心由四个领域对象构成，分别对应个人库存、借出申请、归还与损坏报告：

  • 个人库存 PersonalPartStoreDo：记录个人物品的登记、状态、数量、归属等信息。
  • 个人借出申请单 PersonalApplyBorrowOrdersDo：记录借出申请、审批、发放、归还等流转状态。
  • 个人归还单 PersonalPartReturnOrdersDo：记录归还明细与确认状态。
  • 个人损坏报告 PersonalReportDamageOrdersDo：记录损坏事件、责任判定、处理结果等。

图表来源

章节来源

架构总览 ​

后端采用分层架构：Controller 负责请求入口与参数校验；Service 实现业务规则与事务控制；Mapper 负责数据库访问；实体类承载数据模型。前端通过统一路由与网关对接后端服务，页面组件负责表单与交互。

图表来源

详细组件分析 ​

个人借出申请 PersonalApplyBorrowOrdersDo 流程 ​

个人借出申请涉及“申请—审批—发放—归还”的完整闭环。前端页面提供申请与执行入口，后端控制器接收请求并委派给服务层处理，服务层协调 Mapper 完成持久化与状态更新。

图表来源

章节来源

个人归还订单 PersonalPartReturnOrdersDo 处理机制 ​

归还流程强调“数量核对—状态变更—库存同步”。前端页面支持选择归还数量与备注，后端服务在归还确认时校验可用数量与状态，完成后更新库存与订单状态。

图表来源

章节来源

个人损坏报告 PersonalReportDamageOrdersDo 处理机制 ​

损坏报告流程强调“事件登记—状态流转—责任与处理记录”。前端页面支持输入损坏描述与备注，后端服务创建损坏报告并推进到相应状态，便于后续审计与统计。

图表来源

章节来源

个人库存 PersonalPartStoreDo 管理策略 ​

个人库存管理策略包括：

  • 登记：首次登记或新增数量时，写入用户与物品标识、初始数量与状态。
  • 状态跟踪：库存状态与数量变化需与借还、损坏、报废等事件关联，确保可追溯。
  • 权限控制：仅允许本人或授权人员修改库存，防止越权操作。
  • 审计日志：所有变更应记录操作人、时间、变更前后值，便于审计。

图表来源

章节来源

依赖关系分析 ​

后端服务内部依赖清晰：Controller 依赖 Service，Service 依赖 Mapper，实体类作为数据载体贯穿各层。前端通过 pages.json 配置路由，页面组件通过统一的 HTTP 请求对接后端服务。

图表来源

章节来源

性能考虑 ​

  • 数据库索引：针对 userId、partNo、orderNo、reportNo 等高频查询字段建立索引，提升查询与更新效率。
  • 分页与缓存：对列表查询使用分页，对常用字典与静态配置进行缓存，减少数据库压力。
  • 并发控制：借还与库存扣减需使用乐观锁或悲观锁，避免超卖与并发不一致。
  • 接口幂等：对关键操作（如归还确认、损坏上报）设计幂等机制，防止重复提交导致的数据异常。
  • 日志与监控：对关键业务路径埋点，结合链路追踪与告警，快速定位性能瓶颈。

故障排查指南 ​

  • 借还状态异常：检查订单状态机是否按预期流转，核对 Mapper 的更新条件与返回值。
  • 库存不一致：核对库存变更日志与借还流水，排查并发更新与锁机制是否生效。
  • 权限问题：确认前端传入的用户标识与后端鉴权逻辑一致，避免越权操作。
  • 前端路由错误：检查 pages.json 中路由配置与页面路径是否匹配，避免 404 或跳转失败。

章节来源

结论 ​

本模块以清晰的领域模型与分层架构支撑个人借还与损坏管理的全生命周期。通过严格的权限控制、状态机与审计日志，保障业务合规与可追溯。前端页面与后端服务协同，形成完整的用户体验闭环。建议在生产环境中进一步完善并发控制、缓存策略与监控告警体系，持续优化性能与稳定性。

附录 ​

API 接口设计（概念性） ​

以下为概念性接口定义，具体实现以后端控制器为准。请求与响应均遵循 REST 风格，使用统一的状态码与错误格式。

  • 个人借出申请

    • 方法与路径：POST /dm-store/personal/borrow/orders/apply
    • 请求体：包含 userId、partNo、applyCount、workOrderNo 等
    • 返回：orderNo、approveStatus、message

  • 个人借出执行

    • 方法与路径：POST /dm-store/personal/borrow/orders/execute
    • 请求体：包含 orderNo、action（发放/归还）、approveRemark 等
    • 返回：执行结果与状态

  • 个人归还确认

    • 方法与路径：POST /dm-store/personal/return/orders/confirm
    • 请求体：包含 returnNo、userId、orderNo、returnCount、returnRemark 等
    • 返回：确认结果与状态

  • 个人损坏报告创建

    • 方法与路径：POST /dm-store/personal/damage/reports/create
    • 请求体：包含 reportNo、userId、partNo、damageDesc、reportRemark 等
    • 返回：报告编号与状态

  • 个人库存查询

    • 方法与路径：GET /dm-store/personal/store/inventory/{userId}/
    • 返回：库存详情与状态

章节来源

安全机制（概念性） ​

  • 身份验证：前端登录后携带令牌，后端通过网关与认证服务校验。
  • 权限控制：基于用户角色与资源范围限制访问，个人物品仅允许本人或授权人操作。
  • 操作审计：记录关键操作的用户、时间、参数与结果，支持回溯与合规检查。
  • 参数校验：对数量、状态、时间等关键字段进行严格校验，防止非法输入。

章节来源