DM-ROW 接口文档

Appearance

物料主数据表结构 ​

**本文引用的文件** - [store.sql](file://docs/ddl/store.sql) - [PartMainDo.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/PartMainDo.java) - [PartMainApi.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-common/src/main/java/com/lenovo/lemes/service/dm/device/api/PartMainApi.java) - [PartMainVo.java](file://lemes-cloud/lemes-business-devicemate/lemes-service-dm-device/lemes-service-dm-device-common/src/main/java/com/lenovo/lemes/service/dm/device/client/entity/outer/PartMainVo.java) - [PartMainQueryVo.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/api/modal/PartMainQueryVo.java) - [BaseEntity.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/entity/BaseEntity.java)

目录 ​

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

简介 ​

本文件面向“物料主数据”（part_main）表，提供从数据库结构到应用层对象与接口的完整说明。重点覆盖以下方面：

  • 字段设计与业务含义：物料编码、名称、规格、计量单位、控制类型、价格信息等
  • 分类体系：大类、小类、子类
  • 生命周期与有效期管理：有效期件、寿命件、最大寿命值与单位
  • 唯一性约束与有效性标志：(factory_no, part_no)唯一、valid_flag、is_delete
  • 序列号生成规则：serial_rule
  • 业务规则、数据校验逻辑与与其他表的关联关系
  • 实际插入示例与查询优化建议

项目结构 ​

围绕物料主数据的核心文件分布如下：

  • 数据库定义：docs/ddl/store.sql 中包含 part_main 表结构、注释与序列
  • 应用实体：PartMainDo.java 映射 part_main 的 Java 实体
  • 设备侧对外接口：PartMainApi.java 提供查询接口
  • 设备侧对外 VO：PartMainVo.java 定义返回模型及校验规则
  • 查询参数 VO：PartMainQueryVo.java 定义查询过滤条件
  • 基类：BaseEntity.java 统一注入工厂代号、逻辑删除、创建/更新信息

图表来源

章节来源

核心组件 ​

  • 表结构与注释：part_main 定义了物料主数据的全部字段，并在 DDL 中提供了字段级注释，明确各字段的业务含义与取值范围
  • Java 实体映射：PartMainDo.java 将数据库字段映射为 Java 属性，便于 MyBatis-Plus 持久化操作
  • 接口与 VO：PartMainApi.java 提供查询接口；PartMainVo.java 定义对外返回模型并包含字段校验规则；PartMainQueryVo.java 定义查询参数
  • 基类 BaseEntity：统一注入工厂代号、逻辑删除、创建/更新信息，确保跨模块一致性

章节来源

架构概览 ​

物料主数据在系统中的位置与交互如下：

图表来源

详细组件分析 ​

数据库表结构（part_main） ​

  • 表名与序列：表名为 part_main，使用序列 part_main_id_seq 作为自增主键
  • 唯一性约束：(factory_no, part_no) 唯一，用于保证同一工厂下物料代号唯一
  • 关键字段与注释要点：
    • 工厂代号：用于多工厂隔离
    • 物料代号：业务主键之一，配合工厂代号唯一
    • 物料编码：业务主键之二，通常用于外部系统识别
    • 分类字段：big_category、small_category、son_category
    • 名称与规格：part_name、spec
    • 计量单位：uom
    • 控制类型：control_type
    • 价格信息：currency、price
    • 供应商：preferred_supplier
    • 有效期管理：is_period
    • 寿命件管理：is_life、max_life、max_life_uom、use_model
    • ABC分类：precious_type
    • 有效标志：valid_flag
    • 备注：description
    • 包装数量：package_number
    • 序列号生成规则：serial_rule，默认 1（自动生成）
    • 逻辑删除：is_delete，默认 0（未删除）

章节来源

Java 实体映射（PartMainDo） ​

  • 字段映射：将数据库列映射为 Java 属性，如 partNo、partCode、partName、spec、uom、controlType、price、isPeriod、isLife、maxLife、maxLifeUom、useModel、preciousType、validFlag、description、packageNumber、serialRule
  • 继承 BaseEntity：自动获得 id、createTime、createUser、updateTime、updateUser、factoryNo、isDelete 等字段

章节来源

对外接口与 VO（PartMainApi、PartMainVo） ​

  • 接口能力：
    • 列表查询（不分页）
    • 根据物料代号查询
    • 根据物料编码查询
  • 返回模型 PartMainVo：
    • 字段校验：部分字段标注非空与长度限制
    • 序列号生成规则：serialRule 必填
  • 查询参数 PartMainQueryVo：
    • 支持按分类、编码、名称、规格、控制类型、使用机型、备注、ABC分类、有效期件、寿命件等条件过滤

章节来源

类图（实体与接口关系） ​

图表来源

查询流程（接口到数据库） ​

图表来源

业务规则与数据校验 ​

  • 唯一性约束：(factory_no, part_no) 唯一，防止同工厂重复
  • 有效性标志：valid_flag 默认 1（可用），可用于禁用物料
  • 逻辑删除：is_delete 默认 0（未删除），删除时置 1
  • 序列号生成规则：serial_rule 默认 1（自动生成），支持 2（手动输入）
  • 字段校验：PartMainVo 对部分字段进行非空与长度限制；PartMainQueryVo 对查询参数进行长度限制
  • 工厂隔离：通过 BaseEntity 注入 factoryNo，实现跨模块工厂维度隔离

章节来源

关联关系与扩展点 ​

  • 与库存台账（stock_main）：库存模块通过 partNo 关联物料主数据，实现库存与物料的绑定
  • 与序列号（serial_rule）：序列号生成策略影响出入库与报废单据的序列号维护
  • 与有效期/寿命件：is_period、is_life、max_life、max_life_uom、use_model 等字段为后续作业（如寿命监控、过期预警）提供数据基础

章节来源

依赖分析 ​

  • 表结构依赖：part_main 依赖序列 part_main_id_seq
  • 实体依赖：PartMainDo 依赖 BaseEntity
  • 接口依赖：PartMainApi 依赖 PartMainQueryVo 与 PartMainVo
  • 查询依赖：查询参数与返回模型分别来自不同模块，但统一通过接口暴露

图表来源

章节来源

性能考虑 ​

  • 唯一性索引：(factory_no, part_no) 唯一约束可作为高效查询与去重的基础
  • 逻辑删除：is_delete 默认 0，查询时应默认过滤删除标记，避免全表扫描
  • 字段长度与精度：价格采用 numeric(10,3)，寿命值采用 numeric(10,1)，需结合业务合理设置
  • 查询参数：优先使用 PartMainQueryVo 中的精确字段过滤，减少模糊匹配
  • 分页与分批：列表查询建议分页或分批处理，避免一次性加载过多数据

故障排查指南 ​

  • 插入失败（唯一约束冲突）：检查 (factory_no, part_no) 是否重复
  • 查询不到数据：确认 is_delete 是否被过滤、valid_flag 是否为 1
  • 字段校验错误：核对 PartMainVo 的必填与长度限制
  • 工厂隔离问题：确认 BaseEntity 注入的 factoryNo 是否正确

章节来源

结论 ​

物料主数据表（part_main）以清晰的字段设计支撑多工厂、多分类、有效期与寿命件管理等复杂业务场景。通过 BaseEntity 的统一注入与接口层的严格校验，系统实现了良好的工厂隔离、数据一致性与可维护性。建议在实际使用中遵循唯一性约束、逻辑删除与有效性标志的约定，并结合查询参数进行精准过滤，以提升性能与稳定性。

附录 ​

字段对照与业务含义 ​

  • 工厂代号：用于多工厂隔离
  • 物料代号：业务主键之一，配合工厂代号唯一
  • 物料编码：业务主键之二，通常用于外部系统识别
  • 分类字段：big_category、small_category、son_category
  • 名称与规格：part_name、spec
  • 计量单位：uom
  • 控制类型：control_type
  • 价格信息：currency、price
  • 供应商：preferred_supplier
  • 有效期管理：is_period
  • 寿命件管理：is_life、max_life、max_life_uom、use_model
  • ABC分类：precious_type
  • 有效标志：valid_flag
  • 备注：description
  • 包装数量：package_number
  • 序列号生成规则：serial_rule，默认 1（自动生成）

章节来源

实际插入示例（步骤说明） ​

  • 步骤 1：准备工厂代号（factory_no）、物料代号（part_no）、物料编码（part_code）、物料名称（part_name）、规格（spec）、计量单位（uom）、控制类型（control_type）、价格（price）、序列号生成规则（serial_rule，默认 1）
  • 步骤 2：可选填写分类字段（big_category、small_category、son_category）、有效期件（is_period）、寿命件（is_life、max_life、max_life_uom、use_model）、ABC分类（precious_type）、备注（description）、包装数量（package_number）
  • 步骤 3：执行插入，系统会自动填充 id、create_time、create_user、update_time、update_user、factory_no、is_delete（默认 0）
  • 步骤 4：若需禁用该物料，更新 valid_flag 为 0；若需删除，更新 is_delete 为 1（逻辑删除）

章节来源

查询优化建议 ​

  • 建议在 (factory_no, part_no) 上建立唯一索引（DDL 已提供唯一约束）
  • 查询时默认过滤 is_delete=0，必要时再显式传参
  • 使用 PartMainQueryVo 进行精确过滤，减少模糊匹配
  • 对高频查询字段（如 part_code、part_name、control_type、use_model）考虑建立合适索引

章节来源