392 lines
12 KiB
Markdown
392 lines
12 KiB
Markdown
# 简道云 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": "1.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. **批量操作**: 批量操作在后台线程中执行，不会阻塞主请求
|
||
|
||
## 🔄 版本历史
|
||
|
||
- **v1.0.0**: 初始版本
|
||
- 实现基本的 Webhook 接口
|
||
- 支持 F6 系统相关操作
|
||
- 支持文件上传和校验
|
||
- 支持品牌、客户、车辆管理
|
||
- 支持数据删除操作
|
||
- 支持BI任务处理
|
||
|
||
## 📄 许可证
|
||
|
||
本项目为内部项目，仅供内部使用。
|
||
|
||
## 📞 联系方式
|
||
|
||
如有问题，请联系数据组。
|
||
|
||
---
|
||
|
||
**最后更新**: 2025年
|