Преглед изворни кода

docs: COUPON-C3-FIX 独立核验报告 (verdict=fail, C 纪律阻断)

E2E Test Bot пре 2 недеља
родитељ
комит
b7f371a6c2
1 измењених фајлова са 92 додато и 0 уклоњено
  1. 92 0
      docs/COUPON-C3-FIX核验报告.md

+ 92 - 0
docs/COUPON-C3-FIX核验报告.md

@@ -0,0 +1,92 @@
+# COUPON-C3-FIX 独立核验报告
+
+> 核验对象:领券中心数据源改为可取券模板(grantType=CLAIM)修复,含 E2E 测试提交合并。
+> 被测提交:`ea0cf6192`(Merge of `484a9677c` (E2E Test Bot) into `feature/coupon-c3-fix`;第一父 `deb3fc3ac` 修复提交)
+> 核验基线:`origin/feature/coupon-c3-fix` = `ea0cf6192`
+> 核验方式:独立 worktree `D:\cfc\.wt-c3fix`,只读纪律下逐项验收;运行态验收仅限测试库 `192.168.16.251:3306/zxyj`(INSERT+SELECT 一次性造数,严禁 DELETE / 严禁执行任何 DDL)
+> 核验日期:2026-10-31
+
+---
+
+## 总体结论:**verdict = fail**(未能出具 pass)
+
+- 静态核对(A)8/8 通过。
+- 三端编译(B)全部 EXIT=0 通过。
+- 合并回归(D)通过。
+- **运行态验收(C)被纪律阻断,无法完成**,按任务纪律「发现需写操作停下回报」,本次核验**不能判定 pass**,按规则标记 `verdict=fail`。
+
+**根因(纪律阻断,非代码缺陷)**:被测提交 `ea0cf6192` 的 `DatabaseInitializer.runMigrations()` 在每次 Spring Boot 启动时**无条件**执行 DDL 迁移,且无任何 skip/只读开关;同时 `seedCfSalesTiers()`(约 14389/14392 行)**每次启动无条件执行 `DELETE`**。在测试库 `192.168.16.251:3306/zxyj` 上启动被测后端实例将违反核验纪律「不执行任何迁移/DDL、严禁 DELETE」。按纪律要求停止执行 C 并回报。
+
+**修复建议(供主理人决策)**:
+1. 首选:在已放行迁移、或已具备合并后版本运行实例的测试环境(如 CI 流水线自建库、已部署 `ea0cf6192` 的实例)执行运行态验收 C,无需本机再启动含迁移的实例。
+2. 或:由主理人书面授权在测试库启动含迁移的 `ea0cf6192` 实例(并接受 `seedCfSalesTiers` 的 DELETE 副作用),再补验 C。
+3. 不建议为核验给 `DatabaseInitializer` 增加 skip 开关——那会引入业务代码改动,超出只读核验范围。
+
+---
+
+## A. 静态核对(8/8 通过)
+
+| 项 | 核对点 | 结论 | 证据位置 |
+|----|--------|:----:|----------|
+| A1 | `CouponService.listClaimable`:`grantType=CLAIM` + `status=ACTIVE` + `le(validFrom)` + `ge(validUntil)` + `notIn(ownedIds 全状态)` + 库存未耗 `COALESCE(used_count,0)<total_count` + `orderByAsc(value)` 再 `orderByAsc(id)` | ✅ | `cfc-backend/.../service/CouponService.java` L171-191 |
+| A2 | `CouponController` POST `/api/coupon/claimable` + `@RequestAttribute("userId")` | ✅ | `cfc-backend/.../controller/CouponController.java` L45-48 |
+| A3 | `claim()` 成功后落 `FamilyCouponGrantLog`(CLAIM / quantity=1 / source=claim-center / period 未 set 即 null) | ✅ | `cfc-backend/.../service/CouponService.java` L222-236 |
+| A4 | `api.js getClaimableCoupons()` | ✅ | `cfc-frontend/utils/api.js` L2623 |
+| A5 | `coupon-center.vue loadCoupons` 用 `getClaimableCoupons`,无 `getCouponList` 残留;`pages.json` 已注册 coupon-center;`dist` 产物 `vendor.js` 含 `coupon/claimable` | ✅ | `cfc-frontend/pages/profile-extra/coupon-center.vue`、`pages.json`、`dist/dev/mp-weixin/vendor.js` |
+| A6 | `CouponManagement.vue`:`CLAIM` 下拉选项存在;`grantQuantity` 对 CLAIM 隐藏/置 null | ✅ | `cfc-web/src/views/admin/CouponManagement.vue` |
+| A7 | `CouponGrantLog.vue`:`grantTypeLabel`/`tagType` 含 CLAIM | ✅ | `cfc-web/src/views/admin/CouponGrantLog.vue` |
+| A8 | `schema.sql` `coupon.grant_type` 注释含 CLAIM(仅注释,无实际列约束变更) | ✅ | `cfc-backend/src/main/resources/schema.sql` L2354/4751 |
+
+## B. 三端编译(全部 EXIT=0 通过)
+
+| 端 | 命令 | EXIT | 备注 |
+|----|------|:----:|------|
+| backend | `mvn -q -f cfc-backend/pom.xml compile`(Maven 3.9.6,Aliyun mirror) | 0 | 无编译错误 |
+| frontend | `npm run build:mp-weixin`(Node 24 polyfill:`$env:NODE_OPTIONS="--require ./patch-node-compat.cjs"`) | 0 | dist 产物含 `coupon/claimable` |
+| cfc-web | `npm run build` | 0 | prebuild 会 bump version/changelog,构建后已 `git checkout --` 还原,工作树干净 |
+
+> 注:cfc-web 构建前 `npm install` 约 7 分钟、前端/后端构建各约 1-2 分钟;cfc-web prebuild 污染的文件已还原,无残留改动。
+
+## C. 运行态验收(阻断,无法在只读纪律内执行)
+
+### 目标
+验证 `POST /api/coupon/claimable`(登录用户)在可取券模板存在时返回可取券列表,且 `claim()` 落 `FamilyCouponGrantLog`(claim-center 来源)。
+
+### 阻断证据
+1. **预修复实例不存在接口**:本机 9082 端口后端(PID 4612)`GET /api/product/list` 返回 200,但 `POST /api/coupon/claimable` 返回 **404**(`/api/coupon/claimable` 不存在)→ 该实例为预修复版本,无法用于验收。
+2. **启动被测版本会触发写库**:`cfc-backend/.../config/DatabaseInitializer.java` 为 `CommandLineRunner`,无 skip 开关(仅 `app.init-test-data` 控制种子数据),每次启动执行 `runMigrations()`(DDL 迁移)**及无条件执行的 `seedCfSalesTiers()` DELETE**(约 14389/14392 行)。在测试库启动 `ea0cf6192` 实例 = 执行 DDL + DELETE → 违反「不执行任何迁移/DDL、严禁 DELETE」。
+3. **测试库最新 schema 已就绪**:`coupon.grant_type` 已含 `CLAIM`,迁移 433/434 已应用(`nutrition` 列 + `sku_combo` 表存在),`claim_coupons` 表 0 行——库本身具备验收条件,**仅启动实例这一动作受纪律约束**。
+
+### 处置
+按任务纪律「发现需写操作停下回报」,停止执行 C。运行态行为(listClaimable 的 SQL 过滤与 claim 落库)依据 A1/A3 静态核对与既有测试用例推定为正确,但**未获运行态实证**,故不能判定 pass。
+
+## D. 合并回归检查(通过)
+
+- `ea0cf6192` 为 `deb3fc3ac`(修复,第一父)与 `484a9677c`(E2E Test Bot)的合并。
+- 6 个冲突文件(`CouponController` / `CouponService` / `coupon-center.vue` / `api.js` / `PROJECT-OVERVIEW.md` / `API_REFERENCE.md`)全部取 `--ours`(`deb3fc3ac`),与第一父零差异。
+- 无重复定义:`listClaimable` ×1、`/claimable` ×1、`getClaimableCoupons` ×1。
+- `diff 484a9677c..ea0cf6192` 仅含第一父系 lineage 的既有内容(sku-combo / bundle-pricing / COUPON-P2 等,非本任务引入,属分支基座差异)。
+
+## E. 合入预检(完成,仅报告未合并)
+
+> 纪律要求:不回写 `cfclub`、不合并其他分支到 `cfclub`。本项仅做只读预检,未执行合并。
+
+- `ea0cf6192` 的祖先 `37bcc3d76` 是 `ea0cf6192` 的祖先(`git merge-base --is-ancestor` exit=0),但**不是** `cfclub` 的祖先(exit=1)——即被测修复已包含分支内后续提交,但尚未进入 `cfclub` 主线。
+- `merge-base(cfclub, ea0cf6192) = 252f32f26`。
+- `git merge-tree --write-tree f1d6f3c49 ea0cf6192`(`f1d6f3c49` = `origin/cfclub` 最新)→ **仅 1 个内容冲突文件:`DatabaseInitializer.java`**。`cfclub` 侧尚无 claimable 相关代码,coupon 相关文件可干净合并。合入冲突点为迁移编号/种子数据区,属正常演进冲突,需合入时人工处理。
+
+## 遗留风险与建议
+
+1. **运行态未实证(verdict=fail 主因)**:`listClaimable` SQL 过滤与 `claim()` 落库行为未在真实数据库上运行验证。建议在已放行迁移的 CI/测试环境补验 C。
+2. **与 `cfclub` 合入冲突**:仅 `DatabaseInitializer.java` 一个文件冲突(迁移编号/种子区)。合入时需合并 `runMigrations()` 迁移列表与 `seedCfSalesTiers()`,避免重复迁移编号或覆盖对方种子逻辑。
+3. **Node 24 构建依赖 polyfill**:`cfc-frontend` 的 mp-weixin 构建需 `--require ./patch-node-compat.cjs`(Node 24 环境)。若 CI 用旧 Node 版本则无需;建议在 `package.json` 或构建脚本固化该环境,避免构建漂移。
+4. **P2 命名债**:`grantType=CLAIM` 语义与历史 `P2`(平台券/自领)存在命名差异,`coupon-center.vue`/`CouponManagement.vue` 的 `CLAIM` 展示文案建议与后端注释、API 文档保持一致,避免后续混淆。
+5. **只读纪律说明**:本报告仅含核验发现,未对任何业务代码、数据库、迁移做写操作;唯一新增文件为本报告,提交至独立分支 `verify/coupon-c3-fix`。
+
+---
+
+## 核验人签名
+
+- 核验分支:`verify/coupon-c3-fix`(基于 `ea0cf6192` checkout -b,仅含本报告文件)
+- 核验范围:A(静态)✅ / B(编译)✅ / C(运行态)⛔ 纪律阻断 / D(合并回归)✅ / E(合入预检)✅ 仅报告
+- 最终 verdict:**fail**(因 C 无法验证;非代码缺陷,纪律阻断)