# 后台与小程序修复记录（2026-10-08）

## 已完成

1. **交易一致性**：CheckoutService 从已保存的订单明细发放权益，不再读取最新套餐。余额扣款、余额流水、供水收款、企业权益、支付状态同事务提交；任何一步失败全部回滚。付款前检查明细金额之和及桶数整除关系。
2. **套餐生命周期**：修改、停用、删除影响新购；已创建且未过期的待支付订单保留原价格、名称、SKU 和桶数。原 SKU 或企业停用/不存在仍拒绝支付；有效期仍为 30 分钟。后台删除确认框说明这条规则。
3. **报价确认**：创建订单时按 ID 排序锁全部套餐和 SKU，生成一致快照。报价新增 quote_revision，小程序下单原样提交；价格未变但名称、规格或桶数变化也返回 40904。兼容旧客户端允许省略此字段，旧客户端仅校验金额。
4. **收款复用与来源**：WaterPurchaseReceipt 集中处理收款、权益和审计。余额支付供水记录的 created_by=0，小程序用户通过 MiniAudit、MiniBalanceLedger 和订单凭据追踪，避免当作后台人员 ID。付款锁顺序统一为全部 SKU → 企业 → 余额/权益。
5. **财务来源**：列表和导出通过已支付余额订单、实际扣款流水和对应凭据识别“企业余额购水”，兼容历史余额订单；不只按 MP 前缀判断，也不再写成已核实线下到账。未新增数据库字段或迁移。
6. **小程序准确展示**：套餐金额显示到分；去除首项即热门、名称猜分类、固定两张水卡、到期优先扣减、自动开票等无依据承诺。分类使用接口公布的列表；未配置设备服务显示未知。实际权益按企业和 SKU 合并，可分次预约配送。
7. **刷新与提交**：套餐页每次显示重新加载；购物车更新为服务端报价中的名称、规格 ID、价格和桶数。重新报价立即清空旧报价，失败可重试且禁止下单；旧响应、身份切换及清空选择不能恢复可提交状态。
8. **高德可靠性**：同一页面规划共享队列，请求至少相隔 1100ms；CUQPS 错误最多尝试 3 次并退避；定向道路矩阵按策略缓存 60 秒、最多 256 条。取消任务不继续发送请求，仍仅接受真实道路结果。
9. **配送任务关联**：预警列表、权益列表、企业统计复用 WaterAccount::withActiveDelivery，按企业、SKU、active_key 非空关联；兼容旧任务标识和包含地址的新标识，防止已有任务仍显示可补货。
10. **契约与发布**：补齐现有多地址接口、地址 Schema 和支付成功文档断言；从 OpenAPI 重新生成类型。H5 发布先复制资源再原子替换入口 HTML，保留旧哈希资源供已打开页面使用。

## 验证

- 后端 1653 项检查通过：订单快照 89、小程序业务 167、供水业务 64、套餐删除 28、财务 87、预警 97、企业 64、调度 42、履约 59、API 契约 844、架构 112。业务夹具均回滚。套餐删除另含实际 HTTP 校验的 29 项版本已通过。
- 快照回归覆盖套餐改价/改桶数/换 SKU、下架、删除、规格停用、过期、取消、损坏总额、余额不足、幂等、新请求再次支付，以及已生成收款后凭据冲突时整笔回滚。
- 小程序 21 项测试通过，新增实际购物车组件回归覆盖报价更新、精确金额、失败禁止提交、过期响应、身份切换与清空选择。
- 后台删除确认与道路规划脚本通过，覆盖定向矩阵、缓存到期、QPS 退避、并发请求间隔与取消。
- PHP 语法、PHP CS Fixer、后台修改文件 ESLint/Prettier、两端类型检查通过。后台 Vite、H5、微信小程序生产构建完成。
- 本地后台 http://127.0.0.1:4173/ 和 H5 http://127.0.0.1:8787/water-mini/index.html 的 HTML、入口 JS/CSS 哈希与最新构建一致；公开套餐接口返回 3 条。
- 未调用真实微信支付、真实高德道路接口或上传微信版本；未完成浏览器点击、真机交互验收。

## 剩余事项

- **企业余额充值、退款**：供水企业余额与旧租赁个人钱包是两个账本。入账来源、到账凭据、审核和退款时已用/冻结权益的处理仍需确定，没有模拟充值代替正式闭环。
- **真实微信支付、开票、独立水卡有效期、套餐分类和设备服务配置**：尚无完整业务实现；本次展示当前能力。
- **权限细分**：编辑和删除仍使用 packages:write，小程序绑定仍受现有管理员规则限制。独立删除权限和身份管理范围需结合岗位定义调整，未扩大权限。
- **历史数据与会计口径**：此前已支付的金额/权益差异没有自动改账；充值与权益消费如何确认收入仍需财务定义。测试数据识别仍使用名称/凭据约定，需逐步替换为明确标记。
- **规模限制**：高德节流仅覆盖当前浏览器页面，不能控制其他浏览器或服务共用 Key 的总请求量；多用户需服务端统一限流。道路缓存是短时估计，不预测未来交通。旧 H5 资源仍需运维按发布版本清理。

## 2026-10-09 接续验收

- 复跑后端10组共1589项：订单快照89、套餐删除28、小程序业务167、财务87、预警97、企业64、调度42、履约59、API契约844、架构112；全部通过，业务夹具回滚。
- 小程序21项测试、`npm run type-check`、后台 `vue-tsc --noEmit`、`test-water-driving.mjs` 和 `test-water-package-delete.mjs` 通过。一次从工作区根目录直接调用小程序测试因相对导入失败，改为从 `water-mini` 目录执行后全部通过，未改动测试代码。
- 后台4173入口HTML及2个入口资源、8787 H5入口HTML及3个入口资源的SHA256与现有构建一致；本轮未重复构建或发布。
- 实际配置接口报告企业余额支付与本机测试手机号登录开启，微信登录和真实微信支付关闭。修正小程序README/上下文中旧的余额能力、开票、分类猜测和Schema数量说明；当前OpenAPI为64个Schema。
- 浏览器工具未能启动：`node_repl kernel exited unexpectedly`，诊断为 `windows sandbox failed: orchestrator_helper_exit_nonzero: setup helper exited with status Some(1)`。点击、截图和真机验收仍为未执行，不能由回归测试或HTTP资源核对替代。
- 本轮仅更新交接文档，无业务代码、API、数据库结构、Redis或服务配置变更；没有充值、退款、迁移、重启或微信平台上传。上述剩余业务事项仍需明确规则后实现。