# DataOps Platform 代码说明文档

> 本文档为 DataOps Platform 的技术说明文档，涵盖系统架构、模块设计、API 接口及数据结构说明。

---

## 目录

1. [项目概述](#1-项目概述)
2. [系统架构图](#2-系统架构图)
3. [技术栈](#3-技术栈)
4. [目录结构](#4-目录结构)
5. [核心模块说明](#5-核心模块说明)
6. [API 接口说明](#6-api-接口说明)
7. [数据流程图](#7-数据流程图)
8. [统一响应格式](#8-统一响应格式)
9. [配置说明](#9-配置说明)

---

## 1. 项目概述

DataOps Platform 是一个基于 Flask 的数据运营管理平台，用于数据管理、处理和分析。平台集成了图数据库 Neo4j 用于元数据管理、MinIO 用于文件存储、PostgreSQL 用于关系型数据存储，并集成 LLM（大语言模型）能力用于智能解析和代码生成。

### 核心功能

- **元数据管理**：管理和维护数据元信息
- **业务领域管理**：定义和管理业务领域及其关联关系
- **数据源管理**：数据源连接配置、验证和管理
- **数据流管理**：数据流程的定义、执行和监控
- **数据接口管理**：数据标准和标签的管理
- **图谱操作**：Neo4j 图数据库操作
- **系统管理**：用户认证、健康检查和配置管理

---

## 2. 系统架构图

```
┌─────────────────────────────────────────────────────────────────────────┐
│                              前端应用层                                  │
│                        (Vue.js / React 等)                               │
└───────────────────────────────┬─────────────────────────────────────────┘
                                │ HTTP/RESTful API
                                ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                            Flask 应用层                                  │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        API 蓝图层 (Blueprints)                    │   │
│  │  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │   │
│  │  │ /api/meta│ │ /api/bd  │ │/api/data │ │/api/data │ │/api/   │ │   │
│  │  │          │ │          │ │ source   │ │  flow    │ │ graph  │ │   │
│  │  └──────────┘ └──────────┘ └──────────┘ └──────────┘ └────────┘ │   │
│  │  ┌──────────┐ ┌────────────────────────────────────────────────┐ │   │
│  │  │/api/     │ │            /api/system                         │ │   │
│  │  │interface │ │  (健康检查/配置/认证)                            │ │   │
│  │  └──────────┘ └────────────────────────────────────────────────┘ │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                   │                                     │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        Core 核心业务层                            │   │
│  │  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────────────┐ │   │
│  │  │ meta_data │ │ business_ │ │ data_flow │ │ data_processing   │ │   │
│  │  │           │ │ domain    │ │           │ │ (validator/cleaner)│ │   │
│  │  └───────────┘ └───────────┘ └───────────┘ └───────────────────┘ │   │
│  │  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────────────┐ │   │
│  │  │   graph   │ │    llm    │ │ data_     │ │    common         │ │   │
│  │  │ operations│ │ (解析/生成)│ │ interface │ │  (通用函数)        │ │   │
│  │  └───────────┘ └───────────┘ └───────────┘ └───────────────────┘ │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                   │                                     │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        Services 服务层                            │   │
│  │  ┌────────────────┐ ┌─────────────────┐ ┌─────────────────────┐  │   │
│  │  │ neo4j_driver   │ │ db_healthcheck  │ │ package_function    │  │   │
│  │  └────────────────┘ └─────────────────┘ └─────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────────────┘   │
│                                   │                                     │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │                        Models 模型层                              │   │
│  │  ┌────────────────────────────────────────────────────────────┐  │   │
│  │  │  result.py (统一响应格式: success/failed/json_response)     │  │   │
│  │  └────────────────────────────────────────────────────────────┘  │   │
│  └─────────────────────────────────────────────────────────────────┘   │
└───────────────────────────────────┬─────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                            数据存储层                                    │
│  ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────────┐    │
│  │    Neo4j        │ │   PostgreSQL    │ │       MinIO             │    │
│  │  (图数据库)     │ │  (关系型数据库)  │ │    (对象存储)           │    │
│  │                 │ │                 │ │                         │    │
│  │ • 元数据节点    │ │ • 用户数据      │ │ • SQL 文件              │    │
│  │ • 业务领域      │ │ • 日历记录      │ │ • 文档文件              │    │
│  │ • 数据源        │ │ • 数据流日志    │ │ • 上传资源              │    │
│  │ • 标签关系      │ │                 │ │                         │    │
│  └─────────────────┘ └─────────────────┘ └─────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
                                    │
                                    ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                            外部服务层                                    │
│  ┌─────────────────────┐ ┌─────────────────────────────────────────┐    │
│  │    LLM API          │ │            Airflow                      │    │
│  │  (通义千问/Qwen)    │ │       (工作流调度)                       │    │
│  └─────────────────────┘ └─────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## 3. 技术栈

| 类别 | 技术 | 版本要求 |
|------|------|---------|
| 后端框架 | Flask | 2.3.3+ |
| ORM | SQLAlchemy | 2.0+ |
| 图数据库 | Neo4j | 4.0+ |
| 关系数据库 | PostgreSQL | 13+ |
| 对象存储 | MinIO | - |
| LLM | 通义千问 (Qwen) | - |
| 语言 | Python | 3.8+ |

---

## 4. 目录结构

```
DataOps-platform-new/
├── app/                              # 主应用目录
│   ├── __init__.py                   # Flask 应用工厂
│   ├── api/                          # API 蓝图模块
│   │   ├── business_domain/          # 业务领域 API
│   │   │   ├── __init__.py
│   │   │   └── routes.py             # 路由定义
│   │   ├── data_flow/                # 数据流 API
│   │   ├── data_interface/           # 数据接口 API
│   │   ├── data_source/              # 数据源 API
│   │   ├── graph/                    # 图操作 API
│   │   ├── meta_data/                # 元数据 API
│   │   └── system/                   # 系统 API
│   ├── config/                       # 配置模块
│   │   ├── config.py                 # 主配置文件
│   │   └── cors.py                   # CORS 配置
│   ├── core/                         # 核心业务逻辑
│   │   ├── business_domain/          # 业务领域逻辑
│   │   ├── common/                   # 通用函数
│   │   ├── data_flow/                # 数据流逻辑
│   │   ├── data_interface/           # 数据接口逻辑
│   │   ├── data_processing/          # 数据处理 (验证/清洗)
│   │   ├── graph/                    # 图操作逻辑
│   │   ├── llm/                      # LLM 服务
│   │   ├── meta_data/                # 元数据逻辑
│   │   └── system/                   # 系统逻辑
│   ├── models/                       # 数据模型
│   │   └── result.py                 # 统一响应格式
│   ├── scripts/                      # 数据库脚本
│   └── services/                     # 服务层
│       ├── neo4j_driver.py           # Neo4j 驱动
│       └── db_healthcheck.py         # 数据库健康检查
├── database/                         # 数据库 SQL 脚本
├── docs/                             # 文档目录
├── mcp-servers/                      # MCP 服务器
├── tests/                            # 测试目录
├── application.py                    # 应用入口
├── requirements.txt                  # Python 依赖
└── README.md                         # 项目说明
```

---

## 5. 核心模块说明

### 5.1 应用初始化模块 (`app/__init__.py`)

Flask 应用工厂模式实现，主要功能：

1. **创建应用实例**：加载配置并初始化 Flask 应用
2. **注册蓝图**：注册所有 API 蓝图
3. **配置 CORS**：跨域资源共享配置
4. **配置日志**：应用日志记录
5. **全局异常处理**：统一的错误响应处理

```python
# 蓝图注册路径
/api/meta       -> 元数据接口
/api/bd         -> 业务领域接口
/api/datasource -> 数据源接口
/api/dataflow   -> 数据流接口
/api/interface  -> 数据接口
/api/graph      -> 图操作接口
/api/system     -> 系统接口
```

### 5.2 统一响应模块 (`app/models/result.py`)

提供标准化的 API 响应格式：

```python
# 成功响应
def success(data=None, message="操作成功", code=200):
    return {"code": code, "message": message, "data": data}

# 失败响应
def failed(message="操作失败", code=500, data=None, error=None):
    return {"code": code, "message": message, "data": data, "error": error}
```

### 5.3 Neo4j 驱动模块 (`app/services/neo4j_driver.py`)

图数据库连接管理，采用单例模式：

- **延迟初始化**：避免模块导入时的上下文问题
- **连接验证**：提供连接可用性检查
- **会话管理**：提供 Neo4j 会话获取接口

### 5.4 图操作模块 (`app/core/graph/graph_operations.py`)

核心图数据库操作：

| 函数 | 功能 |
|------|------|
| `connect_graph()` | 连接 Neo4j 数据库 |
| `create_or_get_node()` | 创建或更新节点 |
| `create_relationship()` | 创建节点关系 |
| `get_subgraph()` | 获取子图数据 |
| `execute_cypher_query()` | 执行 Cypher 查询 |
| `relationship_exists()` | 检查关系是否存在 |

---

## 6. API 接口说明

### 6.1 系统接口 (`/api/system`)

| 接口路径 | 方法 | 描述 |
|----------|------|------|
| `/health` | GET | 系统健康检查 |
| `/config` | GET | 获取系统配置 |
| `/info` | GET | 获取系统运行信息 |
| `/config/validate` | GET | 验证配置有效性 |
| `/auth/register` | POST | 用户注册 |
| `/auth/login` | POST | 用户登录 |
| `/auth/user/<username>` | GET | 获取用户信息 |
| `/translate` | POST | 翻译节点名称 |

#### 用户登录接口

**请求参数：**
```json
{
  "username": "string (必填)",
  "password": "string (必填)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "user_id": "integer",
    "username": "string",
    "token": "string"
  }
}
```

---

### 6.2 业务领域接口 (`/api/bd`)

| 接口路径 | 方法 | 描述 |
|----------|------|------|
| `/list` | POST | 获取业务领域列表 |
| `/detail` | POST | 获取业务领域详情 |
| `/save` | POST | 保存业务领域 |
| `/update` | POST | 更新业务领域 |
| `/delete` | POST | 删除业务领域 |
| `/upload` | POST | 上传文件 |
| `/download` | GET | 下载文件 |
| `/graphall` | POST | 获取完整关系图谱 |
| `/ddlparse` | POST | 解析 DDL 语句 |
| `/search` | POST | 搜索关联元数据 |
| `/compose` | POST | 组合创建业务领域 |
| `/labellist` | POST | 获取数据标签列表 |

#### 获取业务领域列表

**请求参数：**
```json
{
  "current": "integer (页码，默认 1)",
  "size": "integer (每页数量，默认 10)",
  "name_en": "string (英文名过滤，可选)",
  "name_zh": "string (中文名过滤，可选)",
  "type": "string (类型过滤：all/table/view 等，默认 all)",
  "category": "string (分类过滤，可选)",
  "tag": "string (标签过滤，可选)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": "integer",
        "name_en": "string",
        "name_zh": "string",
        "type": "string",
        "category": "string",
        "create_time": "string",
        "update_time": "string"
      }
    ],
    "total": "integer",
    "size": "integer",
    "current": "integer"
  }
}
```

#### 文件上传接口

**请求参数：**
- Content-Type: `multipart/form-data`
- file: 上传的文件（支持格式：txt, pdf, png, jpg, xlsx, xls, csv, sql, dll）

**返回结果：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "filename": "string (原始文件名)",
    "size": "integer (文件大小，字节)",
    "type": "string (文件类型)",
    "url": "string (MinIO 存储路径)"
  }
}
```

#### DDL 解析接口

**请求参数（方式一 - JSON）：**
```json
{
  "sql": "string (SQL DDL 内容)"
}
```

**请求参数（方式二 - 文件上传）：**
- Content-Type: `multipart/form-data`
- file: SQL 文件

**返回结果：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "table_info": {
        "name_en": "string (表名)",
        "name_zh": "string (中文名)",
        "comment": "string (表注释)"
      },
      "columns": [
        {
          "name": "string",
          "type": "string",
          "comment": "string",
          "nullable": "boolean"
        }
      ],
      "exist": "boolean (是否已存在)"
    }
  ]
}
```

---

### 6.3 元数据接口 (`/api/meta`)

| 接口路径 | 方法 | 描述 |
|----------|------|------|
| `/node/list` | POST | 获取元数据列表 |
| `/node/graph` | POST | 获取元数据图谱 |
| `/node/add` | POST | 添加元数据节点 |
| `/node/edit` | POST | 编辑元数据节点 |
| `/node/update` | POST | 更新元数据节点 |
| `/node/delete` | POST | 删除元数据节点 |
| `/check` | GET | 检查元数据是否存在 |
| `/search` | GET | 搜索元数据 |
| `/full/text/query` | POST | 全文检索查询 |
| `/unstructure/text/query` | POST | 非结构化文本查询 |
| `/resource/upload` | POST | 资源文件上传 |
| `/resource/display` | POST | 获取资源文件信息 |
| `/resource/download` | GET | 下载资源文件 |
| `/resource/translate` | POST | 文本资源翻译 |
| `/resource/node` | POST | 创建文本资源节点 |
| `/unstructured/process` | POST | 处理非结构化数据 |
| `/text/graph` | POST | 创建文本图谱 |
| `/config` | GET | 获取元数据配置 |

#### 获取元数据列表

**请求参数：**
```json
{
  "current": "integer (页码，默认 1)",
  "size": "integer (每页数量，默认 10)",
  "name_en": "string (英文名过滤，可选)",
  "name_zh": "string (中文名过滤，可选)",
  "category": "string (分类过滤，可选)",
  "time": "string (时间过滤，可选)",
  "tag": "array (标签过滤，可选)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [
      {
        "id": "integer",
        "name_en": "string",
        "name_zh": "string",
        "data_type": "string",
        "category": "string",
        "status": "boolean",
        "create_time": "string",
        "updateTime": "string"
      }
    ],
    "total": "integer",
    "size": "integer",
    "current": "integer"
  }
}
```

#### 获取元数据图谱

**请求参数：**
```json
{
  "nodeId": "integer (必填，节点 ID)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "node": {
      "id": "integer",
      "name_zh": "string",
      "name_en": "string",
      "properties": {}
    },
    "related_nodes": [
      {
        "id": "integer",
        "name_zh": "string",
        "labels": ["string"]
      }
    ],
    "relationships": [
      {
        "id": "integer",
        "type": "string",
        "source": "integer",
        "target": "integer"
      }
    ]
  }
}
```

#### 添加元数据节点

**请求参数：**
```json
{
  "name_zh": "string (必填，中文名称)",
  "name_en": "string (英文名称，可选)",
  "data_type": "string (必填，数据类型)",
  "category": "string (分类，可选)",
  "alias": "string (别名，可选)",
  "affiliation": "string (归属，可选)",
  "describe": "string (描述，可选)",
  "status": "boolean (状态，默认 true)",
  "tag": "array (标签列表，可选)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": "integer",
    "name_zh": "string",
    "name_en": "string",
    "data_type": "string",
    "create_time": "string",
    "tag": [
      {
        "id": "integer",
        "name_zh": "string",
        "name_en": "string"
      }
    ]
  }
}
```

---

### 6.4 数据源接口 (`/api/datasource`)

| 接口路径 | 方法 | 描述 |
|----------|------|------|
| `/save` | POST | 保存数据源 |
| `/list` | POST | 获取数据源列表 |
| `/delete` | POST | 删除数据源 |
| `/parse` | POST | 解析连接字符串 |
| `/valid` | POST | 验证连接信息 |
| `/conntest` | POST | 测试数据源连接 |
| `/graph` | POST | 获取数据源关系图 |

#### 保存数据源

**请求参数：**
```json
{
  "database": "string (必填，数据库名)",
  "host": "string (必填，主机地址)",
  "port": "integer (必填，端口号)",
  "username": "string (必填，用户名)",
  "password": "string (必填，密码)",
  "name_en": "string (必填，数据源英文名)",
  "type": "string (必填，数据库类型：postgresql/mysql 等)",
  "name_zh": "string (中文名，可选)",
  "describe": "string (描述，可选)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "id": "integer",
    "message": "string (数据源创建成功/数据源更新成功)"
  }
}
```

#### 测试数据源连接

**请求参数：**
```json
{
  "type": "string (必填，数据库类型)",
  "username": "string (必填，用户名)",
  "password": "string (必填，密码)",
  "host": "string (必填，主机地址)",
  "port": "integer (必填，端口号)",
  "database": "string (必填，数据库名)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "message": "string (连接测试成功)",
    "connected": true
  }
}
```

---

### 6.5 数据流接口 (`/api/dataflow`)

| 接口路径 | 方法 | 描述 |
|----------|------|------|
| `/get-dataflows-list` | GET | 获取数据流列表 |
| `/get-dataflow/<id>` | GET | 获取数据流详情 |
| `/add-dataflow` | POST | 创建数据流 |
| `/update-dataflow/<id>` | PUT | 更新数据流 |
| `/delete-dataflow/<id>` | DELETE | 删除数据流 |
| `/execute-dataflow/<id>` | POST | 执行数据流 |
| `/get-dataflow-status/<id>` | GET | 获取执行状态 |
| `/get-dataflow-logs/<id>` | GET | 获取执行日志 |
| `/create-script` | POST | 生成数据处理脚本 |
| `/get-BD-list` | GET | 获取业务领域列表 |

#### 创建数据流

**请求参数：**
```json
{
  "name": "string (必填，数据流名称)",
  "description": "string (描述，可选)",
  "source_id": "integer (源数据配置，可选)",
  "target_id": "integer (目标数据配置，可选)",
  "config": "object (流程配置，可选)",
  "schedule": "string (调度配置，可选)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "数据流创建成功",
  "data": {
    "id": "integer",
    "name": "string",
    "description": "string",
    "status": "string",
    "created_at": "string"
  }
}
```

#### 生成脚本接口

**请求参数：**
```json
{
  "requirement": "string (需求描述)",
  "source_config": "object (源配置)",
  "target_config": "object (目标配置)",
  "rules": "array (转换规则)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "脚本生成成功",
  "data": {
    "script_content": "string (生成的脚本内容)",
    "format": "txt",
    "generated_at": "string (生成时间)"
  }
}
```

---

### 6.6 数据接口模块 (`/api/interface`)

| 接口路径 | 方法 | 描述 |
|----------|------|------|
| `/data/standard/add` | POST | 添加数据标准 |
| `/data/standard/detail` | POST | 获取数据标准详情 |
| `/data/standard/code` | POST | 生成标准代码 |
| `/data/standard/update` | POST | 更新数据标准 |
| `/data/standard/list` | POST | 获取数据标准列表 |
| `/data/standard/graph/all` | POST | 获取标准图谱 |
| `/data/label/add` | POST | 添加数据标签 |
| `/data/label/detail` | POST | 获取标签详情 |
| `/data/label/list` | POST | 获取标签列表 |
| `/data/label/delete` | POST | 删除标签 |
| `/data/label/graph/all` | POST | 获取标签图谱 |
| `/data/label/dynamic/identify` | POST | 动态识别标签 |
| `/labellist` | POST | 获取标签列表(简化版) |
| `/graphall` | POST | 获取完整图谱 |
| `/metric/label/standard/delete` | POST | 删除指标标签关联 |

#### 添加数据标签

**请求参数：**
```json
{
  "name_zh": "string (必填，中文名称)",
  "category": "string (分类，可选)",
  "group": "string (分组，可选)",
  "describe": "string (描述，可选)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "success",
  "data": ""
}
```

---

### 6.7 图操作接口 (`/api/graph`)

| 接口路径 | 方法 | 描述 |
|----------|------|------|
| `/query` | POST | 执行 Cypher 查询 |
| `/node/create` | POST | 创建节点 |
| `/relationship/create` | POST | 创建关系 |
| `/subgraph` | POST | 获取子图数据 |

#### 执行 Cypher 查询

**请求参数：**
```json
{
  "cypher": "string (必填，Cypher 查询语句)",
  "params": "object (查询参数，可选)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": [
    {
      "n": {
        "_id": "integer",
        "_labels": ["string"],
        "property1": "value1"
      }
    }
  ]
}
```

#### 创建节点

**请求参数：**
```json
{
  "labels": "array (必填，节点标签列表)",
  "properties": "object (节点属性)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "n": {
      "_id": "integer",
      "_labels": ["string"],
      "properties": {}
    }
  }
}
```

#### 创建关系

**请求参数：**
```json
{
  "startNodeId": "integer (必填，起始节点 ID)",
  "endNodeId": "integer (必填，结束节点 ID)",
  "type": "string (必填，关系类型)",
  "properties": "object (关系属性，可选)"
}
```

**返回结果：**
```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "r": {
      "_id": "integer",
      "_type": "string",
      "_start_node_id": "integer",
      "_end_node_id": "integer"
    }
  }
}
```

---

## 7. 数据流程图

### 7.1 用户认证流程

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   客户端    │     │  Flask API  │     │  Core 层    │     │ PostgreSQL  │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │                   │
       │  POST /auth/login │                   │                   │
       │──────────────────>│                   │                   │
       │                   │  login_user()     │                   │
       │                   │──────────────────>│                   │
       │                   │                   │  查询用户          │
       │                   │                   │──────────────────>│
       │                   │                   │<──────────────────│
       │                   │                   │  验证密码          │
       │                   │<──────────────────│                   │
       │   返回登录结果     │                   │                   │
       │<──────────────────│                   │                   │
       │                   │                   │                   │
```

