聚水潭采购交期预警服务

服务器常驻服务：按采购员隔离聚水潭采购数据，直接按交期计算剩余天数。 0–6 天为红色、7–10 天为黄色、11–15 天为绿色，区间外不统计。 采购员和负责人可分别设置每天、工作日或每周定时推送；每次推送完整的 0–15 天未全部入库数据，无数据时也发送确认消息。

每位用户可在通知中心分别保存“手动获取”和“自动推送”两套逾期未完成数据范围： 关闭（0 天）、最近 7/14/30/60 天或 1–180 天自定义，默认均关闭。两套设置按用户 独立持久化、互不影响；负责人手动团队查询和团队定时推送也分别采用自己的两套范围。 完整网页版不再提供二次筛选，只展示对应飞书卡片发送时已经选定的范围。 逾期以采购明细的预计入库时间（delivery_date）早于当天且仍未全部入库为准。

服务启动及每天 02:30 使用 180 天范围完整校准采购缓存；其余时间每 5 分钟读取 最近 7 天变化并合并。飞书手动获取和定时推送直接读取本地缓存，避免每次重复执行 180 天分页查询。180 天完整范围用于防止遗漏长期未修改但仍有效的采购单。 冲突的完整/增量刷新会进入串行队列依次执行，不会跳过完整校准。

飞书卡片按采购单聚合展示，并提供“完整网页版”按钮。网页版使用采购单级完整 总览表格，包含商品名称、供应商、交期、剩余天数、数量和在途占比，不单独 展开 SKU；手机端自动转为紧凑卡片，无需横向拖动表格。

部署

cp .env.example .env
# 编辑 .env
docker compose up -d --build
curl http://127.0.0.1:8000/health

建议用 Nginx/Caddy 为 8000 端口配置 HTTPS 域名，并把 APP_BASE_URL 改为该域名。

管理员手动绑定（可选）

curl -X POST https://你的域名/admin/buyers \
  -H "X-Admin-Token: .env里的APP_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"purchaser":"王采购","feishu_open_id":"ou_xxx"}'

正常情况下直接使用统一飞书登录入口即可。该接口仅用于管理员已知 open_id 时手动补充固定授权名单内的绑定。

每封飞书推送均附带“管理通知”和“完整网页版”链接。采购员可按采购单号手动关闭推送； 关闭后该单不再出现在本人的定时或手动报告中，也可随时恢复。关闭只影响本人，不影响其他采购员。 同一页面还提供“关闭全部通知”；关闭状态会持久保存，在本人再次手动开启前不接收任何提醒。

手动试跑

curl -X POST https://你的域名/admin/run \
  -H "X-Admin-Token: .env里的APP_ADMIN_TOKEN"

本地演示

在 .env 中设置 DEMO_MODE=true 后，服务使用三条内置模拟采购明细，不访问聚水潭。 演示采购员名称为 演示采购员。生产部署必须改回 false。

仍需提供的聚水潭信息

已确认使用采购单查询和采购入库查询两个 v2 接口，并按官方规则实现： app_secret + 字典序(key+value) 经 UTF-8 MD5 生成小写 sign。生产凭据仅写入服务器 .env，不得提交到 Git。

拿到这些信息后，修改 app/jushuitan.py 的签名与字段映射即可接通。

飞书应用要求

使用企业自建应用机器人，并开通发送消息、以应用身份读取通讯录、获取部门基础信息等权限。 需要 APP_ID、APP_SECRET 和 FEISHU_PRODUCTION_DEPARTMENT_ID。采购部用户在 OAuth 登录后按原固定名单绑定；生产部用户通过飞书 open_id 与生产部及其下级部门成员实时匹配。 服务不会把凭据写入代码或日志。

上线后测试飞书

配置飞书应用凭据后，可通过管理员专用接口立即发送一条测试消息：

curl -X POST https://你的域名/admin/test-feishu \
  -H "X-Admin-Token: .env里的APP_ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"feishu_open_id":"ou_xxx","message":"采购预警服务测试成功"}'

该接口不会触发采购预警或写入提醒记录。未携带正确管理员令牌时返回 401。

采购员自助开通

统一入口：https://purchase-alert.kktree.cn/purchase-alert/join

系统包含两个并列访问域。采购域的采购员和负责人名单分别通过 .env 中的 AUTHORIZED_PURCHASERS、PROCUREMENT_MANAGERS 配置，多个值用英文逗号分隔；用户经飞书 OAuth 登录后按姓名或昵称自动绑定。生产域由飞书生产部及其下级部门成员组成，所有生产部 成员都拥有本域团队权限，但聚水潭采购员范围仅匹配 PRODUCTION_PURCHASER_ALIASES 中配置的 别名。网页、导出、手动推送与定时推送统一执行相同过滤。真实名单不得提交到代码仓库， 两个访问域的用户绑定和推送设置独立保存；未属于任一访问域的账号会被拒绝。 首次登录用于取得飞书 open_id，之后登录状态保存一年。

飞书开放平台需要开启网页应用能力，并将以下地址加入安全设置中的重定向 URL：

https://purchase-alert.kktree.cn/purchase-alert/join/callback

采购身份授权接口需要 X-Admin-Token 请求头。