From 2db9ee7860c296e4a5654728b425896796f4fa71 Mon Sep 17 00:00:00 2001
From: wkc <978997012@qq.com>
Date: Wed, 18 Mar 2026 14:10:20 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85LSFX=20Mock=E5=A4=A7=E9=A2=9D?=
 =?UTF-8?q?=E4=BA=A4=E6=98=93=E6=A0=B7=E6=9C=AC=E8=AE=BE=E8=AE=A1=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...fx-mock-large-transaction-design-record.md |  21 ++
 ...3-18-lsfx-large-transaction-mock-design.md | 277 ++++++++++++++++++
 2 files changed, 298 insertions(+)
 create mode 100644 docs/reports/implementation/2026-03-18-lsfx-mock-large-transaction-design-record.md
 create mode 100644 docs/superpowers/specs/2026-03-18-lsfx-large-transaction-mock-design.md

diff --git a/docs/reports/implementation/2026-03-18-lsfx-mock-large-transaction-design-record.md b/docs/reports/implementation/2026-03-18-lsfx-mock-large-transaction-design-record.md
new file mode 100644
index 00000000..ebd8153b
--- /dev/null
+++ b/docs/reports/implementation/2026-03-18-lsfx-mock-large-transaction-design-record.md
@@ -0,0 +1,21 @@
+# LSFX Mock 大额交易样本设计记录
+
+## 变更概述
+
+- 新增大额交易 Mock 设计文档，明确 `lsfx-mock-server` 如何稳定生成可命中后端 8 条大额交易规则的流水样本。
+- 设计中补充了一个关键前提：Mock 必须复用后端可识别的员工/家属身份证号，否则仅靠金额和摘要无法命中后端规则。
+
+## 新增文件
+
+- `docs/superpowers/specs/2026-03-18-lsfx-large-transaction-mock-design.md`
+
+## 设计要点
+
+- 生成策略从“完全随机流水”调整为“规则命中样本 + 随机噪声流水”。
+- 8 条规则拆为 5 组样本簇，复用样本以减少无意义的硬编码流水。
+- 默认复用已有验证文档中的 4 个身份作为命中身份池。
+- Mock 内置当前后端系统默认阈值，避免对主系统数据库产生耦合。
+
+## 后续动作
+
+- 待用户审阅 spec 后，进入实施计划阶段。
diff --git a/docs/superpowers/specs/2026-03-18-lsfx-large-transaction-mock-design.md b/docs/superpowers/specs/2026-03-18-lsfx-large-transaction-mock-design.md
new file mode 100644
index 00000000..64698963
--- /dev/null
+++ b/docs/superpowers/specs/2026-03-18-lsfx-large-transaction-mock-design.md
@@ -0,0 +1,277 @@
+# LSFX Mock 大额交易命中样本设计
+
+## 背景
+
+当前 `lsfx-mock-server` 的银行流水接口会返回完全随机的流水数据，但后端银行流水打标中的大额交易模型依赖摘要关键词、收支方向、金额阈值、交易日期，以及 `cretNo` 与员工/家属身份关系的匹配。仅有随机金额和随机摘要不足以稳定命中后端规则，导致联调时即使接口返回成功，后端打标结果仍可能为空。
+
+本设计用于调整 Mock 流水生成策略，使其在保留随机噪声数据的同时，稳定产出可命中后端大额交易 8 条规则的样本流水。
+
+## 目标
+
+- 更新 `lsfx-mock-server` 的银行流水生成逻辑。
+- 每个 `logId` 首次生成流水时，稳定包含可命中大额交易 8 条规则的样本。
+- 在命中样本之外继续混入普通随机流水，保持 Mock 数据的随机感和分页场景。
+- 不修改后端打标实现，以后端现有 SQL 口径作为唯一准绳。
+
+## 范围
+
+### In Scope
+
+- `lsfx-mock-server` 获取银行流水接口的生成逻辑。
+- 大额交易 8 条规则所需的命中样本模板。
+- 对应的 Mock 单元测试与接口测试。
+- 本次改动的实施记录文档。
+
+### Out of Scope
+
+- 后端 `CcdiBankTagAnalysisMapper.xml` 或打标 Service 逻辑调整。
+- 其他模型组规则的 Mock 命中样本。
+- Mock 服务接入主系统数据库或动态读取后端参数。
+
+## 后端规则现状
+
+后端当前已实际实现并可命中的大额交易规则为：
+
+1. `HOUSE_OR_CAR_EXPENSE`
+2. `TAX_EXPENSE`
+3. `SINGLE_LARGE_INCOME`
+4. `CUMULATIVE_INCOME`
+5. `ANNUAL_TURNOVER`
+6. `LARGE_CASH_DEPOSIT`
+7. `FREQUENT_CASH_DEPOSIT`
+8. `LARGE_TRANSFER`
+
+这些规则的关键命中条件总结如下：
+
+- 房车消费、税务支出：依赖 `userMemo` 或 `customerName` 的关键词命中，且 `drAmount > 0`。
+- 单笔大额收入、累计收入、年流水、大额转账：依赖员工身份、对手方名称、收支方向、阈值及排除条件。
+- 大额存现、单日多次存现：依赖 `cashType`、`userMemo`、`customerName` 与 `crAmount` 的联合条件。
+- 多条规则要求 `cretNo` 能在后端库中关联到员工或家属，否则规则不会命中。
+
+## 关键前提
+
+Mock 必须复用一组后端环境中真实可识别的身份证号，否则仅靠金额和摘要无法满足后端 `exists staff/relation` 条件。
+
+本次默认复用现有文档中已用于大额交易验证的身份池：
+
+- 员工：`330101198801010011`
+- 家属：`330101199001010022`
+- 员工：`330101198802020033`
+- 家属：`330101199202020044`
+
+这些身份已在既有大额交易验证文档与种子 SQL 中使用，可作为 Mock 默认命中身份池。若后续目标环境不存在这些身份，需要在样本配置中同步替换。
+
+## 设计概览
+
+将现有“逐条完全随机生成”的策略调整为“两段式生成”：
+
+1. 先生成固定数量的规则命中样本。
+2. 再补充普通随机噪声流水。
+3. 合并后统一排序/洗牌，写入当前 `logId` 缓存。
+4. 分页接口继续基于缓存返回，保证同一 `logId` 多次请求结果一致。
+
+## 组件设计
+
+### 1. 普通随机流水生成器
+
+保留现有随机生成能力，继续负责生成非命中噪声数据。其职责仅限于提供分页场景和背景数据，不承担命中保障。
+
+### 2. 大额交易样本生成器
+
+新增专用样本生成层，负责生成 8 条规则所需的流水组合。建议拆为独立模块，例如：
+
+- `services/statement_rule_samples.py`
+
+该模块维护：
+
+- 默认身份池
+- 默认阈值常量
+- 每条规则的样本构造函数
+- 公共流水字段构造辅助函数
+
+### 3. 汇总与缓存层
+
+`statement_service.py` 负责：
+
+- 调用大额交易样本生成器获取命中样本
+- 生成指定数量的噪声流水
+- 为所有记录补齐唯一 `bankStatementId`、`bankTrxNumber`、`uploadSequnceNumber`
+- 合并、打乱顺序并缓存
+- 按页返回 `bankStatementList`
+
+## 样本组织方案
+
+为避免只为单一规则生成孤立流水，8 条规则拆为 5 组样本簇：
+
+### A. 房车消费支出样本
+
+- 1 至 2 条支出流水
+- `drAmount > 0`
+- `userMemo` 含 `购买房产首付款`、`购车首付款` 等关键词
+- 或 `customerName` 命中 `房地产`、`贝壳`、`汽车销售`、`4S店` 等关键词
+- `cretNo` 使用员工或家属身份证
+
+### B. 税务支出样本
+
+- 1 至 2 条支出流水
+- `drAmount > 0`
+- `userMemo` 或 `customerName` 命中 `税务`、`税款`、`税务局`、`国库`
+- `cretNo` 使用员工或家属身份证
+
+### C. 大额收入样本簇
+
+使用同一员工身份证与同一非亲属对手方生成多条收入流水，复用命中：
+
+- `SINGLE_LARGE_INCOME`
+- `CUMULATIVE_INCOME`
+- `ANNUAL_TURNOVER`
+
+约束如下：
+
+- 至少 1 条 `crAmount` 大于 `SINGLE_TRANSACTION_AMOUNT`
+- 多条累计 `crAmount` 大于 `CUMULATIVE_TRANSACTION_AMOUNT`
+- 再叠加大额收入/支出，使近一年累计交易额大于 `ANNUAL_TURNOVER`
+- `leName != customerName`
+- `customerName` 不得映射为该员工家属名称
+- 避开工资排除条件，不能使用 `浙江兰溪农村商业银行股份有限公司`，`userMemo` 也不得含 `代发`、`工资`、`奖金`、`薪酬` 等词
+
+### D. 大额存现样本簇
+
+使用同一身份证、同一天生成 6 条现金存入流水，复用命中：
+
+- `LARGE_CASH_DEPOSIT`
+- `FREQUENT_CASH_DEPOSIT`
+
+约束如下：
+
+- 每条 `crAmount` 大于 `LARGE_CASH_DEPOSIT`
+- 同日条数大于 `FREQUENT_CASH_DEPOSIT`
+- `cashType` / `userMemo` / `customerName` 的组合需满足后端 `cashDepositPredicate`
+- 推荐使用 `现金存款`、`ATM现金存款`、`自助存款现金存入`、`CRS存款`、`本行ATM存款` 等摘要
+
+### E. 大额转账支出样本
+
+- 1 至 2 条支出流水
+- `drAmount > FREQUENT_TRANSFER`
+- `userMemo` 含 `手机银行转账`、`对外转账`
+- 或 `cashType` / `customerName` 含转账特征
+- `userMemo` 不能包含 `款`，避免被后端排除
+- `leName != customerName`
+
+## 默认阈值策略
+
+Mock 不接主系统数据库，因此不动态读取项目参数。为保证命中稳定，样本生成器内置与当前系统默认参数一致的阈值常量：
+
+- `SINGLE_TRANSACTION_AMOUNT = 1111`
+- `CUMULATIVE_TRANSACTION_AMOUNT = 50000001`
+- `ANNUAL_TURNOVER = 50000001`
+- `LARGE_CASH_DEPOSIT = 2000001`
+- `FREQUENT_CASH_DEPOSIT = 5`
+- `FREQUENT_TRANSFER = 100001`
+
+样本金额应显著高于阈值，避免边界值因格式化或比较方式差异导致误判。
+
+## 数据生成细节
+
+### 字段稳定要求
+
+以下字段不得继续完全随机：
+
+- `cretNo`
+- `leName`
+- `customerName`
+- `userMemo`
+- `cashType`
+- `trxDate`
+- `crAmount`
+- `drAmount`
+
+它们需要按规则模板构造。
+
+### 可以继续随机的字段
+
+以下字段可保留随机生成或在模板基础上随机化：
+
+- `accountMaskNo`
+- `customerAccountMaskNo`
+- `bankTrxNumber`
+- `balanceAmount`
+- `bank`
+- `customerBank`
+- `uploadSequnceNumber`
+
+### 日期策略
+
+- `ANNUAL_TURNOVER` 相关样本统一放在当前日期前 12 个月内。
+- `FREQUENT_CASH_DEPOSIT` 相关样本统一放在同一天但不同时间点。
+- 其他样本可分布在近一年内，避免全部集中到同一时刻。
+
+### 总量策略
+
+- 继续沿用当前 `1200-1500` 的总条数范围。
+- 先生成全部命中样本，再以 `totalCount - sampleCount` 的差值补足噪声流水。
+- 若后续命中样本数量增长超过随机总量下限，应自动以命中样本数作为最小总量，避免截断命中数据。
+
+### 排序与分页
+
+生成完成后统一打乱顺序，再根据请求分页返回。这样：
+
+- 前端仍能看到类似真实的随机顺序
+- 同一 `logId` 由于缓存存在，重复请求时顺序稳定
+
+## 错误处理
+
+- 若大额交易样本构造失败，直接抛出明确异常，不静默降级为纯随机流水。
+- 这样能避免接口返回正常但后端永远打不中的隐性问题。
+- 不新增复杂容错或回退机制，保持 Mock 行为可预测。
+
+## 测试设计
+
+至少补充两类验证：
+
+### 1. 样本生成测试
+
+验证大额交易样本生成器输出满足关键特征：
+
+- 存在房车消费关键词支出
+- 存在税务关键词支出
+- 存在单笔超阈值收入
+- 存在同一对手方累计超阈值收入
+- 存在近一年累计交易额超阈值样本
+- 存在同日 6 笔以上现金存入
+- 存在单笔存现超阈值
+- 存在单笔转账支出超阈值且摘要不含 `款`
+
+### 2. 接口返回测试
+
+调用 `getBSByLogId`，验证：
+
+- 返回总数正常
+- `bankStatementList` 中能找到各类命中样本特征
+- 同一 `logId` 多次请求返回相同数据
+- 分页拼接后的全量结果仍包含全部命中样本
+
+## 成功标准
+
+- Mock 每次首次生成流水时都稳定包含大额交易 8 条规则所需样本。
+- 同一 `logId` 多次分页请求数据一致。
+- 在默认身份池存在于目标环境的前提下，后端接入 Mock 返回数据后，现有大额交易 8 条规则可以被正确命中。
+- 普通随机噪声流水仍然存在，不退化为完全固定数据集。
+
+## 风险与约束
+
+- 默认身份池依赖后端环境已有对应员工/家属数据；若环境不一致，需要替换身份池常量。
+- Mock 使用内置阈值，若后端系统默认参数未来变更，Mock 也需要同步更新。
+- 若后端 SQL 规则继续演进，本设计中的样本关键词和排除词也要同步校准。
+
+## 实施输出
+
+实施阶段应至少产出：
+
+- Mock 代码改动
+- 对应测试用例
+- 一份前端实施计划
+- 一份后端实施计划
+- 一份实施记录文档
+
+其中前后端实施计划用于说明联调影响面：本次主要改动在 Mock 服务，但后端计划中需要明确验证路径和命中校验方式。