### 7.2 元数据创建流程

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   客户端    │     │  Flask API  │     │  Core 层    │     │   Neo4j     │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │                   │
       │ POST /node/add    │                   │                   │
       │──────────────────>│                   │                   │
       │                   │  验证参数          │                   │
       │                   │──────────────────>│                   │
       │                   │                   │  MERGE 节点       │
       │                   │                   │──────────────────>│
       │                   │                   │<──────────────────│
       │                   │                   │  创建标签关系      │
       │                   │                   │──────────────────>│
       │                   │                   │<──────────────────│
       │                   │<──────────────────│                   │
       │   返回节点信息     │                   │                   │
       │<──────────────────│                   │                   │
       │                   │                   │                   │
```

### 7.3 文件上传流程

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   客户端    │     │  Flask API  │     │  MinIO 客户端│     │   MinIO     │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │                   │
       │ POST /upload      │                   │                   │
       │ (multipart/form)  │                   │                   │
       │──────────────────>│                   │                   │
       │                   │  验证文件类型      │                   │
       │                   │──────────────────>│                   │
       │                   │                   │  put_object()    │
       │                   │                   │──────────────────>│
       │                   │                   │<──────────────────│
       │                   │<──────────────────│                   │
       │   返回文件信息     │                   │                   │
       │<──────────────────│                   │                   │
       │                   │                   │                   │
```

