# 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 |