# 推广赠水执行记录（2026-10-19）

执行模式：IMPLEMENT，MODE-3 + MODE-4 + MODE-5；风险等级L3。已先分析购水、权限、权益及数据流，再分阶段实现和验证。业务规则与使用说明见 [WATER_PROMOTION.md](WATER_PROMOTION.md)。

## 修改与数据

- 新增3个推广Eloquent模型、配置/邀请/查询/审核领域服务、独立小程序控制器及权限/幂等服务。
- 共用购水收款入口追加首购资格；组合余额结算传递checkout关联，按整笔金额判断，只生成一条奖励。保存首购时已有配送ID上界，拒绝旧签收误领奖。
- 修改后台WaterController/路由，新增财务推广审核面板及API客户端；小程序推广页面、个人中心单位和权益流水改接真实水权益。
- 更新OpenAPI维护源及公开副本，重新生成69个Schema类型，更新维护说明及项目上下文。
- 本机新增 `sa_water_promotion_setting/code/referral` 三张InnoDB表。迁移已验证复跑；新活动关闭、桶数0，不覆盖历史配置，不发放历史奖励。测试期间规则、关系、订单、库存、权益和账本均在事务内回滚。
- 没有Redis、队列、支付渠道或后台岗位权限变更；沿用财务读写权限和企业管理员授权。保留原有未提交改动。

## PASS

| 后端检查 | 项数 |
| --- | ---: |
| water_promotion_test.php | 56 |
| water_business_test.php | 64 |
| water_fulfillment_test.php | 59 |
| water_checkout_snapshot_test.php | 89 |
| water_commission_test.php | 43 |
| mini_api_framework_test.php | 47 |
| water_finance_dashboard_test.php | 87 |
| mini_api_contract_test.php | 883 |
| mini_api_architecture_test.php | 117 |
| 合计 | 1445 |

- 新增推广覆盖开关、规则版本、自邀、循环及共用管理员、权限撤销及普通成员拒绝、重复绑定、门槛、首购、旧签收拒绝、实际配送完整签收、规则快照、组合结算、审核/驳回重试、财务信息隔离、权益流水、个人中心契约及失败回滚。
- 小程序 `npm run type-check` 和25项测试通过，其中新增4项执行实际推广组件及公共composable的测试，覆盖分享参数跨登录、显式绑定、双击、超时后更换邀请人拒绝、重试和身份切换时清除分享数据。
- 后台 `vue-tsc --noEmit`、修改文件ESLint/Prettier/Stylelint通过；小程序修改文件Prettier通过。
- 新增/修改核心PHP文件按现有PHP CS Fixer配置整理，相关控制器、配置路由和账本文件PHP语法通过；文档同步检查通过。
- 后台 `npm run build`（3351模块）、小程序H5及微信构建通过。后台只保留既有system/menu动静态导入提示。

## FAIL：已有身份测试与实现不一致

- `tests/water_mini_api_test.php:331` 给已有企业身份的账号追加司机身份时失败。
- `tests/mini_identity_management_test.php:133` 同样尝试给一个账号追加业务身份时失败。
- 当前 `app/miniapi/service/IdentityManagement.php:72` 明确拒绝一个账号同时绑定多个业务身份。相关身份管理、Access和这两份旧测试本轮未修改；未通过放宽权限或跳过断言掩盖失败。这两项不计入上述通过数。

## 本机发布与运行验证

- 后台dist构建已更新；执行现有preview:publish脚本更新本机H5，先复制资源再切换HTML，保留旧哈希资源。
- 实际后台4173、H5 8787/water-mini/index.html返回200；HTML及2/3个入口JS/CSS资源SHA256与构建一致。
- 新邀请码接口未登录返回401；本机测试账号登录读取真实rewards接口，返回reward_type=water、initialized=true、enabled=false、demo=false、total_buckets=0；随后正常退出测试会话。没有启用活动、真实发奖或保留购水/赠水夹具。
- 未手工重启既有服务，实际请求已确认加载新增代码。未上传微信平台或部署生产环境。

## NOT RUN 与边界

浏览器人工点击、截图、微信真机分享及外部微信端到端未执行。正式退款与已用奖励扣回仍未实现；第一版只能在人工核实后发奖。赠水奖励不表示可提现现金或新增实物库存。

## 回退

先关闭新邀请，保留三张新增表、已发放权益和审计记录，再回退对应代码及前端构建。已有绑定仍按规则快照审核；关闭开关不撤销已发放权益，不通过删除账本或修改余额回退业务。