# 指标公式检查功能 - 快速指南

## 🎯 功能简介

指标公式检查功能用于解析和验证数据指标的计算公式，自动提取公式中的变量并在Neo4j数据库中查找匹配的元数据记录。

**核心价值**:
- ✅ 自动验证指标公式中的变量是否已定义
- ✅ 提前发现数据质量问题
- ✅ 建立数据血缘关系
- ✅ 辅助用户正确定义指标

## 🚀 快速开始

### 1. API调用示例

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

### 2. 响应示例

```json
{
  "code": 200,
  "message": "success",
  "data": [
    {
      "variable": "单价",
      "name_zh": "单价",
      "name_en": "unit_price",
      "id": 101,
      "create_time": "2024-01-15 10:00:00",
      "findit": 1
    },
    {
      "variable": "数量",
      "name_zh": "数量",
      "name_en": "quantity",
      "id": 102,
      "create_time": "2024-01-15 10:01:00",
      "findit": 1
    }
  ]
}
```

## 📋 功能特性

### 支持的运算符
- ➕ 加法 `+`
- ➖ 减法 `-`
- ✖️ 乘法 `*`
- ➗ 除法 `/`
- 📐 括号 `()`, `（）`, `[]`, `{}`

### 智能识别
- 🔤 自动识别中文变量
- 🔢 自动过滤数字
- 🔄 自动去除重复变量
- 🎯 模糊匹配元数据

## 📂 文件结构

```
DataOps-platform/
├── app/
│   ├── core/
│   │   └── data_metric/
│   │       └── metric_interface.py      # 核心函数 metric_check
│   └── api/
│       └── data_metric/
│           └── routes.py                 # API接口 /data/metric/check
├── tests/
│   └── test_metric_check.py             # 单元测试
├── docs/
│   ├── api/
│   │   └── metric-check-api.md          # API文档
│   ├── features/
│   │   └── metric-formula-check.md      # 功能文档
│   ├── diagrams/
│   │   └── metric-check-flow.md         # 流程图
│   └── examples/
│       └── metric-check-examples.md     # 使用示例
├── IMPLEMENTATION_SUMMARY.md            # 实现总结
├── IMPLEMENTATION_CHECKLIST.md          # 检查清单
└── README_METRIC_CHECK.md              # 本文件
```

## 💻 使用示例

### Python

```python
import requests

url = "http://localhost:5000/api/data/metric/check"
data = {"formula": "利润率 = (收入 - 成本) / 收入 * 100"}

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

for item in result['data']:
    status = "✓" if item['findit'] == 1 else "✗"
    print(f"{status} {item['variable']}")
```

### JavaScript

```javascript
fetch('http://localhost:5000/api/data/metric/check', {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({
    formula: '销售额 = 单价 * 数量'
  })
})
  .then(res => res.json())
  .then(data => console.log(data));
```

## 📖 详细文档

| 文档 | 内容 | 路径 |
|------|------|------|
| **API文档** | 接口说明、请求/响应格式、错误处理 | `docs/api/metric-check-api.md` |
| **功能文档** | 技术实现、使用场景、扩展建议 | `docs/features/metric-formula-check.md` |
| **流程图** | 架构图、流程图、时序图 | `docs/diagrams/metric-check-flow.md` |
| **使用示例** | 10+个完整示例、集成代码 | `docs/examples/metric-check-examples.md` |
| **实现总结** | 实现概览、技术细节、部署说明 | `IMPLEMENTATION_SUMMARY.md` |
| **检查清单** | 完成项目、质量检查、后续建议 | `IMPLEMENTATION_CHECKLIST.md` |

## 🧪 测试

```bash
# 运行所有测试
python -m pytest tests/test_metric_check.py -v

# 查看测试覆盖率
python -m pytest tests/test_metric_check.py --cov=app.core.data_metric --cov-report=html
```

## 🔧 技术栈

- **语言**: Python 3.8+
- **框架**: Flask 2.3.3+
- **数据库**: Neo4j
- **驱动**: py2neo
- **测试**: pytest, unittest

## 📊 接口信息

| 项目 | 内容 |
|------|------|
| **URL** | `/api/data/metric/check` |
| **方法** | `POST` |
| **Content-Type** | `application/json` |
| **请求参数** | `{"formula": "指标名称 = 计算表达式"}` |
| **响应格式** | JSON数组，包含变量匹配结果 |

## 🎨 应用场景

### 1. 指标创建验证
在用户创建指标时，自动检查公式中的变量是否都已定义。

### 2. 数据质量检查
提前发现未定义的变量，避免指标计算错误。

### 3. 数据血缘分析
了解指标依赖哪些基础元数据，建立数据血缘关系。

### 4. 智能提示
为用户提供变量的详细信息，辅助指标定义。

## 🔍 工作原理

```
输入公式: "销售额 = 单价 * 数量"
    ↓
解析公式: 提取右侧 "单价 * 数量"
    ↓
识别变量: ["单价", "数量"]
    ↓
查询数据库: 在Neo4j中查找DataMeta节点
    ↓
返回结果: [{variable:"单价", findit:1}, {variable:"数量", findit:1}]
```

## ⚡ 性能特性

- ✅ 变量自动去重，避免重复查询
- ✅ 使用 `LIMIT 1` 限制查询结果
- ✅ 批量处理多个变量
- ✅ 使用Neo4j session连接池

## 🛠️ 配置要求

### 环境依赖
- Python 3.8+
- Flask 2.3.3+
- Neo4j数据库
- py2neo库

### 数据库要求
- Neo4j中需要有DataMeta节点
- DataMeta节点需要有以下属性：
  - `name`: 中文名称
  - `en_name`: 英文名称
  - `createTime`: 创建时间

## 📝 返回字段说明

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

## ❓ 常见问题

### Q1: 公式必须包含等号吗？
**A**: 是的，公式必须包含等号，格式为 `指标名称 = 计算表达式`。

### Q2: 支持哪些运算符？
**A**: 支持 `+`, `-`, `*`, `/`, `()`, `（）`, `[]`, `{}` 等常见运算符。

### Q3: 如何处理未找到的变量？
**A**: 未找到的变量会返回 `findit: 0`，前端可以根据此标识提示用户。

### Q4: 是否支持英文变量？
**A**: 目前只识别包含中文字符的变量，纯英文和数字会被过滤。

### Q5: 相同变量出现多次会查询多次吗？
**A**: 不会，系统会自动去重，每个变量只查询一次。

## 🚦 状态码

| 状态码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 参数错误 |
| 500 | 服务器错误 |

## 📞 获取帮助

如有问题或建议，请：
1. 查看详细文档：`docs/` 目录
2. 查看使用示例：`docs/examples/metric-check-examples.md`
3. 运行测试：`pytest tests/test_metric_check.py -v`

## 🔄 版本历史

### v1.0.0 (2024-10-30)
- ✨ 初始版本发布
- ✅ 实现核心功能
- 📚 完成文档编写
- 🧪 编写测试用例

## 📄 许可证

本项目为DataOps平台的一部分，遵循项目统一许可证。

---

**快速导航**:
- [API文档](docs/api/metric-check-api.md)
- [功能文档](docs/features/metric-formula-check.md)
- [使用示例](docs/examples/metric-check-examples.md)
- [实现总结](IMPLEMENTATION_SUMMARY.md)

**更新日期**: 2024-10-30