# 供应监测模块设计文档 ## 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 抽检合格率换算质量分 | 综合得分计算公式： ```text 综合得分 = 成本分 * 30% + 交付分 * 30% + 账期分 * 15% + 质量分 * 25% ``` 评分等级： - A：综合得分大于等于 85 分。 - B：综合得分大于等于 70 分且小于 85 分。 - C：综合得分大于等于 60 分且小于 70 分。 - 预警：综合得分小于 60 分。 预警标签规则： - 综合得分小于 60 分：综合分预警。 - 有 QA 抽检数据且合格率低于 95%：质量预警。 - 准时交付率低于 60%：交付预警。 - 订单完成率低于 80%：完成率预警。 - 以上条件均未命中：正常。 ### 4.2 成本维度分析 成本分析用于比较供应商针对同一产品的实际采购成本。 系统以产品编码或 SKU 为查询条件，从采购入库数据中按供应商汇总入库数量和入库金额，计算参考价： ```text 参考价 = 入库金额合计 / 入库数量合计 ``` 系统按参考价从低到高排名，并换算为成本分数： - 第 1 名：100 分。 - 第 2 名：90 分。 - 第 3 名：80 分。 - 第 4 名：60 分。 - 其余：0 分。 在供应商总列表中，成本分会按供应商参与的多个 SKU 成本排名取平均值。 ### 4.3 交付维度分析 交付分析用于评价供应商是否按计划交货，以及采购订单是否完成。 供应商列表中的交付分数由两部分组成： - 准时率：占 70 分。按订单入库匹配表中实际验收日期是否小于等于计划交货日期计算。 - 订单完成率：占 30 分。按采购订单完成数量与订单数量的比例计算，最高按 100% 计。 计算公式： ```text 交付分 = 准时率 * 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 文件中的验货日期、供应商、来货数量、抽检数量、不合格数量和大批次品数量，并按供应商汇总。 合格率和质量分计算规则： ```text 不合格数量 = 不合格数量 + 大批次品数量 合格率 = (抽检数量 - 不合格数量) / 抽检数量 质量分 = 合格率 * 100 ``` 当供应商没有 QA 抽检数据时，供应商列表评分卡暂按质量分 80 分处理；同时 `qaPassRate` 返回为空，便于前端区分“无数据”和“合格率为 0”。 供应商列表返回的质量字段包括： - `qualityScore`：质量分。 - `qaPassRate`：QA 合格率，保留 4 位小数。 - `qaSampleQty`：抽检数量。 - `qaDefectQty`：不合格数量。 - `qaIncomingQty`：来货数量。 - `qaLines`：QA 记录行数。 ### 4.6 供应商查询对比 供应商查询对比用于查看供应商在采购、入库、交付、账期和质量方面的明细表现。 当前支持： - 供应商列表查询。 - 按供应商名称筛选。 - 按日期范围筛选。 - 多供应商对比。 - 查看采购数量、完成数量、未完成数量、入库数量、入库金额、准时交付率、订单完成率、账期天数、质量分和 QA 合格率。 ### 4.7 付款计划 付款计划根据采购入库记录和供应商账期生成。 当前逻辑为： ```text 预计付款日 = 实际验收日期 + 供应商账期天数 ``` 系统按供应商和预计付款日汇总入库金额、入库数量和入库单据行数，并根据预计付款日判断付款状态： - 已到期：预计付款日早于当前日期。 - 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 数据、低合格率、缺少账期、无交付匹配等边界场景。