# recharge_ai

**Repository Path**: hankaizhou/recharge_ai

## Basic Information

- **Project Name**: recharge_ai
- **Description**: 基于Python的智能充值系统，支持广告账户的多种充值类型（账期、预付、临垫等），集成DeepSeek AI实现自然语言解析，提供自动化充值流程与pytest接口测试框架，助力高效、安全的充值管理。
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-17
- **Last Updated**: 2026-03-31

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 智能充值系统

## 项目概述

智能充值系统是一个用于处理广告账户充值申请、充值操作和审批流程的Python应用程序。该系统支持多种充值类型，包括账期充值、预付充值、临垫充值、客户专属金和补量后返金。项目集成了DeepSeek AI接口，实现基于用户输入信息的自动充值功能，支持自然语言输入解析。同时，项目集成了基于pytest架构的接口自动化测试框架，用于测试充值相关的API接口。

## 功能特性

### 核心功能
- 支持多种充值类型：账期充值、预付充值、临垫充值、客户专属金、补量后返金
- 自动构建充值请求参数
- 执行SQL更新操作（账期充值和预付充值）
- 提交充值申请
- 查询充值相关信息
- 使用审批人进行充值
- 审批人审批通过
- 详细的日志记录
- 模块化设计，便于维护和扩展
- DeepSeek AI集成，支持自然语言输入解析
- 支持命令行和交互式用户输入
- 安全机制，包括敏感信息加密和二次确认

### 测试功能
- 基于pytest架构的接口自动化测试
- 数据驱动测试，支持YAML格式测试数据
- 并行测试执行，提升测试效率
- 详细的测试报告生成（HTML、Allure）
- 代码覆盖率分析

## 目录结构

```
recharge_ai/
├── common/               # 公共模块
│   ├── api_client.py     # API客户端
│   ├── assertions.py     # 断言工具
│   ├── config.py         # 配置管理
│   ├── database.py       # 数据库操作
│   ├── logger.py         # 日志管理
│   └── test_data.py      # 测试数据管理
├── docs/                # 文档目录
│   ├── apply_analysis.md                # 申请数据结构分析
│   ├── approveForm_analysis.md          # 审批数据结构分析
│   ├── 临垫充值接口.txt                   # 临垫充值接口文档
│   ├── 临垫充值请求参数数据源.txt           # 临垫充值请求参数数据源
│   ├── 充值功能参数说明文档.md             # 充值功能参数说明
│   └── 充值各类型申请请求参数.txt           # 各充值类型申请请求参数
├── src/                 # 源代码目录
│   ├── ai/              # AI相关代码
│   │   └── deepseek_client.py  # DeepSeek AI客户端
│   ├── api/             # API相关代码
│   │   └── api.py       # API请求模块
│   ├── database/        # 数据库相关代码
│   │   └── db.py        # 数据库连接和操作模块
│   ├── services/        # 业务逻辑服务
│   │   ├── input_parser_service.py  # 输入解析服务
│   │   ├── recharge_service.py  # 充值服务模块
│   │   └── security_service.py  # 安全服务模块
│   └── utils/           # 工具函数
│       ├── calculate_over_refund.py  # 计算超额退款
│       ├── token_manager.py  # 令牌管理
│       └── tools.py     # 工具函数
├── testdata/             # 测试数据
│   └── recharge_data.yaml  # 充值测试数据
├── tests/               # 测试目录
│   ├── conftest.py       # pytest配置
│   ├── test_auto_recharge.py  # 自动充值测试
│   ├── test_deepseek_client.py  # DeepSeek客户端测试
│   ├── test_end_to_end_recharge.py  # 端到端测试
│   ├── test_input_parser.py  # 输入解析测试
│   ├── test_security_service.py  # 安全服务测试
│   └── test_token_management.py  # 令牌管理测试

├── README.md            # 项目文档
├── auto_recharge.py     # 自动充值主脚本
├── config.yaml           # 项目配置
├── pytest.ini            # pytest配置
└── requirements.txt     # 依赖项配置
```

