finyx_data_ai/API_OVERVIEW.md

API 接口总览

📊 接口统计

• 总接口数: 9 个
• 已实现: 2 个（通用接口）
• 待实现: 7 个（业务接口）

🗂️ 接口分类

模块一：数据盘点智能分析服务 (4 个接口)

序号	接口路径	方法	功能	是否大模型	优先级	状态
1.1	/api/v1/inventory/parse-document	POST	文档解析接口	❌	中	⏳ 待实现
1.2	/api/v1/inventory/parse-sql-result	POST	SQL 结果解析接口	❌	低	⏳ 待实现
1.3	/api/v1/inventory/parse-business-tables	POST	业务表解析接口	❌	中	⏳ 待实现
1.4	/api/v1/inventory/ai-analyze	POST	数据资产智能识别接口	✅	高	⏳ 待实现

模块二：场景挖掘智能推荐服务 (2 个接口)

序号	接口路径	方法	功能	是否大模型	优先级	状态
2.1	/api/v1/value/scenario-recommendation	POST	潜在场景推荐接口	✅	高	⏳ 待实现
2.2	/api/v1/value/scenario-optimization	POST	存量场景优化建议接口	✅	中	⏳ 待实现

模块三：数据资产盘点报告生成服务 (1 个接口)

序号	接口路径	方法	功能	是否大模型	优先级	状态
3.1	/api/v1/delivery/generate-report	POST	完整报告生成接口	✅	高	⏳ 待实现

通用接口 (2 个接口)

序号	接口路径	方法	功能	状态
-	/api/v1/common/health	GET	健康检查	✅ 已实现
-	/api/v1/common/version	GET	版本信息	✅ 已实现

🎯 开发优先级

🔴 高优先级（核心功能）

1. 数据资产智能识别接口 (/api/v1/inventory/ai-analyze)

   • 工作量: 15 人日
   • 技术难点: 大模型集成、PII识别、合规性检查
   • 参考文档: docs/04-ai-analyze.md

2. 完整报告生成接口 (/api/v1/delivery/generate-report)

   • 工作量: 20 人日
   • 技术难点: 分阶段生成、长文本处理、数据验证
   • 参考文档: docs/07-generate-report.md、docs/数据资产盘点报告-大模型接口设计文档.md

3. 潜在场景推荐接口 (/api/v1/value/scenario-recommendation)

   • 工作量: 12 人日
   • 技术难点: 场景识别、推荐算法
   • 参考文档: docs/05-scenario-recommendation.md

🟡 中优先级

4. 文档解析接口 (/api/v1/inventory/parse-document)

   • 工作量: 5 人日
   • 技术难点: 多格式文档解析（Excel/Word/PDF）
   • 参考文档: docs/01-parse-document.md

5. 业务表解析接口 (/api/v1/inventory/parse-business-tables)

   • 工作量: 3 人日
   • 技术难点: 批量文件处理
   • 参考文档: docs/03-parse-business-tables.md

6. 存量场景优化建议接口 (/api/v1/value/scenario-optimization)

   • 工作量: 8 人日
   • 技术难点: OCR、场景分析
   • 参考文档: docs/06-scenario-optimization.md

🟢 低优先级

7. SQL 结果解析接口 (/api/v1/inventory/parse-sql-result)
   • 工作量: 2 人日
   • 技术难点: CSV/Excel 解析、编码处理
   • 参考文档: docs/02-parse-sql-result.md

📁 文件组织结构

app/
├── api/
│   ├── v1/
│   │   ├── inventory/
│   │   │   └── routes.py      # 模块一：4个接口的路由
│   │   ├── value/
│   │   │   └── routes.py      # 模块二：2个接口的路由
│   │   └── delivery/
│   │       └── routes.py      # 模块三：1个接口的路由
│   └── common/
│       └── routes.py          # 通用接口：2个接口
├── core/
│   ├── config.py              # 配置管理
│   ├── exceptions.py          # 异常定义
│   └── response.py            # 响应格式
├── schemas/
│   ├── common.py              # 通用模型
│   └── [模块名].py            # 各模块的数据模型（待创建）
├── services/
│   └── [服务名].py            # 业务逻辑层（待创建）
├── utils/
│   ├── logger.py              # 日志工具
│   ├── file_handler.py        # 文件处理工具
│   └── llm_client.py          # 大模型客户端
└── main.py                    # 应用入口

🔧 框架特性

✅ 已实现

• ✅ FastAPI 应用框架
• ✅ 统一响应格式
• ✅ 异常处理机制
• ✅ 配置管理系统
• ✅ 日志系统
• ✅ 大模型客户端封装
• ✅ 文件处理工具
• ✅ CORS 配置
• ✅ API 文档自动生成（Swagger/ReDoc）
• ✅ 路由组织（按模块划分）

⏳ 待实现（接口具体功能）

• ⏳ 7 个业务接口的具体实现
• ⏳ 各接口的数据模型定义（Schemas）
• ⏳ 业务逻辑层（Services）
• ⏳ 单元测试
• ⏳ 集成测试

🚀 下一步开发步骤

1. 选择第一个接口（建议：ai-analyze 或 parse-document）
2. 阅读对应文档（在 docs/ 目录下）
3. 创建数据模型（在 app/schemas/ 目录下）
4. 实现业务逻辑（在 app/services/ 目录下或直接在路由中）
5. 完善路由处理函数（在对应的 routes.py 文件中）
6. 编写单元测试（在 tests/ 目录下）
7. 测试和调试

详细开发指南请参考 DEVELOPMENT.md。