dtm_java/docs/supply-monitoring-module-design.md

供应监测模块设计文档

1. 文档范围

本文档说明当前系统中供应监测模块的功能设计、实现逻辑、数据来源、接口进度以及与其他模块的关联关系。

文档内容基于当前 Java 后端、MySQL 数据库和本地 QA 质检数据的实现状态整理，覆盖供应商综合评分、成本分析、交付分析、质量合格率、供应商查询对比、付款计划和入库对账等功能。

2. 模块定位

供应监测模块用于分析供应商在成本、交付、账期和质量四个维度上的表现，帮助业务人员选择更合适的供应商，并对供应过程中的延期、成本差异、质量异常和付款安排进行监控。

当前模块的核心目标包括：

• 查看供应商总体数量、平均得分、预警供应商和优秀供应商数量。
• 针对单个产品查询可选供应商的综合评分和排名。
• 对比多个供应商的采购、入库、交付、账期和质量表现。
• 根据入库日期和账期生成付款计划。
• 按月份汇总采购入库金额、数量和付款计划。
• 引入 QA 抽检数据，按供应商计算合格率并纳入最新评分卡。

3. 当前项目进度

当前供应监测主链路已经接入 Java 后端和 MySQL 数据库，后端优先读取数据库数据；当数据库没有供应监测基础数据时，服务层保留从本地 Excel 加载的兜底能力。

已完成或已接入的能力包括：

• 供应商列表查询：按供应商名称、开始日期、结束日期筛选。
• 多供应商对比：最多支持 5 个供应商横向对比。
• 付款计划：按实际验收日期和账期生成预计付款日。
• 付款月度汇总：基于付款计划按月份汇总金额、数量和状态。
• 入库对账：按月份、供应商汇总采购入库数量、金额、单据行数和均价。
• 单个产品供应商评估：返回 Top 供应商、参考价、成本排名、成本分、交付分、账期分和综合得分。
• 产品评分明细：拆分返回成本详情、交付详情和账期详情。
• 供应商总览：返回供应商总数、平均得分、预警供应商数和优秀供应商数。
• QA 质量数据接入：读取 2026年每日QA登记表.xlsx，汇总供应商抽检数量、不合格数量和合格率。

当前后端接口包括：

接口	方法	说明
/api/supply/monitor/suppliers	GET	供应商列表与评分卡数据
/api/supply/monitor/compare	GET	多供应商对比
/api/supply/monitor/payment-plan	GET	付款计划
/api/supply/monitor/payment-summary	GET	付款月度汇总
/api/supply/monitor/receipt-reconciliation	GET	入库对账
/api/supply/monitor/evaluate	POST	按产品编码评估供应商
/api/supplier/evaluate	POST	兼容旧前端的产品评估接口
/api/supplier/overview	GET	供应商总览统计
/api/supplier/product/{productCode}/details	GET	产品评分明细

4. 功能设计

4.1 最新供应商评分卡

最新评分卡用于供应商列表和多供应商对比，已经加入质量合格率维度。综合得分由四个维度构成：

维度	权重	分数来源
成本维度	30%	同 SKU 下按参考价从低到高排名后换算成本分
交付维度	30%	准时率 70 分 + 订单完成率 30 分
账期维度	15%	按供应商账期天数换算账期分
质量维度	25%	QA 抽检合格率换算质量分

综合得分计算公式：

综合得分 = 成本分 * 30% + 交付分 * 30% + 账期分 * 15% + 质量分 * 25%

评分等级：

• A：综合得分大于等于 85 分。
• B：综合得分大于等于 70 分且小于 85 分。
• C：综合得分大于等于 60 分且小于 70 分。
• 预警：综合得分小于 60 分。

预警标签规则：

• 综合得分小于 60 分：综合分预警。
• 有 QA 抽检数据且合格率低于 95%：质量预警。
• 准时交付率低于 60%：交付预警。
• 订单完成率低于 80%：完成率预警。
• 以上条件均未命中：正常。

4.2 成本维度分析

成本分析用于比较供应商针对同一产品的实际采购成本。

系统以产品编码或 SKU 为查询条件，从采购入库数据中按供应商汇总入库数量和入库金额，计算参考价：

参考价 = 入库金额合计 / 入库数量合计

系统按参考价从低到高排名，并换算为成本分数：

• 第 1 名：100 分。
• 第 2 名：90 分。
• 第 3 名：80 分。
• 第 4 名：60 分。
• 其余：0 分。

在供应商总列表中，成本分会按供应商参与的多个 SKU 成本排名取平均值。

