# 接口开发说明 - 完整报告生成接口 ⭐⭐⭐

## 📋 接口基本信息

- **接口路径**: `/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)