DataOps-platform/docs/meta_data_add_optimization.md

元数据新增接口优化文档

优化时间

2026-01-12

优化目标

优化 meta_node_add 接口的冗余检测和处理逻辑，改进疑似重复元数据的处理流程。

优化内容

1. 完全匹配处理（保持不变）

• 行为：如果检测到完全匹配的元数据（name_zh、name_en、data_type、tag_ids 全部相同）
• 操作：直接返回失败提示，不创建任何节点
• 返回信息：提示元数据已存在，返回已存在的元数据ID

2. 疑似重复处理（优化重点）

• 旧逻辑：

  • 检测到疑似重复 → 立即创建审核记录 → 返回失败，不创建节点
  • 用户需要使用 force_create=true 强制创建

• 新逻辑：

  • 检测到疑似重复 → 先创建新元数据节点 → 创建审核记录（包含新节点ID和疑似重复候选） → 返回成功，提示前往审核页面处理
  • 新元数据节点已创建，用户可以立即使用
  • 审核记录中包含新创建的节点ID和所有疑似重复的候选元数据

3. 无重复处理（保持不变）

• 行为：未检测到任何重复
• 操作：直接创建新节点，正常返回

代码变更

1. app/api/meta_data/routes.py - meta_node_add 函数

变更点 1：冗余检测逻辑调整

# 旧代码：检测到疑似重复时直接返回失败
if redundancy_result["review_created"]:
    return jsonify(failed("发现疑似重复元数据，已创建审核记录..."))

# 新代码：检测到疑似重复时标记状态，继续创建节点
if redundancy_result["has_candidates"]:
    has_suspicious_duplicates = True
    suspicious_candidates = redundancy_result["candidates"]

变更点 2：节点创建后处理疑似重复

# 节点创建成功后
if has_suspicious_duplicates and suspicious_candidates:
    # 构建新元数据快照（包含新创建的节点ID）
    new_meta_snapshot = {
        "id": node_data["id"],  # 新创建的节点ID
        "name_zh": node_name_zh,
        "name_en": node_name_en or "",
        "data_type": node_type,
        "tag_ids": tag_ids,
    }
    
    # 写入审核记录
    write_redundancy_review_record_with_new_id(
        new_meta=new_meta_snapshot,
        candidates=suspicious_candidates,
        source="api",
    )
    
    # 返回成功，但提示疑似重复
    return jsonify(success(node_data, message="元数据创建成功，但发现疑似重复..."))

2. app/core/meta_data/redundancy_check.py

变更点 1：check_redundancy_for_add 函数

• 旧逻辑：检测到疑似重复时自动创建审核记录
• 新逻辑：只进行检测，返回候选列表，不创建审核记录
• 返回值变化：移除 review_created 字段

# 旧代码
write_redundancy_review_record(new_meta, candidates, source="api")
return {
    "has_exact_match": False,
    "exact_match_id": None,
    "has_candidates": True,
    "candidates": candidates,
    "review_created": True,  # 已创建审核记录
}

# 新代码
return {
    "has_exact_match": False,
    "exact_match_id": None,
    "has_candidates": True,
    "candidates": candidates,  # 只返回候选列表，不创建审核记录
}

变更点 2：新增 write_redundancy_review_record_with_new_id 函数

• 用途：在新元数据节点已创建后写入审核记录
• 与原函数的区别：new_meta 参数中包含已创建的节点ID

def write_redundancy_review_record_with_new_id(
    new_meta: Dict[str, Any],  # 包含已创建的节点ID
    candidates: List[Dict[str, Any]],
    source: str = "api",
) -> None:
    """
    写入疑似冗余审核记录到 PostgreSQL（新元数据已创建，包含ID）
    """
    # 实现逻辑与 write_redundancy_review_record 相同
    # 区别在于 new_meta 中包含 id 字段

业务流程对比

旧流程

用户提交新增请求
  ↓
冗余检测
  ↓
发现疑似重复
  ↓
创建审核记录（不包含新节点ID）
  ↓
返回失败，提示使用 force_create=true
  ↓
用户需要再次提交请求（force_create=true）
  ↓
创建节点

新流程

用户提交新增请求
  ↓
冗余检测
  ↓
发现疑似重复
  ↓
创建新元数据节点
  ↓
创建审核记录（包含新节点ID + 疑似重复候选）
  ↓
返回成功，提示前往审核页面
  ↓
用户可以立即使用新节点，同时在审核页面处理重复问题

优势分析

1. 用户体验改善

• 旧方式：需要两次操作（第一次失败 → 强制创建）
• 新方式：一次操作即可完成，节点立即可用

2. 审核记录更完整

• 旧方式：审核记录中 new_meta 没有 ID，无法直接定位新创建的节点
• 新方式：审核记录中包含新节点ID，便于后续处理（如合并、删除等）

3. 业务连续性

• 旧方式：发现疑似重复时，业务流程被中断
• 新方式：业务流程不中断，新节点立即可用，审核可以异步处理

4. 灵活的后续处理

审核人员可以根据实际情况选择：

• 如果确认是重复：删除新节点，使用已有节点
• 如果确认不重复：标记审核记录为已处理，保留新节点
• 如果需要合并：合并新旧节点，更新关联关系

注意事项

1. force_create 参数保留：仍然支持 force_create=true 跳过冗余检测
2. 完全匹配仍然拦截：如果是完全匹配，仍然不创建新节点
3. 审核记录格式兼容：新的审核记录格式与旧格式兼容，只是 new_meta 中多了 id 字段
4. 数据库事务：审核记录写入失败不影响节点创建（已在 try-catch 外）

测试建议

测试场景 1：完全匹配

• 输入：与已有元数据完全相同的数据
• 预期：返回失败，提示元数据已存在，不创建新节点

测试场景 2：疑似重复

• 输入：name_zh 相同但其他字段不同的数据
• 预期：创建新节点，创建审核记录，返回成功并提示疑似重复

测试场景 3：无重复

• 输入：完全新的元数据
• 预期：创建新节点，不创建审核记录，正常返回

测试场景 4：强制创建

• 输入：force_create=true
• 预期：跳过冗余检测，直接创建节点

相关文件

• app/api/meta_data/routes.py - API 路由层
• app/core/meta_data/redundancy_check.py - 冗余检测核心逻辑
• app/models/metadata_review.py - 审核记录数据模型