python/finyx_data_ai

Fork 0

Ubuntu 74dbbebffb 初步完成接口开发和冒烟测试

2026-01-11 07:48:19 +08:00

34 KiB

Raw Permalink Blame History

Finyx Data AI API - 接口文档

📋 文档概述

本文档提供了 Finyx Data AI 系统所有接口的详细说明，包括请求/响应格式、使用示例和注意事项。

版本: v1.0.0
更新日期: 2026-01-10

📚 接口总览

| 序号 | 模块 | 接口名称 | 方法 | 状态 | |------|------|---------|------| | 1 | 数据盘点 | 文档解析接口 | POST | ✅ 已完成 | | 2 | 数据盘点 | SQL 结果解析接口 | POST | ✅ 已完成 | | 3 | 数据盘点 | 业务表解析接口 | POST | ✅ 已完成 | | 4 | 数据盘点 | 数据资产智能识别接口 | POST | ✅ 已完成 | | 5 | 场景挖掘 | 潜在场景推荐接口 | POST | ✅ 已完成 | | 6 | 场景挖掘 | 存量场景优化建议接口 | POST | ✅ 已完成 | | 7 | 报告生成 | 完整报告生成接口 | POST | ✅ 已完成 |

🔧 基础配置

环境变量

所有接口都需要配置以下环境变量：

# 大模型配置
DASHSCOPE_API_KEY=your_dashscope_api_key
OPENAI_API_KEY=your_openai_api_key
SILICONFLOW_API_KEY=your_siliconflow_api_key

# 默认模型配置
DEFAULT_LLM_MODEL=qwen-max
DEFAULT_TEMPERATURE=0.3

# Redis 缓存配置（可选）
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_DB=0
REDIS_PASSWORD=your_redis_password
ENABLE_CACHE=true

基础 URL

API 基础路径: http://localhost:8000/api/v1
Swagger 文档: http://localhost:8000/docs
ReDoc 文档: http://localhost:8000/redoc

📦 模块一：数据盘点智能分析服务

1.1 文档解析接口

基本信息

路径: /api/v1/inventory/parse-document
方法: POST
描述: 解析上传的数据字典文档（Excel/Word/PDF），提取表结构信息
优先级: 中

请求格式

Content-Type: application/json

{
  "file_path": "/path/to/document.xlsx",
  "file_type": "excel",
  "project_id": "project_001"
}

请求参数说明:

参数名	类型	必填	说明
`file_path`	string	是	文件路径（绝对路径）
`file_type`	string	否	文件类型：`excel`/`word`/`pdf`，不传则自动识别
`project_id`	string	是	项目ID

响应格式

成功响应 (200):

{
  "success": true,
  "code": 200,
  "message": "文档解析成功",
  "data": {
    "tables": [
      {
        "raw_name": "t_user_base_01",
        "display_name": "用户基础信息表",
        "description": "存储用户基本信息的表",
        "fields": [
          {
            "raw_name": "user_id",
            "display_name": "用户ID",
            "type": "varchar(64)",
            "comment": "用户的唯一标识符",
            "is_primary_key": true,
            "is_nullable": false,
            "default_value": null
          }
        ],
        "field_count": 2
      }
    ],
    "total_tables": 10,
    "total_fields": 245,
    "parse_time": 1.23,
    "file_info": {
      "file_name": "数据字典.xlsx",
      "file_size": 1024000,
      "file_type": "excel"
    }
  }
}

错误响应 (400/404/500):

{
  "success": false,
  "code": 400,
  "message": "文件格式不支持",
  "error": {
    "error_code": "UNSUPPORTED_FILE_TYPE",
    "error_detail": "仅支持 Excel (.xlsx, .xls), Word (.doc, .docx), PDF (.pdf) 格式"
  }
}

响应字段说明

字段名	类型	说明
`success`	boolean	请求是否成功
`code`	integer	HTTP 状态码
`message`	string	响应消息
`data`	object	响应数据
`data.tables`	array	解析出的表列表
`data.tables[].raw_name`	string	表名（英文/原始名称）
`data.tables[].display_name`	string	表显示名称（中文）
`data.tables[].description`	string	表描述
`data.tables[].fields`	array	字段列表
`data.tables[].field_count`	integer	字段数量
`data.total_tables`	integer	总表数
`data.total_fields`	integer	总字段数
`data.parse_time`	float	解析耗时（秒）
`data.file_info`	object	文件信息
`error`	object	错误信息（仅在失败时返回）

