483 lines
15 KiB
Markdown
483 lines
15 KiB
Markdown
# 数据资源盘点系统 - 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 |
|