# 指标公式检查API文档

## API概述

该API用于检查指标计算公式中的变量，并在Neo4j数据库中查找匹配的元数据。

## 接口信息

- **URL**: `/api/data/metric/check`
- **方法**: `POST`
- **Content-Type**: `application/json`

## 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| formula | string | 是 | 指标计算公式文本 |

### 公式格式说明

公式格式为：`指标名称 = 计算表达式`

- 等号左侧：指标名称
- 等号右侧：包含中文变量和数学运算符的计算表达式
- 支持的运算符：`+`、`-`、`*`、`/`、`()`、`（）`、`[]`、`{}`
- 变量：中文字符串或数字
- 只有中文字符串会被识别为需要查找的变量

### 请求示例

```json
{
  "formula": "销售额 = 单价 * 数量 + 运费"
}
```

更复杂的示例：

```json
{
  "formula": "利润率 = (销售收入 - 成本) / 销售收入 * 100"
}
```

## 响应格式

### 成功响应

```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "variable": "单价",
      "name_zh": "单价",
      "name_en": "unit_price",
      "id": 12345,
      "create_time": "2024-01-15 10:30:00",
      "findit": 1
    },
    {
      "variable": "数量",
      "name_zh": "数量",
      "name_en": "quantity",
      "id": 12346,
      "create_time": "2024-01-15 10:31:00",
      "findit": 1
    },
    {
      "variable": "运费",
      "name_zh": "",
      "name_en": "",
      "id": null,
      "create_time": "",
      "findit": 0
    }
  ]
}
```

### 响应字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| variable | string | 从公式中提取的变量名 |
| name_zh | string | 匹配到的元数据中文名称（未找到时为空字符串） |
| name_en | string | 匹配到的元数据英文名称（未找到时为空字符串） |
| id | integer/null | 匹配到的元数据节点ID（未找到时为null） |
| create_time | string | 匹配到的元数据创建时间（未找到时为空字符串） |
| findit | integer | 是否找到匹配：1表示找到，0表示未找到 |

### 错误响应

#### 参数错误

```json
{
  "code": 400,
  "message": "failed",
  "data": {},
  "error": {
    "error": "公式文本不能为空"
  }
}
```

#### 公式格式错误

```json
{
  "code": 400,
  "message": "failed",
  "data": {},
  "error": {
    "error": "公式格式错误：缺少等号"
  }
}
```

#### 服务器错误

```json
{
  "code": 500,
  "message": "failed",
  "data": {},
  "error": {
    "error": "具体错误信息"
  }
}
```

## 功能说明

### 变量提取规则

1. 公式以等号（`=`）分割，只处理等号右侧的计算表达式
2. 按照数学运算符分割表达式，提取所有token
3. 只保留包含中文字符的token作为变量
4. 数字会被自动过滤掉
5. 相同的变量会去重，每个变量只查询一次

### 元数据匹配规则

1. 使用模糊匹配（CONTAINS）在Neo4j的DataMeta节点中查找
2. 匹配字段为节点的`name`属性
3. 每个变量只返回第一个匹配的结果
4. 如果没有找到匹配，`findit`字段设置为0

## 使用场景

1. **指标定义验证**：在创建或编辑指标时，验证公式中的变量是否存在于元数据库中
2. **数据血缘分析**：了解指标依赖哪些元数据
3. **数据质量检查**：发现公式中引用但未在元数据库中定义的变量

## 示例代码

### Python (requests)

```python
import requests
import json

url = "http://your-server/api/data/metric/check"
headers = {"Content-Type": "application/json"}
data = {
    "formula": "销售额 = 单价 * 数量 + 运费"
}

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

print(json.dumps(result, indent=2, ensure_ascii=False))
```

### JavaScript (fetch)

```javascript
const url = 'http://your-server/api/data/metric/check';
const data = {
  formula: '销售额 = 单价 * 数量 + 运费'
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.error('Error:', error));
```

### cURL

```bash
curl -X POST http://your-server/api/data/metric/check \
  -H "Content-Type: application/json" \
  -d '{"formula": "销售额 = 单价 * 数量 + 运费"}'
```

## 注意事项

1. 公式必须包含等号（`=`），否则会返回错误
2. 变量名必须包含中文字符才会被识别
3. 元数据匹配使用模糊匹配，可能会匹配到相似的名称
4. 数据库连接失败时会返回空数组
5. 相同的变量名只会查询一次并返回一个结果

## 更新历史

- **2025-10-30**: 初始版本创建