使用示例

cURL 示例:

curl -X POST "http://localhost:8000/api/v1/inventory/parse-document" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "/tmp/data_dictionary.xlsx",
    "project_id": "project_001"
  }'

Python 示例:

import requests

url = "http://localhost:8000/api/v1/inventory/parse-document"
headers = {"Content-Type": "application/json"}
payload = {
    "file_path": "/tmp/data_dictionary.xlsx",
    "project_id": "project_001"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

注意事项

文件大小限制: 单个文件最大 50MB
支持的文件格式: Excel (.xlsx, .xls)、Word (.doc, .docx)、PDF (.pdf)
文件路径: 必须是绝对路径
文件类型: 不传则根据文件扩展名自动识别
错误处理: 文件不存在、格式不支持、解析失败等情况会返回明确的错误信息

1.2 SQL 结果解析接口

基本信息

路径: /api/v1/inventory/parse-sql-result
方法: POST
描述: 解析 IT 执行 SQL 脚本后导出的 Excel/CSV 结果文件
优先级: 低

请求格式

{
  "file_path": "/path/to/sql_result.xlsx",
  "file_type": "excel",
  "project_id": "project_001"
}

请求参数说明:

参数名	类型	必填	说明
`file_path`	string	是	文件路径（绝对路径）
`file_type`	string	否	文件类型：`excel`/`csv`，不传则自动识别
`project_id`	string	是	项目ID

响应格式

成功响应 (200):

{
  "success": true,
  "code": 200,
  "message": "SQL 结果解析成功",
  "data": {
    "tables": [
      {
        "raw_name": "t_user_base_01",
        "display_name": "用户基础信息表",
        "description": null,
        "fields": [
          {
            "raw_name": "user_id",
            "display_name": "用户ID",
            "type": "varchar(64)",
            "comment": null
          }
        ],
        "field_count": 1
      }
    ],
    "total_tables": 5,
    "total_fields": 150,
    "parse_time": 0.45,
    "file_info": {
      "file_name": "schema_export.xlsx",
      "file_size": 512000,
      "file_type": "excel"
    }
  }
}

注意事项

列名映射: 支持多种列名格式（中英文）
CSV 编码: 自动尝试 UTF-8、GBK、GB2312、Latin-1
数据清洗: 自动去除空值和空行
按表名分组: 根据表名列将字段分组

1.3 业务表解析接口

基本信息

路径: /api/v1/inventory/parse-business-tables
方法: POST
描述: 解析业务人员手动导出的核心业务表（Excel/CSV），支持批量文件解析
优先级: 中

请求格式

{
  "file_paths": [
    "/path/to/orders.xlsx",
    "/path/to/products.csv"
  ],
  "project_id": "project_001"
}

请求参数说明:

参数名	类型	必填	说明
`file_paths`	array	是	文件路径列表（绝对路径）
`project_id`	string	是	项目ID

响应格式

成功响应 (200):

{
  "success": true,
  "code": 200,
  "message": "成功解析 5 个文件，提取 10 个表",
  "data": {
    "tables": [...],
    "total_tables": 10,
    "total_fields": 150,
    "total_files": 5,
    "success_files": 5,
    "failed_files": [],
    "parse_time": 3.45,
    "file_info": {
      "processed_files": [
        {
          "file_name": "orders.xlsx",
          "file_size": 1024000,
          "tables_extracted": 1,
          "status": "success"
        }
      ]
    }
  }
}

失败响应示例 (部分失败):

{
  "success": true,
  "code": 200,
  "message": "成功解析 4 个文件，提取 8 个表",
  "data": {
    "tables": [...],
    "total_tables": 8,
    "total_fields": 120,
    "total_files": 5,
    "success_files": 4,
    "failed_files": [
      {
        "file_name": "invalid_file.txt",
        "error": "不支持的文件类型: txt"
      }
    ],
    "parse_time": 3.20,
    "file_info": {
      "processed_files": [...]
    }
  }
}

注意事项

批量处理: 支持一次上传多个文件
单个文件失败不影响其他: 单个文件解析失败不会中断整个流程
Excel 多 Sheet: 自动识别每个 Sheet 为独立的表
字段类型推断: 基于 pandas 类型自动推断数据库字段类型

1.4 数据资产智能识别接口

基本信息

路径: /api/v1/inventory/ai-analyze
方法: POST
描述: 使用大模型识别数据资产的中文名称、业务含义、PII 敏感信息、重要数据特征，并提供置信度评分
优先级: 高 ⭐⭐⭐

请求格式

{
  "tables": [
    {
      "raw_name": "t_user_base_01",
      "fields": [
        {
          "raw_name": "user_id",
          "type": "varchar(64)",
          "comment": "用户ID"
        },
        {
          "raw_name": "phone",
          "type": "varchar(11)",
          "comment": "手机号"
        },
        {
          "raw_name": "id_card",
          "type": "varchar(18)",
          "comment": "身份证号"
        }
      ]
    }
  ],
  "project_id": "project_001",
  "industry": "retail-fresh",
  "context": "某连锁生鲜零售企业，主营水果、蔬菜等生鲜产品",
  "options": {
    "model": "qwen-max",
    "temperature": 0.3,
    "enable_pii_detection": true,
    "enable_important_data_detection": true
  }
}

请求参数说明:

参数名	类型	必填	说明
`tables`	array	是	表列表，每个表包含表名和字段列表
`tables[].raw_name`	string	是	表名（英文/原始名称）
`tables[].fields`	array	是	字段列表
`tables[].fields[].raw_name`	string	是	字段名（英文）
`tables[].fields[].type`	string	是	字段类型
`tables[].fields[].comment`	string	否	字段注释
`project_id`	string	是	项目ID
`industry`	string	否	行业信息（如：retail-fresh）
`context`	string	否	业务背景信息
`options.model`	string	否	大模型选择（qwen-max/gpt-4/siliconflow:xxx）
`options.temperature`	float	否	温度参数（0.0-1.0），默认 0.3
`options.enable_pii_detection`	boolean	否	是否启用 PII 识别，默认 true
`options.enable_important_data_detection`	boolean	否	是否启用重要数据识别，默认 true

响应格式

成功响应 (200):

{
  "success": true,
  "code": 200,
  "message": "数据资产识别成功",
  "data": {
    "tables": [
      {
        "raw_name": "t_user_base_01",
        "ai_name": "会员基础信息表",
        "desc": "存储C端注册用户的核心身份信息",
        "confidence": 98,
        "ai_completed": true,
        "fields": [
          {
            "raw_name": "user_id",
            "ai_name": "用户ID",
            "desc": "用户的唯一标识符",
            "type": "varchar(64)",
            "pii": [],
            "pii_type": null,
            "is_important_data": false,
            "confidence": 95
          },
          {
            "raw_name": "phone",
            "ai_name": "手机号",
            "desc": "用户的联系电话",
            "type": "varchar(11)",
            "pii": ["手机号"],
            "pii_type": "contact",
            "is_important_data": false,
            "confidence": 98
          },
          {
            "raw_name": "id_card",
            "ai_name": "身份证号",
            "desc": "用户的身份证号码",
            "type": "varchar(18)",
            "pii": ["身份证号"],
            "pii_type": "identity",
            "is_important_data": false,
            "confidence": 99
          }
        ],
        "pii": ["手机号", "身份证号"],
        "important": false,
        "important_data_types": []
      }
    ],
    "statistics": {
      "total_tables": 1,
      "total_fields": 3,
      "pii_fields_count": 2,
      "important_data_fields_count": 0,
      "average_confidence": 97.3
    },
    "processing_time": 5.2,
    "model_used": "qwen-max",
    "token_usage": {
      "prompt_tokens": 1200,
      "completion_tokens": 800,
      "total_tokens": 2000
    }
  }
}

响应字段说明

字段名	类型	说明
`data.tables[].ai_name`	string	AI 识别的中文名称
`data.tables[].desc`	string	业务描述
`data.tables[].confidence`	integer	置信度评分（0-100）
`data.tables[].fields[].pii`	array	PII 信息列表（如：["手机号"]）
`data.tables[].fields[].pii_type`	string	PII 类型（contact/identity/name/email/address/financial）
`data.tables[].fields[].is_important_data`	boolean	是否重要数据
`statistics.pii_fields_count`	integer	包含 PII 的字段数
`statistics.important_data_fields_count`	integer	重要数据字段数
`statistics.average_confidence`	float	平均置信度

支持的模型

模型名称	说明
`qwen-max`	通义千问 Max（推荐）
`qwen-plus`	通义千问 Plus
`qwen-turbo`	通义千问 Turbo
`gpt-4`	OpenAI GPT-4
`gpt-3.5-turbo`	OpenAI GPT-3.5 Turbo
`deepseek-chat`	硅基流动 DeepSeek Chat
`deepseek-coder`	硅基流动 DeepSeek Coder
`Qwen/Qwen3-VL-32B-Instruct`	硅基流动 Qwen3-VL 视觉模型

注意事项

PII 识别规则: 除了 AI 识别，还使用规则引擎补充识别（基于关键词）
置信度评分: 综合考虑命名规范度、注释完整性、AI 识别结果质量
重试机制: API 调用失败会自动重试（最多 3 次，指数退避）
Token 优化: 提示词经过优化，减少不必要的 Token 消耗

🎯 模块二：场景挖掘智能推荐服务

2.1 潜在场景推荐接口

基本信息

路径: /api/v1/value/scenario-recommendation
方法: POST
描述: 基于企业背景、数据资产清单和存量场景，使用 AI 推荐潜在的数据应用场景
优先级: 高 ⭐⭐

请求格式

{
  "project_id": "project_001",
  "company_info": {
    "industry": ["retail-fresh"],
    "description": "某连锁生鲜零售企业，主营水果、蔬菜等生鲜产品，拥有线下门店500家",
    "data_scale": "100TB",
    "data_sources": ["self-generated"]
  },
  "data_assets": [
    {
      "name": "会员基础信息表",
      "core_tables": ["Dim_Customer"],
      "description": "存储C端注册用户的核心身份信息"
    },
    {
      "name": "订单流水记录表",
      "core_tables": ["Fact_Sales"],
      "description": "全渠道销售交易明细"
    }
  ],
  "existing_scenarios": [
    {
      "name": "月度销售经营报表",
      "description": "统计各区域门店的月度GMV，维度单一"
    }
  ],
  "options": {
    "model": "qwen-max",
    "recommendation_count": 10,
    "exclude_types": []
  }
}

请求参数说明:

参数名	类型	必填	说明
`project_id`	string	是	项目ID
`company_info.industry`	array	是	行业列表
`company_info.description`	string	是	企业描述
`company_info.data_scale`	string	是	数据规模
`company_info.data_sources`	array	是	数据来源
`data_assets`	array	是	数据资产列表
`data_assets[].name`	string	是	资产名称
`data_assets[].core_tables`	array	是	核心表名列表
`data_assets[].description`	string	是	资产描述
`existing_scenarios`	array	否	存量场景列表
`existing_scenarios[].name`	string	是	场景名称
`existing_scenarios[].description`	string	是	场景描述
`options.model`	string	否	大模型选择
`options.recommendation_count`	integer	否	推荐数量（1-20），默认 10
`options.exclude_types`	array	否	排除的场景类型

响应格式

成功响应 (200):

{
  "success": true,
  "code": 200,
  "message": "场景推荐成功",
  "data": {
    "recommended_scenarios": [
      {
        "id": 1,
        "name": "精准会员营销",
        "type": "营销增长",
        "recommendation_index": 5,
        "desc": "基于用户画像与历史交易行为，实现千人千面的优惠券发放。",
        "dependencies": ["会员基础信息表", "订单流水记录表"],
        "business_value": "提升复购率 15-20%",
        "implementation_difficulty": "中等",
        "estimated_roi": "高",
        "technical_requirements": ["用户画像引擎", "推荐算法"],
        "data_requirements": ["会员基础信息", "交易历史", "行为数据"]
      },
      {
        "id": 2,
        "name": "库存智能预警",
        "type": "降本增效",
        "recommendation_index": 4,
        "desc": "基于销售预测和库存分析，实现智能补货和库存优化。",
        "dependencies": ["订单流水记录表"],
        "business_value": "降低库存成本 10-15%",
        "implementation_difficulty": "中",
        "estimated_roi": "中",
        "technical_requirements": ["预测算法", "库存管理系统"],
        "data_requirements": ["销售数据", "库存数据"]
      }
    ],
    "total_count": 10,
    "generation_time": 8.5,
    "model_used": "qwen-max"
  }
}

响应字段说明:

字段名	类型	说明
`data.recommended_scenarios[].id`	integer	场景 ID
`data.recommended_scenarios[].name`	string	场景名称
`data.recommended_scenarios[].type`	string	场景分类（降本增效/营销增长/金融服务/决策支持/风险控制）
`data.recommended_scenarios[].recommendation_index`	integer	推荐指数（1-5 星）
`data.recommended_scenarios[].dependencies`	array	依赖的数据资产
`data.recommended_scenarios[].business_value`	string	商业价值描述
`data.recommended_scenarios[].implementation_difficulty`	string	实施难度（低/中/高）
`data.recommended_scenarios[].estimated_roi`	string	预估 ROI（低/中/高）
`data.recommended_scenarios[].technical_requirements`	array	技术要求
`data.recommended_scenarios[].data_requirements`	array	数据要求

场景分类

分类	说明	示例场景
降本增效	提升运营效率、降低成本	库存优化、供应链优化
营销增长	提升销售额、用户增长	精准营销、用户画像、推荐系统
金融服务	金融相关场景	风险评估、信用评分、欺诈检测
决策支持	辅助决策制定	数据分析、报表分析、可视化
风险控制	风险管理	合规监控、异常检测、安全审计

注意事项

避免重复: 推荐的场景会与存量场景对比，避免重复
依赖分析: 推荐的场景会明确标注依赖的数据资产
商业价值评估: 综合考虑业务价值、实施难度、数据准备度
推荐指数: 1-5 星评分，综合考虑多个因素

2.2 存量场景优化建议接口

基本信息

路径: /api/v1/value/scenario-optimization
方法: POST
描述: 基于存量场景信息和截图，分析场景不足，提供优化建议
优先级: 中

请求格式

{
  "existing_scenarios": [
    {
      "name": "月度销售经营报表",
      "description": "统计各区域门店的月度GMV，维度单一"
    }
  ],
  "data_assets": [
    {
      "name": "订单流水记录表",
      "core_tables": ["Fact_Sales"],
      "description": "全渠道销售交易明细"
    }
  ],
  "company_info": {
    "industry": ["retail-fresh"],
    "description": "某连锁生鲜零售企业，主营水果、蔬菜等生鲜产品"
  }
}

请求参数说明:

参数名	类型	必填	说明
`existing_scenarios`	array	是	存量场景列表
`existing_scenarios[].name`	string	是	场景名称
`existing_scenarios[].description`	string	是	场景描述
`data_assets`	array	否	数据资产列表
`company_info`	object	否	企业信息
`company_info.industry`	array	否	行业列表
`company_info.description`	string	否	企业描述

响应格式

成功响应 (200):

{
  "success": true,
  "code": 200,
  "message": "场景优化建议生成成功",
  "data": {
    "optimization_suggestions": [
      {
        "scenario_name": "月度销售经营报表",
        "current_status": "维度单一，仅统计GMV",
        "suggestions": [
          "增加时间维度分析（同比、环比）",
          "增加商品类别维度分析",
          "增加区域对比分析"
        ],
        "potential_value": "提升决策支持能力 30%"
      },
      {
        "scenario_name": "库存管理报表",
        "current_status": "缺乏实时库存监控",
        "suggestions": [
          "实现实时库存预警机制",
          "增加库存周转率分析",
          "优化补货策略"
        ],
        "potential_value": "降低库存成本 10-15%"
      }
    ],
    "generation_time": 3.2,
    "model_used": "qwen-max"
  }
}

响应字段说明:

字段名	类型	说明
`data.optimization_suggestions[].scenario_name`	string	场景名称
`data.optimization_suggestions[].current_status`	string	当前状态描述
`data.optimization_suggestions[].suggestions`	array	优化建议列表
`data.optimization_suggestions[].potential_value`	string	潜在价值描述

注意事项

OCR 功能: 当前版本未实现图片识别（OCR），仅支持基于文本的场景分析
建议可操作性: 优化建议必须具体、可执行
价值提升: 识别可提升的价值点

📊 模块三：数据资产盘点报告生成服务

3.1 完整报告生成接口

基本信息

路径: /api/v1/delivery/generate-report
方法: POST
描述: 基于数据盘点结果、背景调研信息和价值挖掘场景，使用大模型生成完整的数据资产盘点工作总结报告
优先级: 高 ⭐⭐⭐

请求格式

{
  "project_info": {
    "project_name": "数据资产盘点项目",
    "industry": "retail-fresh",
    "company_name": "某连锁生鲜零售企业"
  },
  "inventory_data": {
    "total_tables": 14582,
    "total_fields": 245000,
    "total_data_volume": "58 PB",
    "storage_distribution": [
      {
        "category": "供应链物流",
        "volume": "25.4 PB",
        "storage_type": "主要存储于 HDFS / NoSQL",
        "color": "blue"
      },
      {
        "category": "零售业务",
        "volume": "20.5 PB",
        "storage_type": "主要存储于 MySQL",
        "color": "purple"
      }
    ],
    "data_source_structure": {
      "structured": 35,
      "semi_structured": 65
    },
    "identified_assets": [
      {
        "name": "消费者全景画像",
        "core_tables": ["Dim_Customer", "Fact_Sales"],
        "description": "核心依赖客户维度表与销售事实表，并整合了线上电商ID、线下门店会员卡号及社交媒体账号。"
      }
    ]
  },
  "context_data": {
    "enterprise_background": "某连锁生鲜零售企业成立于2010年，目前在全国拥有500家线下门店...",
    "informatization_status": "已建立基础IT系统，包括ERP、CRM、WMS等...",
    "business_flow": "采购-仓储-销售-配送..."
  },
  "value_data": {
    "selected_scenarios": [
      {
        "name": "精准会员营销",
        "description": "基于用户画像与历史交易行为，实现千人千面的优惠券发放。"
      }
    ]
  },
  "options": {
    "language": "zh-CN",
    "detail_level": "standard",
    "generation_mode": "full"
  }
}

请求参数说明:

参数名	类型	必填	说明
`project_info.project_name`	string	是	项目名称
`project_info.industry`	string	是	行业类型
`project_info.company_name`	string	否	企业名称
`inventory_data.total_tables`	integer	是	总表数
`inventory_data.total_fields`	integer	是	总字段数
`inventory_data.total_data_volume`	string	是	总数据量（如："58 PB"）
`inventory_data.storage_distribution`	array	是	存储分布列表
`inventory_data.data_source_structure.structured`	integer	结构化数据百分比（0-100）
`inventory_data.data_source_structure.semi_structured`	integer	半结构化数据百分比（0-100）
`inventory_data.identified_assets`	array	是	识别的数据资产列表
`context_data.enterprise_background`	string	是	企业背景描述
`context_data.informatization_status`	string	是	信息化建设现状
`context_data.business_flow`	string	是	业务流与数据流
`value_data.selected_scenarios`	array	是	选中的场景列表
`options.language`	string	否	语言（zh-CN/en-US），默认 zh-CN
`options.detail_level`	string	否	详细程度（brief/standard/detailed），默认 standard
`options.generation_mode`	string	否	生成模式（full/staged），默认 full

响应格式

成功响应 (200):

{
  "success": true,
  "code": 200,
  "message": "报告生成成功",
  "data": {
    "header": {
      "project_name": "数据资产盘点项目"
    },
    "section1": {
      "enterprise_background": {
        "description": "某连锁生鲜零售企业成立于2010年，目前在全国拥有500家线下门店，年销售额约50亿元，员工数约5000人。"
      },
      "informatization_status": {
        "overview": "企业已建立较为完善的信息化体系，包括ERP、CRM、WMS等核心系统...",
        "private_cloud": {
          "title": "私有云平台",
          "description": "基于 OpenStack 构建的私有云平台，承载核心业务系统..."
        },
        "public_cloud": {
          "title": "公有云服务",
          "description": "使用阿里云、腾讯云等公有云服务，用于弹性扩容和备份..."
        }
      },
      "business_data_flow": {
        "overview": "企业的业务流程涵盖采购、仓储、销售、配送四个主要环节，形成了完整的供应链闭环...",
        "manufacturing": {
          "title": "采购环节",
          "description": "建立供应商管理体系，实现集中采购和智能补货..."
        },
        "logistics": {
          "title": "仓储环节",
          "description": "建立区域配送中心，实现智能分仓和路径优化..."
        },
        "retail": {
          "title": "销售环节",
          "description": "全渠道销售网络，包括线下门店、电商平台、社区团购..."
        },
        "data_aggregation": {
          "title": "数据汇聚",
          "description": "建立数据中台，汇聚各环节数据，支持实时分析和决策..."
        }
      }
    },
    "section2": {
      "summary": {
        "total_data_volume": "58 PB",
        "total_data_objects": {
          "tables": "14,582 张表",
          "fields": "24.5万+ 字段"
        }
      },
      "storage_distribution": [...],
      "data_source_structure": {
        "structured": {
          "percentage": 35,
          "description": "结构化数据主要存储在关系型数据库中，包括MySQL、PostgreSQL等，约占总数据量的35%。"
        },
        "semi_structured": {
          "percentage": 65,
          "description": "半结构化与非结构化数据主要存储在数据湖中，包括日志、文档、图片等，约占总数据量的65%。"
        }
      }
    },
    "section3": {
      "overview": {
        "asset_count": 3,
        "high_value_assets": ["消费者全景画像", "供应链智能分析", "销售预测模型"],
        "description": "通过数据资产盘点，识别出3个高价值数据资产，其中消费者全景画像价值最高..."
      },
      "assets": [
        {
          "id": "customer360",
          "title": "消费者全景画像",
          "subtitle": "Customer 360",
          "composition": {
            "description": "核心依赖 Dim_Customer（客户维度表）与 Fact_Sales（销售事实表），并整合了线上电商ID、线下门店会员卡号及社交媒体账号。",
            "core_tables": ["Dim_Customer", "Fact_Sales"]
          },
          "application_scenarios": {
            "description": "旨在构建OneID体系，支持计算客户生命周期价值（CLV），进行精准营销（如针对流失风险自动触发挽留策略），提升复购率。"
          },
          "compliance_risks": {
            "warnings": [
              {
                "type": "个人信息预警",
                "content": "共识别出 12 项敏感个人信息（SPI），包含生物识别信息（人脸）、医疗健康（体检报告）、金融账户及行踪轨迹。",
                "highlights": ["12 项", "敏感个人信息", "SPI"]
              }
            ]
          }
        }
      ]
    },
    "section4": {
      "compliance_remediation": {
        "title": "合规整改",
        "items": [
          {
            "order": 1,
            "category": "跨境传输",
            "description": "对于涉及个人信息的跨境数据传输，需进行数据出境安全评估，确保符合《个人信息保护法》和《数据出境安全评估办法》的要求。",
            "code_references": ["Dim_Customer", "Fact_Sales"]
          },
          {
            "order": 2,
            "category": "访问控制",
            "description": "建立完善的个人信息访问权限管理体系，实施最小权限原则，定期进行权限审计。",
            "code_references": ["Dim_Customer"]
          }
        ]
      },
      "technical_evolution": {
        "title": "技术演进",
        "description": "建议引入数据湖技术（如 Apache Iceberg 或 Apache Hudi），提升数据查询性能和灵活性。同时考虑引入实时流处理框架（如 Apache Flink），支持实时数据分析。",
        "technologies": ["Apache Iceberg", "Apache Hudi", "Apache Flink", "Kafka"]
      },
      "value_deepening": {
        "title": "价值深化",
        "items": [
          {
            "description": "基于消费者全景画像，深化精准营销场景，包括个性化推荐、流失预警、生命周期价值提升等。",
            "scenarios": ["精准会员营销", "客户生命周期管理"]
          },
          {
            "description": "利用供应链智能分析和销售预测模型，优化库存管理，降低缺货率和库存成本。",
            "scenarios": ["库存智能预警", "需求预测"]
          }
        ]
      }
    },
    "generation_time": 25.5,
    "model_used": "qwen-max"
  }
}

响应字段说明

字段名	类型	说明
`section1`	object	章节一：企业数字化情况简介
`section2`	object	章节二：数据资源统计
`section3`	object	章节三：数据资产情况盘点
`section4`	object	章节四：专家建议与下一步计划
`generation_time`	float	生成耗时（秒）
`model_used`	string	使用的大模型

注意事项

分阶段生成: 报告采用分阶段生成策略，确保每个章节的质量
数据验证: 章节二的数据百分比总和会验证是否为 100%
合规风险分析: 章节三会识别符合 PIPL 和数据安全法要求的合规风险
建议可操作性: 章节四的建议必须具体、可执行

🔐 错误码说明

通用错误码

错误码	HTTP 状态	说明
200	OK	请求成功
400	Bad Request	请求参数错误
404	Not Found	资源不存在
422	Unprocessable Entity	无法处理的实体
429	Too Many Requests	请求过于频繁
500	Internal Server Error	服务器内部错误
503	Service Unavailable	服务不可用

业务错误码

错误码	说明	解决方案
`UNSUPPORTED_FILE_TYPE`	不支持的文件类型	仅支持 Excel、Word、PDF 格式
`FILE_NOT_FOUND`	文件不存在	检查文件路径是否正确
`PARSE_ERROR`	文件解析失败	检查文件格式是否正确
`MISSING_REQUIRED_COLUMNS`	缺少必要列	检查 SQL 结果文件是否包含必要列
`LLM_API_ERROR`	大模型 API 调用失败	检查 API Key 配置，稍后重试
`VALIDATION_ERROR`	数据验证失败	检查输入数据格式是否正确
`RATE_LIMIT_EXCEEDED`	请求频率过高	降低请求频率

🚀 快速开始

启动服务

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，填入必要的配置

# 启动服务
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

测试接口

# 测试文档解析接口
curl -X POST "http://localhost:8000/api/v1/inventory/parse-document" \
  -H "Content-Type: application/json" \
  -d '{
    "file_path": "/tmp/test.xlsx",
    "project_id": "test_project"
  }'

