finyx_data_ai/README.md

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. 安装依赖

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

3. 配置环境变量

# 复制环境变量示例文件
cp .env.example .env

# 编辑 .env 文件，配置必要的环境变量
# 至少需要配置大模型 API Key（通义千问或 OpenAI）

4. 启动服务

# 开发模式（自动重载）
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. 编写单元测试

使用大模型客户端

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)

文件上传处理

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)

🧪 测试

# 运行测试
pytest

# 运行测试并生成覆盖率报告
pytest --cov=app --cov-report=html

📖 详细文档

更多详细的接口开发文档请参考 docs/ 目录：

• API 接口开发文档索引
• 数据资产盘点报告-大模型接口设计文档
• 各接口详细开发说明

📞 联系方式

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

📄 许可证

[待填写]