### 7.4 DDL 解析流程

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   客户端    │     │  Flask API  │     │  DDLParser  │     │  LLM API    │
└──────┬──────┘     └──────┬──────┘     └──────┬──────┘     └──────┬──────┘
       │                   │                   │                   │
       │ POST /ddlparse    │                   │                   │
       │──────────────────>│                   │                   │
       │                   │  parse_ddl()      │                   │
       │                   │──────────────────>│                   │
       │                   │                   │  调用 LLM 解析    │
       │                   │                   │──────────────────>│
       │                   │                   │<──────────────────│
       │                   │                   │  格式化结果       │
       │                   │<──────────────────│                   │
       │                   │  检查节点存在性    │                   │
       │                   │──────────────────>│ (Neo4j 查询)      │
       │                   │<──────────────────│                   │
       │   返回解析结果     │                   │                   │
       │<──────────────────│                   │                   │
       │                   │                   │                   │
```

---

## 8. 统一响应格式

### 8.1 成功响应

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    // 具体业务数据
  }
}
```

### 8.2 失败响应

```json
{
  "code": 500,
  "message": "操作失败描述",
  "data": null,
  "error": "详细错误信息（可选）"
}
```

### 8.3 分页响应

```json
{
  "code": 200,
  "message": "操作成功",
  "data": {
    "records": [],
    "total": 100,
    "size": 10,
    "current": 1
  }
}
```