## 安装步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd api_recharge
   ```

2. **安装依赖**
   ```bash
   pip install -r requirements.txt
   ```

3. **配置环境**

   复制配置模板并填入真实值：
   ```bash
   # 1. 复制配置文件模板
   cp config.yaml.example config.yaml

   # 2. 编辑 config.yaml，填入以下必填项：
   #    - api.base_url         : 你的 API 服务地址
   #    - auth.salesman_no     : 申请人工号
   #    - auth.approver_no     : 审批人工号
   #    - database.*           : 数据库连接信息

   # 3. 设置环境变量（密码类敏感信息推荐用环境变量，不写进 config.yaml）
   cp .env.example .env
   # 编辑 .env，至少填入：
   #    LOGIN_PASSWORD=...      （登录密码，token_manager 自动登录用）
   #    DEEPSEEK_API_KEY=...    （如需 AI 解析功能）
   ```

   > ⚠️ `config.yaml` 和 `.env` 已加入 `.gitignore`，不会被提交到版本库。


## 配置说明

### 环境变量配置

系统支持通过环境变量配置以下参数，优先从环境变量读取：

```
# DeepSeek AI配置（推荐通过环境变量设置，提高安全性）
DEEPSEEK_API_KEY=<deepseek-api-key>
DEEPSEEK_API_URL=https://api.deepseek.com/v1/chat/completions

# API配置
API_BASE_URL=https://your-api-host/prod-api

# 申请人Authorization
SALESMAN_AUTH=Bearer <salesman-token>

# 审批人Authorization
APPROVER_AUTH=Bearer <approver-token>

# 数据库配置（敏感信息请勿提交到版本库）
DB_HOST=your_db_host
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_NAME=doss_db
DB_PORT=3306
```

### 项目配置

项目配置文件 `config.yaml` 包含以下配置项：

```yaml
# API配置
api:
  base_url: https://your-api-host/prod-api
  timeout: 30
  retry_count: 3

# 认证配置
auth:
  salesman_token: "Bearer <salesman-token>"
  approver_token: "Bearer <approver-token>"

# 数据库配置
database:
  host: your_db_host
  port: 3306
  user: your_db_user
  password: your_db_password
  database: doss_db

# DeepSeek AI配置
deepseek:
  api_key: "<deepseek-api-key>"  # 优先从环境变量DEEPSEEK_API_KEY读取
  api_url: "https://api.deepseek.com/v1/chat/completions"  # 优先从环境变量DEEPSEEK_API_URL读取
  timeout: 30
  retry_count: 3

# 测试配置
test:
  parallel: true
  workers: 4
  timeout: 120
  retry: 2

# 报告配置
report:
  html: true
  allure: true
  generate_on_failure: true

# 日志配置
log:
  level: INFO
  format: "%(asctime)s - %(name)s - %(levelname)s - %(message)s"
  file: "logs/test.log"
```

## 使用方法

### 运行自动充值脚本

```bash
# 使用命令行参数
python auto_recharge.py 帮我充3笔，测试用户，商机DS2020010072，账号YOUR_ADVERT_ID，临垫充值10000

# 交互式输入
python auto_recharge.py
# 然后按照提示输入充值请求
```

### 直接使用充值服务

```python
from src.services.recharge_service import recharge_service

# 构建用户输入参数
user_input = {
    "nick_name": "钟燕林",
    "business_code": "DS2024060392",
    "advert_id": "202602010000501",
    "media_id": 12,
    "recharge_type": 3,  # 临垫充值
    "is_urgent": 0,  # 不急加
    "is_add": 0,  # 不是后补
    "collectionDays": 3,  # 回款期限
    "is_advance": 0,  # 不凭客户水单充值
    "order_model": 1,  # 竞价模式
    "recharge_display_amount": 1000,  # 充值金额
    "recharge_principal_amount": 1000  # 充值本金金额
}

# 执行充值流程
success = recharge_service.run_recharge_process(user_input)

if success:
    print("充值流程执行成功")
else:
    print("充值流程执行失败")
```

### 从用户输入执行充值

```python
from src.services.recharge_service import recharge_service

# 用户输入
user_input = "帮我充3笔，测试用户，商机DS2020010072，账号YOUR_ADVERT_ID，临垫充值10000"

# 执行充值流程
results = recharge_service.run_recharge_from_input(user_input)

# 处理结果
for result in results:
    if result['success']:
        print(f"第{result['index']}笔充值成功")
    else:
        print(f"第{result['index']}笔充值失败: {result['error']}")
