JY1.0/docs/物料编码搜索功能/核心物料搜索栏添加物料编码查询设计方案.md

核心物料搜索栏添加物料编码查询设计方案

1. 需求背景

本需求由罗伟提出，主要服务于现场库存盘点业务。

当前现场正在进行库存盘点。盘点过程中发现，系统内部分物料在新建物料信息时，由于历史录入习惯、命名规则不统一、同类物料复用名称、图号或型号描述不完整等原因，存在物料名称重复、图号或型号重复、名称与图号组合仍无法准确区分物料的情况。

在盘点现场，仓库人员需要快速确认实物标签对应的系统物料。如果仅依赖物料名称、规格型号、图号等字段进行搜索，当多个物料名称或图号相近甚至重复时，页面会返回多条近似记录，盘点人员需要逐条比对，容易出现以下问题：

1. 盘点确认速度慢，影响现场盘点效率。
2. 同名或同图号物料难以区分，增加误选风险。
3. 实物标签与系统数据匹配不稳定，后续盘点差异复核成本高。
4. 现场人员对物料主数据命名差异不熟悉时，更难快速定位唯一物料。

为解决上述问题，现场计划后续物料标签统一使用唯一的物料编码作为识别依据。同时，系统内最核心的物料搜索栏页面需要增加“物料编码”查询筛选能力，使盘点人员可以直接根据标签上的唯一物料编码定位系统物料，避免因物料名称、图号或型号重复导致的识别困难。

2. 建设目标

本次设计目标是在项目中最核心、最常用于物料查询和盘点确认的页面搜索栏中增加“物料编码”查询功能。

具体目标如下：

1. 在核心物料搜索栏页面增加独立的“物料编码”输入条件。
2. 支持用户输入物料编码后直接查询并筛选唯一或近似匹配物料。
3. 保留原有物料名称、图号或型号、物料类型、库位、仓库等查询条件，保证历史操作习惯不受影响。
4. 支持物料编码与原有查询条件组合筛选。
5. 后端查询过程增加物料编码可选参数，未输入物料编码时保持原查询结果不变。
6. 涉及导出、分页、排序等功能的页面，应保持查询结果与导出结果一致。
7. 为后续物料标签使用唯一物料编码提供系统查询支撑。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

3. 设计范围

本次范围以“页面搜索栏”为主，不包含新增物料、选择物料、查看库存等弹窗中的临时查询入口。

优先改造以下最核心页面：

模块	页面名称	文件路径	当前查询特点	本次调整
技术中心	物料查询	src/views/TechnologyCenter/MaterialQuery/index.vue	物料主数据查询，已有物料编码、物料名称、图号/型号等条件	统一确认物料编码条件传参和后端过滤能力
技术中心	物料维护	src/views/TechnologyCenter/MaterialMaintain/index.vue	物料主数据维护，已有物料编码、物料名称、图号/型号等条件	统一确认物料编码条件传参和后端过滤能力
仓储管理	库存查询	src/views/WarehouseManagement/InventoryQuery/index.vue	库存主查询，包含物料编号、物料名称、图号型号、类型、库位等条件	增强物料编码精确定位能力
仓储管理	物料库位	src/views/WarehouseManagement/MaterialLocation/index.vue	按物料、图号、库位查询物料所在库位	增强按物料编码定位库位能力
仓储管理	库存盘点	src/views/WarehouseManagement/InventoryCheck/index.vue	盘点现场高频页面，涉及物料、图号、编码等查询条件	重点支持标签物料编码查询
仓储管理	入库记录	src/views/WarehouseManagement/WarehousingRecord/WarehousingRecord.vue	入库记录中可按物料名称、物料编码等条件筛选	确认搜索栏编码条件与导出条件一致
仓储管理	退货记录	src/views/WarehouseManagement/ReturnRecord/index.vue	当前输入框偏综合条件，按物料名称/编号/规格/型号查询	明确拆分或补充物料编码查询能力
仓储管理	物料记录	src/views/WarehouseManagement/MaterialRecord/index.vue	物料出入库记录查询，当前主要按物料名称筛选	增加物料编码条件
仓储管理	库存记录	src/views/WarehouseManagement/InventoryRecord/index.vue	库存历史记录查询，当前主要按物料名称筛选	增加物料编码条件
仓储管理	采购件入库	src/views/WarehouseManagement/PurchasePartsStorage/index.vue	入库相关查询涉及物料名称、图号或型号	增加或统一物料编码条件

后续可根据现场使用频率扩展至采购、精工车间、销售、装配等更多页面，但第一阶段应优先保证仓储盘点和物料主数据查询链路完整。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

4. 现状问题分析

4.1 物料名称不是唯一识别字段