### 8.4 HTTP 状态码

| 状态码 | 含义 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权/认证失败 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 9. 配置说明

### 9.1 环境配置

系统支持两种环境配置：

| 环境 | 说明 | 触发条件 |
|------|------|---------|
| development | 开发环境 | Windows 系统或 FLASK_ENV=development |
| production | 生产环境 | Linux 系统或 FLASK_ENV=production |

### 9.2 主要配置项

#### 数据库配置

| 配置项 | 开发环境 | 生产环境 |
|--------|---------|---------|
| NEO4J_URI | bolt://localhost:7687 | bolt://192.168.3.143:7687 |
| SQLALCHEMY_DATABASE_URI | postgresql://postgres:postgres@localhost:5432/dataops | postgresql://postgres:dataOps@192.168.3.143:5432/dataops |

#### MinIO 配置

| 配置项 | 开发环境 | 生产环境 |
|--------|---------|---------|
| MINIO_HOST | localhost:9000 | 192.168.3.143:9000 |
| MINIO_BUCKET | dataops-bucket | dataops-bucket |

#### LLM 配置

| 配置项 | 说明 |
|--------|------|
| LLM_BASE_URL | 通义千问 API 地址 |
| LLM_MODEL_NAME | 模型名称 (qwen-turbo) |
| LLM_API_KEY | API 密钥 |

### 9.3 文件上传配置

支持的文件类型：`txt, pdf, png, jpg, jpeg, gif, xlsx, xls, csv, sql, dll`

---

## 附录

### A. Neo4j 节点标签说明

| 标签 | 说明 |
|------|------|
| DataMeta | 元数据节点 |
| BusinessDomain | 业务领域节点 |
| DataSource | 数据源节点 |
| DataLabel | 数据标签节点 |
| data_standard | 数据标准节点 |
| Tag | 标签节点 |

### B. 常用关系类型

| 关系类型 | 说明 |
|----------|------|
| LABEL | 元数据与标签的关联 |
| HAS_TAG | 资源与标签的关联 |
| master_data | 主数据关联 |
| BELONGS_TO | 归属关系 |

### C. 错误码参考

| 错误码 | 含义 |
|--------|------|
| 200 | 操作成功 |
| 400 | 参数错误 |
| 401 | 认证失败 |
| 404 | 资源不存在 |
| 500 | 服务器错误 |

---

*文档生成时间：2025年12月*
*版本：1.0*