测试总览与分层策略.md 25 KB

测试总览与分层策略

本文引用的文件

  • vitest.config.mts
  • package.json
  • eslint.config.mjs
  • stylelint.config.mjs
  • ai-template-match-test-cases.md
  • ai-llm-template-match-bug-report-20261026.md
  • run_tests.py
  • generate.py
  • manifest.json
  • HeaderScorerTest.java
  • AiTemplateMatcherTest.java
  • AiCleanSupportTest.java
  • AiTemplateMatchEdgeTest.java

目录

  1. 引言
  2. 项目结构中的测试资产
  3. 五类测试分层模型
  4. Electron 主进程 Vitest 配置说明
  5. 前端 ESLint 与 Stylelint 质量门禁
  6. 关键组件测试实现分析
  7. E2E 真链路执行流程
  8. 新增测试用例规范
  9. 覆盖率、持续集成与发布前检查建议
  10. 故障排查指南
  11. 结论

引言

清鉴 AI 调查工具围绕“AI 清洗模板匹配”这条高风险链路建立了一套分层测试体系。核心设计原则是:确定性逻辑必须用单元测试钉住,真实业务行为必须用 E2E 在 dev 库上核验,异常和全量模板覆盖不能只靠人工。

项目把测试分为 A/E 五个层级:

层级 名称 目标 主要技术栈 典型断言
A 离线匹配规则 校验表头指纹、归一化、同义词、模糊词、打分、出口闸门 JUnit 5 + Mockito 分数阈值、是否直通、是否调用大模型
B 绑定与计划 校验字段绑定改写、歧义丢弃、列计划生成 JUnit 5 绑定名替换、越界处理、歧义处理
C E2E 真链路 上传 → 智能清洗 → job/批次/数据/治理树 HTTP API + PostgreSQL 核验 matched_by、exit_code、行数、模型调用次数
D 异常容错 损坏文件、空行、重复上传、跨案件复用 Python 批量脚本 + HTTP API 状态为 SKIP/NEED_REVIEW/SUCCESS,不拖垮批次
E 全量模板覆盖 对 table_info 全部模板做逐条匹配验证 Python 样本生成 + manifest 驱动 命中模板编号、错配数量、直中比例

这个分层不是按代码文件划分,而是按“离确定性有多远”划分:A/B 最确定,C/D/E 逐步依赖外部服务、数据库和大模型。

本节来源

  • ai-template-match-test-cases.md:1-111
  • ai-llm-template-match-bug-report-20261026.md:1-50

项目结构中的测试资产

仓库中与测试直接相关的资产分布在四个位置:

graph TB
    Root["仓库根"] --> ServerTests["后端单测<br/>ai-server/src/test/java"]
    Root --> GatewayTests["网关单测<br/>ai-gateway/src/test/java"]
    Root --> ElectronVitest["Electron 主进程 Vitest<br/>ai-electron/vitest.config.mts"]
    Root --> DocsTesting["测试文档与固定数据<br/>docs/testing/*"]
    DocsTesting --> Manifest["manifest.json<br/>用例清单"]
    DocsTesting --> Runner["run_tests.py<br/>批量执行器"]
    DocsTesting --> Generator["generate.py<br/>样本生成器"]
    ServerTests --> MatchTests["匹配规则单测<br/>HeaderScorer / Matcher / Edge"]

图表来源

  • vitest.config.mts:1-10
  • ai-template-match-test-cases.md:1-111
  • run_tests.py:1-40
  • generate.py:1-20
  • manifest.json:1-20

各层对应路径

测试类型 推荐位置 说明
A/B 类 JUnit 单测 ai-server/src/test/java/com/zsjz/ai/module/aiclean/... 与后端业务包结构对齐,例如 match、exec、verify、probe
E2E 固定数据 docs/testing/fixtures/ai-llm-match-20261026/{bills,calls,edge,...} Excel/CSV 输入、结果 JSON、manifest
E2E 执行脚本 docs/testing/fixtures/ai-llm-match-20261026/run_tests.py 通过 /auth/login、/dm/preFileUpload、/aiClean/smartClean 驱动
全量样本生成 docs/testing/fixtures/ai-llm-match-20261026/generate.py 从数据库读取 table_info 生成生产风格假数据
Electron 主进程测试 ai-electron/electron/**/*.test.ts 由 vitest.config.mts 的 include 控制
前端代码质量 ai-electron/frontend/eslint.config.mjs、ai-electron/frontend/stylelint.config.mjs 不参与运行测试,但参与提交或流水线检查

本节来源

  • ai-template-match-test-cases.md:1-111
  • run_tests.py:1-40
  • generate.py:1-20