4.3 交付维度分析

交付分析用于评价供应商是否按计划交货，以及采购订单是否完成。

供应商列表中的交付分数由两部分组成：

• 准时率：占 70 分。按订单入库匹配表中实际验收日期是否小于等于计划交货日期计算。
• 订单完成率：占 30 分。按采购订单完成数量与订单数量的比例计算，最高按 100% 计。

计算公式：

交付分 = 准时率 * 70 + 订单完成率 * 30

产品维度交付详情使用订单入库匹配数据，展示匹配行数、准时行数、延迟行数、准时率、数量满足率、平均偏差天数、最大延迟天数、交付状态和风险等级。

4.4 账期维度分析

账期分析用于评价供应商给出的付款周期。

系统从供应商账期表读取账期天数，并按以下规则换算为账期分数：

• 大于等于 90 天：100 分。
• 大于等于 60 天：90 分。
• 大于等于 45 天：80 分。
• 大于等于 30 天：60 分。
• 小于 30 天或缺少账期：40 分。

账期详情会展示供应商代码、供应商名称、结算期限、账期天数、账期分数、账期等级和维护状态。

4.5 质量维度和合格率

质量维度来自 QA 抽检数据，当前后端读取 2026年每日QA登记表.xlsx。文件路径优先级如下：

1. 环境变量 SUPPLY_QA_DATA_PATH。
2. 环境变量 DTM_SUPPLY_QA_DATA_PATH。
3. Spring 配置项 supply.qa.path。
4. supply.data.path 指向目录下的 2026年每日QA登记表.xlsx。
5. 项目运行目录下的 data/supply/2026年每日QA登记表.xlsx。

系统读取 QA 文件中的验货日期、供应商、来货数量、抽检数量、不合格数量和大批次品数量，并按供应商汇总。

合格率和质量分计算规则：

不合格数量 = 不合格数量 + 大批次品数量
合格率 = (抽检数量 - 不合格数量) / 抽检数量
质量分 = 合格率 * 100

当供应商没有 QA 抽检数据时，供应商列表评分卡暂按质量分 80 分处理；同时 qaPassRate 返回为空，便于前端区分“无数据”和“合格率为 0”。

供应商列表返回的质量字段包括：

• qualityScore：质量分。
• qaPassRate：QA 合格率，保留 4 位小数。
• qaSampleQty：抽检数量。
• qaDefectQty：不合格数量。
• qaIncomingQty：来货数量。
• qaLines：QA 记录行数。

4.6 供应商查询对比

供应商查询对比用于查看供应商在采购、入库、交付、账期和质量方面的明细表现。

当前支持：

• 供应商列表查询。
• 按供应商名称筛选。
• 按日期范围筛选。
• 多供应商对比。
• 查看采购数量、完成数量、未完成数量、入库数量、入库金额、准时交付率、订单完成率、账期天数、质量分和 QA 合格率。

4.7 付款计划

付款计划根据采购入库记录和供应商账期生成。

当前逻辑为：

预计付款日 = 实际验收日期 + 供应商账期天数

系统按供应商和预计付款日汇总入库金额、入库数量和入库单据行数，并根据预计付款日判断付款状态：

• 已到期：预计付款日早于当前日期。
• 7 天内到期：预计付款日在当前日期到未来 7 天内。
• 未到期：预计付款日晚于未来 7 天。

4.8 入库对账

入库对账按采购入库业务日期统计，当前返回月度维度数据：

• 月份。
• 供应商代码。
• 供应商名称。
• 入库数量。
• 入库金额。
• 入库单据行数。
• 入库单据数。
• 平均入库单价。

该功能用于辅助采购侧和财务侧核对供应商入库规模、金额变化和付款基础数据。

5. 数据与业务逻辑

5.1 数据来源

当前供应监测使用以下数据源：

• dtm_supply_purchase_order：采购订单表，保存业务日期、计划交货日期、供应商、订单数量、完成数量、未完成数量和金额。
• dtm_supply_purchase_receipt：采购入库表，保存业务日期、实际验收日期、供应商、产品编码、实际入库数量和金额。
• dtm_supply_supplier_term：供应商账期表，保存供应商名称、供应商代码、结算期限和账期天数。
• dtm_supply_order_receipt_match：订单入库匹配表，保存产品、供应商、计划交货日期、实际验收日期、计划数量和实际入库数量。
• 2026年每日QA登记表.xlsx：QA 质量数据，保存验货日期、供应商、来货数量、抽检数量、不合格数量和大批次品数量。

