147 lines
5.5 KiB
Markdown
147 lines
5.5 KiB
Markdown
# 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`。
|