五类测试分层模型

A 类:离线匹配规则(JUnit,确定性)

A 类测试覆盖的是“可纯函数复现”的逻辑,包括:

  • 表头指纹是否对顺序敏感;
  • 归一化是否抹平空白、全角半角、括号后缀;
  • 同义词注入后是否 EXACT 命中;
  • 模糊相似词是否按编辑距离、共同前缀等规则判断;
  • 重复列是否不会膨胀 Jaccard 分数;
  • 空表头、空模板是否返回 0 分且不抛异常;
  • 形状闸门是否拒绝 DATE 字段走 MONEY 等错误出口;
  • 必填覆盖是否允许 SIMILAR 命中也算覆盖;
  • 短模板、乱序、无关表头是否被低分拦截。

这些用例的核心价值是防止确定性门槛退化为黑盒。如果只跑 E2E,很难区分“模型没选对”和“打分公式写错了”。

本节来源

  • HeaderScorerTest.java:1-80
  • AiCleanSupportTest.java:1-60
  • AiTemplateMatchEdgeTest.java:1-60
  • ai-template-match-test-cases.md:25-63

B 类:绑定与计划(JUnit)

B 类关注“命中模板之后怎么落到字段”,重点包括:

  • 绑定名等于英文字段名时原样放行;
  • 绑定名等于中文时改写为英文;
  • AI 模板候选列 c0..cN 与中文名绑定时改写为 c{i};
  • 同义词改写后 EXACT 命中;
  • 模糊唯一命中改写到规范字段;
  • 模糊歧义时丢弃绑定,不让模型替业务做主;
  • 列号越界、空字段名、编造字段时丢弃。

这类测试保护的是“即使模板命中正确,也不能把脏绑定落库”。

本节来源

  • ai-template-match-test-cases.md:65-80

C 类:E2E 真链路(HTTP API + dev 库核验)

C 类不是只看接口返回 200,而是串联完整流程:

  1. 登录并打开案件;
  2. 上传文件;
  3. 发起智能清洗;
  4. 查询批次状态;
  5. 查 ai_clean_job、ai_clean_batch、治理树、动态表分页;
  6. 核对 matched_by、exit_code、ref_template_id、llm_calls、成功失败行数。

文档记录的关键指标包括:

指标 含义
matched_by HEADER_CACHE、SCORE、LLM
exit_code A=既有业务表,B=AI 动态表
llm_calls 大模型调用次数
success_num / fail_num 文件行级统计
need_review_count 需要人工复核的数量

本节来源

  • ai-template-match-test-cases.md:82-111
  • run_tests.py:41-120

D 类:异常容错

D 类覆盖非正常输入和边界场景:

  • 只有表头没有数据行;
  • 损坏 xlsx;
  • 治理树与 AI 数据页共存;
  • 同案件重复上传;
  • 跨案件复用同一文件。

这些用例的目标不是“功能更强”,而是“一个坏文件不应拖垮整个批次”。

本节来源

  • ai-template-match-test-cases.md:100-111

E 类:全量模板覆盖

E 类是对 table_info 中全部模板的回归扫描。其流程是:

  1. 从数据库读取模板及字段;
  2. 按字段类型生成生产风格假数据;
  3. 对每个模板生成同名类型的 Excel;
  4. 通过 manifest 分组分批上传;
  5. 比对预期模板与实际模板。

实际结果显示 362 个模板中 346 个命中正确,16 个错配。错配原因是既有匹配器的子集模板族歧义,而不是本轮改动引入的新问题。

本节来源

  • ai-template-match-test-cases.md:106-111
  • generate.py:1-20
  • manifest.json:1-20

Electron 主进程 Vitest 配置说明

ai-electron/vitest.config.mts 当前是一个轻量配置,核心约束只有一项:

include: ['electron/**/*.test.ts']

这意味着:

  • Vitest 只会查找 ai-electron/electron/ 下以 .test.ts 结尾的文件;
  • frontend/ 下的前端工程有自己独立的构建和工具链,不在此处运行;
  • passWithNoTests: true 表示即使当前没有找到主进程测试也不会失败;
  • 这是为后续主进程侧测试保留的基础能力。

执行命令

根据 ai-electron/package.json 中的脚本:

命令 作用
pnpm test 运行 vitest run,一次性执行所有符合 include 规则的测试
pnpm test:watch 启动 watch 模式,适合开发时增量验证

为什么这样设计

Electron 应用通常拆成:

  • 主进程:Node/Electron 原生能力;
  • 渲染进程:Vue 前端;
  • 后端:Java 服务。

