# 添加新任务类指南

本文档详细说明如何在项目中添加一个新的任务类，包含立即响应和后台执行功能。

## 目录

1. [架构概述](#架构概述)
2. [添加步骤](#添加步骤)
3. [代码示例](#代码示例)
4. [文件结构说明](#文件结构说明)
5. [注意事项](#注意事项)

---

## 架构概述

项目采用**立即响应 + 后台执行**的架构模式：

- **立即响应函数**：位于 `app/module/f6_plugin_handlers.py`，负责快速响应请求，立即返回"正在执行"消息
- **后台执行函数**：位于 `app/tasks/` 目录下，负责在后台线程中执行实际任务

### 工作流程

```
客户端请求 
  ↓
立即响应函数（F6PluginHandlers）
  ↓
启动后台线程
  ↓
后台执行函数（tasks/*.py）
  ↓
更新简道云表单
  ↓
自动提交工作流
```

---

## 添加步骤

### 步骤 1: 创建后台任务文件

在 `app/tasks/` 目录下创建新的任务文件，例如 `app/tasks/your_task.py`：

```python
"""
你的任务相关后台任务模块

本模块包含你的任务相关的后台任务，包括：
- 任务描述1
- 任务描述2

这些任务在后台线程中执行，不会阻塞主请求。
执行完成后会更新简道云表单并自动提交工作流。
"""
import logging
import os
import requests
import pandas as pd
from typing import Dict, Any
from tqdm import tqdm
from app.tasks.common import update_jiandaoyun, approve_workflow

logger = logging.getLogger('app')


def your_task_background(data: Dict[str, Any], cookies: Dict[str, str] = None, 
                         df: pd.DataFrame = None, save_path: str = None):
    """
    你的任务后台执行函数
    
    在后台线程中执行你的任务。
    执行完成后会更新简道云表单并自动提交工作流。
    
    Args:
        data: 包含表单ID(api_key)、表单ID(entry_id)、数据ID(data_id)的字典
        cookies: 用户登录 F6 系统的 cookies 信息（可选）
        df: Excel 文件读取的内容，DataFrame 格式（可选）
        save_path: Excel 文件保存的地址，执行完成后会删除此文件（可选）
        
    Returns:
        None
        
    注意:
        - 执行完成后会自动删除上传的文件（如果提供了save_path）
        - 执行结果会更新到简道云表单
    """
    try:
        # TODO: 在这里实现具体的任务逻辑
        results = []
        
        # 示例：处理数据
        if df is not None:
            df = df.where(pd.notnull(df), None)
            for index, row in tqdm(df.iterrows(), total=df.shape[0], desc="处理数据"):
                # 实现具体的数据处理逻辑
                result_item = {
                    '行号': index + 1,
                    '状态': '处理成功'
                }
                results.append(result_item)
        else:
            # 如果没有DataFrame，执行其他任务
            results.append({'状态': '任务执行成功'})
        
        # 删除文件（如果提供了save_path）
        if save_path and os.path.exists(save_path):
            os.remove(save_path)
            logger.info(f'{save_path}已删除')
        
        # 格式化结果
        results_str = f'{results}' if results else '任务执行完成'
        logger.info(f"任务执行结果: {results_str}")
        
        # 调用api回写改掉 执行明细与执行状态
        msg = update_jiandaoyun(data, results_str)
        
        if msg.get('msg'):
            approve_workflow(data)
            logger.info('表单已自动提交至下一步')
            
    except Exception as e:
        error_msg = f'任务执行失败: {str(e)}'
        logger.error(error_msg, exc_info=True)
        msg = update_jiandaoyun(data, error_msg)
        if msg.get('msg'):
            approve_workflow(data)
```

### 步骤 2: 在任务导出文件中注册

在 `app/tasks/__init__.py` 中添加导入和导出：

```python
# 你的任务
from app.tasks.your_task import your_task_background

__all__ = [
    # ... 其他任务
    # 你的任务
    'your_task_background',
]
```

### 步骤 3: 添加立即响应函数

在 `app/module/f6_plugin_handlers.py` 中添加立即响应函数：

```python
from app.tasks.your_task import your_task_background

class F6PluginHandlers:
    # ... 其他方法
    
    @staticmethod
    def your_task(data: Dict[str, Any]) -> Dict[str, str]:
        """
        你的任务
        
        从简道云获取任务请求，读取 Excel 文件（如果需要），并在后台线程中执行任务。
        立即返回"正在执行"的提示，实际执行在后台线程中完成。
        
        Args:
            data: 包含表单ID(api_key)、表单ID(entry_id)、数据ID(data_id)的字典
            
        Returns:
            Dict[str, str]: 包含执行状态的字典
        """
        entry_data = api_instance.entry_data_get(data=data)
        print('执行 你的任务')
        
        # 获取必要的参数（根据实际需求调整）
        username = entry_data['data'].get('账号')
        password = entry_data['data'].get('密码')
        company_name = entry_data['data'].get('公司名称')
        save_path = entry_data['data'].get('文件保存地址')
        
        # 如果需要登录F6系统
        cookies = None
        if username and password and company_name:
            login_response = F6Module.login_in(username, password, company_name)
            if login_response is None:
                return {'msg': '登录失败', 'msg_details': '无法登录F6系统'}
            cookies = requests.utils.dict_from_cookiejar(login_response.cookies)
        
        # 如果需要读取Excel文件
        df = None
        if save_path:
            try:
                df = pd.read_excel(save_path, sheet_name=0, dtype='string')
            except Exception as e:
                return {'msg': f'读取Excel文件失败: {str(e)},文件路径：{save_path}'}
        
        # 启动后台线程执行任务
        try:
            thread = threading.Thread(target=your_task_background,
                                      args=(data, cookies, df, save_path))
            thread.start()
        except Exception as e:
            print(f'创建线程失败: {str(e)}')
            return {'msg': '任务启动失败', 'msg_details': f'无法启动后台任务: {str(e)}'}

        return {'msg': '正在执行', 'msg_details': '正在执行，请稍后看结果'}
```

### 步骤 4: 注册操作到模块注册表

在 `main.py` 的 `lifespan` 函数中注册操作：

```python
core_manager.register_action('your_task', f6_plugin_handlers.your_task, 'f6_plugin_module',
                             description='你的任务描述')
```

---

## 代码示例

### 完整示例：BI任务

以下是一个完整的示例，展示如何添加BI任务类：

#### 1. 后台任务文件 (`app/tasks/bi_tasks.py`)

```python
"""
BI相关后台任务模块
"""
import logging
import os
import pandas as pd
from typing import Dict, Any
from tqdm import tqdm
from app.tasks.common import update_jiandaoyun, approve_workflow

logger = logging.getLogger('app')

def bi_task_background(data: Dict[str, Any], cookies: Dict[str, str] = None, 
                      df: pd.DataFrame = None, save_path: str = None):
    """BI任务后台执行函数"""
    try:
        results = []
        if df is not None:
            # 处理Excel数据
            for index, row in tqdm(df.iterrows(), total=df.shape[0], desc="处理BI数据"):
                results.append({'行号': index + 1, '状态': '处理成功'})
        else:
            results.append({'状态': 'BI任务执行成功'})
        
        if save_path and os.path.exists(save_path):
            os.remove(save_path)
        
        msg = update_jiandaoyun(data, f'{results}')
        if msg.get('msg'):
            approve_workflow(data)
    except Exception as e:
        error_msg = f'BI任务执行失败: {str(e)}'
        logger.error(error_msg, exc_info=True)
        update_jiandaoyun(data, error_msg)
```

#### 2. 立即响应函数 (`app/module/f6_plugin_handlers.py`)

```python
@staticmethod
def bi_task(data: Dict[str, Any]) -> Dict[str, str]:
    """BI任务立即响应函数"""
    entry_data = api_instance.entry_data_get(data=data)
    
    # 获取参数
    username = entry_data['data'].get('账号')
    password = entry_data['data'].get('密码')
    company_name = entry_data['data'].get('公司名称')
    save_path = entry_data['data'].get('文件保存地址')
    
    # 登录（如果需要）
    cookies = None
    if username and password and company_name:
        login_response = F6Module.login_in(username, password, company_name)
        if login_response is None:
            return {'msg': '登录失败'}
        cookies = requests.utils.dict_from_cookiejar(login_response.cookies)
    
    # 读取文件（如果需要）
    df = None
    if save_path:
        df = pd.read_excel(save_path, sheet_name=0, dtype='string')
    
    # 启动后台线程
    thread = threading.Thread(target=bi_task_background,
                              args=(data, cookies, df, save_path))
    thread.start()
    
    return {'msg': '正在执行', 'msg_details': '正在执行，请稍后看结果'}
```

#### 3. 注册操作 (`main.py`)

```python
core_manager.register_action('bi_task', f6_plugin_handlers.bi_task, 'f6_plugin_module',
                             description='BI任务')
```

---

## 文件结构说明

### 关键文件位置

```
fastapi_app/
├── app/
│   ├── module/
│   │   └── f6_plugin_handlers.py    # 立即响应处理器（重命名自 f6_plugin_module.py）
│   │
│   ├── tasks/
│   │   ├── __init__.py               # 任务导出文件
│   │   ├── common.py                  # 通用任务函数
│   │   ├── bi_tasks.py               # BI任务（示例）
│   │   ├── brand_tasks.py            # 品牌任务
│   │   ├── customer_tasks.py         # 客户任务
│   │   └── delete_tasks.py          # 删除任务
│   │
│   └── api/
│       └── routes.py                  # API路由
│
└── main.py                            # 应用入口，注册所有操作
```

### 命名规范

- **立即响应函数**：位于 `F6PluginHandlers` 类中，使用小写下划线命名（如 `bi_task`）
- **后台执行函数**：位于 `app/tasks/` 目录，使用 `{task_name}_background` 命名（如 `bi_task_background`）
- **操作名称**：在 `main.py` 中注册时使用，通常与立即响应函数名相同（如 `'bi_task'`）

---

## 注意事项

### 1. 文件命名变更

**重要**：`f6_plugin_module.py` 已重命名为 `f6_plugin_handlers.py`，类名从 `F6PluginModule` 改为 `F6PluginHandlers`。

- 文件名更清晰地表达了其功能：处理立即响应的处理器
- 所有引用已更新，但 `app.state.f6_plugin_module` 保持向后兼容

### 2. 参数传递

后台执行函数通常接收以下参数：

- `data`: 必需，包含简道云表单信息
- `cookies`: 可选，F6系统登录凭证
- `df`: 可选，Excel文件数据（DataFrame）
- `save_path`: 可选，文件保存路径

### 3. 错误处理

- 立即响应函数：应捕获登录、文件读取等错误，立即返回错误信息
- 后台执行函数：应使用 try-except 包裹整个逻辑，确保错误能更新到简道云表单

### 4. 文件清理

如果任务处理了上传的文件，应在执行完成后删除：

```python
if save_path and os.path.exists(save_path):
    os.remove(save_path)
    logger.info(f'{save_path}已删除')
```

### 5. 简道云表单更新

所有后台任务完成后都应：

1. 调用 `update_jiandaoyun(data, results_str)` 更新执行结果
2. 如果更新成功，调用 `approve_workflow(data)` 自动提交工作流

### 6. 日志记录

使用项目统一的日志记录器：

```python
import logging
logger = logging.getLogger('app')
logger.info("信息日志")
logger.error("错误日志", exc_info=True)  # exc_info=True 记录异常堆栈
```

### 7. 进度显示

对于批量处理任务，使用 `tqdm` 显示进度：

```python
from tqdm import tqdm

for index, row in tqdm(df.iterrows(), total=df.shape[0], desc="处理数据"):
    # 处理逻辑
```

---

## 快速检查清单

添加新任务类时，请确认：

- [ ] 创建了后台任务文件 `app/tasks/{task_name}_tasks.py`
- [ ] 在 `app/tasks/__init__.py` 中导出了后台任务函数
- [ ] 在 `app/module/f6_plugin_handlers.py` 中添加了立即响应函数
- [ ] 在 `main.py` 中注册了操作
- [ ] 实现了错误处理逻辑
- [ ] 添加了日志记录
- [ ] 实现了文件清理（如果处理了文件）
- [ ] 实现了简道云表单更新和工作流提交

---

## 常见问题

### Q: 如何测试新添加的任务？

A: 启动应用后，通过API调用测试：
- 请求头设置 `Action: your_task`
- 请求体包含简道云表单数据

### Q: 任务执行失败怎么办？

A: 后台执行函数中的异常会被捕获，错误信息会更新到简道云表单的"执行明细"字段。

### Q: 如何修改任务执行逻辑？

A: 只需修改 `app/tasks/{task_name}_tasks.py` 中的后台执行函数即可。

### Q: 可以添加不需要登录的任务吗？

A: 可以，在立即响应函数中不调用 `F6Module.login_in`，`cookies` 参数传 `None` 即可。

---

## 相关文件

- `app/module/f6_plugin_handlers.py` - 立即响应处理器
- `app/tasks/common.py` - 通用任务函数（update_jiandaoyun, approve_workflow）
- `app/core/module_registry.py` - 模块注册表
- `main.py` - 应用入口和操作注册

---

**最后更新**: 2025年

**维护者**: 数据组