本文引用的文件
本设计文档聚焦 AI 数据清洗链路中的数据库层,围绕以下目标展开:
本次分析涉及的数据库定义全部位于 sql 目录下,采用“按业务域拆分 SQL 脚本”的组织方式:
ai_clean_synonym_init.sql:创建并初始化同义词库。
graph TB
A["sql/ai_clean.sql<br/>AI 清洗主表"] --> B["ai_clean_template<br/>AI 清洗模板"]
A --> C["ai_clean_field<br/>模板字段"]
A --> D["ai_clean_rule<br/>清洗规则快照"]
A --> E["ai_clean_job<br/>清洗任务"]
A --> F["ai_clean_batch<br/>清洗批次"]
A --> G["ai_clean_synonym<br/>同义词库"]
H["sql/ai_clean_field_short_names.sql<br/>字段短名迁移"] --> C
I["sql/ai_clean_row_stats.sql<br/>行级统计扩展"] --> E
I --> F
J["sql/ai_clean_synonym_init.sql<br/>同义词建表+初始化"] --> G
图表来源
章节来源
本节从数据类型、主外键、索引和业务约束角度,梳理 AI 清洗相关表。
ai_clean_template:AI 清洗模板,替代既有 table_info 在 AI 链路中的作用,避免污染既有匹配器。
ai_clean_field:模板字段,既是动态表 DDL 真源,也是前端列表头真源。
索引:idx_ai_clean_field_tpl。
erDiagram
AI_CLEAN_TEMPLATE {
bigint id PK
varchar table_name_cn
varchar table_name_en
varchar headers
varchar header_md5 UK
integer header_line_no
text func_regex
integer block_no
text struct_ops
integer needs_struct
varchar category
varchar category_l2
integer main_ref_template_id
varchar match_tier
varchar status
integer ver
numeric confidence
bigint create_by
timestamp create_time
timestamp update_time
}
AI_CLEAN_FIELD {
bigint id PK
bigint ai_template_id FK
varchar column_name
varchar field_name_cn
varchar field_name_en
varchar field_type
integer required
integer field_len
integer field_sort
text direction_conf
integer col_index
integer matched
timestamp create_time
}
AI_CLEAN_TEMPLATE ||--o{ AI_CLEAN_FIELD : "包含"
图表来源
章节来源
章节来源
ai_clean_job:清洗任务记录,承担幂等游标、状态线和成本埋点。
ai_clean_batch:融合入口状态机与幂等锚点。
索引:uk_ai_clean_batch、idx_ai_clean_batch_stage。
flowchart TD
Start(["上传并创建批次"]) --> CreateBatch["插入 ai_clean_batch<br/>stage=JUDGING"]
CreateBatch --> Judge["判定 sheet 是否命中既有模板"]
Judge -->|命中| LoadExisting["走既有模板加载"]
Judge -->|未命中| AiJudge["AI 判定并生成模板"]
AiJudge --> LoadAI["按出口 B 入库"]
LoadExisting --> UpdateJob["写入 ai_clean_job<br/>exit_code=A/A2/A3"]
LoadAI --> UpdateJob
UpdateJob --> Stats["更新 row_total/loaded/rejected/warned/unprocessed"]
Stats --> Done["batch.stage=DONE/PARTIAL"]
图表来源
章节来源
章节来源
ai_clean_field_short_names.sql:
ai_clean_row_stats.sql:
章节来源
AI 清洗链路在数据库层面的职责划分如下:
ai_clean_synonym:支撑表头评分与绑定域的标准化,不影响模板指纹。
graph LR
Upload["上传文件"] --> Batch["ai_clean_batch"]
Batch --> Job["ai_clean_job"]
Job --> Template["ai_clean_template"]
Job --> Rule["ai_clean_rule"]
Template --> Field["ai_clean_field"]
Job --> Synonym["ai_clean_synonym"]
图表来源
章节来源
matched 作为 AI 内部证据位,两采样不一致时置 0,不作为打分证据。
classDiagram
class AiCleanField {
+long id
+long aiTemplateId
+string columnName
+string fieldNameCn
+string fieldNameEn
+string fieldType
+int required
+int fieldLen
+int fieldSort
+String directionConf
+int colIndex
+int matched
+timestamp createTime
}
图表来源
章节来源
章节来源
章节来源
章节来源
章节来源
ai_clean_synonym 不直接被表间外键约束,但被评分与绑定域逻辑消费。
graph TB
Template["ai_clean_template"] --> Field["ai_clean_field"]
Template --> Rule["ai_clean_rule"]
Template --> Job["ai_clean_job"]
Rule --> Job
Batch["ai_clean_batch"] --> Job
Synonym["ai_clean_synonym"] -.-> Job
图表来源
章节来源
结合表结构与注释,可抽象出以下数据流阶段:
sequenceDiagram
participant Client as "客户端"
participant Service as "清洗服务"
participant DB as "数据库"
participant Model as "AI 模型"
Client->>Service: 提交文件并选择智能清洗
Service->>DB: 创建 ai_clean_batch(stage=JUDGING)
Service->>DB: 读取 ai_clean_synonym
Service->>Service: 表头评分与绑定域归一
Service->>DB: 按 header_md5 查询 ai_clean_template
alt 命中既有模板
Service->>DB: 读取 ai_clean_field/ai_clean_rule
Service->>DB: 写入 ai_clean_job(exit_code=A/A2/A3)
else 未命中
Service->>Model: 请求 AI 判定与生成模板
Model-->>Service: 返回模板、字段、规则
Service->>DB: 插入 ai_clean_template/field/rule
Service->>DB: 写入 ai_clean_job(exit_code=B)
end
Service->>DB: 更新 row_total/loaded/rejected/warned/unprocessed
Service->>DB: 更新 ai_clean_batch(stage=DONE/PARTIAL)
Service-->>Client: 返回 batch_id 与状态
图表来源
[本节为通用实践建议,不直接分析具体文件]
查询某案件下所有清洗任务状态:
SELECT
id,
case_id,
file_id,
sheet_id,
block_no,
ver,
status,
exit_code,
matched_by,
match_tier,
row_total,
row_loaded,
row_rejected,
row_warned,
row_unprocessed,
fail_reason,
create_time,
update_time
FROM ai_clean_job
WHERE case_id = ?
ORDER BY create_time DESC;
查询某个文件的所有清洗任务:
SELECT *
FROM ai_clean_job
WHERE file_id = ?
ORDER BY create_time DESC;
章节来源
按任务状态聚合行数:
SELECT
status,
count(*) AS job_count,
sum(row_total) AS total_rows,
sum(row_loaded) AS loaded_rows,
sum(row_rejected) AS rejected_rows,
sum(row_warned) AS warned_rows,
sum(row_unprocessed) AS unprocessed_rows
FROM ai_clean_job
GROUP BY status;
按批次聚合统计:
SELECT
stage,
file_count,
sheet_total,
matched_count,
ai_judged_count,
existing_hit_count,
ai_load_count,
loaded_rows,
rejected_rows,
unprocessed_rows,
self_built_count,
need_review_count,
failed_count
FROM ai_clean_batch
WHERE case_id = ?
ORDER BY create_time DESC;
章节来源
查询在线模板:
SELECT id, table_name_cn, table_name_en, headers, header_md5,
status, ver, confidence, category, category_l2
FROM ai_clean_template
WHERE status = 'ONLINE'
ORDER BY update_time DESC;
根据表头指纹查找模板:
SELECT id, table_name_cn, table_name_en, status, ver, confidence
FROM ai_clean_template
WHERE header_md5 = ?;
查询模板字段:
SELECT
id,
column_name,
field_name_cn,
field_name_en,
field_type,
required,
field_len,
field_sort,
col_index,
matched
FROM ai_clean_field
WHERE ai_template_id = ?
ORDER BY field_sort ASC;
查询模板规则快照:
SELECT id, col_index, field_name_en, hints, ref_template_id, ver
FROM ai_clean_rule
WHERE ai_template_id = ?
ORDER BY col_index ASC;
章节来源
查询启用的同义词:
SELECT std_word, alias_word, remark
FROM ai_clean_synonym
WHERE status = 1
ORDER BY std_word, alias_word;
新增同义词(忽略冲突):
INSERT INTO ai_clean_synonym (std_word, alias_word, remark, status)
VALUES (?, ?, ?, 1)
ON CONFLICT (std_word, alias_word) DO NOTHING;
停用同义词:
UPDATE ai_clean_synonym
SET status = 0, update_time = current_timestamp
WHERE std_word = ? AND alias_word = ?;
章节来源
章节来源
AI 数据清洗链路通过独立的模板、字段、规则、任务、批次与同义词表,实现了与既有匹配器的解耦、可观测的任务状态、可追溯的模型调用成本,以及可扩展的清洗规则。header_md5 的零模型重放、job 幂等唯一键、batch 幂等唯一键共同保障批量清洗的可重复性与稳定性。同义词库在不破坏指纹的前提下提升表头评分准确率。建议在部署时优先执行 ai_clean.sql,再按需执行字段短名与行级统计迁移脚本,并维护 ai_clean_synonym_init.sql 的内置词条。