python/finyx_data_frontend

Fork 0

李季 0891e67715 完成初版功能页面，提交更新。

2026-01-11 08:26:28 +08:00

15 KiB

Raw Blame History

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

📋 接口总览

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

📊 接口清单表格

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

📈 接口统计汇总

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

🔍 接口详细说明

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

1.1 文档解析接口

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

请求参数:

{
  "file_path": "string",  // 上传文件路径
  "file_type": "excel | word | pdf",
  "project_id": "string"
}

响应格式:

{
  "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 结果文件

请求参数:

{
  "file_path": "string",
  "file_type": "excel | csv",
  "project_id": "string"
}

响应格式: 同 1.1

1.3 业务表解析接口

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

请求参数:

{
  "files": ["file_path1", "file_path2", ...],
  "project_id": "string"
}

响应格式: 同 1.1

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

响应格式:

{
  "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 推荐潜在的数据应用场景

请求参数:

{
  "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"
    }
  ]
}

响应格式:

{
  "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
功能描述: 基于存量场景信息和截图，生成优化建议

请求参数:

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

响应格式:

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

关键要求:

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

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

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

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

请求参数:

{
  "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"
  }
}

响应格式:

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

2. 性能要求

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

3. 错误处理

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

4. 数据安全

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

📅 开发优先级建议

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

优先级顺序:

1.4 数据资产智能识别接口（核心功能，15 人日）
3.1 完整报告生成接口（核心功能，20 人日，简化版）
1.1, 1.2, 1.3 文档解析接口（10 人日）

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

优先级顺序:

2.1 潜在场景推荐接口（12 人日）
2.2 存量场景优化建议接口（8 人日）
3.1 报告生成质量优化（5 人日）

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

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

🔗 相关文档

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

📞 联系方式

如有接口开发相关问题，请联系：

Python 技术负责人: [待填写]
大模型技术顾问: [待填写]
接口对接负责人: [待填写]

📅 更新记录

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

15 KiB Raw Blame History Unescape Escape

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

📋 接口总览

📊 接口清单表格

📈 接口统计汇总

🔍 接口详细说明

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

1.1 文档解析接口

1.2 SQL 结果解析接口

1.3 业务表解析接口

1.4 数据资产智能识别接口 ⭐⭐⭐

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

2.1 潜在场景推荐接口 ⭐⭐

2.2 存量场景优化建议接口

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

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

⚠️ 接口开发注意事项

1. 大模型接口特殊要求

2. 性能要求

3. 错误处理

4. 数据安全

📅 开发优先级建议

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

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

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

🔗 相关文档

📞 联系方式

📅 更新记录

15 KiB

Raw Blame History