12 KiB
12 KiB
简道云 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（用于验证码识别，可选）
安装依赖
pip install -r requirements.txt
配置说明
编辑 app/config.py 文件，配置以下内容：
JIANDAOYUN_API_TOKEN: 简道云API Token（生产环境建议使用环境变量）
运行应用
# 方式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 接口
健康检查
GET /health
响应示例：
{
"status": "ok",
"version": "2.0.0"
}
Webhook 接口
POST /webhook
请求头：
Action: 操作类型（必需）Check: 检查标志（F6_Plugin 操作时需要，值为"是"或"否"）
请求体：
{
"api_key": "简道云应用ID",
"entry_id": "简道云表单ID",
"data_id": "简道云数据ID",
"Action": "操作类型（F6_Plugin 操作时需要）",
"username": "用户名",
"password": "密码",
"company_name": "公司名称"
}
响应示例：
{
"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
🏛️ 架构设计
核心特性
- 模块化设计: 业务逻辑按模块分离，易于维护和扩展
- 依赖注入: 使用 FastAPI 的依赖注入系统，减少耦合
- 模块注册表: 使用
module_registry统一管理所有操作 - 路由分离: API 路由分离到独立文件，职责清晰
- 数据验证: 使用 Pydantic schemas 进行请求和响应验证
- 异常处理: 完善的异常处理机制，统一的错误响应格式
- 日志记录: 规范的日志记录，支持日志轮转（单文件5MB，保留5个备份）
生命周期管理
应用使用 FastAPI 的 lifespan 功能管理应用生命周期：
- 启动时:
- 初始化工具类（AppTools）
- 设置全局日志记录器
- 初始化业务模块（F6Module、F6PluginModule、OtherPluginModule）
- 注册所有操作到模块注册表
- 运行时: 处理请求，执行业务逻辑
- 关闭时: 清理资源，关闭后台调度器
任务处理机制
系统支持两种任务处理方式：
-
同步任务:
- 通过任务队列同步执行，等待结果返回
- 适用于快速操作（如登录、信息获取）
- 超时时间：55秒（简道云默认60秒超时）
-
后台任务:
- 在模块函数内部启动线程执行耗时操作
- 立即返回"正在执行中"的提示
- 适用于批量操作（如品牌创建、数据删除）
- 执行完成后自动更新简道云表单并提交工作流
简道云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 | 需配置 |
📝 开发指南
添加新操作
-
在模块中实现方法:
# app/module/your_module.py class YourModule: def your_action(self, data: Dict[str, Any]) -> Dict[str, str]: # 实现业务逻辑 return {'msg': '操作完成'} -
在 main.py 中注册:
# 在 lifespan 函数中 core_manager.register_action( 'your_action', your_module.your_action, 'your_module', description='操作描述' )
添加新路由
在 app/api/routes.py 中添加新的路由：
@router.post("/your-endpoint", tags=["业务"])
async def your_endpoint(
request: Request,
logger: logging.Logger = Depends(get_logger)
):
# 实现路由逻辑
return {"message": "success"}
添加新的数据模型
在 app/schemas.py 中添加新的 Pydantic 模型：
class YourRequest(BaseModel):
field1: str = Field(..., description="字段1")
field2: Optional[int] = Field(None, description="字段2")
添加后台任务
-
在 tasks 目录下创建任务文件:
# app/tasks/your_tasks.py def your_task_background(data, ...): # 实现后台任务逻辑 # 完成后调用 update_jiandaoyun 和 approve_workflow -
在模块中调用:
import threading from app.tasks.your_tasks import your_task_background thread = threading.Thread(target=your_task_background, args=(...)) thread.start() return {'msg': '正在执行中'}
🧪 测试
健康检查测试
curl http://localhost:5003/health
Webhook 测试
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 编码
- 日志格式：
时间戳 级别:模块名:消息
⚠️ 注意事项
- API Token: 当前 API Token 硬编码在配置文件中，生产环境建议使用环境变量管理
- CORS: 当前配置允许所有来源，生产环境建议限制允许的来源
- 超时时间: 任务执行超时时间默认为 55 秒，可根据需要调整
- 文件存储: 下载的文件存储在
下载文件/目录，注意定期清理 - 验证码识别: 需要系统安装 Tesseract OCR 才能正常识别验证码
- 删除操作: 删除客户和车辆时会检查会员卡和消费记录，有记录的数据会被跳过
- 批量操作: 批量操作在后台线程中执行，不会阻塞主请求
🔄 版本历史
-
v2.0.0:
- fastapi 完全重构
- 支持 F6 系统相关操作
- 支持BI任务处理
-
1.0.0: 初始版本
- 实现基本的 Webhook 接口
- 支持 F6 系统相关操作
📄 许可证
本项目为内部项目，仅供内部使用。
📞 联系方式
如有问题，请联系数据组。
最后更新: 2025年