# 数据资源盘点系统 - Python 接口开发清单

## 📋 接口总览

本文档以表格形式罗列数据资源盘点系统中所有需要 Python 技术人员开发的接口及其详细说明。

---

## 📊 接口清单表格

| 序号 | 接口路径 | 请求方法 | 功能描述 | 涉及页面 | 是否大模型 | 工作量（人日） | 优先级 | 技术栈 | 备注 |
|------|---------|---------|---------|---------|-----------|--------------|--------|--------|------|
| **模块一：数据盘点智能分析服务** |
| 1.1 | `/api/v1/inventory/parse-document` | POST | 文档解析接口<br/>解析上传的数据字典文档（Excel/Word/PDF），提取表结构信息（表名、字段名、字段类型、注释） | `InventoryStep.vue`<br/>方案一（已有文档导入） | ❌ 否 | 5 | 中 | `openpyxl` / `pandas`<br/>`python-docx`<br/>`pdfplumber` | 支持 Excel/Word/PDF<br/>提取表结构信息 |
| 1.2 | `/api/v1/inventory/parse-sql-result` | POST | SQL 结果解析接口<br/>解析 IT 执行 SQL 脚本后导出的 Excel/CSV 结果文件，提取表名、字段名、字段类型等信息 | `InventoryStep.vue`<br/>方案二（IT 脚本提取） | ❌ 否 | 2 | 低 | `pandas` | 支持 Excel/CSV<br/>数据验证和清洗 |
| 1.3 | `/api/v1/inventory/parse-business-tables` | POST | 业务表解析接口<br/>解析业务人员手动导出的核心业务表（Excel/CSV），支持批量文件解析和表结构识别 | `InventoryStep.vue`<br/>方案三（业务关键表导入） | ❌ 否 | 3 | 中 | `pandas` | 批量文件处理<br/>异常处理和进度反馈 |
| 1.4 | `/api/v1/inventory/ai-analyze` | POST | 数据资产智能识别接口 ⭐⭐⭐<br/>使用大模型识别数据资产的中文名称、业务含义、PII 敏感信息、重要数据特征，并提供置信度评分 | `InventoryStep.vue`<br/>AI 盘点处理阶段 | ✅ **是** | **15** | **高** | `通义千问` / `文心一言` / `GPT-4`<br/>提示词工程<br/>PII 识别规则引擎 | **核心功能**<br/>PII 识别需符合 PIPL<br/>重要数据识别需符合《数据安全法》 |
| **模块二：场景挖掘智能推荐服务** |
| 2.1 | `/api/v1/value/scenario-recommendation` | POST | 潜在场景推荐接口 ⭐⭐<br/>基于企业背景、数据资产清单和存量场景，使用 AI 推荐潜在的数据应用场景，包括场景分类、推荐指数评分（1-5星）和场景依赖分析 | `ValueStep.vue`<br/>AI 推荐潜在场景清单 | ✅ **是** | **12** | **高** | `通义千问` / `文心一言` / `GPT-4`<br/>提示词工程<br/>场景分类算法 | 场景分类：降本增效、营销增长、金融服务、决策支持等 |
| 2.2 | `/api/v1/value/scenario-optimization` | POST | 存量场景优化建议接口<br/>基于存量场景信息和截图，分析场景不足，提供优化建议和改进方向，识别可提升的价值点（支持图片识别 OCR） | `ContextStep.vue`<br/>生成场景挖掘与优化建议按钮 | ✅ **是** | 8 | 中 | `通义千问` / `文心一言` / `GPT-4`<br/>`PaddleOCR` (OCR) | 支持场景截图识别<br/>文本分析和建议生成 |
| **模块三：数据资产盘点报告生成服务** |
| 3.1 | `/api/v1/delivery/generate-report` | POST | 完整报告生成接口 ⭐⭐⭐<br/>基于数据盘点结果、背景调研信息和价值挖掘场景，使用大模型生成完整的数据资产盘点工作总结报告（四个章节），支持分阶段生成、内容验证和格式化 | `DeliveryStep.vue`<br/>成果交付页面 | ✅ **是** | **20** | **高** | `GPT-4` / `通义千问 Max`<br/>提示词工程（多章节）<br/>数据验证引擎 | **核心功能**<br/>长文本生成<br/>分阶段生成策略<br/>合规性检查 |