```

## 测试说明

### 运行测试用例

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

# 运行特定测试
pytest tests/test_end_to_end_recharge.py

# 运行特定标记的测试
pytest -m e2e

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

### 测试参数说明

- `-v`：详细模式
- `-m`：运行特定标记的测试
- `-n auto`：自动并行执行测试
- `--html=reports/report.html`：生成HTML测试报告
- `--alluredir=reports/allure-results`：生成Allure测试报告
- `--cov=common`：计算代码覆盖率

### 报告查看方法

1. **HTML报告**：打开 `reports/report.html` 文件
2. **Allure报告**：
   ```bash
   allure serve reports/allure-results
   ```
3. **覆盖率报告**：打开 `reports/coverage/index.html` 文件

## 测试用例编写规范

### 命名规则

- **测试文件**：`test_*.py`
- **测试类**：`Test*`
- **测试方法**：`test_*`

### 结构要求

1. **测试类**：使用 `@pytest.mark` 标记测试类别
2. **测试方法**：
   - 使用fixture获取测试依赖
   - 加载测试数据
   - 执行测试步骤
   - 断言测试结果

### 编写示例

```python
import pytest
from common.logger import logger

@pytest.mark.recharge
@pytest.mark.api
class TestRechargeAPI:
    """充值API测试类"""
    
    def test_recharge_apply(self, api, test_data, assert_tools):
        """测试充值申请接口"""
        # 加载测试数据
        test_cases = test_data.load_parametrize('recharge_data.yaml', 'recharge_apply')
        
        for test_case in test_cases:
            logger.info(f"执行测试用例: {test_case['nick_name']}")
            
            # 构建请求数据
            request_data = {
                # 请求数据
            }
            
            # 发送请求
            response = api.post('/finance/recharge', request_data)
            
            # 断言响应
            assert_tools.assert_status_code(response, 200)
            assert_tools.assert_success(response)
            
            logger.info("测试用例执行成功")
```

## 模块说明

### 1. 配置管理模块 (`common/config.py`)

**功能**：加载和管理项目配置

**接口**：
- `config.get(key, default)`：获取配置值
- `config.api`：API配置
- `config.auth`：认证配置
- `config.database`：数据库配置
- `config.test`：测试配置
- `config.report`：报告配置
- `config.log`：日志配置
- `config.deepseek`：DeepSeek AI配置

**使用示例**：
```python
from common.config import config

base_url = config.get('api.base_url')
token = config.get('auth.salesman_token')
deepseek_api_key = config.get('deepseek.api_key')
```

### 2. 日志管理模块 (`common/logger.py`)

**功能**：配置和管理日志

**接口**：
- `logger.get_logger(name)`：获取日志记录器

**使用示例**：
```python
from common.logger import logger

log = logger.get_logger('test')
log.info('测试开始')
log.error('测试失败')
```

### 3. API客户端模块 (`common/api_client.py`)

**功能**：发送API请求

**接口**：
- `api.get(endpoint, headers=None, auth_type='salesman')`：发送GET请求
- `api.post(endpoint, data, headers=None, auth_type='salesman')`：发送POST请求
- `api.put(endpoint, data, headers=None, auth_type='salesman')`：发送PUT请求
- `api.delete(endpoint, headers=None, auth_type='salesman')`：发送DELETE请求

**使用示例**：
```python
from common.api_client import api_client

response = api_client.post('/finance/recharge', request_data)
```

### 4. 数据库模块 (`common/database.py`)

**功能**：数据库操作

**接口**：
- `db.connect()`：连接数据库
- `db.close()`：关闭数据库连接
- `db.execute_query(sql, params=None)`：执行查询
- `db.execute_update(sql, params=None)`：执行更新

**使用示例**：
```python
from common.database import db

result = db.execute_query('SELECT * FROM users WHERE id = %s', (1,))
```

### 5. 测试数据模块 (`common/test_data.py`)

**功能**：加载测试数据

**接口**：
- `test_data.load(file_name)`：加载测试数据文件
- `test_data.load_parametrize(file_name, key=None)`：加载参数化测试数据

**使用示例**：
```python
from common.test_data import test_data

data = test_data.load('recharge_data.yaml')
test_cases = test_data.load_parametrize('recharge_data.yaml', 'recharge_apply')
```

### 6. 断言工具模块 (`common/assertions.py`)

**功能**：提供断言方法

**接口**：
- `assertions.assert_equal(actual, expected, message=None)`：断言相等
- `assertions.assert_true(condition, message=None)`：断言为真
- `assertions.assert_status_code(response, expected_code=200, message=None)`：断言状态码
- `assertions.assert_success(response, message=None)`：断言成功响应

**使用示例**：
```python
from common.assertions import assertions

assertions.assert_status_code(response, 200)
assertions.assert_success(response)
```

### 7. DeepSeek AI客户端模块 (`src/ai/deepseek_client.py`)

**功能**：与DeepSeek AI API交互

**接口**：
- `deepseek_client.chat_completion(messages, model="deepseek-chat")`：发送聊天完成请求
- `deepseek_client.parse_recharge_request(user_input)`：解析充值请求

**使用示例**：
```python
from src.ai.deepseek_client import deepseek_client

