# 智能补货预警

2026-09-17：用户明确改为平台统一算法。下述规则取代早先的企业自设阈值及日均用量规则。同日用户进一步明确：保留“阈值策略”编辑平台统一参数，默认值不再写死。

## 当前计算口径

- 每个启用企业、启用规格的账户独立计算，现场满桶 full_qty < alert_qty 时预警；等于阈值不预警。预警内 full_qty <= urgent_qty 为紧急，其余普通。默认alert_qty=5、urgent_qty=2。预计天数不再触发或升级预警。
- 日均桶数 = 公司人数 ÷ days_per_barrel；日均升数 = 规格升数 × 公司人数 ÷ days_per_barrel；预计可用天数 = 现场满桶 × days_per_barrel ÷ 公司人数。days_per_barrel默认3天。18.9L、30人时日均10桶/189L。
- 人数读取企业档案 employee_count。新增/编辑支持1至10000000的整数，NULL/空字符串为未登记；省略字段保留原值。旧企业不推断或填充人数。未登记时天数、日均升数及耗尽日期返回null，仍按现场桶数预警。
- 原账户 threshold_qty、daily_liters 保留历史值，但不参与平台预警或预测，不批量改写原数据。POST alerts action=policy保存平台统一配置，拒绝携带id/enterprise_id/account_id/threshold_qty的企业覆盖；预警页恢复平台“阈值策略”入口，企业详情不提供单独阈值。
- 当前算法以登记的现场满桶为基准，预计用水不会随时间自动扣减实物库存；现场数量仍由盘点、换桶、签收等原业务维护。查询时刻加预计天数生成耗尽日期，超过3650天不生成日期；SQL筛选与返回时间同用表达式，天数显示一位小数。
- 一企业多个规格各自估算，不分配人数到设备或不同规格，不汇总多规格的日均值为企业总用水。设备子查询避免放大库存或预警数量。
- 预警不会自动建配送单。可用权益 = entitlement − frozen；建单由工作人员确认数量，原批次事务重新校验企业、规格、权益、仓库库存及有效任务。任何一条失败整批回滚。成功后冻结，签收消耗权益；库存规则不变。
- 全量卡片包括已有有效配送任务的风险；今日及近7日建单趋势按真实未取消任务统计、排除未来数据。暂无历史预警快照或命中评估，准确率为null。

## 页面与接口

- /water-alerts：四卡、企业/地址/规格/设备搜索、严重度/辖区/耗尽日期筛选、仅预警或全部账户、10条分页、详情、当前页Excel导出、单条和批量建单、近7日建单趋势。显示公司人数、算法日均用量与平台规则说明；“阈值策略”编辑平台统一参数，读取失败可重试，失败保留草稿，成功刷新看板。
- 企业新增/编辑和详情增加公司人数，修改即影响预测；权限沿用 enterprises:write。查询/翻页丢弃过期结果、清空勾选，保留总数避免重置分页。导出继续转义公式前缀。
- GET /core/water/alerts/dashboard 要求 alerts:read。返回 summary/list/regions/trend/trend_kind/policy/updated_at；policy包含当前持久值alert_qty、days_per_barrel、urgent_qty、revision、updated_at，以及comparison=lt、accuracy_available=false。
- 行新增 employee_count、estimated_daily_liters、estimated_daily_barrels，days_left/exhausts_at 使用人数公式。历史 daily_liters/threshold_qty 为兼容原字段保留，前端不展示。
- 筛选 keyword最长120字、severity为空或urgent/normal/healthy、region精确匹配、exhaust_date合法日期、scope=alerts/all、page/limit（最大100），支持enterprise_id。旧GET alerts委托同一服务；accounts预测和企业风险共用策略。
- 配送 POST dispatch action=batch_create 保留独立 dispatch:write 权限；GET alerts/policy要求alerts:read；POST alerts action=policy要求alerts:write。alert_qty为1–10000000整数、days_per_barrel为1–365整数、urgent_qty为非负整数且小于alert_qty。提交必须带当前revision，行锁核对版本，冲突要求重新打开，不覆盖其他操作员修改。
- 后端 service/WaterAlertDashboard.php、alerts/AlertFilters.php、alerts/ReplenishmentPolicy.php；前端 api/water/alerts.ts、views/water/alerts/index.vue、AlertPolicyDialog.vue、alerts.scss，复用BatchDeliveryDialog/WaterChart/WaterMetricCards。

## 数据迁移

已执行并复跑 php -d extension=mbstring scripts/migrate_water_enterprise_employee_count.php --apply，仅新增 sa_water_enterprise.employee_count 可空无符号整数列，幂等。不写测试人数、库存、权益或配送单。部署时先迁移再启用新查询。旧演示种子脚本已移除弃用的阈值保存调用，本次未执行演示种子。

已执行并复跑 scripts/migrate_water_alert_setting.php --apply，新增单例配置表sa_water_alert_setting（InnoDB，id=1），默认5桶/3天/紧急2桶，复跑不覆盖已有配置。AlertSettings通过Eloquent读写配置、追加platform:alerts审计，与配置修改同事务；ReplenishmentPolicy读取一次形成查询快照，SQL、分类、日期及返回policy一致，无跨请求缓存。初次本机默认MyISAM导致测试配置未回滚，已转换引擎并恢复初始行，最终事务快照验证全部通过。

## 验证

- 新增平台策略43项、预警118项（含本机HTTP）、原供水业务64项、企业68项，共293项通过。平台策略覆盖全局保存、公式和日期联动、跨页面状态、合法范围、旧账户覆盖拒绝、revision冲突、审计、无业务库存改动、HTTP读取及完整回滚；原回归在事务内固定测试默认值，不依赖用户的实际配置。覆盖4/5桶边界、旧阈值及旧日均忽略、人数为空/非法/更新/清空/省略、18.9L公式、账户与预警一致、过滤排序分页、耗尽日期、HTTP新契约、权限和拒绝覆盖、批次回滚与防重复。
- 全部夹具/审计回滚，原账户、SKU、配送、流水快照一致。检查时29个启用账户，28条预警（紧急24、普通4），17条风险有有效任务；当天0单。
- 修改文件PHP语法、前端Prettier/ESLint/Stylelint/vue-tsc通过。生产构建与预览产物核对见项目记录。
- 浏览器本轮复测仍报 unsupported Codex auth method: apikey，未完成实际点击、截图及窄屏视觉验收。