当前仓库的前端测试不在本文件中定义,后端测试也不走 Vitest。因此 Vitest 在这里的职责非常明确:将来承载 Electron 主进程侧的单测,而不是接管前端或后端。

本节来源

  • vitest.config.mts:1-10
  • package.json:15-16

前端 ESLint 与 Stylelint 质量门禁

ESLint 和 Stylelint 不属于“运行期测试”,但它们构成代码质量的静态门禁。

ESLint 的作用

ai-electron/frontend/eslint.config.mjs 配置了:

  • Vue 3 文件解析;
  • TypeScript 与 JavaScript 混合支持;
  • Prettier 格式化规则;
  • 忽略 node_modules、dist、public、build、snapshots 等目录;
  • 关闭部分过于严格的规则,例如未使用变量、any 类型、显式返回值类型;
  • 统一单引号、分号、尾随逗号、打印宽度 120。

它的主要目标是保证前端 TS/JS/Vue 代码风格一致,并在提交或手动 lint 时暴露语法、导入、格式问题。

本节来源

  • eslint.config.mjs:1-177

Stylelint 的作用

ai-electron/frontend/stylelint.config.mjs 负责样式质量:

  • 支持 HTML、Vue、LESS、SCSS、CSS;
  • 继承标准规则和 Vue/Less/SCSS 推荐规则;
  • 针对 Vue 伪类/伪元素允许 global、deep、v-deep、v-global、v-slotted;
  • 禁止未知 at-rule 白名单中包含 UnoCSS、Unocss 相关指令;
  • 允许 rpx 单位;
  • 将 prettier 规则应用到样式文件;
  • 禁用部分可能影响现有项目的严格规则。

Stylelint 的核心价值是避免样式规则漂移、未知选择器、无效属性进入分支。

本节来源

  • stylelint.config.mjs:1-121

前端质量命令

根据 ai-electron/frontend/package.json:

命令 作用
pnpm lint:eslint 检查并修复 TS/TSX/MJS/Vue 的代码风格
pnpm lint:stylelint 检查并修复 Vue/LESS/SCSS/CSS 的样式风格
pnpm lint:all 组合安装、类型检查、ESLint、Prettier、Stylelint

本节来源

  • package.json:17-20

关键组件测试实现分析

HeaderScorerTest:打分与出口闸门

该测试直接验证 HeaderScorer.score 和 passesStrong,属于 A 类测试的核心。它关注:

  • 完全同表头应获得高分;
  • 同义词注入后应能通过短模板强匹配;
  • 空表头、空模板不会崩溃;
  • 重复列不会让 Jaccard 虚高;
  • 必填覆盖、形状闸门、模糊规则共同决定能否直通出口 A。

测试通过 GlobalCache.clearForTesting() 隔离缓存,并通过 setSynonymsForTesting 注入同义词,模拟生产环境加载 ai_clean_synonym 的行为。

flowchart TD
    Start["输入:文件表头 + 模板候选"] --> Normalize["归一化与同义词映射"]
    Normalize --> Score["计算相似度分数"]
    Score --> Strong{"是否通过强匹配?"}
    Strong -->|是| ExitA["允许出口 A:写入既有业务表"]
    Strong -->|否| LLM["进入模型裁决或出口 B"]
    ExitA --> End["结束"]
    LLM --> End

图表来源

  • HeaderScorerTest.java:1-80

本节来源

  • HeaderScorerTest.java:1-80
  • AiTemplateMatchEdgeTest.java:1-60

AiTemplateMatcherTest:匹配、向量召回与模型兜底

该测试覆盖三个关键假设:

  1. 同表头指纹直通必须零模型;
  2. 模型幻觉必须被兜住,越界序号不能落库;
  3. 出口 A 保留确定性闸门,向量召回只影响候选顺序。

测试中使用 Mockito mock LlmService 和 AiCleanTemplateVectorIndex,避免启动 Spring 上下文,从而保持 A 类测试快速、稳定。

sequenceDiagram
    participant Test as "AiTemplateMatcherTest"
    participant Matcher as "AiTemplateMatcher"
    participant Vector as "AiCleanTemplateVectorIndex"
    participant LLM as "LlmService"

    Test->>Matcher: "传入文件表头与证据"
    Matcher->>Vector: "向量召回候选模板"
    Vector-->>Matcher: "候选列表"
    alt "同表头指纹命中"
        Matcher-->>Test: "直中,不调用模型"
    else "指纹未命中"
        Matcher->>LLM: "请求模型裁决"
        LLM-->>Matcher: "返回候选或越界序号"
        Matcher->>Matcher: "校验序号与出口闸门"
        Matcher-->>Test: "返回匹配结果"
    end

