# 简道云 FastAPI 服务

简道云插件后端服务，提供数据同步和处理功能。

## 📋 项目简介

本项目是一个基于 FastAPI 框架的简道云插件后端服务，主要用于处理简道云插件发送的请求，执行各种业务操作。系统与 F6 汽车维修管理系统集成，提供以下核心功能：

- **F6系统集成**: 登录认证、公司信息获取、门店信息管理
- **文件处理**: 文件上传、校验、Excel批量处理
- **数据管理**: 品牌批量创建、客户信息管理、车辆信息管理
- **数据清理**: 历史记录删除、客户删除、车辆删除
- **BI任务**: 数据处理和报表生成
- **工作流自动化**: 自动提交简道云工作流

## 🏗️ 项目结构

```
fastapi_app/
├── main.py                    # 应用入口，生命周期管理
├── requirements.txt           # Python依赖清单
├── README.md                  # 项目文档（本文件）
│
├── app/                       # 应用主目录
│   ├── __init__.py
│   ├── config.py              # 配置管理（目录、API Token等）
│   ├── schemas.py             # Pydantic数据模型定义
│   │
│   ├── api/                   # API路由模块
│   │   ├── __init__.py        # 简道云API封装类
│   │   ├── routes.py          # FastAPI路由定义
│   │   └── dependencies.py    # 依赖注入函数
│   │
│   ├── core/                  # 核心功能模块
│   │   ├── __init__.py        # 核心管理器
│   │   └── module_registry.py # 模块注册表
│   │
│   ├── module/                # 业务模块
│   │   ├── __init__.py
│   │   ├── module.py          # F6Module - F6系统相关功能
│   │   ├── f6_plugin_module.py # F6PluginModule - F6插件功能
│   │   └── other_module.py    # OtherPluginModule - 其他功能
│   │
│   ├── tasks/                 # 后台任务模块
│   │   ├── __init__.py        # 任务统一导出
│   │   ├── common.py          # 通用任务函数
│   │   ├── brand_tasks.py     # 品牌相关任务
│   │   ├── customer_tasks.py  # 客户相关任务
│   │   ├── delete_tasks.py    # 删除相关任务
│   │   └── bi_tasks.py        # BI相关任务
│   │
│   └── utils/                 # 工具模块
│       └── app_tools.py       # 应用工具类（日志、任务队列等）
│
├── logs/                      # 日志目录
├── 下载文件/                  # 下载文件存储目录
└── 模板文件/                  # 模板文件存储目录
```

## 🚀 快速开始

### 环境要求

- Python 3.8+
- pip
- Tesseract OCR（用于验证码识别，可选）

### 安装依赖

```bash
pip install -r requirements.txt
```

### 配置说明

编辑 `app/config.py` 文件，配置以下内容：

- `JIANDAOYUN_API_TOKEN`: 简道云API Token（生产环境建议使用环境变量）

### 运行应用

```bash
# 方式1：直接运行
python main.py

# 方式2：使用 uvicorn（推荐）
uvicorn main:app --host 0.0.0.0 --port 5003 --reload
```

### 访问API文档

启动应用后，访问以下地址查看API文档：

- **Swagger UI**: http://localhost:5003/docs
- **ReDoc**: http://localhost:5003/redoc

## 📡 API 接口

### 健康检查

```http
GET /health
```

**响应示例：**
```json
{
  "status": "ok",
  "version": "2.0.0"
}
```

### Webhook 接口

```http
POST /webhook
```

**请求头：**
- `Action`: 操作类型（必需）
- `Check`: 检查标志（F6_Plugin 操作时需要，值为"是"或"否"）

**请求体：**
```json
{
  "api_key": "简道云应用ID",
  "entry_id": "简道云表单ID",
  "data_id": "简道云数据ID",
  "Action": "操作类型（F6_Plugin 操作时需要）",
  "username": "用户名",
  "password": "密码",
  "company_name": "公司名称"
}
```

**响应示例：**
```json
{
  "msg": "操作完成",
  "msg_details": "详细信息",
  "status": "success"
}
```

## 🔧 支持的操作

### F6Module 操作

