feat: refresh material names in background every two days

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

@@ -16,7 +16,7 @@ AR51 于 2026-10-09 在本地 Codex 请求将金蝶 ERP 全量物料编码和名
 
 1. 仍由 AR836 接口提供缺料记录，不根据名称缓存判断缺料。
 2. 优先使用缺料记录里的名称；名称缺失时，根据该条记录的 `缺料物料` 编码查本地缓存。
-3. 首次需要时加载并校验文件，后续在内存中查询。回复过程不访问金蝶、不刷新缓存。
+3. 首次需要时加载并校验文件，后续在内存中查询；检测到本地文件变化时重新加载。回复过程不访问金蝶、不刷新缓存，后台新增名称在下一次查询时生效。
 4. 回复只列缺料物料名称并去重，原有减速器展开规则继续有效。
 5. 编码未命中，或文件缺失、损坏时，仍返回可用的其他名称，并提示未找到名称的记录数及维护原因，不编造名称。
 
@@ -46,4 +46,46 @@ python3 capabilities/am516-delivery-prediction/scripts/refresh_material_names.py
 
 维护电脑提交代码、规则和 `data/material_names.json`，推送到 AM516 Git 仓库。另一台电脑在该项目拉取对应提交后，重启原有飞书机器人进程，使新代码和缓存生效。
 
-运行机器人只需项目内的缓存文件，不需要维护电脑上的 TH51 仓库或金蝶 ERP 凭证。新增物料或改名后，由 AR51 在维护电脑再次刷新、提交、推送，运行电脑拉取并重启。
+仅使用名称缓存回复时不需要 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 提交、推送和其他电脑的拉取由既有同步流程执行，不在定时脚本内处理。