# 元数据新增接口优化文档

## 优化时间
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：冗余检测逻辑调整
```python
# 旧代码：检测到疑似重复时直接返回失败
if redundancy_result["review_created"]:
    return jsonify(failed("发现疑似重复元数据，已创建审核记录..."))

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

#### 变更点 2：节点创建后处理疑似重复
```python
# 节点创建成功后
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` 字段

```python
# 旧代码
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

```python
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` - 审核记录数据模型