92 lines
6.1 KiB
Markdown
92 lines
6.1 KiB
Markdown
# 缺料物料名称本地缓存
|
||
|
||
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 项目根目录运行。刷新脚本只能由本地维护执行，不能由飞书消息触发。
|
||
|
||
使用已配置只读金蝶凭证的现有客户端，全量分页查询两个字段：
|
||
|
||
```bash
|
||
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 仓库。
|
||
|
||
也可以从已经核验的全量物料参考缓存导出，无需联网：
|
||
|
||
```bash
|
||
python3 capabilities/am516-delivery-prediction/scripts/refresh_material_names.py \
|
||
--reference-json /path/to/material_master.json
|
||
```
|
||
|
||
导出会校验来源对象、全量未筛选范围、计数和内容哈希，并保留原快照时间。空结果、异常分页、无效记录或名称冲突不会覆盖旧文件。成功后输出行数、编码数和快照时间，不输出全量物料内容或凭证。
|
||
|
||
## 同步到另一台电脑
|
||
|
||
维护电脑提交代码、规则和 `data/material_names.json`，推送到 AM516 Git 仓库。另一台电脑在该项目拉取对应提交后，重启原有飞书机器人进程，使新代码和缓存生效。
|
||
|
||
仅使用名称缓存回复时不需要 ERP 凭证；运行后台自动刷新时，需要在执行电脑配置自己的只读 ERP 凭证。新增物料或改名后，缓存文件变化会自动生效；修改机器人代码后仍需重启机器人。
|
||
|
||
## 每两天后台自动刷新
|
||
|
||
使用 macOS `launchd` 用户后台服务 `com.am516.material-name-refresh`，安装器根据执行电脑的实际路径生成配置。每小时启动一次轻量检查；距离上次成功查询满 48 小时后，才全量查询 ERP 的 `FNumber,FName`。首次安装立即查询一次；失败时保留缓存和上次成功时间，下次小时检查重试。电脑休眠或关机时不能保证精确到点，恢复运行后补查。
|
||
|
||
自动刷新会加入新增编码、更新已有名称，并保留本轮未返回的旧编码。没有名称变化时不重写 Git 中的缓存，仅更新 Git 忽略的 `logs/material_names_refresh_state.json`；有变化时先完成分页、验证名称无冲突，再原子替换文件。进程锁避免并发刷新，日志只记录状态、数量、时间和安全错误摘要。
|
||
|
||
### 另一台 Mac 的安装步骤
|
||
|
||
1. 拉取包含缓存和脚本的提交，进入 AM516 项目根目录。
|
||
2. 随项目提供的 `shared/runtime/kingdee_materials.py` 只允许查询物料编码和名称，不依赖 TH51 仓库。它读取本机环境变量、钥匙串中的 `TH51_KINGDEE_ACCT_ID` / `TH51_KINGDEE_USERNAME` / `TH51_KINGDEE_PASSWORD`，或本机配置文件 `configs/material_cache_erp.local`。
|
||
3. 如果本机未配置只读凭证，从 `configs/material_cache_erp.local.example` 复制为 `configs/material_cache_erp.local`，在本机编辑账套、用户名和密码，并将权限设为 `600`。该文件匹配 `configs/*.local`，不会进入 Git；不要把实际凭证写入命令、日志或提交。
|
||
4. 运行安装命令：
|
||
|
||
```bash
|
||
python3 shared/runtime/install_material_name_refresh.py install
|
||
```
|
||
|
||
安装后的路径随电脑生成，首次立即检查，以后每小时检查是否已满 48 小时。用户服务在该 macOS 用户登录期间运行；本机需允许该后台 Python 进程访问项目目录和使用已批准的网络。
|
||
|
||
维护电脑也可复用已经配置好的现有只读客户端：
|
||
|
||
```bash
|
||
python3 shared/runtime/install_material_name_refresh.py install \
|
||
--kingdee-client /path/to/TH51_Knowledge_System/91_Scripts/kingdee_openapi/kingdee_query.py
|
||
```
|
||
|
||
查看、预览和卸载：
|
||
|
||
```bash
|
||
python3 shared/runtime/install_material_name_refresh.py status
|
||
python3 shared/runtime/install_material_name_refresh.py preview
|
||
python3 shared/runtime/install_material_name_refresh.py uninstall
|
||
```
|
||
|
||
手动执行一次到期检查（不会重复查询未到期的数据）：
|
||
|
||
```bash
|
||
python3 capabilities/am516-delivery-prediction/scripts/refresh_material_names.py --due
|
||
```
|
||
|
||
日志位于执行用户的 `~/Library/Logs/AM516_Feishu_Bot/material_name_refresh.log` 和 `material_name_refresh.error.log`。后台服务只更新本机缓存和状态；Git 提交、推送和其他电脑的拉取由既有同步流程执行，不在定时脚本内处理。
|