# lan-engine

**Repository Path**: lanqi-fintech/lan-engine

## Basic Information

- **Project Name**: lan-engine
- **Description**: 金融报告书写引擎
- **Primary Language**: Python
- **License**: Apache-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2025-09-19
- **Last Updated**: 2026-05-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: llm, Python

## README

# lan-engine

## 介绍

lan-engine 是一款以"提升研报生成效率"为核心目标的智能化系统。该系统通过"流程编排技术"与 ChatReport 思路的深度结合，实现研报写作流程的标准化、自动化与智能化。

### 核心功能

- **商业分析报告自动生成**：当请求包含"公司"和"商业分析报告"关键词时，自动使用预设大纲生成完整的商业分析报告（约5万字）
- **多源素材整合**：自动检索数据库中的相关素材，生成内容丰富的专业报告
- **MCP 工具集成**：支持通过 MCP 协议调用多种报告生成工具

## 软件架构

```
lan-engine/
├── app-cors.py          # Flask API 服务（主入口）
├── server.py            # MCP 服务端
├── mcp_client.py        # MCP 客户端
├── report_generator.py  # 报告生成核心模块
├── mysql_database.py    # 数据库管理
├── chunk_processor.py   # 文档切片处理
├── chart_description_generator.py  # 图表描述生成
├── docx_to_md.py        # 文档格式转换
├── tests/               # 测试套件
│   ├── conftest.py      # pytest 配置
│   ├── test_mysql_database.py
│   ├── test_report_generator.py
│   ├── test_chunk_processor.py
│   └── test_api.py
├── pytest.ini           # pytest 配置文件
├── run_tests.sh         # 测试运行脚本
└── docker/              # Docker 部署配置
```

### 架构说明

1. **API 服务层** (`app-cors.py`)
   - 提供 RESTful API 接口
   - 智能识别商业分析报告请求
   - 文件上传与管理

2. **报告生成引擎** (`report_generator.py`)
   - 大纲解析与层级识别
   - 动态字数分配算法
   - 基于 LLM 的内容生成
   - 素材检索与整合

3. **数据处理模块**
   - 文档切片与向量化存储
   - 多格式文件解析（PDF、DOCX、MD 等）
   - 关键信息抽取

4. **MCP 工具服务** (`server.py`)
   - `generate_report_from_outline`: 根据大纲生成报告
   - `generate_report_content`: 生成报告内容
   - `generate_report_from_references`: 根据参考资料生成报告
   - `get_report_keyinfo`: 获取报告关键信息

## 安装教程

### 环境变量配置

在开始部署之前，需要先配置环境变量：

1. **复制环境变量模板文件**：
   ```bash
   cp .env.example .env
   ```

2. **修改环境变量文件**：
   打开 `.env` 文件，根据您的实际配置修改以下参数：
   ```bash
   # client 配置
   LLM_API_KEY="your_llm_api_key_here"          # 替换为你的LLM API密钥
   LLM_BASE_URL="https://your-llm-api-endpoint.com"    # 替换为LLM API基础地址
   
   # OCR 配置
   TEXTIN_APP_ID="your_textin_app_id_here"         # TextIn OCR应用ID
   TEXTIN_APP_SECRET="your_textin_app_secret_here"   # TextIn OCR应用密钥
   
   # server 配置
   BASE_URL="https://your-llm-api-endpoint.com"    # 替换为LLM API基础地址
   DASHSCOPE_API_KEY="your_dashscope_api_key_here"  # LLM API 密钥
   ```

3. **确保配置正确**：
   请根据您的实际环境修改数据库连接信息和其他相关配置。

### Docker 部署

本项目提供了完整的Docker配置，用于快速部署lan-engine应用及其MySQL数据库环境。

### 快速开始

1. 进入 docker 目录：
   ```bash
   cd docker
   ```

2. 构建并启动服务：
   ```bash
   # 使用docker compose构建并启动所有服务
   docker compose up --build
   ```

   或者，如果您希望在后台运行：
   ```bash
   # 在后台启动所有服务
   docker compose up -d --build
   ```

3. 查看服务状态：
   ```bash
   # 查看所有服务状态
   docker compose ps
   ```

4. 查看日志：
   ```bash
   # 查看应用服务日志
   docker compose logs app

   # 查看MySQL服务日志
   docker compose logs mysql

   # 查看所有服务日志
   docker compose logs
   ```