物料名称用于业务人员理解物料含义，但并不适合作为唯一识别依据。现场存在同类物料使用相同或近似名称的情况，例如名称相同但规格、批次、厂家、图号或内部编码不同。

仅按物料名称查询时，系统可能返回多条记录，盘点人员需要再人工判断，效率低且容易误选。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

4.2 图号或型号也可能重复或不完整

图号或型号通常来源于技术资料、采购资料或历史录入。由于历史数据存在命名不统一、字段填写不完整、图号简称和完整图号混用等情况，图号或型号同样无法稳定保证唯一。

盘点人员如果只扫描或输入图号，仍可能出现多条记录，无法快速确认实物对应的系统物料。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

4.3 现场标签需要与系统查询方式统一

现场后续计划使用唯一物料编码作为标签识别字段。如果系统页面没有物料编码搜索能力，即使实物标签已经规范，人员仍需要通过名称或图号间接查找，标签规范化的价值无法充分发挥。

因此，系统查询方式必须与标签识别方式保持一致。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

5. 总体方案

本次方案采用“前端增加独立查询条件、后端存储过程增加可选参数、查询和导出同步支持”的方式实施。

5.1 前端搜索栏调整

在核心页面搜索栏中增加或确认“物料编码”输入框。

推荐展示方式：

<el-input
  v-model="materialCodeValue"
  style="width: 160px"
  placeholder="物料编码"
  size="small"
  clearable
  @keyup.enter.native="pageCurrent=1;searchTable()"/>

如果页面已有“物料编号”输入框，应统一确认其实际传参字段是否对应数据库中的 物料编码。如果只是综合搜索字段，应调整为独立字段，避免和物料名称、规格型号混在同一个条件中。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

5.2 前端参数拼接规则

在 searchTable() 或对应主查询方法中增加物料编码条件。

推荐参数格式：

this.materialCodeValue ? materialCodeValue_check = 1 : materialCodeValue_check = 0
param[n] = ['物料编码_check', materialCodeValue_check]
param[n + 1] = ['物料编码', this.materialCodeValue]

如果后端存储过程使用字段名 物料编码，前端统一传 物料编码_check 和 物料编码。如果历史过程使用 物料码、物料编号、物料流水号 等字段，需要在后端过程内做兼容或在本页面保持原过程约定，但文档和页面显示统一为“物料编码”。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

5.3 后端查询过程调整

涉及页面对应的存储过程需要增加物料编码可选参数。

推荐参数：

@物料编码_check int = 0,
@物料编码 nvarchar(100) = null

推荐过滤逻辑：

if @物料编码_check = 1
begin
    set @sql = @sql + ' and 物料编码 like ''%'' + @物料编码 + ''%'' '
end

如果业务上要求扫码后精确定位，可在库存盘点页面优先使用精确匹配：

and 物料编码 = @物料编码

考虑到目前系统搜索习惯多为模糊查询，第一阶段建议使用模糊查询；后续如果标签扫码稳定，可在盘点页面增加“精确匹配”策略或自动识别完整编码时使用精确匹配。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

5.4 查询与导出一致

凡是页面支持 Excel 导出的，导出参数必须同步增加物料编码条件。

要求：

1. 页面查询传入 物料编码_check 和 物料编码。
2. 导出方法传入同样的 物料编码_check 和 物料编码。
3. 同一组搜索条件下，页面列表与导出文件数据范围一致。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

6. 页面设计细节

6.1 物料查询页面

文件：src/views/TechnologyCenter/MaterialQuery/index.vue

设计要求：

1. 搜索栏保留物料编码、物料名称、图号/型号、物料类型、修改时间。
2. 查询方法 searchTable() 中确认 物料编码_check、物料编码 参数可传入后端。
3. 表格中建议保留或增加物料编码列，便于和搜索条件互相验证。
4. 物料编码为空时，查询结果与原逻辑一致。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

6.2 物料维护页面

文件：src/views/TechnologyCenter/MaterialMaintain/index.vue

设计要求：

1. 与物料查询页面保持搜索条件一致。
2. 维护人员可通过物料编码快速定位需要修改的物料。
3. 如果物料名称或图号重复，编码搜索结果应能明确定位到具体记录。
4. 修改物料基础信息时，不允许随意修改唯一物料编码；如确需修改，应由权限或后端规则控制。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

6.3 库存查询页面

文件：src/views/WarehouseManagement/InventoryQuery/index.vue

设计要求：