5.2 产品维度评分流程

单个产品评分的核心流程如下：

1. 根据产品编码查询采购入库数据，计算不同供应商的参考价和成本排名。
2. 根据产品编码查询订单入库匹配数据，计算准时率、数量满足率和交付分数。
3. 根据供应商名称读取账期天数，计算账期分数。
4. 按成本 40%、交付 40%、账期 20% 计算产品维度综合得分。
5. 按综合得分降序输出 Top 5 供应商排名。

说明：产品维度 Top 供应商接口当前仍使用成本、交付、账期三维评分，尚未把 QA 合格率纳入单个产品评分。最新四维评分卡已用于供应商列表和多供应商对比。

5.3 供应商总览统计流程

供应商总览会汇总采购入库、订单入库匹配和供应商账期中的供应商，形成供应商基础集合。

系统分别计算各供应商的成本分、交付分和账期分，再计算综合得分，并输出：

• 供应商总数。
• 平均综合得分。
• 综合得分低于 60 分的预警供应商数量。
• 综合得分大于等于 85 分的优秀供应商数量。

说明：/api/supplier/overview 当前 SQL 仍按成本 40%、交付 40%、账期 20% 计算总览统计；如需总览卡片与最新四维评分卡完全一致，需要后续把 QA 合格率也纳入总览 SQL 或改由服务层统一聚合。

5.4 日期筛选

供应商列表、供应商对比、付款计划、付款汇总和入库对账支持日期范围筛选。

不同数据侧使用的日期口径如下：

• 采购订单统计：主要使用采购订单业务日期。
• 采购入库统计：主要使用采购入库业务日期或实际验收日期。
• 交付统计：主要使用订单入库匹配中的实际验收日期。
• 付款计划：使用采购入库实际验收日期计算预计付款日。
• QA 质量统计：使用 QA 文件中的验货日期。

5.5 数据兜底逻辑

后端服务优先读取 MySQL 数据库。当采购订单、采购入库、供应商账期和订单入库匹配表均无数据时，服务层会尝试从本地供应监测 Excel 数据中加载，以兼容早期开发和演示阶段的数据来源。

6. 与其他模块的关联关系

6.1 数据上传模块

供应监测依赖采购订单、采购入库、供应商账期、订单入库匹配和 QA 质检数据。当前核心采购侧数据已写入数据库，后端接口直接从数据库读取；QA 质量数据仍从本地 Excel 文件读取。

后续可将 QA 文件导入流程纳入统一数据上传模块，落库后再由供应监测统一从数据库聚合，减少本地文件路径依赖。

6.2 产品基础数据

供应监测以产品编码作为成本和交付分析的核心查询条件。产品编码可与订单监测、生命周期模块中的商品编码进行关联，用于分析同一商品的销售表现和供应能力。

6.3 订单监测模块

订单监测反映销售端表现，供应监测反映采购和供应端表现。两者通过产品编码关联后，可以判断高销售商品是否存在供应成本过高、交付延迟、质量合格率偏低或账期不足的问题。

6.4 库存管理模块

供应监测中的采购入库数量、交付完成情况和质量合格率可为库存管理提供补充信息。库存模块关注库存现状，供应监测关注供应商履约、质量表现和后续付款安排。

6.5 财务付款模块

供应监测中的付款计划按入库验收日期和账期生成，可作为后续应付计划、资金安排和供应商对账的基础数据。当前模块只生成预计付款计划和状态，不处理实际付款核销。

7. 当前实现边界和后续事项

当前实现边界：

• 最新四维评分卡已用于供应商列表和多供应商对比。
• 单个产品 Top 供应商评分仍使用成本、交付、账期三维评分。
• 供应商总览 SQL 仍使用旧三维权重，暂未纳入 QA 合格率。
• QA 质量数据当前来自本地 Excel 文件，尚未落入 MySQL 表。
• 权重配置页面在前端代码中仍保留原有接口入口，不属于当前 Java 与数据库主链路。

建议后续事项：

• 新增 QA 质检数据表和导入接口，将 2026年每日QA登记表.xlsx 落库。
• 统一供应商列表、供应商总览、产品评估的评分口径，避免页面间得分口径不一致。
• 将评分权重抽成配置项，支持成本、交付、账期、质量权重维护。
• 给 QA 合格率增加产品维度映射后，再纳入单个产品供应商评分。
• 增加评分计算单元测试，覆盖无 QA 数据、低合格率、缺少账期、无交付匹配等边界场景。