# 新增模型打标完整验证计划

## 背景

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 规则输入，再验证主工程真实规则识别，最后验证数据库事实和接口结果是否闭环一致。若任何一层失败，只输出证据和问题清单，不进入代码修复。
