water/server/docs/WATER_DISPATCH.md

配送调度中心

数据与业务

• 页面 /water-dispatch 使用企业供水配送表，按所选日期显示当天任务及此前未完成任务。企业/配送员/路线关键词和片区筛选影响任务池、任务表和合单候选；任务表再按状态分页。
• GET /core/water/dispatch/board 返回全范围汇总、片区、任务和配送员排班状态；超过 5000 条要求缩小范围，避免悄悄遗漏任务。页面每页 10/20/50/100 条。
• GET /core/water/dispatch/route?id=... 返回完整路线，包含搜索未命中或其他日期已完成的站点，站序不会因当前搜索变化。
• 配送员状态按未完成任务和选定日期排班计算，不代表设备心跳在线。已有任务的姓名/电话迁移到配送员档案，未推断排班。新档案默认容量 100 桶，可按实际车辆修改；有未完成任务时禁止改容量、服务片区或停用。
• GET /core/water/dispatch/plan 按当前筛选待派单任务，以送达时限（无时限按配送日期当天结束）和任务编号排序；同片区合单，每个已排班且无未完成任务的配送员最多一个新批次，按容量容纳整单。未纳入的任务逐条返回原因。此算法不计算道路最短路或预计到达时间。
• POST /core/water/dispatch：driver 维护档案；shift 按日期上班/休息；schedule 调整待派单任务日期、送达时限和坐标；plan_commit 原子确认一个或多个路线并派单。普通派单也通过同一校验创建单站路线。
• 合单确认重新核对任务状态、排班、服务片区、容量和日期；按商品、配送员、任务的顺序加锁，任一失败整批回滚。请求标识及方案哈希防止重复派单或将同一标识用于不同方案。
• 出库、签收、取消复用 WaterBusiness：出库锁定转在途；签收扣权益、解冻结、增加现场满桶并回收空桶；未出库取消释放库存和权益。路线进度与司机负载由任务实时推导，没有第二套状态。未来日期路线禁止提前出库。
• 补货预警单笔跳转带入企业和商品，批量建单仍走原批量冻结流程。任务详情可跳转企业权益/现场库存、补货预警及仓库库存，带入搜索关键词。总览直接查询同一库存、配送、权益表。
• 读取看板及路线要求 water:dispatch:read；预览合单及所有写入要求 water:dispatch:write。新配送配置操作记录 dispatch_config 审计流水，实物流转继续使用原库存流水类型。

地图

• 企业可选登记高德坐标，经纬度需成对填写。新任务保存地址、片区和坐标快照；待派单任务可在配送计划中修正坐标。
• 高德底图始终加载，无坐标时默认全国视野；有坐标时绘制编号站点及橙色出发点，支持缩放、比例尺、查看全部站点及点击站点查看任务。单任务或同一真实路线具有唯一出发点且所有送达点坐标完整时，调用 AMap.Driving，按既有站序绘制服务返回的实际道路，显示公里数及预计驾车分钟数（不含配送停留）。
• 驾车插件独立加载，失败不影响底图；提供加载、失败原因及重新规划入口，不回退为虚构的直线道路。每次至多16个途经点，长路线分段规划并汇总，任一段失败不展示不完整路线；切换任务或离开页面后丢弃旧请求结果。连续重复位置只规划一次，站点任务仍保留。多起点、缺坐标或未生成真实路线的多任务组明确提示，不擅自拼接。
• 真实路线必须加载完整站点后才规划，关键词筛选不会截断道路线路。此功能不改变派单站序，也不计算各站承诺到达时间。
• 配送计划新增“高德地图选点 / 搜索地址”：使用 Geocoder 搜索完整地址，或点击地图指定位置，确认后回填经纬度，保存配送计划才持久化。保存后看板切换到该任务组并刷新位置。只更新配送坐标，不自动改写企业名称、文字地址、库存或权益。
• 地图和选点弹窗复用 src/utils/waterAmap.ts 的脚本/插件加载，与旧商户页面共享脚本标识，显式补载缩放、比例尺、Geocoder 插件；不用反复插入高德脚本。
• 不生成虚构设备位置、在线人数或行驶轨迹。深圳三条测试任务已有高德查询得到的起止坐标，目的地暂按南山海德一道中洲控股中心；通过 seed_water_shenzhen_coordinates.php 固定批次写入。

迁移与回退

• php scripts/migrate_water_dispatch.php 只输出计划；--apply 执行可重入增量迁移。
• 新增 sa_water_driver、sa_water_driver_shift、sa_water_route，企业新增可空经纬度，配送新增可空日期、时限、坐标、配送员及路线关联，站序默认 0，相关检索列增加索引。
• 迁移只关联旧任务已有配送员，不改变配送状态、库存、权益、金额或历史时间。当前业务表很小；生产大表执行 ALTER 前应评估元数据锁及索引建立时间，低峰执行。
• 应用回退时保留新增表/列及路线记录，用旧任务操作继续完成已有派单。不要删除已有路线数据或重置任务、库存；结构回退仅在确认无新业务写入、完成备份并另行授权后进行。

验证

• php tests/water_dispatch_test.php 验证区域/关键词汇总、容量和时限排序、休息限制、幂等和过期方案、库存不重复冻结、出库、签收扣权益及预警消除、取消释放、未来日期限制、权限和事务回滚。
• 同时回归 water_business_test.php、water_ledger_test.php、water_device_ingress_test.php；没有保留回归测试产生的业务记录。
• 2026-09-10 驾车规划：前端 ESLint、vue-tsc、Vite build 通过；node scripts/test-water-driving.mjs 验证分段不漏站、累计距离/时间、重复位置、过期请求、部分失败及空路径。真实浏览器显示深圳测试线路沿道路行驶约2.0公里，初次预计11分钟，重新规划10分钟（估计随路况变化）。本次未修改业务数据。

当前模型与策略实现

2026-09-10已增加三种道路站序优化策略，供水业务切换Eloquent模型，新增起点设置与优化预览/应用。上文旧的仅站序展示说明由此更新；接口、事务、算法范围和验证详见 WATER_ROUTING_STRATEGIES.md。