# 数据指标删除接口文档

## API 接口

### 删除数据指标

**接口路径**: `/api/data_metric/delete`

**请求方法**: `POST`

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| id | Integer | 是 | 指标节点ID |

**请求示例**:

```json
{
  "id": 1378
}
```

**响应格式**:

成功响应：
```json
{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "id": 1378,
    "message": "成功删除数据指标节点 (ID: 1378)"
  }
}
```

失败响应（节点不存在）：
```json
{
  "code": 500,
  "msg": "数据指标节点不存在 (ID: 1378)",
  "data": {
    "id": 1378,
    "message": "数据指标节点不存在 (ID: 1378)"
  }
}
```

失败响应（参数错误）：
```json
{
  "code": 500,
  "msg": {
    "error": "指标ID不能为空"
  },
  "data": {}
}
```

## 核心功能

### metric_delete 函数

**位置**: `app/core/data_metric/metric_interface.py`

**函数签名**:
```python
def metric_delete(metric_node_id: int) -> dict:
    """
    删除数据指标节点及其所有关联关系
    
    Args:
        metric_node_id: 指标节点ID
        
    Returns:
        dict: 删除结果，包含 success 状态和 message 信息
    """
```

**功能说明**:
1. 连接 Neo4j 图数据库
2. 检查指定ID的 DataMetric 节点是否存在
3. 使用 `DETACH DELETE` 删除节点及其所有关联关系
4. 返回删除结果状态

**返回值结构**:
```python
{
    "success": True/False,  # 删除是否成功
    "message": "状态信息"    # 详细的状态描述
}
```

## 删除机制

### Cypher 查询

**检查节点存在**:
```cypher
MATCH (n:DataMetric)
WHERE id(n) = $nodeId
RETURN n
```

**删除节点和关系**:
```cypher
MATCH (n:DataMetric)
WHERE id(n) = $nodeId
DETACH DELETE n
RETURN count(n) as deleted_count
```

### DETACH DELETE 说明

`DETACH DELETE` 是 Neo4j 的关键字，功能包括：
1. 自动删除节点的所有传入关系（incoming relationships）
2. 自动删除节点的所有传出关系（outgoing relationships）
3. 删除节点本身

这意味着不需要手动遍历和删除关系，一条语句即可完成。

## 删除的关系类型

根据 DataMetric 节点的关系模型，删除时会自动清理以下关系：

| 关系类型 | 方向 | 目标节点 | 说明 |
|---------|------|---------|------|
| origin | 传出 | DataModel / DataMetric | 指标来源 |
| connection | 传出 | DataMeta | 元数据连接 |
| LABEL | 传出 | DataLabel | 数据标签 |
| child | 传出/传入 | DataMetric | 父子关系 |

## 错误处理

### 异常情况

1. **数据库连接失败**
   - 返回: `{"success": False, "message": "无法连接到数据库"}`
   - HTTP 状态: 500

2. **节点不存在**
   - 返回: `{"success": False, "message": "数据指标节点不存在 (ID: xxx)"}`
   - HTTP 状态: 500

3. **参数错误**
   - 缺少 ID: `{"error": "指标ID不能为空"}`
   - 无效 ID: `{"error": "指标ID必须为整数"}`
   - HTTP 状态: 500

4. **删除异常**
   - 返回: `{"success": False, "message": "删除失败: [错误详情]"}`
   - HTTP 状态: 500

## 使用示例

### Python 请求示例

```python
import requests
import json

url = "http://localhost:5500/api/data_metric/delete"
headers = {"Content-Type": "application/json"}
data = {"id": 1378}

response = requests.post(url, headers=headers, json=data)
result = response.json()

if result["code"] == 200:
    print(f"删除成功: {result['data']['message']}")
else:
    print(f"删除失败: {result['msg']}")
```

### cURL 请求示例

```bash
curl -X POST http://localhost:5500/api/data_metric/delete \
  -H "Content-Type: application/json" \
  -d '{"id": 1378}'
```

### JavaScript/Fetch 示例

```javascript
fetch('http://localhost:5500/api/data_metric/delete', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ id: 1378 })
})
.then(response => response.json())
.then(data => {
  if (data.code === 200) {
    console.log('删除成功:', data.data.message);
  } else {
    console.log('删除失败:', data.msg);
  }
})
.catch(error => console.error('请求错误:', error));
```

## 日志记录

删除操作会在以下情况记录日志：

| 日志级别 | 场景 | 日志内容 |
|---------|------|---------|
| ERROR | 数据库连接失败 | "无法连接到数据库" |
| WARNING | 节点不存在 | "数据指标节点不存在: ID={id}" |
| INFO | 删除成功 | "成功删除数据指标节点: ID={id}" |
| WARNING | 删除失败 | "删除失败，节点可能已被删除: ID={id}" |
| ERROR | 异常错误 | "删除数据指标节点失败: {错误详情}" |

## 注意事项

⚠️ **重要提示**:

1. **不可恢复**: 删除操作是永久性的，无法撤销
2. **级联影响**: 删除会清除所有关联关系，可能影响其他节点的关系结构
3. **权限控制**: 建议在生产环境中添加权限验证
4. **审计日志**: 建议记录删除操作的审计信息（操作人、时间等）
5. **业务验证**: 删除前应检查是否有其他业务逻辑依赖此节点

## 最佳实践

1. **删除前确认**: 在前端添加二次确认对话框
2. **批量删除**: 如需批量删除，建议在循环中调用，并记录每次结果
3. **事务管理**: 当前实现使用单次会话，确保原子性
4. **错误通知**: 删除失败时应通知用户具体原因
5. **软删除**: 对于重要数据，考虑实现软删除（标记而不是物理删除）

## 测试建议

### 单元测试场景

1. 测试删除存在的节点
2. 测试删除不存在的节点
3. 测试无效的节点ID（非整数、null等）
4. 测试数据库连接失败的情况
5. 测试删除后关系是否被清理

### 集成测试场景

1. 创建节点 -> 删除节点 -> 验证删除
2. 创建带关系的节点 -> 删除节点 -> 验证关系被清理
3. 验证删除后其他相关节点的状态

## 版本历史

| 版本 | 日期 | 变更说明 |
|------|------|---------|
| 1.0 | 2025-11-03 | 初始版本，实现基本删除功能 |

## 相关接口

- `POST /api/data_metric/add` - 新增数据指标
- `POST /api/data_metric/update` - 更新数据指标
- `POST /api/data_metric/detail` - 查询指标详情
- `POST /api/data_metric/list` - 指标列表查询