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

日期：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/覆盖，也不要删除此前小程序基础接口。无结构迁移，无数据库结构回退步骤。回退电话/并发修复会重新暴露对应缺陷，应先评估原因。

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