| 操作名 | 描述 | 说明 |
|--------|------|------|
| `login_in` | F6系统登录 | 使用用户名、密码登录F6系统，支持验证码识别 |
| `get_company_information` | 获取公司信息 | 获取F6系统中的公司列表，保存到简道云 |
| `get_store_information` | 获取门店信息 | 获取指定公司的门店列表及统计数据 |
| `keep_alive` | 保持连接 | 心跳检测，保持连接活跃 |

### F6PluginModule 操作

| 操作名 | 描述 | 说明 |
|--------|------|------|
| `check_file` | 校验上传文件 | 校验Excel文件格式，支持品牌创建、客户修改等场景 |
| `create_brand` | 创建品牌 | 批量创建品牌，从Excel文件读取品牌名称 |
| `delete_history` | 删除历史记录 | 删除指定门店的历史维修记录 |
| `delete_customer` | 删除客户 | 批量删除客户信息（会检查会员卡和消费记录） |
| `delete_cars` | 删除车辆 | 批量删除客户车辆信息（会检查会员卡和消费记录） |
| `modify_customer_info` | 修改客户信息 | 批量修改客户信息，从Excel文件读取修改内容 |
| `bi_task` | BI任务 | 执行BI相关任务（数据处理、报表生成等） |

### OtherPluginModule 操作

| 操作名 | 描述 | 说明 |
|--------|------|------|
| `sms_signature_status` | 短信签名状态 | 查询短信签名状态（待实现） |

## 🛠️ 技术栈

- **FastAPI**: 现代、快速的 Web 框架，支持异步处理
- **Pydantic**: 数据验证和设置管理
- **Uvicorn**: ASGI 服务器
- **APScheduler**: 后台任务调度
- **Requests**: HTTP 请求库
- **Pandas**: Excel文件处理和数据分析
- **Pillow**: 图像处理
- **Pytesseract**: OCR 识别（用于验证码识别）

## 📦 依赖列表

```
anyio==4.11.0
apscheduler==3.11.1
fastapi==0.121.0
log_config==2.1.1
numpy==2.3.4
pandas==2.3.3
Pillow==12.0.0
pytesseract==0.3.13
Requests==2.32.5
tqdm==4.67.1
uvicorn==0.38.0
```

## 🏛️ 架构设计

### 核心特性

1. **模块化设计**: 业务逻辑按模块分离，易于维护和扩展
2. **依赖注入**: 使用 FastAPI 的依赖注入系统，减少耦合
3. **模块注册表**: 使用 `module_registry` 统一管理所有操作
4. **路由分离**: API 路由分离到独立文件，职责清晰
5. **数据验证**: 使用 Pydantic schemas 进行请求和响应验证
6. **异常处理**: 完善的异常处理机制，统一的错误响应格式
7. **日志记录**: 规范的日志记录，支持日志轮转（单文件5MB，保留5个备份）

### 生命周期管理

应用使用 FastAPI 的 `lifespan` 功能管理应用生命周期：

- **启动时**: 
  - 初始化工具类（AppTools）
  - 设置全局日志记录器
  - 初始化业务模块（F6Module、F6PluginModule、OtherPluginModule）
  - 注册所有操作到模块注册表
- **运行时**: 处理请求，执行业务逻辑
- **关闭时**: 清理资源，关闭后台调度器

### 任务处理机制

系统支持两种任务处理方式：

1. **同步任务**: 
   - 通过任务队列同步执行，等待结果返回
   - 适用于快速操作（如登录、信息获取）
   - 超时时间：55秒（简道云默认60秒超时）

2. **后台任务**: 
   - 在模块函数内部启动线程执行耗时操作
   - 立即返回"正在执行中"的提示
   - 适用于批量操作（如品牌创建、数据删除）
   - 执行完成后自动更新简道云表单并提交工作流

### 简道云API封装

`app/api/__init__.py` 中的 `API` 类封装了简道云的所有API接口：

- **表单数据操作**: 获取、创建、更新、删除（单条/批量）
- **表单字段获取**: 获取表单字段信息，支持字段ID到标签名的替换
- **工作流操作**: 获取实例、审批、转交
- **文件操作**: 获取上传凭证、上传文件
- **重试机制**: 所有API调用都支持失败重试（默认最多20次）

