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

🎯 功能简介

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

核心价值:

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

🚀 快速开始

1. API调用示例

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

2. 响应示例

{
  "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

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

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`

🧪 测试

# 运行所有测试
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	服务器错误

📞 获取帮助

如有问题或建议，请：

查看详细文档：docs/ 目录
查看使用示例：docs/examples/metric-check-examples.md
运行测试：pytest tests/test_metric_check.py -v

🔄 版本历史

v1.0.0 (2024-10-30)

✨ 初始版本发布
✅ 实现核心功能
📚 完成文档编写
🧪 编写测试用例

📄 许可证

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

快速导航:

更新日期: 2024-10-30

README_METRIC_CHECK.md 7.3 KB Historik Rå