water/server/docs/WATER_MINI_REVIEW_FIXES.md

小程序规则整改与前端接口交接

日期：2026-09-18。用户明确授权修改代码并输出接口文档。按根目录 AI_RULES.md 执行 IMPLEMENT，MODE-3 + MODE-4，L3；架构约束依据根 AGENTS.md。AI_RULES.md 当前只有93–118节，引用的 PROJECT_RULES.md 在项目内未找到，不推断未提供的规则。

变更计划与风险

入口为 /api/mini/v1，沿用 Controller → Service → Eloquent Model → Database；复用公共校验、权限、事务/幂等与审计。调整范围是上轮检查确认的地址并发、电话校验/脱敏和代理客户查询问题，并新增前端文档。不涉及前端页面、数据库结构、Redis、支付通道或身份授权规则变更。

风险在于地址与配送并发、历史联系电话隐私、列表统计兼容性。处理方式：保留企业公共锁并改为当前读；电话格式集中校验，异常历史值不输出明文；关联聚合保留查询时点、权限与返回字段。每阶段以业务测试验证，最终补两连接交错回归、查询数回归、契约与本地HTTP检查。

已修改

文件	修改目的
app/miniapi/service/EnterpriseCommands.php	企业锁后用 WaterDelivery 模型 lockForUpdate 当前读检查有效配送；阻止旧快照下误改地址；电话使用公共校验
app/miniapi/support/PhoneNumber.php	统一规范化与脱敏；接受完整7–15位国内/国际格式；拒绝纯符号、掩码及非法号码格式
app/miniapi/http/Fields.php	phone 校验适配，统一42201和字段错误
app/miniapi/service/WaterPresenter.php	复用电话脱敏，不对异常历史格式回退明文
app/miniapi/service/AgentQuery.php	orders/devices 模型关联聚合替代每个客户的4次查询；保留空值与未来收款排除口径
tests/water_mini_api_test.php	电话、规范化落库、聚合值/空值/未来订单、固定查询次数及真实响应Schema回归
tests/mini_api_address_concurrency_test.php	两条独立连接交错执行真实预约/地址修改，验证旧快照与新当前读行为
tests/mini_api_contract_test.php、tests/support/MiniApiContract.php	实际路由覆盖、鉴权、引用、路径参数、请求示例与项目Schema子集验证
.php-cs-fixer.mini.php	纳入新增测试文件
docs/WATER_MINI_FRONTEND.md、docs/openapi/water-mini-v1.json	前端交接、45个操作、请求/响应字段与错误处理

继续沿用有实际用途的模式：外部身份适配器、司机命令接口与简单工厂、配送中动作模板方法；未增加空转的Repository或无业务用途的模式层。控制器保持薄层，业务读写经Eloquent模型。

API路径和返回字段不变。电话输入更严格，规范化后保存，历史号码脱敏范围扩大；前端编辑应使用管理员地址详情，不能提交脱敏列表号码。代理客户统计改为一条列表查询中的关联聚合，不随返回客户数增加往返查询。

本次实际验证

检查	结果
小程序业务回归	161项通过；包含32组实际返回数据Schema检查，夹具事务回滚
双连接地址并发回归	12项通过；独立夹具提交后按ID清理
架构约束	97项通过
接口契约	45个操作与实际路由、鉴权一致；引用与示例通过
框架含HTTP	64项通过
小程序真实HTTP	112项通过；临时用户及会话清理
原业务/调度/履约/代理/企业	分别64/42/59/59/64项通过，夹具回滚
PHP语法	小程序及本次测试共57个文件通过
PHP CS Fixer	范围内64个文件 dry-run，0个待修改

本地接口服务可访问，未执行生产部署、数据库迁移或服务重启。无新增持久业务数据；并发测试独立夹具短暂提交后清理，自增序列可能前移。OpenAPI由本地契约测试验证，未在Apifox客户端实际点击导入；校验器不是完整OpenAPI标准验证器。真实微信登录（当前缺凭据）、支付/提现等外部联调未执行。

回退与交接

工作区原有大量未提交修改。需要回退时，只逐项撤销本表列出的本次变更并重新验证；不要对整个工作区执行 reset/覆盖，也不要删除此前小程序基础接口。无结构迁移，无数据库结构回退步骤。回退电话/并发修复会重新暴露对应缺陷，应先评估原因。

交给前端的入口是 接入文档 与 OpenAPI文件。真实登录联调还需后端微信凭据、可访问域名与管理员绑定测试业务身份。支付、余额、佣金/提现、推广奖励、多站点、独立水卡和设备绑定等能力继续按实际开关关闭。