AM516/capabilities/am516-delivery-prediction/docs/material_name_cache.md

缺料物料名称本地缓存

AR51 于 2026-10-09 在本地 Codex 请求将金蝶 ERP 全量物料编码和名称缓存到可同步的 Git 文件，用于在 AR836 交期接口只返回缺料编码时补充名称。本文件记录该实现的范围和维护方式。

文件和数据范围

固定文件：capabilities/am516-delivery-prediction/data/material_names.json。

• 来源为 BD_MATERIAL，不按物料类型、审核状态、禁用状态或组织筛选。
• 仅保存编码 FNumber 和名称 FName，以及快照时间、来源行数、去重后编码数和内容哈希。
• 多组织的相同编码、相同名称合并成一条；同一编码出现不同名称时停止刷新，保留原缓存。
• 文件位于项目内，纳入 Git 同步。凭证、完整物料主数据、规格、BOM、数量和价格不进入这个文件。
• source.snapshot_at 是 ERP 查询或原参考缓存的时点；generated_at 是生成本文件的时间，不能把二者混为最新 ERP 数据时间。

回复逻辑

1. 仍由 AR836 接口提供缺料记录，不根据名称缓存判断缺料。
2. 优先使用缺料记录里的名称；名称缺失时，根据该条记录的 缺料物料 编码查本地缓存。
3. 首次需要时加载并校验文件，后续在内存中查询。回复过程不访问金蝶、不刷新缓存。
4. 回复只列缺料物料名称并去重，原有减速器展开规则继续有效。
5. 编码未命中，或文件缺失、损坏时，仍返回可用的其他名称，并提示未找到名称的记录数及维护原因，不编造名称。

在 AR51 的维护电脑刷新

以下命令均在 AM516 项目根目录运行。刷新脚本只能由本地维护执行，不能由飞书消息触发。

使用已配置只读金蝶凭证的现有客户端，全量分页查询两个字段：

PYTHONDONTWRITEBYTECODE=1 python3 capabilities/am516-delivery-prediction/scripts/refresh_material_names.py \
  --kingdee-client /path/to/TH51_Knowledge_System/91_Scripts/kingdee_openapi/kingdee_query.py

其中路径替换为维护电脑上实际的已批准客户端路径。凭证仍由该客户端通过其已有的环境变量、钥匙串或本地凭证文件读取，不复制到 AM516 仓库。

也可以从已经核验的全量物料参考缓存导出，无需联网：

python3 capabilities/am516-delivery-prediction/scripts/refresh_material_names.py \
  --reference-json /path/to/material_master.json

导出会校验来源对象、全量未筛选范围、计数和内容哈希，并保留原快照时间。空结果、异常分页、无效记录或名称冲突不会覆盖旧文件。成功后输出行数、编码数和快照时间，不输出全量物料内容或凭证。

同步到另一台电脑

维护电脑提交代码、规则和 data/material_names.json，推送到 AM516 Git 仓库。另一台电脑在该项目拉取对应提交后，重启原有飞书机器人进程，使新代码和缓存生效。

运行机器人只需项目内的缓存文件，不需要维护电脑上的 TH51 仓库或金蝶 ERP 凭证。新增物料或改名后，由 AR51 在维护电脑再次刷新、提交、推送，运行电脑拉取并重启。