简道云V2.0
This commit is contained in:
@@ -0,0 +1,391 @@
|
||||
# 简道云 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年
|
||||
Reference in New Issue
Block a user