result = deepseek_client.parse_recharge_request("帮我充3笔，测试用户，商机DS2020010072，账号YOUR_ADVERT_ID，临垫充值10000")
```

### 8. 输入解析服务模块 (`src/services/input_parser_service.py`)

**功能**：解析用户输入

**接口**：
- `input_parser_service.parse_user_input(user_input)`：解析用户输入

**使用示例**：
```python
from src.services.input_parser_service import input_parser_service

result = input_parser_service.parse_user_input("帮我充3笔，测试用户，商机DS2020010072，账号YOUR_ADVERT_ID，临垫充值10000")
```

### 9. 充值服务模块 (`src/services/recharge_service.py`)

**功能**：处理充值流程

**接口**：
- `recharge_service.run_recharge_process(recharge_data)`：执行充值流程
- `recharge_service.run_recharge_from_input(user_input)`：从用户输入执行充值

**使用示例**：
```python
from src.services.recharge_service import recharge_service

results = recharge_service.run_recharge_from_input("帮我充3笔，测试用户，商机DS2020010072，账号YOUR_ADVERT_ID，临垫充值10000")
```

### 10. 安全服务模块 (`src/services/security_service.py`)

**功能**：提供安全相关功能

**接口**：
- `security_service.encrypt_sensitive_data(data)`：加密敏感数据
- `security_service.decrypt_sensitive_data(encrypted_data)`：解密敏感数据
- `security_service.generate_confirmation_code(data)`：生成确认码

**使用示例**：
```python
from src.services.security_service import security_service

confirmation_code = security_service.generate_confirmation_code({"user_name": "测试用户", "amount": 10000})
```

## 文档说明

- `docs/临垫充值接口.txt`：临垫充值接口的详细说明
- `docs/临垫充值请求参数数据源.txt`：临垫充值请求参数的数据源信息
- `docs/充值功能参数说明文档.md`：充值功能的参数说明
- `docs/充值各类型申请请求参数.txt`：各充值类型的申请请求参数
- `docs/apply_analysis.md`：申请数据结构分析
- `docs/approveForm_analysis.md`：审批数据结构分析
- `docs/登录接口.txt`：登录接口的详细说明

## 依赖项

- requests==2.32.3
- pymysql==1.1.0
- python-dotenv==1.0.1
- pytest==7.4.3
- pytest-html==3.1.1
- pytest-xdist==3.3.1
- allure-pytest==2.13.2
- pytest-cov==7.0.0
- pyyaml==6.0.1

## 注意事项

1. 确保配置正确，特别是Authorization token
2. 确保数据库连接信息正确
3. 运行前确保API接口可用
4. 临垫充值需要设置collectionDays参数（1-3天）
5. 账期充值和预付充值会执行SQL更新操作，确保数据库权限正确
6. 测试数据存放在 `testdata` 目录，使用YAML格式
7. 所有配置通过 `config.yaml` 文件管理，不要硬编码配置信息
8. 使用 `logger` 模块记录日志，不要使用 `print`
9. 使用 `assertions` 模块进行断言，提供统一的断言方式
10. 捕获并处理异常，确保测试的稳定性
11. 确保测试用例之间相互独立，不影响其他测试的执行
12. 确保DeepSeek API密钥配置正确（推荐通过环境变量设置，提高安全性），以启用AI输入解析功能

## 日志说明

系统会生成日志文件，记录详细的操作日志，包括：
- 充值流程的各个步骤
- API请求和响应
- 数据库操作
- 错误信息
- 测试执行情况
- AI解析结果

## 常见问题

1. **API认证失败**：检查 `config.yaml` 中的token是否有效
2. **数据库连接失败**：检查数据库连接信息是否正确
3. **测试数据加载失败**：检查测试数据文件是否存在且格式正确
4. **测试报告生成失败**：确保 `reports` 目录存在
5. **AI解析失败**：检查DeepSeek API密钥是否正确（环境变量或config.yaml），网络连接是否正常

## 贡献指南

1. **代码风格**：遵循PEP 8编码规范
2. **提交信息**：使用清晰的提交信息，描述变更内容
3. **测试**：为新功能添加测试用例
4. **文档**：更新相关文档
5. **代码审查**：提交前进行代码审查

## 联系方式

如有问题，请联系系统管理员或项目维护人员。