图表来源

  • AiTemplateMatcherTest.java:1-80

本节来源

  • AiTemplateMatcherTest.java:1-80

AiCleanSupportTest:归一化、指纹与列形状

该测试聚焦整条链路中最基础的确定性组件:

  • 列名归一化;
  • 表头指纹;
  • 表块切分;
  • 列形状推断。

注释明确指出:整条 AI 链路中只有这几处是确定性的,其他都依赖模型。因此它们一旦出错,症状往往是“莫名不命中”,排查成本很高。

本节来源

  • AiCleanSupportTest.java:1-60

E2E 真链路执行流程

执行入口

run_tests.py 提供以下用法:

  • python run_tests.py group1:按 manifest 分组定向执行;
  • python run_tests.py group1 --upload-only:只上传,不发起智能清洗;
  • python run_tests.py list:列出分组;
  • 支持 --limit、--ids、批量大小和超时参数。

默认连接:

  • 后端 API:http://127.0.0.1:8980/js/a;
  • PostgreSQL:192.168.0.106:5432/zsjz-ai;
  • 账号:admin/admin123;
  • 默认案件 ID:20(脚本内可调整)。

关键步骤

sequenceDiagram
    participant Script as "run_tests.py"
    participant API as "后端 HTTP API"
    participant DB as "PostgreSQL"

    Script->>API: "POST /auth/login"
    API-->>Script: "返回 token"
    Script->>API: "POST /case/open"
    API-->>Script: "打开案件"
    Script->>API: "POST /dm/preFileUpload"
    API-->>Script: "返回批次与 sheet 信息"
    Script->>API: "POST /aiClean/smartClean"
    API-->>Script: "返回任务状态"
    Script->>DB: "查询 ai_clean_job / ai_clean_batch"
    DB-->>Script: "返回执行结果"
    Script->>Script: "合并结果并输出 JSON"

图表来源

  • run_tests.py:1-120

结果记录方式

脚本会查询:

  • ai_clean_job:每个 sheet 的 job 级别结果;
  • ai_clean_batch:批次汇总;
  • ai_clean_template:AI 模板详情;
  • ai_clean_field:AI 模板字段。

输出包含:

  • 测试编号;
  • 文件路径;
  • 预期模板;
  • 实际模板;
  • 上传状态;
  • 批次 ID;
  • 文件 ID;
  • sheet 列表;
  • job 级别字段如 status、exit_code、matched_by、match_tier、llm_calls、row_total、row_loaded、row_rejected、fail_reason。

本节来源

  • run_tests.py:1-200

全量模板样本生成

generate.py 支持三种模式:

  • targeted:账单、话单、跨行业、异常样本;
  • full:table_info 全量模板的原表头和变体;
  • all:全部模式。

它使用固定随机种子,确保样本可复现,并按字段类型生成银行流水、通话记录、地址、时间、金额等生产风格数据。

本节来源

  • generate.py:1-20
  • manifest.json:1-20

新增测试用例规范

A/B 类单测

项目 建议
位置 ai-server/src/test/java/com/zsjz/ai/module/aiclean/<模块>/...
命名 <被测类>Test.java,例如 HeaderScorerTest.java
用例命名 使用 JUnit 5 @DisplayName 描述具体场景,例如“同义表头命中”“空表头得分 0”
依赖 尽量使用 Mockito 和内存对象,不启动 Spring
断言 断言分数、阈值、是否调用模型、是否抛出异常
清理 使用 @BeforeEach / @AfterEach 清理 GlobalCache 等共享状态

C/D/E 类 E2E

项目 建议
固定数据 放在 docs/testing/fixtures/ai-llm-match-YYYYMMDD/ 下
清单 维护 manifest.json,标注 test_id、category、path、expected_template_id
执行脚本 复用 run_tests.py,按 category 分组
结果记录 输出 JSON,保存 job_id、batch_id、exit_code、matched_by
数据库核验 至少校验 ai_clean_job 与 ai_clean_batch
截图 复杂 UI 流程可补充截图到 fixtures 目录

命名约定

推荐采用“场景编号 + 简短语义”的方式,例如:

  • A1:同表头指纹;
  • A6:模糊正向命中;
  • C5:账单缺必填;
  • D2:损坏 xlsx;
  • E-full-exact:全量模板精确匹配。

这要与 ai-template-match-test-cases.md 中的编号保持一致,便于追踪发现项 F1–F6 和修复记录。

本节来源

  • ai-template-match-test-cases.md:1-111
  • manifest.json:1-20