1. 搜索栏保留物料编号、物料名称、图号型号、类型、库位或仓库等条件。
2. 页面显示文案建议统一为“物料编码”，避免“物料编号”和“物料编码”混用造成理解偏差。
3. 查询时支持按物料编码过滤当前库存。
4. 如果用户同时输入物料编码和库位，应返回该编码在指定库位下的库存记录。
5. 导出库存数据时同步带入物料编码条件。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

6.4 物料库位页面

文件：src/views/WarehouseManagement/MaterialLocation/index.vue

设计要求：

1. 搜索栏保留物料编码、物料名称/规格、图号/型号、库位。
2. 现场可输入标签物料编码，快速确认该物料当前绑定或存放库位。
3. 物料编码与库位组合查询时，应可用于检查实物库位与系统库位是否一致。
4. 若未查到数据，应提示用户确认物料编码是否存在或是否已维护库位。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

6.5 库存盘点页面

文件：src/views/WarehouseManagement/InventoryCheck/index.vue

设计要求：

1. 作为本次需求的重点页面，搜索栏必须支持物料编码。
2. 现场盘点时，人员可根据物料标签输入或扫码物料编码，快速筛选盘点记录。
3. 如果物料编码唯一匹配一条库存记录，应减少人工在多条同名物料中判断的成本。
4. 如果同一物料编码在多个库位有库存，应按库位分行展示，便于盘点人员逐库位确认。
5. 盘点导入、盘点导出、盘点明细查询如使用同一查询条件，应同步支持物料编码。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

6.6 入库记录和退货记录页面

涉及文件：

• src/views/WarehouseManagement/WarehousingRecord/WarehousingRecord.vue
• src/views/WarehouseManagement/ReturnRecord/index.vue

设计要求：

1. 入库记录应可按物料编码追溯某一物料的入库历史。
2. 退货记录应可按物料编码追溯某一物料的退货历史。
3. 如果当前页面只有“物料名称/编号/规格/型号”综合输入框，建议拆分出独立“物料编码”输入框。
4. 页面查询与导出保持一致。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

7. 接口和存储过程影响

本项目业务请求统一通过 MESCommonBase.ashx，前端通过 CreateData(type, name, data, pageSize, pageList) 构建请求。新增物料编码查询不改变请求端点，不新增前端请求封装方式。

可能涉及的后端过程包括但不限于：

页面	可能涉及接口或过程	调整内容
物料查询	物料管理_查询数据_分页	增加物料编码过滤
物料维护	物料管理_查询数据_分页 或对应维护查询过程	增加物料编码过滤
库存查询	仓储库存查询相关过程	增加物料编码过滤
物料库位	仓储管理物料库位查询相关过程	增加物料编码过滤
库存盘点	仓储管理库存盘点查询相关过程	增加物料编码过滤
入库记录	仓储管理入库记录查询和导出过程	增加物料编码过滤
退货记录	仓储管理退货记录查询过程	增加物料编码过滤

后端调整原则：

1. 新增参数必须为可选参数，避免影响未改造页面。
2. 原有查询条件保持不变，物料编码作为新增条件叠加。
3. SQL 字段命名优先使用数据库现有字段，常见字段为 物料编码。
4. 如果查询主表没有物料编码字段，应通过物料流水号关联物料主文件取得编码后过滤。
5. 对大数据页面应确认物料编码字段有索引或可使用已有索引，避免新增条件后查询变慢。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

8. 数据规则

8.1 物料编码唯一性

物料编码应作为系统内识别物料的唯一业务编码。后续标签打印、库存盘点、入库、出库、库位维护等环节，应优先使用物料编码进行识别和核对。

如果历史数据中存在物料编码为空或重复，应先由主数据维护人员进行清理，并形成异常清单。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

8.2 物料名称和图号保留辅助识别

新增物料编码搜索后，物料名称、图号或型号仍然保留，用于人工理解和辅助筛选。系统不应因为新增物料编码而删除或弱化原有查询字段。

推荐使用方式：

1. 盘点现场优先输入或扫码物料编码。
2. 不清楚编码时，可使用物料名称或图号模糊查询。
3. 编码、名称、图号可组合使用，进一步缩小范围。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

9. 前端开发步骤

1. 梳理核心页面现有搜索栏，确认是否已有物料编码输入框。
2. 对没有独立物料编码输入框的页面，新增 el-input。
3. 在 data() 中新增或确认变量，例如 materialCodeValue、MaterialCode。
4. 在 searchTable() 中增加编码输入值判断，生成 物料编码_check。
5. 在 param 数组中追加 物料编码_check 和 物料编码。
6. 同步调整导出方法中的查询参数。
7. 确认分页重置逻辑：点击查询或回车查询时，pageCurrent 应重置为 1。
8. 检查表格是否显示物料编码列；若不显示，应评估是否需要补充。
9. 按项目要求在变更代码处追加备注：修改人:Ld 修改时间:当时的时间。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

