本文引用的文件
本指南面向需要理解并扩展 AI 清洗测试的开发者,覆盖以下目标:
target/aitest_*.py 和 target/aitest/*.json 记录结果。vitest.config.mts 中 include=['electron/**/*.test.ts'] 与 passWithNoTests=true 的含义,以及如何在主进程新增 .test.ts 单测。项目中的 AI 清洗测试采用“离线确定性 + 在线真实链路”的分层设计:
E 层:全量模板覆盖(遍历 table_info 模板族)。
flowchart TD
A["A 层:JUnit 确定性测试<br/>HeaderScorer / AiTemplateMatcher / Edge / Support"] --> B["B 层:绑定与计划<br/>filterBinds / 列计划 / 歧义处理"]
B --> C["C 层:E2E 真链路<br/>HTTP API 上传 + 智能清洗"]
C --> D["D 层:异常容错<br/>损坏文件 / 去重 / 跨案"]
C --> DB["数据库核验<br/>ai_clean_job / ai_clean_batch / ai_clean_template"]
A --> Result["结果:target/aitest_*.py / target/aitest/*.json"]
B --> Result
D --> Result
图示来源
章节来源
后端测试位于 ai-server/src/test/java/com/zsjz/ai/module/aiclean/**,主要围绕 AI 清洗模块中的“匹配—绑定—支撑工具”展开:
| 测试类 | 职责 | 关键断言目标 |
|---|---|---|
HeaderScorerTest |
表头打分与出口 A 闸门 | 同表头高分、同义词 EXACT、模糊相似、单位差异、形状矛盾、必填缺失、F-01 收紧 |
AiTemplateMatcherTest |
三腿匹配、向量召回、绑定过滤、模型幻觉兜底 | 指纹直通零模型、既有模板强命中出口 A、越界候选降级为未命中、绑定域合法性和改写 |
AiTemplateMatchEdgeTest |
边界严格测试 | 空表头、重复列、必填相似覆盖、无关表头、短词边界、同义词改写 |
AiCleanSupportTest |
纯逻辑支撑 | 列名归一化、表头指纹、复用安全、表块切分、列形状识别、列名消毒 |
这些测试共同保证:
模型返回不可信时,按未命中或低置信降级,而不是直接落库。
classDiagram
class HeaderScorerTest {
+exactHeaders()
+synonyms()
+fuzzySimilarRules()
+fuzzyNeverCollapsesUnits()
+reordered()
+shapeMismatchBlocksStrong()
+requiredMissingBlocksStrong()
}
class AiTemplateMatcherTest {
+fingerprintShortCircuits()
+scoreHitsExistingTemplate()
+hallucinatedIndexDegradesToNone()
+filterBindsAcceptsBothDomainsAndRejectsInventedFields()
+lowConfidenceCannotReachExistingTable()
}
class AiTemplateMatchEdgeTest {
+emptyHeadersScoreZero()
+duplicateColumnsDoNotInflateScore()
+requiredCoveredBySimilarWord()
+unrelatedHeadersScoreLow()
+shortWordBoundary()
+filterBindsExactViaSynonymEntry()
}
class AiCleanSupportTest {
+normalizeHeaders()
+fingerprintIsPositionSensitive()
+sameOrderedHeaders()
+singleBlockWithTitleRow()
+twoBlocks()
+colShapes()
+colStats()
+sanitizeColumns()
}
HeaderScorerTest --> "验证" HeaderScorer : "打分 / STRONG / WEAK"
AiTemplateMatcherTest --> "依赖" LlmService : "mock"
AiTemplateMatcherTest --> "依赖" AiCleanTemplateVectorIndex : "mock"
AiTemplateMatchEdgeTest --> "验证" HeaderScorer : "边界条件"
AiCleanSupportTest --> "验证" HeaderNormalizer : "归一化"
AiCleanSupportTest --> "验证" HeaderFingerprint : "指纹"
AiCleanSupportTest --> "验证" BlockDetector : "表块切分"
AiCleanSupportTest --> "验证" ColStatBuilder : "列形状"
图示来源
章节来源
该测试聚焦确定性打分逻辑,避免模型误判直接写入既有业务表:
GlobalCache.setSynonymsForTesting 注入,验证词条链路;无词条时不应命中。章节来源
该测试重点验证三件事:
关键行为包括:
BY_CACHE,不调用 LLM,且出口为 B。BY_NONE,candidate 为空。en=c0..cN)下,模型回中文名也应放行并改写为物理列名。高置信度但确定性分数为 0 时,只能走出口 B。
sequenceDiagram
participant Test as "AiTemplateMatcherTest"
participant Matcher as "AiTemplateMatcher"
participant Vector as "AiCleanTemplateVectorIndex"
participant LLM as "LlmService"
Test->>Matcher: match(evidence, templates, byScore)
alt 指纹命中
Matcher-->>Test: BY_CACHE / 不调 LLM / 出口 B
else 既有模板强命中
Matcher-->>Test: BY_SCORE / 不调 LLM / 出口 A
else 需要模型裁决
Matcher->>Vector: recall(query, topK)
Vector-->>Matcher: 候选列表
Matcher->>LLM: chatAsDetail(...)
LLM-->>Matcher: 结构化草稿
alt 候选序号越界或无效
Matcher-->>Test: BY_NONE / candidate=null
else 有效草稿
Matcher-->>Test: 由置信度与确定性分数决定出口
end
end
图示来源
章节来源
该测试专门钉住容易退化的边界:
章节来源
该测试覆盖整条 AI 链路中最关键的确定性部分:
章节来源
E2E 脚本位于 docs/testing/fixtures/ai-llm-match-20261026/run_tests.py,其职责是:
http://127.0.0.1:8980/js/a。admin/admin123 登录。manifest.json 中的文件清单。ai_clean_job、ai_clean_batch、ai_clean_template 数据。target/aitest_*.py 和 target/aitest/*.json。需要注意:脚本当前默认 CASE_ID = 20,而测试文档锚定的是案件 A=16、B=17。若要在 16/17 上执行真实链路,应调整脚本中的 CASE_ID 和相关配置,并确保服务地址、数据库连接、登录凭据与本环境一致。
章节来源
E2E 客户端封装了常用接口:
| 阶段 | API | 作用 |
|---|---|---|
| 登录 | /auth/login |
获取 token,设置请求头 x-token |
| 开案 | /case/open |
打开测试案件,带重试 |
| 上传 | /dm/preFileUpload |
上传 xlsx/csv,支持 batchId 和 reClean |
| 智能清洗 | /aiClean/smartClean |
提交清洗任务 |
| 状态查询 | /aiClean/smartClean/status |
根据 batchId 查询批次状态 |
| 数据查看 | /gt/treeTablePage |
查看治理树中的表数据 |
sequenceDiagram
participant Py as "run_tests.py"
participant API as "后端 HTTP API"
participant DB as "PostgreSQL"
Py->>API: POST /auth/login
API-->>Py: 返回 token
Py->>API: POST /case/open
API-->>Py: 开案成功
Py->>API: POST /dm/preFileUpload(batchId, reClean)
API-->>Py: 返回 file/batch 结构
Py->>API: POST /aiClean/smartClean(fileInfos, reClean)
API-->>Py: 返回清洗任务
Py->>API: GET /aiClean/smartClean/status?batchId
API-->>Py: 返回批次进度
Py->>DB: 查询 ai_clean_job / ai_clean_batch
DB-->>Py: 返回清洗结果
Py-->>Py: 写入 target/aitest_*.py / target/aitest/*.json
图示来源
E2E 结果关键字段包括:
matched_by:HEADER_CACHE、SCORE、LLM。exit:A 表示写既有业务表,B 表示 AI 动态表。llm:模型调用次数。upload:OK、DATA_NULL、SKIP 等上传状态。template_id、expected_template_id:实际命中模板与期望模板。sheet_id、job_id、row_total、row_loaded、row_rejected:Sheet 与 Job 粒度数据。测试文档明确说明:同表头文件在上传阶段可能被既有匹配器直中,AI 清洗作为兜底链路;因此“未产生 ai_clean_job”不一定是失败,而是设计内行为。
章节来源
ai-electron/vitest.config.mts 中:
include: ['electron/**/*.test.ts'] 表示只扫描 ai-electron/electron/ 目录下以 .test.ts 结尾的文件。ai-electron/frontend/,有自己独立的工程,不在该配置范围内。ai-electron/electron/.../.test.ts,否则不会被发现。.test.ts,vitest 也不会把整个命令当作失败。ai-electron/electron/ 下的功能目录创建 .test.ts 文件。如只需验证某几个测试,可使用 Vitest 的路径或名称过滤参数。
flowchart TD
Dev["开发者创建 electron/**/*.test.ts"] --> Config["vitest.config.mts 扫描 include 规则"]
Config --> Match{"是否匹配 electron/**/*.test.ts"}
Match -->|是| Run["vitest 执行测试"]
Match -->|否| Skip["passWithNoTests=true,不报错但也不执行"]
Run --> Report["输出测试结果"]
Skip --> Warning["建议检查文件路径和命名"]
图示来源
章节来源
GlobalCache.clearForTesting() 和 setSynonymsForTesting() 控制全局缓存。batchId 区分不同批次,并通过 manifest.json 固定测试文件和期望模板。章节来源
现有 E2E 脚本更偏向“执行并记录”,并未在每轮测试前自动清空数据库。若需强隔离:
章节来源
E2E 客户端使用 requests.Session 保存会话,登录后将 token 放入 x-token 请求头。响应码为 401 时会重试一次登录并重新开案,提升弱网或服务重启后的稳定性。
章节来源
reClean 的重复上传会触发 md5 去重,可能出现 data=null,即无需再次解析。reClean 的请求会触发重新清洗。章节来源
E2E 文档记录:损坏 xlsx(伪造内容)时,job 应为 SKIP,llm=0,不会拖垮整个批次。这是 E2E 验收的关键容错点。
章节来源
HeaderScorerTest 相关断言。AiTemplateMatcherTest 的指纹、评分、模型兜底。AiTemplateMatchEdgeTest。AiCleanSupportTest。GlobalCache 是否被其他测试污染:确认 @BeforeEach/@AfterEach 中的 clearForTesting() 生效。章节来源
CASE_ID 是否为期望值;文档锚定 A=16/B=17,脚本默认 CASE_ID=20。/auth/login 和 /case/open 返回 200。upload_code、upload_message、upload、sheets。/aiClean/smartClean/status 的 stage、failed_count、need_review_count。ai_clean_job:matched_by、exit_code、exit、llm_calls、fail_reason。ai_clean_batch:stage、loaded_rows、rejected_rows、self_built_count。ai_clean_template:模板 headers、status、confidence、match_tier。target/aitest_*.py 和 target/aitest/*.json,确认是哪一批次、哪个 sheet、哪个 job 失败。章节来源
推荐顺序:
target/aitest_*.py 和 target/aitest/*.json 汇总。章节来源
这套测试体系的核心价值在于:
target/aitest_*.py 和 target/aitest/*.json。passWithNoTests=true 支持渐进式补充。新增测试时,建议遵循“先确定性、再 E2E、再全量覆盖”的顺序,并始终关注:同表头是否零模型、出口 A 是否过闸、模型幻觉是否被兜住、E2E 结果是否可回溯。