---

## 📈 接口统计汇总

| 统计项 | 数量 |
|--------|------|
| **接口总数** | **7** |
| 涉及大模型接口 | 4 |
| 非大模型接口 | 3 |
| **总工作量（人日）** | **65** |
| 大模型接口工作量 | 47 (72%) |
| 非大模型接口工作量 | 18 (28%) |

---

## 🔍 接口详细说明

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

#### 1.1 文档解析接口

**接口路径**: `/api/v1/inventory/parse-document`  
**请求方法**: `POST`  
**功能描述**: 解析上传的数据字典文档（Excel/Word/PDF），提取表结构信息

**请求参数**:
```json
{
  "file_path": "string",  // 上传文件路径
  "file_type": "excel | word | pdf",
  "project_id": "string"
}
```

**响应格式**:
```json
{
  "success": true,
  "data": {
    "tables": [
      {
        "raw_name": "t_user_base_01",
        "fields": [
          {
            "raw_name": "user_id",
            "type": "varchar(64)",
            "comment": ""
          }
        ]
      }
    ],
    "total_tables": 10
  }
}
```

---

#### 1.2 SQL 结果解析接口

**接口路径**: `/api/v1/inventory/parse-sql-result`  
**请求方法**: `POST`  
**功能描述**: 解析 IT 执行 SQL 脚本后导出的 Excel/CSV 结果文件

**请求参数**:
```json
{
  "file_path": "string",
  "file_type": "excel | csv",
  "project_id": "string"
}
```

**响应格式**: 同 1.1

---

#### 1.3 业务表解析接口

**接口路径**: `/api/v1/inventory/parse-business-tables`  
**请求方法**: `POST`  
**功能描述**: 解析业务人员手动导出的核心业务表（Excel/CSV），支持批量文件解析

**请求参数**:
```json
{
  "files": ["file_path1", "file_path2", ...],
  "project_id": "string"
}
```

**响应格式**: 同 1.1

---