10. 后端开发步骤

1. 确认各页面 CreateData 中的 name 对应后端存储过程。
2. 在存储过程参数中增加 物料编码_check 和 物料编码。
3. 在查询条件中增加物料编码过滤逻辑。
4. 如果过程使用动态 SQL，同步补充 sp_executesql 参数定义和参数传值。
5. 如果导出使用独立过程，导出过程同步增加物料编码过滤。
6. 对库存盘点、库存查询等大数据过程执行查询计划检查。
7. 使用实际物料编码测试单条件查询、组合条件查询、空条件查询。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

11. 验收标准

11.1 功能验收

1. 在核心物料搜索栏页面可以看到“物料编码”查询条件。
2. 输入完整物料编码后，可以查询到对应物料或库存记录。
3. 输入不存在的物料编码时，页面返回空结果，不报错。
4. 物料编码与物料名称组合查询时，结果同时满足两个条件。
5. 物料编码与图号或型号组合查询时，结果同时满足两个条件。
6. 清空物料编码后，查询结果恢复为原有条件下的结果。
7. 页面分页、排序、刷新后查询逻辑正常。
8. 导出文件与页面查询结果范围一致。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

11.2 现场验收

1. 使用现场物料标签上的唯一物料编码进行查询。
2. 同名物料、同图号物料场景下，能通过物料编码准确区分。
3. 盘点人员可以根据物料编码快速定位物料及库位。
4. 现场不再需要仅依赖物料名称或图号人工判断同名物料。
5. 盘点差异复核时，可以通过物料编码追溯库存记录、入库记录或退货记录。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

12. 测试用例

用例编号	测试场景	操作步骤	预期结果
TC-001	按完整物料编码查询	输入完整物料编码，点击查询	返回对应物料记录
TC-002	按部分物料编码查询	输入物料编码前几位，点击查询	返回编码包含输入内容的记录
TC-003	编码不存在	输入不存在的编码，点击查询	返回空列表，页面不报错
TC-004	编码加名称组合查询	输入物料编码和物料名称，点击查询	结果同时满足编码和名称条件
TC-005	编码加图号组合查询	输入物料编码和图号，点击查询	结果同时满足编码和图号条件
TC-006	清空编码查询	清空物料编码，仅保留原条件查询	结果与原逻辑一致
TC-007	盘点页面标签验证	使用现场标签编码查询库存盘点页面	能快速定位对应物料或对应库位库存
TC-008	导出一致性	输入物料编码查询后导出	导出数据与页面筛选范围一致

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

13. 风险与控制

风险	影响	控制措施
历史物料编码为空	无法通过编码定位部分旧物料	输出异常清单，先补齐主数据
历史物料编码重复	查询结果仍可能多条	主数据维护阶段校验唯一性
前端显示“物料编号”、后端字段为“物料编码”	用户理解和开发传参不一致	页面文案统一为“物料编码”，后端字段按实际字段兼容
大表增加模糊查询后变慢	查询性能下降	对物料编码字段建立索引，必要时完整编码使用精确匹配
查询和导出条件不一致	用户导出数据与页面不一致	导出方法同步加入物料编码参数
弹窗查询未同步改造	部分业务入口仍无法按编码查	第一阶段聚焦页面搜索栏，第二阶段再扩展弹窗

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

14. 推进计划

阶段	工作内容	产出
第一阶段	确认核心页面和对应存储过程	页面与接口清单
第二阶段	改造库存盘点、库存查询、物料库位、物料查询、物料维护	核心页面支持物料编码查询
第三阶段	改造入库记录、退货记录、物料记录、库存记录、采购件入库	相关追溯页面支持物料编码查询
第四阶段	调整导出、分页、排序、后端过程性能	查询与导出一致
第五阶段	使用现场标签数据验收	验收记录和问题清单

备注：修改人:Ld 修改时间:2026-06-29 13:26:44

15. 结论

本次“核心物料搜索栏添加物料编码查询功能”是库存盘点现场提出的实际业务需求。需求核心不是简单增加一个输入框，而是将现场实物标签识别方式与系统查询方式统一起来。

通过在核心物料搜索栏页面增加物料编码查询能力，系统可以减少因物料名称、图号或型号重复导致的盘点确认困难，帮助现场人员以唯一物料编码快速定位物料、库存和库位记录，提高盘点效率和数据准确性。

第一阶段建议优先完成仓储盘点和物料主数据相关页面，确保现场库存盘点可用；第二阶段再逐步扩展到采购、生产、装配、销售等模块中更多物料相关查询入口。

备注：修改人:Ld 修改时间:2026-06-29 13:26:44