覆盖率、持续集成与发布前检查建议

覆盖率

当前仓库未发现专门的覆盖率插件配置,建议:

  1. 后端 JUnit 单测启用 JaCoCo;
  2. 仅对 A/B 类单测收集覆盖率,因为 C/D/E 依赖外部服务;
  3. 设置最低覆盖率阈值,例如核心 match/verify 包不低于 80%;
  4. 对 E2E 结果单独报告“通过率”,不与单测覆盖率混在一起。

持续集成建议

CI 建议分阶段执行:

阶段 命令 目的
前端静态检查 pnpm lint:all ESLint、Stylelint、Prettier
后端编译 mvn compile -pl ai-server 确保 Java 代码可编译
后端单测 mvn test -pl ai-server A/B 类确定性测试
Electron 主进程测试 cd ai-electron && pnpm test 未来主进程 Vitest 测试
E2E 真链路 启动后端 + dev 库,执行 run_tests.py C/D 类链路
全量模板覆盖 generate.py full + run_tests.py full-exact E 类回归
发布前检查 全量 lint + 单测 + E2E 基础组 阻止明显回归

发布前检查清单

  • A/B 类 JUnit 单测全部通过;
  • 前端 ESLint 与 Stylelint 无新增警告;
  • Electron 主进程 Vitest 无新增失败;
  • C 类核心场景至少跑一遍;
  • D 类异常场景至少跑一遍;
  • E 类全量模板覆盖至少跑一次基准;
  • 若涉及大模型,确认并发配置与本地模型会话限制;
  • 结果 JSON 已归档,便于复现。

本节来源

  • ai-template-match-test-cases.md:100-111
  • ai-llm-template-match-bug-report-20261026.md:1-40

故障排查指南

常见问题与定位思路

现象 可能原因 排查方向
同表头文件被既有匹配器直中,AI 腿未触发 设计内行为:既有匹配器优先 改用同义词、相似词或缺失必填列
模型漏绑必填列,最终走出口 B 模型输出不稳定 查看 C 类用例中 NEED_REVIEW 分支
批卡在 JUDGING 本地模型并发过高 检查 max-concurrent 配置
文件识别调度器与 AI 清洗争用模型 线程池配置冲突 检查文件识别与清洗并发参数
既有匹配器误判话单 部分匹配分支过宽 参考 F-01B 修复
金额清洗写 0.00 既有清洗未识别千分位/货币符号 参考 F-03,非本轮范围
全量模板命中率不到 100% 子集模板族歧义 参考 F-01C/F-05

关键发现项

编号 严重度 摘要
F-01 P0 交通银行同义表被错配为农商行模板,业务表 0 行
F-01B P0 导出话单被误判为通信登记信息,字段丢失
F-01C P2 table_info 全量覆盖存在固有歧义
F-02 P1 统计口径把非数据行算作导入成功
F-03B P1 AI 动态表方向字典值未归一
F-03 P1 既有清洗未识别带千分位/货币符号的金额
F-04 P1 本地单会话模型并发导致硬超时
F-04B P1 文件识别与 AI 清洗争用模型
F-05 P2 日志无法区分既有表与 AI 动态表
F-06 P2 二次 askLlm 返回越界序号
F-07 P2 语义命中但确定性闸门不通过,转 AI 表

这些发现项直接体现了分层测试的价值:A/B 类单测能提前抓住打分和闸门问题,C/D 类 E2E 能发现真实链路中的统计、并发、可观测性问题,E 类全量覆盖能暴露模板族的系统性歧义。

本节来源

  • ai-llm-template-match-bug-report-20261026.md:1-50
  • ai-template-match-test-cases.md:82-111

结论

清鉴 AI 调查工具的测试体系可以概括为一句话:用 A/B 类单测钉住确定性门槛,用 C/D 类 E2E 守护真实业务链路,用 E 类全量模板覆盖防止模板退化。

其中:

  • A 类测试是安全基线,防止“模型不可控”掩盖“确定性逻辑写错”;
  • B 类测试是字段落地防线,防止脏绑定写库;
  • C 类测试是用户视角的真实链路;
  • D 类测试是稳定性底线;
  • E 类测试是模板库回归护栏。

同时,Electron 主进程的 Vitest 目前只聚焦 electron/**/*.test.ts,前端代码质量则由 ESLint 和 Stylelint 承担。新增测试时应遵循“确定性逻辑进 JUnit,真实链路进 E2E,固定数据进 fixtures,执行结果进 JSON 或文档”的原则,并尽量复用已有的 manifest、脚本和文档结构,使回归可复制、结果可追溯。