5. 停止服务：
   ```bash
   # 停止所有服务
   docker compose down
   ```

### Docker 配置说明

- `Dockerfile`: 定义了Python 3.12环境的构建过程
- `docker-compose.yml`: 定义了应用服务和MySQL数据库服务的编排
- `.dockerignore`: 指定在构建Docker镜像时忽略的文件和目录

### 环境变量

应用服务已配置以下环境变量，用于连接MySQL数据库：

- `DB_HOST=mysql`
- `DB_PORT=3306`
- `DB_USER=root`
- `DB_PASSWORD=123456`
- `DB_NAME=lan_engine`

### 故障排除

1. 端口冲突：
   如果遇到端口冲突，可以修改 `docker-compose.yml` 中的端口映射：
   ```yaml
   ports:
     - "5001:5050"  # 将主机端口改为5001
   ```

2. 数据库连接问题：
   如果应用无法连接到数据库，请确保：
   - MySQL服务已启动：`docker compose ps`
   - 检查应用服务日志：`docker compose logs app`
   - 确认数据库初始化完成：`docker compose logs mysql`

3. 重新初始化数据库：
   如果需要重新初始化数据库：
   ```bash
   # 停止并删除数据卷
   docker compose down -v

   # 重新启动服务
   docker compose up --build
   ```

## 使用说明

应用将在 `http://localhost:5050` 上运行。

### API 接口

#### 1. 查询接口 `/query`

**POST** `/query`

```json
{
  "query": "为XX公司生成商业分析报告"
}
```

**商业分析报告自动触发条件**：
- 请求中同时包含"公司"和"商业分析报告"关键词
- 系统自动提取公司名称并生成完整报告

**响应示例**：
```json
{
  "status": "success",
  "result": "已成功生成XX公司的商业分析报告",
  "report_file": "XX公司_商业分析报告.md",
  "chinese_chars": 42000,
  "sections_count": 60
}
```

#### 2. 上传大纲 `/upload_outline`

**POST** `/upload_outline`

支持上传自定义大纲文件（PDF、DOCX、MD 等格式）。

#### 3. 上传参考资料 `/upload_reference`

**POST** `/upload_reference`

上传参考资料文件，系统会自动进行切片处理并存入数据库。

## 测试

本项目包含完整的单元测试和集成测试套件。

### 测试结构

- **test_mysql_database.py** - 数据库模块测试（80+ 测试用例）
- **test_report_generator.py** - 报告生成器测试
- **test_chunk_processor.py** - 切片处理器测试
- **test_api.py** - Flask API 集成测试

### 运行测试

#### 使用测试脚本（推荐）

```bash
# 赋予执行权限
chmod +x run_tests.sh

# 运行所有测试
./run_tests.sh

# 只运行单元测试
./run_tests.sh -u

# 生成覆盖率报告
./run_tests.sh -c

# 快速运行（跳过慢速测试）
./run_tests.sh -f

# 显示帮助
./run_tests.sh -h
```

#### 直接使用 pytest

```bash
# 运行所有测试
pytest

# 运行特定文件的测试
pytest tests/test_mysql_database.py

# 运行带特定标记的测试
pytest -m unit          # 只运行单元测试
pytest -m integration   # 只运行集成测试
pytest -m "not slow"    # 跳过慢速测试

# 生成覆盖率报告
pytest --cov=. --cov-report=html

# 并行运行测试
pytest -n auto
```

### 环境变量

测试需要配置以下环境变量：

```bash
# 测试数据库配置（默认值）
export TEST_DB_HOST=localhost
export TEST_DB_PORT=3306
export TEST_DB_USER=root
export TEST_DB_PASSWORD=""
export TEST_DB_NAME=test_report_files_db

# LLM API 配置（用于 LLM 测试）
export LLM_API_KEY=your_api_key
```

### 测试覆盖

- ✅ 数据库 CRUD 操作
- ✅ 报告生成核心逻辑
- ✅ 文档切片和处理
- ✅ API 端点集成测试
- ✅ 错误处理和边界条件

详细的测试文档请查看 [tests/README.md](tests/README.md)

## 技术栈

- **后端框架**: Flask 3.0.1
- **LLM**: 阿里云 DashScope (qwen3-max)
- **数据库**: MySQL 8.0
- **文档处理**: TextIn OCR, python-docx
- **协议**: MCP (Model Context Protocol)
- **测试框架**: pytest, pytest-cov
- **部署**: Docker, Docker Compose