# 测试 AI 分析接口
curl -X POST "http://localhost:8000/api/v1/inventory/ai-analyze" \
  -H "Content-Type: application/json" \
  -d '{
    "tables": [{
      "raw_name": "t_user",
      "fields": [
        {"raw_name": "user_id", "type": "varchar(64)", "comment": "用户ID"}
      ]
    }],
    "project_id": "test_project"
  }'

📞 联系方式

如有问题或建议，请联系：

技术负责人: [待填写]
大模型技术顾问: [待填写]
项目负责人: [待填写]

📝 更新记录

版本	日期	更新内容	作者
v1.0.0	2026-01-10	初始版本，创建详细的 API 文档	AI Assistant

34 KiB Raw Permalink Blame History Unescape Escape

Finyx Data AI API - 接口文档

📋 文档概述

📚 接口总览

🔧 基础配置

环境变量

基础 URL

📦 模块一：数据盘点智能分析服务

1.1 文档解析接口

基本信息

请求格式

响应格式

响应字段说明

使用示例

注意事项

1.2 SQL 结果解析接口

基本信息

请求格式

响应格式

注意事项

1.3 业务表解析接口

基本信息

请求格式

响应格式

注意事项

1.4 数据资产智能识别接口

基本信息

请求格式

响应格式

响应字段说明

支持的模型

注意事项

🎯 模块二：场景挖掘智能推荐服务

2.1 潜在场景推荐接口

基本信息

请求格式

响应格式

场景分类

注意事项

2.2 存量场景优化建议接口

基本信息

请求格式

响应格式

注意事项

📊 模块三：数据资产盘点报告生成服务

3.1 完整报告生成接口

基本信息

请求格式

响应格式

响应字段说明

注意事项

🔐 错误码说明

通用错误码

业务错误码

🚀 快速开始

启动服务

测试接口

📞 联系方式

📝 更新记录

34 KiB

Raw Permalink Blame History