本文引用的文件
清鉴 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 逐步依赖外部服务、数据库和大模型。
本节来源
仓库中与测试直接相关的资产分布在四个位置:
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"]
图表来源
| 测试类型 | 推荐位置 | 说明 |
|---|---|---|
| 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 |
不参与运行测试,但参与提交或流水线检查 |
本节来源
A 类测试覆盖的是“可纯函数复现”的逻辑,包括:
这些用例的核心价值是防止确定性门槛退化为黑盒。如果只跑 E2E,很难区分“模型没选对”和“打分公式写错了”。
本节来源
B 类关注“命中模板之后怎么落到字段”,重点包括:
c0..cN 与中文名绑定时改写为 c{i};这类测试保护的是“即使模板命中正确,也不能把脏绑定落库”。
本节来源
C 类不是只看接口返回 200,而是串联完整流程:
ai_clean_job、ai_clean_batch、治理树、动态表分页;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 |
需要人工复核的数量 |
本节来源
D 类覆盖非正常输入和边界场景:
这些用例的目标不是“功能更强”,而是“一个坏文件不应拖垮整个批次”。
本节来源
E 类是对 table_info 中全部模板的回归扫描。其流程是:
实际结果显示 362 个模板中 346 个命中正确,16 个错配。错配原因是既有匹配器的子集模板族歧义,而不是本轮改动引入的新问题。
本节来源
ai-electron/vitest.config.mts 当前是一个轻量配置,核心约束只有一项:
include: ['electron/**/*.test.ts']
这意味着:
ai-electron/electron/ 下以 .test.ts 结尾的文件;frontend/ 下的前端工程有自己独立的构建和工具链,不在此处运行;passWithNoTests: true 表示即使当前没有找到主进程测试也不会失败;根据 ai-electron/package.json 中的脚本:
| 命令 | 作用 |
|---|---|
pnpm test |
运行 vitest run,一次性执行所有符合 include 规则的测试 |
pnpm test:watch |
启动 watch 模式,适合开发时增量验证 |
Electron 应用通常拆成:
当前仓库的前端测试不在本文件中定义,后端测试也不走 Vitest。因此 Vitest 在这里的职责非常明确:将来承载 Electron 主进程侧的单测,而不是接管前端或后端。
本节来源
ESLint 和 Stylelint 不属于“运行期测试”,但它们构成代码质量的静态门禁。
ai-electron/frontend/eslint.config.mjs 配置了:
它的主要目标是保证前端 TS/JS/Vue 代码风格一致,并在提交或手动 lint 时暴露语法、导入、格式问题。
本节来源
ai-electron/frontend/stylelint.config.mjs 负责样式质量:
global、deep、v-deep、v-global、v-slotted;Stylelint 的核心价值是避免样式规则漂移、未知选择器、无效属性进入分支。
本节来源
根据 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 |
本节来源
该测试直接验证 HeaderScorer.score 和 passesStrong,属于 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
图表来源
本节来源
该测试覆盖三个关键假设:
测试中使用 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
图表来源
本节来源
该测试聚焦整条链路中最基础的确定性组件:
注释明确指出:整条 AI 链路中只有这几处是确定性的,其他都依赖模型。因此它们一旦出错,症状往往是“莫名不命中”,排查成本很高。
本节来源
run_tests.py 提供以下用法:
python run_tests.py group1:按 manifest 分组定向执行;python run_tests.py group1 --upload-only:只上传,不发起智能清洗;python run_tests.py list:列出分组;--limit、--ids、批量大小和超时参数。默认连接:
http://127.0.0.1:8980/js/a;192.168.0.106:5432/zsjz-ai;admin/admin123;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"
图表来源
脚本会查询:
ai_clean_job:每个 sheet 的 job 级别结果;ai_clean_batch:批次汇总;ai_clean_template:AI 模板详情;ai_clean_field:AI 模板字段。输出包含:
status、exit_code、matched_by、match_tier、llm_calls、row_total、row_loaded、row_rejected、fail_reason。本节来源
generate.py 支持三种模式:
targeted:账单、话单、跨行业、异常样本;full:table_info 全量模板的原表头和变体;all:全部模式。它使用固定随机种子,确保样本可复现,并按字段类型生成银行流水、通话记录、地址、时间、金额等生产风格数据。
本节来源
| 项目 | 建议 |
|---|---|
| 位置 | ai-server/src/test/java/com/zsjz/ai/module/aiclean/<模块>/... |
| 命名 | <被测类>Test.java,例如 HeaderScorerTest.java |
| 用例命名 | 使用 JUnit 5 @DisplayName 描述具体场景,例如“同义表头命中”“空表头得分 0” |
| 依赖 | 尽量使用 Mockito 和内存对象,不启动 Spring |
| 断言 | 断言分数、阈值、是否调用模型、是否抛出异常 |
| 清理 | 使用 @BeforeEach / @AfterEach 清理 GlobalCache 等共享状态 |
| 项目 | 建议 |
|---|---|
| 固定数据 | 放在 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 目录 |
推荐采用“场景编号 + 简短语义”的方式,例如:
这要与 ai-template-match-test-cases.md 中的编号保持一致,便于追踪发现项 F1–F6 和修复记录。
本节来源
当前仓库未发现专门的覆盖率插件配置,建议:
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 基础组 | 阻止明显回归 |
本节来源
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 同表头文件被既有匹配器直中,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 调查工具的测试体系可以概括为一句话:用 A/B 类单测钉住确定性门槛,用 C/D 类 E2E 守护真实业务链路,用 E 类全量模板覆盖防止模板退化。
其中:
同时,Electron 主进程的 Vitest 目前只聚焦 electron/**/*.test.ts,前端代码质量则由 ESLint 和 Stylelint 承担。新增测试时应遵循“确定性逻辑进 JUnit,真实链路进 E2E,固定数据进 fixtures,执行结果进 JSON 或文档”的原则,并尽量复用已有的 manifest、脚本和文档结构,使回归可复制、结果可追溯。