# 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/)

## 📞 联系方式

如有问题，请联系开发团队。

## 📄 许可证

[待填写]