1132 lines
34 KiB
Markdown
1132 lines
34 KiB
Markdown
# 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 | ✅ 已完成 |
|
||
|
||
---
|
||
|
||
## 🔧 基础配置
|
||
|
||
### 环境变量
|
||
|
||
所有接口都需要配置以下环境变量：
|
||
|
||
```bash
|
||
# 大模型配置
|
||
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`
|
||
|
||
```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):
|
||
|
||
```json
|
||
{
|
||
"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):
|
||
|
||
```json
|
||
{
|
||
"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 示例**:
|
||
|
||
```bash
|
||
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 示例**:
|
||
|
||
```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())
|
||
```
|
||
|
||
#### 注意事项
|
||
|
||
1. **文件大小限制**: 单个文件最大 50MB
|
||
2. **支持的文件格式**: Excel (.xlsx, .xls)、Word (.doc, .docx)、PDF (.pdf)
|
||
3. **文件路径**: 必须是绝对路径
|
||
4. **文件类型**: 不传则根据文件扩展名自动识别
|
||
5. **错误处理**: 文件不存在、格式不支持、解析失败等情况会返回明确的错误信息
|
||
|
||
---
|
||
|
||
### 1.2 SQL 结果解析接口
|
||
|
||
#### 基本信息
|
||
|
||
- **路径**: `/api/v1/inventory/parse-sql-result`
|
||
- **方法**: `POST`
|
||
- **描述**: 解析 IT 执行 SQL 脚本后导出的 Excel/CSV 结果文件
|
||
- **优先级**: 低
|
||
|
||
#### 请求格式
|
||
|
||
```json
|
||
{
|
||
"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):
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 注意事项
|
||
|
||
1. **列名映射**: 支持多种列名格式（中英文）
|
||
2. **CSV 编码**: 自动尝试 UTF-8、GBK、GB2312、Latin-1
|
||
3. **数据清洗**: 自动去除空值和空行
|
||
4. **按表名分组**: 根据表名列将字段分组
|
||
|
||
---
|
||
|
||
### 1.3 业务表解析接口
|
||
|
||
#### 基本信息
|
||
|
||
- **路径**: `/api/v1/inventory/parse-business-tables`
|
||
- **方法**: `POST`
|
||
- **描述**: 解析业务人员手动导出的核心业务表（Excel/CSV），支持批量文件解析
|
||
- **优先级**: 中
|
||
|
||
#### 请求格式
|
||
|
||
```json
|
||
{
|
||
"file_paths": [
|
||
"/path/to/orders.xlsx",
|
||
"/path/to/products.csv"
|
||
],
|
||
"project_id": "project_001"
|
||
}
|
||
```
|
||
|
||
**请求参数说明**:
|
||
|
||
| 参数名 | 类型 | 必填 | 说明 |
|
||
|--------|------|------|------|
|
||
| `file_paths` | array | 是 | 文件路径列表（绝对路径） |
|
||
| `project_id` | string | 是 | 项目ID |
|
||
|
||
#### 响应格式
|
||
|
||
**成功响应** (200):
|
||
|
||
```json
|
||
{
|
||
"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"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**失败响应示例** (部分失败):
|
||
|
||
```json
|
||
{
|
||
"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": [...]
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 注意事项
|
||
|
||
1. **批量处理**: 支持一次上传多个文件
|
||
2. **单个文件失败不影响其他**: 单个文件解析失败不会中断整个流程
|
||
3. **Excel 多 Sheet**: 自动识别每个 Sheet 为独立的表
|
||
4. **字段类型推断**: 基于 pandas 类型自动推断数据库字段类型
|
||
|
||
---
|
||
|
||
### 1.4 数据资产智能识别接口
|
||
|
||
#### 基本信息
|
||
|
||
- **路径**: `/api/v1/inventory/ai-analyze`
|
||
- **方法**: `POST`
|
||
- **描述**: 使用大模型识别数据资产的中文名称、业务含义、PII 敏感信息、重要数据特征，并提供置信度评分
|
||
- **优先级**: 高 ⭐⭐⭐
|
||
|
||
#### 请求格式
|
||
|
||
```json
|
||
{
|
||
"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):
|
||
|
||
```json
|
||
{
|
||
"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 视觉模型 |
|
||
|
||
#### 注意事项
|
||
|
||
1. **PII 识别规则**: 除了 AI 识别，还使用规则引擎补充识别（基于关键词）
|
||
2. **置信度评分**: 综合考虑命名规范度、注释完整性、AI 识别结果质量
|
||
3. **重试机制**: API 调用失败会自动重试（最多 3 次，指数退避）
|
||
4. **Token 优化**: 提示词经过优化，减少不必要的 Token 消耗
|
||
|
||
---
|
||
|
||
## 🎯 模块二：场景挖掘智能推荐服务
|
||
|
||
### 2.1 潜在场景推荐接口
|
||
|
||
#### 基本信息
|
||
|
||
- **路径**: `/api/v1/value/scenario-recommendation`
|
||
- **方法**: `POST`
|
||
- **描述**: 基于企业背景、数据资产清单和存量场景，使用 AI 推荐潜在的数据应用场景
|
||
- **优先级**: 高 ⭐⭐
|
||
|
||
#### 请求格式
|
||
|
||
```json
|
||
{
|
||
"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):
|
||
|
||
```json
|
||
{
|
||
"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. **避免重复**: 推荐的场景会与存量场景对比，避免重复
|
||
2. **依赖分析**: 推荐的场景会明确标注依赖的数据资产
|
||
3. **商业价值评估**: 综合考虑业务价值、实施难度、数据准备度
|
||
4. **推荐指数**: 1-5 星评分，综合考虑多个因素
|
||
|
||
---
|
||
|
||
### 2.2 存量场景优化建议接口
|
||
|
||
#### 基本信息
|
||
|
||
- **路径**: `/api/v1/value/scenario-optimization`
|
||
- **方法**: `POST`
|
||
- **描述**: 基于存量场景信息和截图，分析场景不足，提供优化建议
|
||
- **优先级**: 中
|
||
|
||
#### 请求格式
|
||
|
||
```json
|
||
{
|
||
"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):
|
||
|
||
```json
|
||
{
|
||
"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 | 潜在价值描述 |
|
||
|
||
#### 注意事项
|
||
|
||
1. **OCR 功能**: 当前版本未实现图片识别（OCR），仅支持基于文本的场景分析
|
||
2. **建议可操作性**: 优化建议必须具体、可执行
|
||
3. **价值提升**: 识别可提升的价值点
|
||
|
||
---
|
||
|
||
## 📊 模块三：数据资产盘点报告生成服务
|
||
|
||
### 3.1 完整报告生成接口
|
||
|
||
#### 基本信息
|
||
|
||
- **路径**: `/api/v1/delivery/generate-report`
|
||
- **方法**: `POST`
|
||
- **描述**: 基于数据盘点结果、背景调研信息和价值挖掘场景，使用大模型生成完整的数据资产盘点工作总结报告
|
||
- **优先级**: 高 ⭐⭐⭐
|
||
|
||
#### 请求格式
|
||
|
||
```json
|
||
{
|
||
"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):
|
||
|
||
```json
|
||
{
|
||
"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 | 使用的大模型 |
|
||
|
||
#### 注意事项
|
||
|
||
1. **分阶段生成**: 报告采用分阶段生成策略，确保每个章节的质量
|
||
2. **数据验证**: 章节二的数据百分比总和会验证是否为 100%
|
||
3. **合规风险分析**: 章节三会识别符合 PIPL 和数据安全法要求的合规风险
|
||
4. **建议可操作性**: 章节四的建议必须具体、可执行
|
||
|
||
---
|
||
|
||
## 🔐 错误码说明
|
||
|
||
### 通用错误码
|
||
|
||
| 错误码 | 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` | 请求频率过高 | 降低请求频率 |
|
||
|
||
---
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 启动服务
|
||
|
||
```bash
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
|
||
# 配置环境变量
|
||
cp .env.example .env
|
||
# 编辑 .env 文件，填入必要的配置
|
||
|
||
# 启动服务
|
||
python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
|
||
```
|
||
|
||
### 测试接口
|
||
|
||
```bash
|
||
# 测试文档解析接口
|
||
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 |
|