water/server/docs/WATER_ENTERPRISES.md

企业客户管理

页面与接口

saiadmin-artd/src/views/water/enterprises/index.vue 为独立企业客户页，替代通用 WaterWorkspace。布局包含四张经营统计卡、条件筛选、六行分页表格、客户增长及转化漏斗；详情提供档案、分规格权益/库存、公司人数和最近十笔购水订单。编辑继续复用高德地图选点。

• GET /core/water/enterprises/dashboard：统计、图表、代理选项及分页列表。
• GET /core/water/enterprises/detail?id=...：企业详情。
• POST /core/water/enterprises/export：全部匹配客户的 XLSX，最多 50000 条，防公式注入。
• POST /core/water/enterprises/batch-status：ids（1–100 个）、status（1 启用、2 停用），事务全成功或全回滚；重复提交不重复记审计。
• 企业新增/编辑沿用 POST /core/water/enterprises；支持已有 agent_id 字段，0 表示直营。停用代理不可新分配，原关联允许保留；省略字段不清空原关联。
• 公司人数employee_count由企业编辑维护（1至10000000整数，可留空），省略保留原值。09-17增量迁移已添加字段；预警改为平台统一算法，预警页“阈值策略”配置全平台参数（POST alerts policy），详情不提供企业单独阈值。

查询和导出要求 water:enterprises:read，档案与批量操作要求 water:enterprises:write；控制器每次重新校验账号及角色权限。

业务口径

• 企业总数包含停用客户；本月新增按企业建档时间计算。
• 活跃企业：近 30 个自然日有正值设备用水记录或实际换桶出库记录的启用企业，企业去重。无遥测时不会伪造用水量。
• 套餐权益为账户剩余待履约总量，含已冻结部分；可用权益 = 剩余权益 − 冻结权益。筛选分为 0、1–10、超过 10 桶。现场满桶/空桶分别汇总，不与套餐权益混用。
• 设备沿用 DeviceStatusPolicy，15 分钟内上报且无故障计在线；没有上报计未接入。
• 最近订单按 created_at DESC, id DESC 取最新已登记线下收款，不依据前端样例数字。
• 本月复购率：本月有购水的企业中，截至当前累计至少两次购水的企业占比。上月按完整上月统计，差异以百分点显示；分母为零显示“—”。
• 客户增长：近 30 天每日累计建档数（包含停用），悬停显示当日新增。
• 转化漏斗：同一批本月新增企业，依次统计建档、至少一次购水、至少两次购水；不把不同批次混成漏斗。当前没有线索表，展示三个有数据来源的阶段并注明。
• 顶部统计和图表始终是全量；列表分页及导出共用关键词、状态、代理、可用权益筛选。关键词匹配企业名称、联系人、电话。
• 补货风险按启用规格逐账户计算：按平台保存的alert_qty、urgent_qty判定预警及严重度（默认少于5桶预警、0–2桶紧急），按days_per_barrel与公司人数估算天数（默认每人3天一桶），天数不触发预警。已有有效任务的规格不重复标待补货；其他规格的未处理紧急风险优先。企业展示顺序：停用 → 未处理紧急 → 未处理待补货 → 已建单 → 正常/未建账户。

实现边界

控制器采用薄控制器/应用服务门面分层，仅负责鉴权、解析请求和返回响应。WaterEnterpriseDashboard 组织查询及批量事务；EnterpriseFilters 是查询值对象；EnterpriseReplenishmentPolicy 是补货状态策略。全部数据通过 Eloquent 业务模型访问，WaterEnterprise 定义代理、账户、订单、设备关系。

账户、设备、有效任务先按企业聚合再关联，避免多个一对多关系导致权益和库存被重复累计。无表结构迁移，查询不改业务记录；批量启停不改变权益、库存或已存在配送任务。

验证

php -d extension=mbstring tests/water_enterprise_dashboard_test.php --http：68 项通过，覆盖多规格汇总、在线边界、补货优先级、筛选分页、统计口径、代理校验、批量事务/审计、导出和权限；测试数据均回滚，HTTP 只读查询及导出。

原 tests/water_business_test.php 69 项通过；前端 vue-tsc、ESLint、Stylelint 和 Vite 生产构建通过，已更新 saiadmin-artd/dist。浏览器工具返回 unsupported Codex auth method: apikey，未完成浏览器交互及截图对照验收。