# 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`。