## 🔐 配置说明

配置文件位于 `app/config.py`，主要配置项：

| 配置项 | 说明 | 默认值 |
|--------|------|--------|
| `BASE_DIR` | 项目根目录 | 自动获取 |
| `SAVE_DIRECTORY` | 下载文件保存目录 | `下载文件/` |
| `MODE_DIRECTORY` | 模板文件保存目录 | `模板文件/` |
| `LOGS_DIRECTORY` | 日志文件目录 | `logs/` |
| `LOG_FILE` | 日志文件路径 | `logs/简道云.log` |
| `JIANDAOYUN_API_TOKEN` | 简道云API Token | 需配置 |

## 📝 开发指南

### 添加新操作

1. **在模块中实现方法**:
   ```python
   # app/module/your_module.py
   class YourModule:
       def your_action(self, data: Dict[str, Any]) -> Dict[str, str]:
           # 实现业务逻辑
           return {'msg': '操作完成'}
   ```

2. **在 main.py 中注册**:
   ```python
   # 在 lifespan 函数中
   core_manager.register_action(
       'your_action',
       your_module.your_action,
       'your_module',
       description='操作描述'
   )
   ```

### 添加新路由

在 `app/api/routes.py` 中添加新的路由：

```python
@router.post("/your-endpoint", tags=["业务"])
async def your_endpoint(
    request: Request,
    logger: logging.Logger = Depends(get_logger)
):
    # 实现路由逻辑
    return {"message": "success"}
```

### 添加新的数据模型

在 `app/schemas.py` 中添加新的 Pydantic 模型：

```python
class YourRequest(BaseModel):
    field1: str = Field(..., description="字段1")
    field2: Optional[int] = Field(None, description="字段2")
```

### 添加后台任务

1. **在 tasks 目录下创建任务文件**:
   ```python
   # app/tasks/your_tasks.py
   def your_task_background(data, ...):
       # 实现后台任务逻辑
       # 完成后调用 update_jiandaoyun 和 approve_workflow
   ```

2. **在模块中调用**:
   ```python
   import threading
   from app.tasks.your_tasks import your_task_background
   
   thread = threading.Thread(target=your_task_background, args=(...))
   thread.start()
   return {'msg': '正在执行中'}
   ```

## 🧪 测试

### 健康检查测试

```bash
curl http://localhost:5003/health
```

### Webhook 测试

```bash
curl -X POST http://localhost:5003/webhook \
  -H "Content-Type: application/json" \
  -H "Action: login_in" \
  -d '{
    "username": "test",
    "password": "test",
    "company_name": "测试公司"
  }'
```

## 📊 日志

日志文件位于 `logs/简道云.log`，支持日志轮转：

- 单个日志文件最大 5MB
- 保留 5 个备份文件
- 使用 UTF-8 编码
- 日志格式：`时间戳 级别:模块名:消息`

## ⚠️ 注意事项

1. **API Token**: 当前 API Token 硬编码在配置文件中，生产环境建议使用环境变量管理
2. **CORS**: 当前配置允许所有来源，生产环境建议限制允许的来源
3. **超时时间**: 任务执行超时时间默认为 55 秒，可根据需要调整
4. **文件存储**: 下载的文件存储在 `下载文件/` 目录，注意定期清理
5. **验证码识别**: 需要系统安装 Tesseract OCR 才能正常识别验证码
6. **删除操作**: 删除客户和车辆时会检查会员卡和消费记录，有记录的数据会被跳过
7. **批量操作**: 批量操作在后台线程中执行，不会阻塞主请求

## 🔄 版本历史

- **v2.0.0**:
  - fastapi 完全重构
  - 支持 F6 系统相关操作
  - 支持BI任务处理


- **1.0.0**: 初始版本
  - 实现基本的 Webhook 接口
  - 支持 F6 系统相关操作


## 📄 许可证

本项目为内部项目，仅供内部使用。

## 📞 联系方式

如有问题，请联系数据组。

---

**最后更新**: 2025年