补充新增模型打标完整验证设计

docs/superpowers/specs/2026-03-20-bank-tag-new-model-validation-design.md

@@ -0,0 +1,244 @@
+# 新增模型打标完整验证设计
+
+## 背景
+
+2026-03-20 已落地两条与“新增模型打标”直接相关的后端改动：
+
+- `lsfx-mock-server` 新增按 `logId` 稳定随机命中的规则计划，用于为联调链路提供可重复、可命中的 Mock 流水样本。
+- 主工程 `ccdi-project` 已接通第一期真实规则打标链路，覆盖明细型规则、对象型规则、参数映射和真实 SQL 分发。
+
+当前需要做的不是继续扩展规则，而是对这两条改动线做一轮完整验证，确认“新加入的模型”在 Mock 样本层、真实规则层和最终接口链路层都能正确打标。
+
+## 目标
+
+- 同时验证 `lsfx-mock-server` 随机命中规则与主工程第一期真实规则。
+- 验证深度覆盖自动化测试、数据库核验和接口端到端调用。
+- 若发现打标异常，只输出验证结论与问题清单，不进入修复。
+
+## 范围
+
+### In Scope
+
+- `lsfx-mock-server` 中与随机命中规则计划、样本拼装、缓存稳定性相关的验证。
+- `ccdi-project` 中第一期真实规则相关的参数映射、真实 SQL、Service 分发与风险人数刷新链路验证。
+- 关键数据库基线与元数据核验。
+- 实际接口调用后的打标结果核验。
+- 本次验证对应的实施记录与验证记录沉淀。
+
+### Out of Scope
+
+- 第二期仍为占位状态的规则。
+- 新增规则、补丁逻辑、兜底逻辑或兼容性改造。
+- 任何修复实现与代码修改方案。
+
+## 验证对象
+
+本次只验证已在既有实施记录中明确落地的内容，不扩展额外模型。
+
+### 1. Mock 随机命中链路
+
+关注以下能力是否仍成立：
+
+- `FileService` 能为新 `logId` 写入稳定随机的规则命中计划。
+- `StatementService` 能按命中计划拼装对应样本，而不是回退到全量样本。
+- 同一 `logId` 重复读取时，规则命中子集和分页结果保持稳定。
+- `LARGE_PURCHASE_TRANSACTION` 对应的采购基线数据已通过独立 SQL 提供。
+
+### 2. 主工程第一期真实规则链路
+
+关注以下规则在现有打标链路中是否仍能按真实规则命中：
+
+- `GAMBLING_SENSITIVE_KEYWORD`
+- `SPECIAL_AMOUNT_TRANSACTION`
+- `SUSPICIOUS_INCOME_KEYWORD`
+- `FOREX_BUY_AMT`
+- `FOREX_SELL_AMT`
+- `LARGE_PURCHASE_TRANSACTION`
+- `STOCK_TFR_LARGE`
+- `WITHDRAW_CNT`
+- `LARGE_STOCK_TRADING`
+
+重点关注点：
+
+- 参数编码与规则编码保持全大写。
+- 阈值规则仍正确透传到 Mapper。
+- `WITHDRAW_CNT` 对象型规则仍保持“命中为空不回退任务状态”的链路约束。
+- `LARGE_PURCHASE_TRANSACTION` 仍走采购交易表数据源，不伪造银行流水替代。
+
+## 方案对比
+
+### 方案一：分三层顺序验证
+
+按 `Mock 自动化 -> 主工程自动化 -> 数据库核验 -> 接口端到端` 顺序执行。
+
+优点：
+
+- 最容易定位问题落点。
+- 与当前仓库已有测试资产和实施记录天然对齐。
+- 能覆盖你要求的完整验证深度。
+
+缺点：
+
+- 执行步骤最多。
+
+### 方案二：纯端到端驱动
+
+直接起服务并调用接口，看最终打标结果。
+
+优点：
+
+- 离业务使用最近。
+
+缺点：
+
+- 一旦失败，难以快速分辨是 Mock 样本、真实 SQL、参数分发还是接口编排问题。
+
+### 方案三：自动化为主，接口抽样补充
+
+优点：
+
+- 执行更快。
+
+缺点：
+
+- 对数据库事实和最终链路覆盖不足，不满足本次“完整验证”的要求。
+
+## 推荐方案
+
+采用方案一。
+
+原因是当前需求不是只看“有没有结果”，而是要同时确认：
+
+- Mock 样本能不能正确提供命中前提；
+- 主工程真实规则能不能正确识别；
+- 最终接口链路有没有把命中结果正确暴露出来。
+
+分层验证能把这三层责任拆开，失败时也能严格停在结论和问题清单，不会直接滑向修复。
+
+## 验证设计
+
+### 一、环境与基线确认
+
+先确认本次验证依赖的数据与环境处于可验证状态：
+
+- 主工程数据库连接可用。
+- `sql/migration/2026-03-20-lsfx-mock-random-hit-rule-purchase-baseline.sql` 已执行或可幂等重跑。
+- 采购基线记录 `LSFXMOCKPUR001` 存在，且 `actual_amount > 100000`。
+
+这一阶段的目标是确认“验证素材存在”，不直接下结论说模型已命中。
+
+### 二、Mock 随机命中自动化验证
+
+执行现有 `lsfx-mock-server` pytest 资产，覆盖四类能力：
+
+- 规则命中计划生成；
+- 命中计划持久化；
+- 按规则子集拼装样本；
+- 同一 `logId` 下缓存和分页稳定性；
+- 端到端集成链路。
+
+这一阶段通过后，才能认为 Mock 服务仍在稳定提供“可命中的输入数据”。
+
+### 三、主工程第一期真实规则自动化验证
+
+执行 `ccdi-project` 中与第一期真实规则直接相关的 Maven 测试，覆盖：
+
+- 规则参数映射；
+- XML 真实 SQL；
+- Service 分发；
+- 风险人数刷新链路。
+
+这一阶段通过后，才能认为主工程内部的规则识别与分发逻辑没有回退。
+
+### 四、数据库关键事实核验
+
+自动化通过后，再直接核验数据库事实，避免只依赖测试断言：
+
+- 采购基线记录存在且满足门槛。
+- 第一期开启真实规则的元数据仍与预期一致。
+- 规则编码、参数编码、指标编码继续保持全大写。
+- 端到端验证依赖的关键项目、流水、采购或对象数据具备最小命中条件。
+
+这一阶段的结论是“数据前提是否成立”，不是替代接口结果。
+
+### 五、接口端到端打标验证
+
+启动本次验证需要的最小服务集合，按真实链路执行一次完整调用：
+
+- 触发 Mock 取数或上传链路；
+- 触发主工程打标分析链路；
+- 查询最终模型或标签结果；
+- 对照数据库事实与规则预期，确认新增模型是否真正出现在结果中。
+
+这里的判定标准不是仅返回 HTTP 200，而是最终打标结果中是否包含预期命中的新增模型规则。
+
+## 通过标准
+
+只有同时满足以下三层条件，才视为本次验证通过：
+
+- 自动化层：相关 pytest 与 Maven 测试全部通过。
+- 数据层：关键基线与元数据查询结果符合预期。
+- 接口层：最终接口返回中包含预期命中的新增模型规则。
+
+只要任一层不满足，就记为失败，并停止给出“验证通过”的结论。
+
+## 失败判定与停点
+
+### 自动化失败
+
+任一既有 pytest 或 Maven 目标失败，记为：
+
+- 代码级回归；或
+- 环境级阻塞。
+
+此时记录失败命令、失败用例和首个错误点，不继续放大为“模型已失败命中”的业务结论。
+
+### 数据核验失败
+
+若自动化通过，但基线数据不存在、门槛不满足或元数据不一致，记为：
+
+- 验证数据不足；或
+- 数据基线异常。
+
+此时停止进入最终通过判定。
+
+### 接口链路失败
+
+若服务能启动、接口能调用，但最终结果缺失预期命中项，记为：
+
+- 链路级打标异常。
+
+输出接口请求、响应摘要、相关数据库证据和可疑断点位置，但不进入修复。
+
+## 记录与产物
+
+本次验证至少沉淀两类文档：
+
+- `docs/reports/implementation/` 下新增本次实施记录，说明验证执行内容与调整范围。
+- `docs/tests/records/` 下新增本次验证记录，说明执行命令、核验 SQL、接口结果与结论。
+
+文档内容固定包含：
+
+- 验证目标与范围；
+- 执行命令；
+- 数据库核验 SQL 与结果摘要；
+- 接口端到端步骤与结果摘要；
+- 最终结论；
+- 若失败则输出问题清单，不包含修复动作。
+
+## 进程管理
+
+若本次验证启动了 Java 后端、前端或 Mock 服务进程，验证结束后必须主动关闭，并在验证记录中写明已完成清理，避免残留端口占用。
+
+## 风险与边界
+
+- Mock 随机命中只保证“稳定随机子集”，不保证每个 `logId` 全量命中所有规则。
+- `LARGE_PURCHASE_TRANSACTION` 的命中依赖采购表基线，不应误判为银行流水样本问题。
+- 对象型规则 `WITHDRAW_CNT` 的结论需要和明细型规则区分，避免用相同口径判断失败。
+- 本次验证只为确认现状是否正确，不引申为修复设计或二期规则推进。
+
+## 结论
+
+本设计采用分层完整验证方案，对 2026-03-20 新加入的模型打标改动做统一校验。
+
+执行时先验证 Mock 规则输入，再验证主工程真实规则识别，最后验证数据库事实和接口结果是否闭环一致。若任何一层失败，只输出证据和问题清单，不进入代码修复。