151 lines
4.7 KiB
Markdown
151 lines
4.7 KiB
Markdown
# 接口开发说明 - 完整报告生成接口 ⭐⭐⭐
|
||
|
||
## 📋 接口基本信息
|
||
|
||
- **接口路径**: `/api/v1/delivery/generate-report`
|
||
- **请求方法**: `POST`
|
||
- **接口功能**: 基于数据盘点结果、背景调研信息和价值挖掘场景，使用大模型生成完整的数据资产盘点工作总结报告（四个章节）
|
||
- **涉及页面**: `DeliveryStep.vue` - 成果交付页面
|
||
- **是否涉及大模型**: ✅ **是**（核心功能）
|
||
- **工作量评估**: **20 人日**
|
||
- **优先级**: **高**
|
||
|
||
---
|
||
|
||
## 🎯 功能描述
|
||
|
||
该接口是数据资产盘点系统的核心输出功能，使用大模型生成完整的工作总结报告，包含四个章节：
|
||
|
||
1. **章节一**: 企业数字化情况简介（企业背景、信息化建设现状、业务流与数据流）
|
||
2. **章节二**: 数据资源统计（数据总量、存储分布、数据来源结构）
|
||
3. **章节三**: 数据资产情况盘点（资产构成、应用场景、合规风险提示）
|
||
4. **章节四**: 专家建议与下一步计划（合规整改、技术演进、价值深化）
|
||
|
||
支持功能：
|
||
- **分阶段生成**: 支持分阶段生成，提高质量和可控性
|
||
- **内容验证**: 验证统计数据逻辑正确性（如百分比总和为100%）
|
||
- **合规性检查**: 验证合规风险分析的完整性
|
||
- **格式化输出**: 返回结构化的 JSON 格式
|
||
|
||
---
|
||
|
||
## 📥 请求格式
|
||
|
||
```json
|
||
{
|
||
"project_id": "project_001",
|
||
"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",
|
||
"generation_mode": "full | staged"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 📤 响应格式
|
||
|
||
详见《数据资产盘点报告-大模型接口设计文档.md》中的详细响应格式定义。
|
||
|
||
---
|
||
|
||
## 💻 实现要点
|
||
|
||
### 1. 分阶段生成策略（推荐）
|
||
|
||
```python
|
||
# 阶段一：生成章节一和章节二
|
||
stage1_result = await generate_sections_1_2(inventory_data, context_data)
|
||
|
||
# 阶段二：生成章节三（重点合规风险分析）
|
||
stage2_result = await generate_section_3(identified_assets, stage1_result)
|
||
|
||
# 阶段三：生成章节四（基于前面章节的分析结果）
|
||
stage3_result = await generate_section_4(stage1_result, stage2_result, value_data)
|
||
```
|
||
|
||
### 2. 数据验证
|
||
|
||
```python
|
||
def validate_report_data(report_data: dict) -> bool:
|
||
"""验证报告数据"""
|
||
# 验证百分比总和为100%
|
||
section2 = report_data.get("section2", {})
|
||
structured = section2.get("data_source_structure", {}).get("structured", {}).get("percentage", 0)
|
||
semi_structured = section2.get("data_source_structure", {}).get("semi_structured", {}).get("percentage", 0)
|
||
|
||
if structured + semi_structured != 100:
|
||
raise ValueError("数据来源结构百分比总和必须为100%")
|
||
|
||
# 验证合规风险分析完整性
|
||
section3 = report_data.get("section3", {})
|
||
assets = section3.get("assets", [])
|
||
|
||
for asset in assets:
|
||
if not asset.get("compliance_risks", {}).get("warnings"):
|
||
logger.warning(f"资产 {asset.get('title')} 缺少合规风险分析")
|
||
|
||
return True
|
||
```
|
||
|
||
### 3. 提示词模板
|
||
|
||
详见《数据资产盘点报告-大模型接口设计文档.md》中的提示词工程设计方案。
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **长文本生成**: 需要使用支持长文本的模型（GPT-4 / 通义千问 Max）
|
||
2. **Token 消耗**: 报告生成会消耗大量 Token，需要优化提示词
|
||
3. **数据准确性**: 统计数据必须准确，基于输入数据
|
||
4. **合规性**: 合规风险分析必须符合 PIPL、数据安全法等法规
|
||
5. **建议可操作性**: 专家建议必须具体、可执行
|
||
|
||
---
|
||
|
||
## 📝 开发检查清单
|
||
|
||
- [ ] 大模型集成（GPT-4 / 通义千问 Max）
|
||
- [ ] 分阶段生成策略实现
|
||
- [ ] 四个章节的提示词工程
|
||
- [ ] 数据验证引擎
|
||
- [ ] 合规性验证
|
||
- [ ] 错误处理和重试机制
|
||
- [ ] 缓存机制（可选）
|
||
- [ ] 日志记录
|
||
- [ ] 单元测试
|
||
|
||
---
|
||
|
||
## 🔗 相关文档
|
||
|
||
- [数据资产盘点报告-大模型接口设计文档](../数据资产盘点报告-大模型接口设计文档.md) - **详细设计文档**
|
||
- [接口清单表格](../Python接口清单表格.md)
|
||
- [Python技术人员工作量文档](../Python技术人员工作量文档.md)
|