# 云泉智配业务合并（2026-09-09）

> 2026-09-11 更新：下文为基础合并时的历史范围。地图及路线策略已由 WATER_DISPATCH.md / WATER_ROUTING_STRATEGIES.md 接续；部分签收、拒收、退回、重送和返仓结算现已实现，当前状态及限制以 [WATER_FULFILLMENT.md](WATER_FULFILLMENT.md) 为准。

本轮将 P01–P09 的菜单与基础供水流程合并进现有 SaiAdmin。新业务使用 `sa_water_*` 表，不将旧租赁订单、充值余额或押金自动转换为购水权益。

## 已实现

- 12 个后端动态菜单：运营总览、补货预警、配送调度、库存管理、设备管理、企业客户、套餐商品、代理商管理、财务结算、内容配置、角色与权限、操作审计。
- 旧页面仍注册路由并保留数据；新菜单存在时，旧一级菜单在前端导航隐藏。代理商、角色和审计页面复用已有实现与其原有接口权限。
- 企业档案（当前一企业一个供水地址）、水商品规格、套餐、饮水设备档案、轮播配置的新增与编辑。
- 登记已核实线下套餐收款，按套餐快照发放权益。收款凭据唯一，重试不重复发放。该功能不执行外部扣款。
- 仓库满桶入库、可用满桶盘点、企业满桶盘点、人工换桶登记、库存流水。
- 配送建单、人工派单、出库、签收、取消，操作使用数据库事务、行锁和有效任务唯一键。
- 真实数据统计、分页搜索、当前页 Excel 导出、错误重试、设备无上报状态、移动端内容预览。

## 基础业务口径

- 套餐权益与实物库存独立。建单冻结权益和仓库库存；签收时扣减权益，增加企业现场满桶；取消释放冻结。
- 仓库“可用”不包含“锁定”和“在途”，满桶总数为三者之和。企业满桶、空桶与仓库空桶另记。
- 人工换桶登记表示现场满桶转为空桶；不重复扣除套餐权益。签收回收空桶时，从企业空桶转入仓库空桶。
- 已出库任务不能直接取消；基础版需先完成异常核对，后续实现退回/拒收流程。
- 同企业及规格同时只有一个有效配送任务，保存供水地址快照。存在有效任务时不能更改企业地址。
- 库存不高于账户 `threshold_qty`（默认 2）或依据已有 `daily_liters` 计算的剩余天数不超过 5 天时提醒；3 天内或库存不高于 2 桶为紧急。日均数据未知则返回 `days_left=null`，不虚构预测。
- 设备 `last_seen` 最近 15 分钟内算在线；没有遥测记录显示“尚无上报”，不把设备录入当作在线。
- 今日履约分母仅统计今日新建且未取消任务，分子为该集合中的已签收任务。

## 权限

新接口 `/core/water/*` 使用现有登录中间件，并在 WaterController 内逐次检查用户状态、角色状态及 `water:<module>:read|write` 权限。新业务为平台运营权限，不自动授权给旧代理角色。代理端数据辖区尚未迁入新供水业务，不应将平台运营权限直接授予代理。

当前新代理菜单复用旧代理功能，佣金与辖区规则尚未重构。角色、操作审计菜单亦需对应的既有接口权限；菜单可见性不代替接口授权。

## 运行与验证

```text
php scripts/migrate_water_business.php          # 查看计划
php scripts/migrate_water_business.php --apply  # 新增表及菜单，可重复运行
php tests/water_business_test.php              # 数据库事务回滚测试
```

前端位于 `../saiadmin-artd/src/views/water`，API 位于 `../saiadmin-artd/src/api/water`。迁移后重新构建前端并刷新，入口 `/#/water-overview`。Windows 如关闭文件监控，需重启该项目 Webman HTTP 进程加载新代码。

2026-09-09 验证结果：36 项真实数据库检查通过且数据已回滚；PHP 语法、前端 TypeScript、相关 ESLint 与生产构建通过（3245 modules）。浏览器 `http://localhost:4173/#/water-overview` 正常加载 12 个新菜单及真实零数据；企业新增表单的必填校验、库存页面、内容配置手机预览与旧操作审计页面已确认可用。

## 后续未实现

### 2026-09-10 已接续完成

- 补货账户数量阈值可编辑（包含未触发预警的启用账户），按 `water:alerts:write` 授权；审计流水 `alert_policy` 记录前后值，不开放手填遥测。
- 预警列表勾选当前页记录，逐条确认配送桶数、企业规格与地址后批量建单；接口 `POST /core/water/dispatch`，`action=batch_create`、`items:[{account_id,quantity}]`，单批 1–50 条。权限为 `water:dispatch:write`。
- 按现有账户解析配送对象，统一事务冻结，合计库存/权益不足、企业规格停用或已有有效任务时整批回滚。重复提交不会重复创建有效任务；所有任务继续使用既有派单、出库、签收和取消流程。
- 69 项数据库检查通过且全部回滚；PHP lint、vue-tsc、相关 ESLint 和 Vite 构建（3247 modules）通过。浏览器验证新入口和零数据页面，本地 HTTP 子进程已重启。当前没有真实账户，批量弹窗实际数据交互仍待录入业务数据后验收。

### 剩余工作

- 2026-09-10 已预留设备 HTTP `/iot/water/report` 和 MQTT 事件适配入口，默认关闭且未配置厂商适配器；已有内部心跳/累计用量更新逻辑，30项回滚检查通过。具体协议待用户取得设备后提供，详见 `WATER_DEVICE_INTEGRATION.md`。

- 配送地图、车辆容量、配送员排班、批次合单、路线优化、移动端签收与异常/部分签收。
- 一企业多个供水地址、企业代理归属迁移与辖区数据范围。
- 设备 MQTT 饮水遥测/换桶协议、去重上报、可靠日均统计与趋势预测；现有 MQTT 服务保持原业务。
- 套餐线上支付、退款及权益冲回、有效期、折扣赠送规则。
- 代理佣金计算、推广奖励、提现审核及外部打款。
- 轮播按登录用户身份与企业区域动态投放到真实小程序/App（本轮仅配置和预览）。
- 预警天数策略配置、自动预测准确率统计（数量阈值编辑及补货批量建单已完成）。

这些功能不能仅根据静态设计图推定完成。菜单和基础页面已合并，智能功能仍需对应业务规则和外部协议。