197 lines
5.7 KiB
Markdown
197 lines
5.7 KiB
Markdown
# Finyx Data AI - 数据资产盘点系统后端服务
|
||
|
||
## 📋 项目简介
|
||
|
||
本项目是数据资产盘点系统的后端 API 服务，提供数据资产盘点、场景挖掘和报告生成等功能。
|
||
|
||
## 🏗️ 项目结构
|
||
|
||
```
|
||
finyx_data_ai/
|
||
├── app/ # 应用主目录
|
||
│ ├── api/ # API 路由
|
||
│ │ ├── v1/ # API v1 版本
|
||
│ │ │ ├── inventory/ # 数据盘点模块
|
||
│ │ │ ├── value/ # 场景挖掘模块
|
||
│ │ │ └── delivery/ # 报告生成模块
|
||
│ │ └── common/ # 通用路由
|
||
│ ├── core/ # 核心模块
|
||
│ │ ├── config.py # 配置管理
|
||
│ │ ├── exceptions.py # 异常定义
|
||
│ │ └── response.py # 响应格式
|
||
│ ├── models/ # 数据模型（ORM）
|
||
│ ├── schemas/ # 数据模式（Pydantic）
|
||
│ ├── services/ # 业务逻辑层
|
||
│ ├── utils/ # 工具函数
|
||
│ │ ├── logger.py # 日志配置
|
||
│ │ ├── file_handler.py # 文件处理
|
||
│ │ └── llm_client.py # 大模型客户端
|
||
│ └── main.py # 应用入口
|
||
├── docs/ # 文档目录
|
||
├── logs/ # 日志目录
|
||
├── uploads/ # 上传文件目录
|
||
├── tests/ # 测试目录
|
||
├── requirements.txt # Python 依赖
|
||
├── .env.example # 环境变量示例
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 环境要求
|
||
|
||
- Python 3.10+
|
||
- pip 或 poetry
|
||
|
||
### 2. 安装依赖
|
||
|
||
```bash
|
||
# 创建虚拟环境
|
||
python -m venv venv
|
||
source venv/bin/activate # Linux/Mac
|
||
# 或
|
||
venv\Scripts\activate # Windows
|
||
|
||
# 安装依赖
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 3. 配置环境变量
|
||
|
||
```bash
|
||
# 复制环境变量示例文件
|
||
cp .env.example .env
|
||
|
||
# 编辑 .env 文件，配置必要的环境变量
|
||
# 至少需要配置大模型 API Key（通义千问或 OpenAI）
|
||
```
|
||
|
||
### 4. 启动服务
|
||
|
||
```bash
|
||
# 开发模式（自动重载）
|
||
python -m app.main
|
||
|
||
# 或使用 uvicorn
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
### 5. 访问 API 文档
|
||
|
||
- Swagger UI: http://localhost:8000/docs
|
||
- ReDoc: http://localhost:8000/redoc
|
||
|
||
## 📚 API 接口列表
|
||
|
||
### 模块一：数据盘点智能分析服务
|
||
|
||
| 接口路径 | 方法 | 说明 | 状态 |
|
||
|---------|------|------|------|
|
||
| `/api/v1/inventory/parse-document` | POST | 文档解析接口 | ⏳ 待实现 |
|
||
| `/api/v1/inventory/parse-sql-result` | POST | SQL 结果解析接口 | ⏳ 待实现 |
|
||
| `/api/v1/inventory/parse-business-tables` | POST | 业务表解析接口 | ⏳ 待实现 |
|
||
| `/api/v1/inventory/ai-analyze` | POST | 数据资产智能识别接口 | ⏳ 待实现 |
|
||
|
||
### 模块二：场景挖掘智能推荐服务
|
||
|
||
| 接口路径 | 方法 | 说明 | 状态 |
|
||
|---------|------|------|------|
|
||
| `/api/v1/value/scenario-recommendation` | POST | 潜在场景推荐接口 | ⏳ 待实现 |
|
||
| `/api/v1/value/scenario-optimization` | POST | 存量场景优化建议接口 | ⏳ 待实现 |
|
||
|
||
### 模块三：数据资产盘点报告生成服务
|
||
|
||
| 接口路径 | 方法 | 说明 | 状态 |
|
||
|---------|------|------|------|
|
||
| `/api/v1/delivery/generate-report` | POST | 完整报告生成接口 | ⏳ 待实现 |
|
||
|
||
### 通用接口
|
||
|
||
| 接口路径 | 方法 | 说明 | 状态 |
|
||
|---------|------|------|------|
|
||
| `/api/v1/common/health` | GET | 健康检查 | ✅ 已实现 |
|
||
| `/api/v1/common/version` | GET | 版本信息 | ✅ 已实现 |
|
||
|
||
## 🛠️ 开发指南
|
||
|
||
### 添加新接口
|
||
|
||
1. 在对应的模块路由文件中添加路由函数（如 `app/api/v1/inventory/routes.py`）
|
||
2. 定义请求和响应模型（在 `app/schemas/` 目录下）
|
||
3. 实现业务逻辑（可在 `app/services/` 目录下创建服务类）
|
||
4. 添加异常处理和日志记录
|
||
5. 编写单元测试
|
||
|
||
### 使用大模型客户端
|
||
|
||
```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)
|
||
```
|
||
|
||
### 文件上传处理
|
||
|
||
```python
|
||
from app.utils.file_handler import save_upload_file, detect_file_type
|
||
|
||
# 保存上传文件
|
||
file_path = await save_upload_file(file, project_id="project_001")
|
||
|
||
# 检测文件类型
|
||
file_type = detect_file_type(file.filename)
|
||
```
|
||
|
||
## 📝 开发计划
|
||
|
||
### 第一阶段（MVP）- 高优先级接口
|
||
|
||
- [ ] 数据资产智能识别接口 (`/api/v1/inventory/ai-analyze`)
|
||
- [ ] 完整报告生成接口 (`/api/v1/delivery/generate-report`)
|
||
- [ ] 文档解析接口 (`/api/v1/inventory/parse-document`)
|
||
|
||
### 第二阶段 - 中优先级接口
|
||
|
||
- [ ] 潜在场景推荐接口 (`/api/v1/value/scenario-recommendation`)
|
||
- [ ] 业务表解析接口 (`/api/v1/inventory/parse-business-tables`)
|
||
- [ ] 存量场景优化建议接口 (`/api/v1/value/scenario-optimization`)
|
||
|
||
### 第三阶段 - 低优先级接口
|
||
|
||
- [ ] SQL 结果解析接口 (`/api/v1/inventory/parse-sql-result`)
|
||
|
||
## 🧪 测试
|
||
|
||
```bash
|
||
# 运行测试
|
||
pytest
|
||
|
||
# 运行测试并生成覆盖率报告
|
||
pytest --cov=app --cov-report=html
|
||
```
|
||
|
||
## 📖 详细文档
|
||
|
||
更多详细的接口开发文档请参考 `docs/` 目录：
|
||
|
||
- [API 接口开发文档索引](./docs/README.md)
|
||
- [数据资产盘点报告-大模型接口设计文档](./docs/数据资产盘点报告-大模型接口设计文档.md)
|
||
- [各接口详细开发说明](./docs/)
|
||
|
||
## 📞 联系方式
|
||
|
||
如有问题，请联系开发团队。
|
||
|
||
## 📄 许可证
|
||
|
||
[待填写]
|