321 lines
8.7 KiB
Markdown
321 lines
8.7 KiB
Markdown
# 开发指南
|
||
|
||
## 📋 接口开发清单
|
||
|
||
本框架已经构建完成，包含了所有7个接口的路由占位符。后续需要逐个实现每个接口的具体功能。
|
||
|
||
### 待开发接口列表
|
||
|
||
#### 模块一：数据盘点智能分析服务
|
||
|
||
1. **`/api/v1/inventory/parse-document`** - 文档解析接口
|
||
- 文件位置: `app/api/v1/inventory/routes.py`
|
||
- 状态: ⏳ 待实现
|
||
- 优先级: 中
|
||
- 工作量: 5 人日
|
||
- 参考文档: `docs/01-parse-document.md`
|
||
|
||
2. **`/api/v1/inventory/parse-sql-result`** - SQL 结果解析接口
|
||
- 文件位置: `app/api/v1/inventory/routes.py`
|
||
- 状态: ⏳ 待实现
|
||
- 优先级: 低
|
||
- 工作量: 2 人日
|
||
- 参考文档: `docs/02-parse-sql-result.md`
|
||
|
||
3. **`/api/v1/inventory/parse-business-tables`** - 业务表解析接口
|
||
- 文件位置: `app/api/v1/inventory/routes.py`
|
||
- 状态: ⏳ 待实现
|
||
- 优先级: 中
|
||
- 工作量: 3 人日
|
||
- 参考文档: `docs/03-parse-business-tables.md`
|
||
|
||
4. **`/api/v1/inventory/ai-analyze`** - 数据资产智能识别接口 ⭐⭐⭐
|
||
- 文件位置: `app/api/v1/inventory/routes.py`
|
||
- 状态: ⏳ 待实现
|
||
- 优先级: **高**
|
||
- 工作量: **15 人日**
|
||
- 参考文档: `docs/04-ai-analyze.md`
|
||
- 需要: 大模型集成
|
||
|
||
#### 模块二：场景挖掘智能推荐服务
|
||
|
||
5. **`/api/v1/value/scenario-recommendation`** - 潜在场景推荐接口 ⭐⭐
|
||
- 文件位置: `app/api/v1/value/routes.py`
|
||
- 状态: ⏳ 待实现
|
||
- 优先级: **高**
|
||
- 工作量: **12 人日**
|
||
- 参考文档: `docs/05-scenario-recommendation.md`
|
||
- 需要: 大模型集成
|
||
|
||
6. **`/api/v1/value/scenario-optimization`** - 存量场景优化建议接口
|
||
- 文件位置: `app/api/v1/value/routes.py`
|
||
- 状态: ⏳ 待实现
|
||
- 优先级: 中
|
||
- 工作量: 8 人日
|
||
- 参考文档: `docs/06-scenario-optimization.md`
|
||
- 需要: 大模型集成、OCR
|
||
|
||
#### 模块三：数据资产盘点报告生成服务
|
||
|
||
7. **`/api/v1/delivery/generate-report`** - 完整报告生成接口 ⭐⭐⭐
|
||
- 文件位置: `app/api/v1/delivery/routes.py`
|
||
- 状态: ⏳ 待实现
|
||
- 优先级: **高**
|
||
- 工作量: **20 人日**
|
||
- 参考文档: `docs/07-generate-report.md`、`docs/数据资产盘点报告-大模型接口设计文档.md`
|
||
- 需要: 大模型集成、分阶段生成
|
||
|
||
## 🛠️ 框架使用说明
|
||
|
||
### 1. 配置管理
|
||
|
||
所有配置都在 `app/core/config.py` 中管理，通过环境变量加载。
|
||
|
||
```python
|
||
from app.core.config import settings
|
||
|
||
# 使用配置
|
||
api_key = settings.DASHSCOPE_API_KEY
|
||
max_upload_size = settings.MAX_UPLOAD_SIZE
|
||
```
|
||
|
||
### 2. 统一响应格式
|
||
|
||
使用 `app/core/response.py` 中的响应格式：
|
||
|
||
```python
|
||
from app.core.response import success_response, error_response
|
||
|
||
# 成功响应
|
||
return success_response(
|
||
data={"result": "..."},
|
||
message="操作成功"
|
||
)
|
||
|
||
# 错误响应
|
||
return error_response(
|
||
message="操作失败",
|
||
code=400,
|
||
error_code="ERROR_CODE",
|
||
error_detail="详细信息"
|
||
)
|
||
```
|
||
|
||
### 3. 异常处理
|
||
|
||
使用 `app/core/exceptions.py` 中的自定义异常：
|
||
|
||
```python
|
||
from app.core.exceptions import FileUploadException, LLMAPIException
|
||
|
||
# 抛出异常
|
||
raise FileUploadException("文件上传失败", error_detail="具体错误信息")
|
||
```
|
||
|
||
### 4. 大模型调用
|
||
|
||
使用 `app/utils/llm_client.py` 中的 LLM 客户端：
|
||
|
||
```python
|
||
from app.utils.llm_client import llm_client
|
||
|
||
# 调用大模型
|
||
response = await llm_client.call(
|
||
prompt="你的提示词",
|
||
system_prompt="系统提示词",
|
||
temperature=0.3,
|
||
model="qwen-max"
|
||
)
|
||
|
||
# 解析 JSON 响应
|
||
result = llm_client.parse_json_response(response)
|
||
```
|
||
|
||
### 5. 文件处理
|
||
|
||
使用 `app/utils/file_handler.py` 中的文件处理工具：
|
||
|
||
```python
|
||
from app.utils.file_handler import save_upload_file, detect_file_type, cleanup_temp_file
|
||
|
||
# 保存上传文件
|
||
file_path = await save_upload_file(file, project_id="project_001")
|
||
|
||
# 检测文件类型
|
||
file_type = detect_file_type(file.filename)
|
||
|
||
# 清理临时文件
|
||
cleanup_temp_file(file_path)
|
||
```
|
||
|
||
### 6. 日志记录
|
||
|
||
使用 `app/utils/logger.py` 中的日志工具：
|
||
|
||
```python
|
||
from app.utils.logger import logger
|
||
|
||
logger.info("信息日志")
|
||
logger.warning("警告日志")
|
||
logger.error("错误日志")
|
||
logger.exception("异常日志（带堆栈）")
|
||
```
|
||
|
||
## 📝 开发步骤示例
|
||
|
||
以开发 `parse-document` 接口为例：
|
||
|
||
### 步骤 1: 定义请求和响应模型
|
||
|
||
在 `app/schemas/` 目录下创建或更新模型文件：
|
||
|
||
```python
|
||
# app/schemas/inventory.py
|
||
from pydantic import BaseModel
|
||
from typing import Optional, List
|
||
from app.schemas.common import TableInfo
|
||
|
||
class ParseDocumentRequest(BaseModel):
|
||
project_id: str
|
||
file_type: Optional[str] = None # 可选，自动识别
|
||
|
||
class ParseDocumentResponse(BaseModel):
|
||
tables: List[TableInfo]
|
||
total_tables: int
|
||
total_fields: int
|
||
parse_time: float
|
||
file_info: dict
|
||
```
|
||
|
||
### 步骤 2: 实现业务逻辑
|
||
|
||
在 `app/services/` 目录下创建服务类：
|
||
|
||
```python
|
||
# app/services/document_parser.py
|
||
from app.utils.file_handler import detect_file_type
|
||
import pandas as pd
|
||
|
||
class DocumentParser:
|
||
@staticmethod
|
||
async def parse_excel(file_path: str) -> List[TableInfo]:
|
||
# 实现 Excel 解析逻辑
|
||
pass
|
||
|
||
@staticmethod
|
||
async def parse_word(file_path: str) -> List[TableInfo]:
|
||
# 实现 Word 解析逻辑
|
||
pass
|
||
```
|
||
|
||
### 步骤 3: 实现路由处理函数
|
||
|
||
在 `app/api/v1/inventory/routes.py` 中实现：
|
||
|
||
```python
|
||
from fastapi import UploadFile, File, Form
|
||
from app.schemas.inventory import ParseDocumentRequest, ParseDocumentResponse
|
||
from app.services.document_parser import DocumentParser
|
||
from app.core.response import success_response
|
||
from app.utils.file_handler import save_upload_file, detect_file_type
|
||
|
||
@router.post("/parse-document", response_model=ParseDocumentResponse)
|
||
async def parse_document(
|
||
file: UploadFile = File(...),
|
||
project_id: str = Form(...),
|
||
file_type: Optional[str] = Form(None)
|
||
):
|
||
"""文档解析接口"""
|
||
try:
|
||
# 保存文件
|
||
file_path = await save_upload_file(file, project_id)
|
||
|
||
# 检测文件类型
|
||
if not file_type:
|
||
file_type = detect_file_type(file.filename)
|
||
|
||
# 解析文件
|
||
parser = DocumentParser()
|
||
if file_type == "excel":
|
||
tables = await parser.parse_excel(file_path)
|
||
elif file_type == "word":
|
||
tables = await parser.parse_word(file_path)
|
||
else:
|
||
raise ValueError(f"不支持的文件类型: {file_type}")
|
||
|
||
# 返回结果
|
||
return success_response(
|
||
data={
|
||
"tables": [table.dict() for table in tables],
|
||
"total_tables": len(tables),
|
||
"total_fields": sum(t.field_count for t in tables),
|
||
"parse_time": 0.0, # 实际计算耗时
|
||
"file_info": {
|
||
"file_name": file.filename,
|
||
"file_type": file_type
|
||
}
|
||
},
|
||
message="文档解析成功"
|
||
)
|
||
except Exception as e:
|
||
# 异常已在全局异常处理器中处理
|
||
raise
|
||
```
|
||
|
||
### 步骤 4: 编写测试
|
||
|
||
在 `tests/` 目录下创建测试文件：
|
||
|
||
```python
|
||
# tests/test_inventory.py
|
||
import pytest
|
||
from fastapi.testclient import TestClient
|
||
|
||
def test_parse_document(client: TestClient):
|
||
with open("test_data/sample.xlsx", "rb") as f:
|
||
response = client.post(
|
||
"/api/v1/inventory/parse-document",
|
||
files={"file": ("test.xlsx", f, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet")},
|
||
data={"project_id": "test_project"}
|
||
)
|
||
|
||
assert response.status_code == 200
|
||
data = response.json()
|
||
assert data["success"] is True
|
||
assert "tables" in data["data"]
|
||
```
|
||
|
||
## 🎯 开发建议
|
||
|
||
### 优先级顺序
|
||
|
||
1. **第一阶段（MVP）**:
|
||
- 数据资产智能识别接口 (`ai-analyze`)
|
||
- 完整报告生成接口 (`generate-report`)
|
||
- 文档解析接口 (`parse-document`)
|
||
|
||
2. **第二阶段**:
|
||
- 潜在场景推荐接口 (`scenario-recommendation`)
|
||
- 业务表解析接口 (`parse-business-tables`)
|
||
- 存量场景优化建议接口 (`scenario-optimization`)
|
||
|
||
3. **第三阶段**:
|
||
- SQL 结果解析接口 (`parse-sql-result`)
|
||
|
||
### 代码规范
|
||
|
||
- 使用类型注解
|
||
- 添加文档字符串（docstring）
|
||
- 遵循 PEP 8 代码风格
|
||
- 编写单元测试
|
||
- 添加日志记录
|
||
- 处理异常情况
|
||
|
||
### 注意事项
|
||
|
||
1. **大模型接口**: 注意 Token 消耗和 API 限流
|
||
2. **文件处理**: 及时清理临时文件，限制文件大小
|
||
3. **错误处理**: 提供清晰的错误信息和错误码
|
||
4. **性能优化**: 对于耗时操作，考虑异步处理或任务队列
|
||
5. **安全性**: 验证文件类型和大小，防止路径遍历攻击
|