#### 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": "手机号"
        }
      ]
    }
  ],
  "project_id": "string",
  "industry": "string",
  "context": "string"
}
```

**响应格式**:
```json
{
  "success": true,
  "data": {
    "tables": [
      {
        "raw_name": "t_user_base_01",
        "ai_name": "会员基础信息表",
        "desc": "存储C端注册用户的核心身份信息",
        "fields": [
          {
            "raw_name": "user_id",
            "ai_name": "用户ID",
            "desc": "用户的唯一标识符"
          },
          {
            "raw_name": "phone",
            "ai_name": "手机号",
            "desc": "用户的联系电话",
            "pii": ["手机号"],
            "pii_type": "contact"
          }
        ],
        "pii": ["手机号"],
        "important": false,
        "confidence": 98,
        "ai_completed": true
      }
    ],
    "processing_time": 5.2
  }
}
```

**关键要求**:
- PII 识别必须符合《个人信息保护法》(PIPL)
- 重要数据识别必须符合《数据安全法》
- 置信度评分需考虑字段命名规范度、注释完整性等因素
- 提示词工程需要提供 5-10 个典型示例

---

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

#### 2.1 潜在场景推荐接口 ⭐⭐

**接口路径**: `/api/v1/value/scenario-recommendation`  
**请求方法**: `POST`  
**功能描述**: 基于企业背景、数据资产清单和存量场景，使用 AI 推荐潜在的数据应用场景

**请求参数**:
```json
{
  "project_id": "string",
  "company_info": {
    "industry": ["retail-fresh"],
    "description": "某连锁生鲜零售企业...",
    "data_scale": "100TB",
    "data_sources": ["self-generated"]
  },
  "data_assets": [
    {
      "name": "会员基础信息表",
      "core_tables": ["Dim_Customer"],
      "description": "存储C端注册用户的核心身份信息"
    }
  ],
  "existing_scenarios": [
    {
      "name": "月度销售经营报表",
      "description": "统计各区域门店的月度GMV"
    }
  ]
}
```

**响应格式**:
```json
{
  "success": true,
  "data": {
    "recommended_scenarios": [
      {
        "id": 1,
        "name": "精准会员营销",
        "type": "营销增长",
        "recommendation_index": 5,
        "desc": "基于用户画像与历史交易行为，实现千人千面的优惠券发放。",
        "dependencies": ["会员基础信息表", "订单流水记录表"],
        "business_value": "提升复购率 15-20%",
        "implementation_difficulty": "中等"
      }
    ],
    "total_count": 10
  }
}
```

**关键要求**:
- 场景分类：降本增效、营销增长、金融服务、决策支持等
- 推荐指数评分（1-5星）
- 综合考虑业务价值、实施难度、数据准备度等因素
- 避免与存量场景重复推荐

---

#### 2.2 存量场景优化建议接口

**接口路径**: `/api/v1/value/scenario-optimization`  
**请求方法**: `POST`  
**功能描述**: 基于存量场景信息和截图，生成优化建议

**请求参数**:
```json
{
  "existing_scenarios": [
    {
      "name": "月度销售经营报表",
      "description": "统计各区域门店的月度GMV，维度单一",
      "image_url": "string"  // 可选，场景截图
    }
  ],
  "data_assets": [...],
  "company_info": {...}
}
```

**响应格式**:
```json
{
  "success": true,
  "data": {
    "optimization_suggestions": [
      {
        "scenario_name": "月度销售经营报表",
        "current_status": "维度单一，仅统计GMV",
        "suggestions": [
          "增加时间维度分析（同比、环比）",
          "增加商品类别维度分析",
          "增加区域对比分析"
        ],
        "potential_value": "提升决策支持能力 30%"
      }
    ]
  }
}
```

**关键要求**:
- 支持图片识别（OCR），如果上传了场景截图
- 分析存量场景的不足
- 提供可操作的优化建议
- 识别可提升的价值点

---

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

#### 3.1 完整报告生成接口 ⭐⭐⭐

**接口路径**: `/api/v1/delivery/generate-report`  
**请求方法**: `POST`  
**功能描述**: 基于数据盘点结果、背景调研信息和价值挖掘场景，使用大模型生成完整的数据资产盘点工作总结报告（四个章节）

**请求参数**:
```json
{
  "project_id": "string",
  "project_info": {
    "project_name": "数据资产盘点项目",
    "industry": "retail-fresh",
    "company_name": "某连锁生鲜零售企业"
  },
  "inventory_data": {
    "total_tables": 14582,
    "total_fields": 245000,
    "total_data_volume": "58 PB",
    "storage_distribution": [...],
    "data_source_structure": {
      "structured": 35,
      "semi_structured": 65
    },
    "identified_assets": [...]
  },
  "context_data": {
    "enterprise_background": "...",
    "informatization_status": "...",
    "business_flow": "..."
  },
  "value_data": {
    "selected_scenarios": [...]
  },
  "options": {
    "language": "zh-CN",
    "detail_level": "standard"
  }
}
```

**响应格式**:
```json
{
  "success": true,
  "data": {
    "header": {
      "project_name": "数据资产盘点项目"
    },
    "section1": {
      "enterprise_background": {...},
      "informatization_status": {...},
      "business_data_flow": {...}
    },
    "section2": {
      "summary": {...},
      "storage_distribution": [...],
      "data_source_structure": {...}
    },
    "section3": {
      "overview": {...},
      "assets": [...]
    },
    "section4": {
      "compliance_remediation": {...},
      "technical_evolution": {...},
      "value_deepening": {...}
    }
  },
  "metadata": {
    "generation_time": 25.3,
    "model_used": "gpt-4",
    "token_count": 8500
  }
}
```

**报告章节说明**:
- **章节一**: 企业数字化情况简介（企业背景、信息化建设现状、业务流与数据流）
- **章节二**: 数据资源统计（数据总量、存储分布、数据来源结构）
- **章节三**: 数据资产情况盘点（资产构成、应用场景、合规风险提示）
- **章节四**: 专家建议与下一步计划（合规整改、技术演进、价值深化）

**关键要求**:
- 统计数据必须准确，基于输入数据
- 合规风险分析必须符合 PIPL、数据安全法等法规
- 专家建议必须具体、可执行
- 支持分阶段生成（可选，建议用于生产环境）
- 数据验证（百分比总和为100%等）
- 合规性验证（风险分析完整性）

---

## ⚠️ 接口开发注意事项

### 1. 大模型接口特殊要求

| 接口 | 特殊要求 |
|------|---------|
| `/api/v1/inventory/ai-analyze` | 1. PII 识别需符合 PIPL<br/>2. 重要数据识别需符合《数据安全法》<br/>3. 置信度评分算法<br/>4. 提示词工程需要示例学习 |
| `/api/v1/value/scenario-recommendation` | 1. 场景分类算法<br/>2. 推荐指数评分算法<br/>3. 场景依赖关系分析<br/>4. 避免重复推荐 |
| `/api/v1/value/scenario-optimization` | 1. OCR 图片识别（如需要）<br/>2. 文本分析和建议生成<br/>3. 价值点识别 |
| `/api/v1/delivery/generate-report` | 1. 长文本生成能力<br/>2. 分阶段生成策略<br/>3. 数据验证和合规性检查<br/>4. 四个章节的提示词工程 |

### 2. 性能要求

- **异步处理**: 大模型接口应支持异步处理，返回任务 ID，前端轮询结果
- **流式输出**: 报告生成接口可考虑流式输出，提升用户体验
- **缓存机制**: 相同输入建议缓存结果，减少 API 调用成本
- **限流熔断**: 防止大模型 API 调用过多导致成本过高

### 3. 错误处理

- 所有接口需返回统一的错误格式
- 完善的错误码和错误信息
- 记录详细的日志，便于问题排查
- 大模型 API 调用失败时的降级策略

### 4. 数据安全

- **数据脱敏**: 在调用大模型 API 前，对敏感数据进行脱敏处理
- **API 密钥管理**: 使用安全的密钥管理方案
- **隐私保护**: 确保输入数据中的敏感信息不会泄露

---

## 📅 开发优先级建议

### 第一阶段（MVP 版本）- 4 周

**优先级顺序**:
1. **1.4** 数据资产智能识别接口（核心功能，15 人日）
2. **3.1** 完整报告生成接口（核心功能，20 人日，简化版）
3. **1.1, 1.2, 1.3** 文档解析接口（10 人日）

### 第二阶段（完善版本）- 3 周

**优先级顺序**:
1. **2.1** 潜在场景推荐接口（12 人日）
2. **2.2** 存量场景优化建议接口（8 人日）
3. **3.1** 报告生成质量优化（5 人日）

### 第三阶段（优化版本）- 2 周

- 提示词优化和 A/B 测试
- 缓存机制实现
- 异步处理和流式输出
- 单元测试和集成测试

---

## 🔗 相关文档

- [Python技术人员工作量文档](./Python技术人员工作量文档.md) - 详细的功能模块分析和工作量评估
- [数据资产盘点报告-大模型接口设计文档](./数据资产盘点报告-大模型接口设计文档.md) - 报告生成接口的详细设计
- [前端开发规范](./前端开发规范.md) - 前端对接规范

---

## 📞 联系方式

如有接口开发相关问题，请联系：
- **Python 技术负责人**: [待填写]
- **大模型技术顾问**: [待填写]
- **接口对接负责人**: [待填写]

---

## 📅 更新记录

| 版本 | 日期 | 更新内容 | 作者 |
|------|------|---------|------|
| v1.0 | 2025-01-XX | 初始版本创建，包含 7 个接口清单 | AI Assistant |