Files

T

panda 5cde7f852a 1.客户信息修改，将硬编码改为动态取值

2.新增项目批量停用、材料批量修改功能

2026-01-08 10:19:16 +08:00

18 KiB

Raw Blame History

简道云 FastAPI 服务系统说明书

1. 系统概述

1.1 系统简介

简道云 FastAPI 服务是一个基于 FastAPI 框架开发的后端服务系统，主要用于处理简道云插件发送的业务请求，与 F6 汽车维修管理系统进行数据交互，实现数据同步、批量处理、信息管理等核心功能。

1.2 系统定位

服务对象: 简道云插件前端
集成系统: F6 汽车维修管理系统、简道云平台
主要功能: 数据同步、批量操作、信息管理、工作流自动化

1.3 系统特点

高性能: 基于 FastAPI 异步框架，支持高并发请求
模块化: 采用模块化设计，易于扩展和维护
可靠性: 完善的异常处理和重试机制
自动化: 支持后台任务自动执行和工作流自动提交
可维护性: 清晰的代码结构和完善的日志记录

2. 系统功能

2.1 F6系统集成功能

2.1.1 登录认证

功能描述: 实现 F6 系统的登录认证，支持用户名密码登录和验证码识别。

主要流程:

接收用户名、密码、公司名称
对密码进行 MD5 加密
发送登录请求到 F6 系统
如果触发验证码，自动识别并重试
选择指定公司并完成登录
返回登录结果和 Cookie 信息

技术实现:

使用 requests 库发送 HTTP 请求
使用 pytesseract 进行验证码 OCR 识别
使用 PIL 进行图像预处理（对比度、亮度调整）

2.1.2 公司信息获取

功能描述: 获取 F6 系统中用户可访问的公司列表，并保存到简道云表单。

主要流程:

使用用户名密码登录 F6 系统
获取公司列表（单店或多店）
将公司信息批量写入简道云表单
返回时间戳用于后续查询

输出格式:

单店: 返回门店名称
多店: 返回所有公司名称列表

2.1.3 门店信息获取

功能描述: 获取指定公司下的门店列表及统计数据。

主要流程:

登录 F6 系统并选择公司
获取门店列表
统计客户车辆数量和客户数量
将门店信息批量写入简道云表单
返回时间戳和统计数据

输出内容:

门店名称列表
客户车辆总数
客户总数

2.1.4 保持连接

功能描述: 心跳检测功能，用于保持连接活跃。

实现: 直接返回接收到的数据，不做任何处理。

2.2 文件处理功能

2.2.1 文件上传和下载

功能描述: 处理简道云插件上传的文件，下载并保存到本地。

主要流程:

从简道云获取文件 URL
解析文件名和扩展名
根据时间戳生成唯一文件名
下载文件到 下载文件/ 目录
返回文件保存路径

文件命名规则: 原文件名_时间戳.扩展名

2.2.2 文件校验

功能描述: 校验上传的 Excel 文件格式是否符合要求。

支持的操作类型:

create_brand: 校验第一列是否为"品牌"
modify_customer_info: 校验第一列是否为"客户手机号"
delete_cars: 暂不校验

校验流程:

读取 Excel 文件第一列
检查表头是否符合要求
返回校验结果（成功/失败）

2.3 数据管理功能

2.3.1 品牌批量创建

功能描述: 从 Excel 文件读取品牌名称，批量创建到 F6 系统。

主要流程:

从简道云获取任务数据（账号、密码、公司名称、文件路径）
登录 F6 系统
读取 Excel 文件（第一列为品牌名称）
在后台线程中批量创建品牌
立即返回"正在执行"提示
后台任务完成后更新简道云表单并自动提交工作流

后台任务处理:

遍历 Excel 文件中的每一行
调用 F6 API 创建品牌
记录成功和失败的结果
执行完成后删除上传的文件
更新简道云表单的执行明细
自动提交工作流到下一步

2.3.2 客户信息修改

功能描述: 从 Excel 文件读取客户修改信息，批量修改 F6 系统中的客户信息。

主要流程:

从简道云获取任务数据
登录 F6 系统
读取 Excel 文件（包含客户手机号、修改字段等）
获取所有客户列表
获取员工列表（用于匹配专属运营顾问）
在后台线程中批量修改客户信息
立即返回"正在执行中"提示

Excel 文件格式:

第一列: 客户手机号（必需，用于匹配）
其他列: 需要修改的字段（客户姓名、客户类型、客户来源、单位名称、专属运营顾问、客户备注等）

匹配逻辑:

根据客户手机号匹配 F6 系统中的客户
获取客户原始信息
合并 Excel 中的修改字段
解析地址信息（省市区）
匹配专属运营顾问的用户ID

2.3.3 客户信息删除

功能描述: 批量删除 F6 系统中的客户信息。

主要流程:

从简道云获取任务数据
登录 F6 系统
获取所有客户列表
获取会员卡列表（提取客户ID）
在后台线程中批量删除客户
立即返回"正在执行中"提示

删除规则:

跳过有最近消费时间的客户
跳过有会员卡的客户
8-20点之间每3.5秒删除一条，其余时间每1.5秒删除一条
记录成功和失败次数

2.3.4 车辆信息删除

功能描述: 批量删除 F6 系统中的客户车辆信息。

主要流程:

从简道云获取任务数据
登录 F6 系统
分页获取所有车辆列表
获取会员卡列表（提取车辆ID）
在后台线程中批量删除车辆
立即返回"正在执行中"提示

删除规则:

跳过有最近消费时间的客户车辆
跳过有会员卡的车辆
8-20点之间每3秒删除一条，其余时间每1秒删除一条
记录成功和失败次数

2.3.5 历史记录删除

功能描述: 删除指定门店的历史维修记录。

主要流程:

从简道云获取任务数据（账号、密码、公司名称、门店名称）
登录 F6 系统
获取门店列表并匹配门店ID
在后台线程中删除历史维修记录
立即返回"正在执行中"提示

删除方式: 调用 F6 系统的删除接口，删除整个门店的历史维修记录。

2.4 BI任务功能

功能描述: 执行 BI 相关的数据处理和报表生成任务。

当前状态: 框架已搭建，具体业务逻辑待实现。

预留接口:

支持从 Excel 文件读取数据
支持 F6 系统登录（如需要）
支持后台线程执行
支持结果回写到简道云

2.5 工作流自动化

功能描述: 自动获取简道云工作流的待处理任务并提交到下一步。

主要流程:

获取工作流实例信息
查找状态为待处理（status=0）的任务
提取任务信息（username、instance_id、task_id）
调用审批接口自动提交
记录执行结果

应用场景: 后台任务执行完成后，自动将简道云表单提交到工作流下一步，无需人工干预。

3. 技术架构

3.1 系统架构

┌─────────────────┐
│  简道云插件前端  │
└────────┬────────┘
         │ HTTP/JSON
         ▼
┌─────────────────┐
│  FastAPI 服务   │
│  ┌───────────┐  │
│  │  路由层   │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │  业务模块  │  │
│  │  - F6Module│  │
│  │  - Plugin  │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │  任务队列  │  │
│  └─────┬─────┘  │
│        │        │
│  ┌─────▼─────┐  │
│  │ 后台任务   │  │
│  └───────────┘  │
└────────┬────────┘
         │
    ┌────┴────┐
    ▼         ▼
┌────────┐ ┌────────┐
│ F6系统  │ │ 简道云 │
└────────┘ └────────┘

3.2 核心组件

3.2.1 应用入口 (main.py)

职责:

应用初始化和生命周期管理
模块注册和路由配置
异常处理器配置
中间件配置（CORS）

关键功能:

lifespan: 管理应用启动和关闭
全局异常处理
模块实例化并注册到注册表

3.2.2 路由层 (app/api/routes.py)

职责:

定义 API 端点
请求验证和参数解析
调用业务模块处理请求
返回响应

主要端点:

GET /health: 健康检查
POST /webhook: 业务请求处理

3.2.3 业务模块层

F6Module (app/module/module.py):

F6 系统登录和认证
公司信息获取
门店信息获取
保持连接

F6PluginModule (app/module/f6_plugin_module.py):

文件上传和校验
品牌批量创建
客户信息管理（修改、删除）
车辆信息删除
历史记录删除
BI任务

OtherPluginModule (app/module/other_module.py):

其他插件功能（如短信签名状态）

3.2.4 任务处理层

任务队列 (app/utils/app_tools.py):

使用 Queue 实现任务队列
后台线程处理任务
支持同步等待结果

后台任务 (app/tasks/):

common.py: 通用任务函数（更新简道云、工作流审批等）
brand_tasks.py: 品牌相关任务
customer_tasks.py: 客户相关任务
delete_tasks.py: 删除相关任务
bi_tasks.py: BI相关任务

3.2.5 核心工具层

模块注册表 (app/core/module_registry.py):

统一管理所有业务操作
支持操作查询和路由
存储操作元数据（描述、模块名等）

应用工具 (app/utils/app_tools.py):

日志记录器配置（支持轮转）
任务队列管理
请求头解码工具
后台调度器

简道云API封装 (app/api/__init__.py):

封装简道云所有API接口
支持失败重试机制
字段ID到标签名的替换
批量操作支持

3.3 数据流

3.3.1 同步任务流程

简道云插件 → FastAPI路由 → 业务模块 → 任务队列 → 处理线程 → 返回结果 → 简道云插件

3.3.2 后台任务流程

简道云插件 → FastAPI路由 → 业务模块 → 启动后台线程 → 立即返回
                                              ↓
                                        后台任务执行
                                              ↓
                                        更新简道云表单
                                              ↓
                                        自动提交工作流

3.4 技术选型

技术	版本	用途
FastAPI	0.121.0	Web框架
Uvicorn	0.38.0	ASGI服务器
Pydantic	-	数据验证
Requests	2.32.5	HTTP请求
Pandas	2.3.3	Excel处理
APScheduler	3.11.1	任务调度
Pillow	12.0.0	图像处理
Pytesseract	0.3.13	OCR识别

4. 部署运维

4.1 环境要求

操作系统: Windows/Linux/macOS
Python版本: 3.8+
内存: 建议 2GB+
磁盘: 根据文件存储需求，建议 10GB+

4.2 安装步骤

克隆代码:

git clone <repository_url>
cd fastapi_app

安装依赖:
```
pip install -r requirements.txt
```
配置环境:
- 编辑 app/config.py，配置 API Token
- 确保目录权限正确（logs、下载文件、模板文件）

启动服务:

python main.py
# 或
uvicorn main:app --host 0.0.0.0 --port 5003

4.3 生产环境部署

4.3.1 使用 Gunicorn + Uvicorn Workers

pip install gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:5003

4.3.2 使用 systemd 管理服务（Linux）

创建服务文件 /etc/systemd/system/fastapi-app.service:

[Unit]
Description=简道云 FastAPI 服务
After=network.target

[Service]
Type=simple
User=your_user
WorkingDirectory=/path/to/fastapi_app
Environment="PATH=/path/to/venv/bin"
ExecStart=/path/to/venv/bin/uvicorn main:app --host 0.0.0.0 --port 5003
Restart=always

[Install]
WantedBy=multi-user.target

启动服务:

sudo systemctl enable fastapi-app
sudo systemctl start fastapi-app

4.3.3 使用 Nginx 反向代理

Nginx 配置示例:

server {
    listen 80;
    server_name your_domain.com;

    location / {
        proxy_pass http://127.0.0.1:5003;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

4.4 监控和日志

4.4.1 日志管理

日志位置: logs/简道云.log
日志轮转: 单文件最大 5MB，保留 5 个备份
日志级别: INFO
日志格式: 时间戳级别:模块名:消息

4.4.2 健康检查

定期访问 /health 端点检查服务状态:

curl http://localhost:5003/health

4.4.3 性能监控

建议使用以下工具监控服务性能:

APM工具: New Relic、Datadog 等
日志分析: ELK Stack、Loki 等
指标监控: Prometheus + Grafana

4.5 备份和恢复

4.5.1 数据备份

需要备份的内容:

配置文件 (app/config.py)
日志文件 (logs/)
下载的文件 (下载文件/)
模板文件 (模板文件/)

4.5.2 恢复步骤

恢复代码和配置文件
恢复数据文件
重新安装依赖
重启服务

5. 安全说明

5.1 认证和授权

API Token: 使用简道云 API Token 进行认证
F6系统: 使用用户名密码登录，密码进行 MD5 加密

5.2 数据安全

敏感信息: API Token 建议使用环境变量管理
密码处理: 密码在传输前进行 MD5 加密
文件存储: 上传的文件在处理完成后自动删除

5.3 网络安全

CORS配置: 生产环境建议限制允许的来源
HTTPS: 建议使用 HTTPS 加密传输
防火墙: 限制服务端口访问

5.4 安全建议

定期更新依赖包，修复安全漏洞
使用强密码策略
定期审查日志，发现异常访问
限制文件上传大小和类型
实施请求频率限制

6. 故障排查

6.1 常见问题

问题1: 服务启动失败

可能原因:

端口被占用
依赖包未安装
配置文件错误

解决方法:

检查端口占用: netstat -ano | findstr 5003
重新安装依赖: pip install -r requirements.txt
检查配置文件格式

问题2: 登录失败

可能原因:

用户名密码错误
公司名称不正确
验证码识别失败
F6系统服务异常

解决方法:

验证用户名密码和公司名称
检查 Tesseract OCR 是否正确安装
查看日志获取详细错误信息

问题3: 文件上传失败

可能原因:

文件格式不正确
文件路径不存在
磁盘空间不足
网络连接问题

解决方法:

检查文件格式是否符合要求
确保目录存在且有写权限
检查磁盘空间
查看网络连接状态

问题4: 后台任务未执行

可能原因:

线程启动失败
任务执行异常
简道云API调用失败

解决方法:

查看日志中的错误信息
检查简道云API Token是否有效
验证任务数据格式是否正确

6.2 日志分析

查看日志文件:

tail -f logs/简道云.log

搜索错误:

grep -i error logs/简道云.log

6.3 性能优化

并发处理: 调整 Uvicorn workers 数量
数据库连接池: 如使用数据库，配置连接池
缓存: 对频繁访问的数据使用缓存
异步处理: 更多使用异步函数提高性能

7. 扩展开发

7.1 添加新功能模块

在 app/module/ 下创建新模块文件
实现业务逻辑方法
在 main.py 中注册模块和操作
在 app/schemas.py 中添加数据模型（如需要）

7.2 添加新的API端点

在 app/api/routes.py 中添加路由
使用依赖注入获取所需服务
实现业务逻辑
返回响应

7.3 添加新的后台任务

在 app/tasks/ 下创建任务文件
实现后台任务函数
在业务模块中调用，启动线程
使用 update_jiandaoyun 更新结果
使用 approve_workflow 自动提交工作流

8. 附录

8.1 API接口清单

端点	方法	描述
`/health`	GET	健康检查
`/webhook`	POST	业务请求处理

8.2 操作类型清单

操作名	模块	类型
`login_in`	F6Module	同步
`get_company_information`	F6Module	同步
`get_store_information`	F6Module	同步
`keep_alive`	F6Module	同步
`check_file`	F6PluginModule	同步
`create_brand`	F6PluginModule	后台
`delete_history`	F6PluginModule	后台
`delete_customer`	F6PluginModule	后台
`delete_cars`	F6PluginModule	后台
`modify_customer_info`	F6PluginModule	后台
`bi_task`	F6PluginModule	后台
`sms_signature_status`	OtherPluginModule	同步

8.3 配置文件说明

app/config.py:

BASE_DIR: 项目根目录
SAVE_DIRECTORY: 下载文件目录
MODE_DIRECTORY: 模板文件目录
LOGS_DIRECTORY: 日志目录
LOG_FILE: 日志文件路径
JIANDAOYUN_API_TOKEN: 简道云API Token

8.4 目录结构说明

logs/: 日志文件存储
下载文件/: 从简道云下载的文件临时存储
模板文件/: 模板文件存储
app/: 应用代码目录
app/api/: API相关代码
app/core/: 核心功能代码
app/module/: 业务模块代码
app/tasks/: 后台任务代码
app/utils/: 工具类代码

文档版本: 2.0.0
最后更新: 2025年
维护团队: 数据组

18 KiB Raw Blame History Unescape Escape

简道云 FastAPI 服务系统说明书

1. 系统概述

1.1 系统简介

1.2 系统定位

1.3 系统特点

2. 系统功能

2.1 F6系统集成功能

2.1.1 登录认证

2.1.2 公司信息获取

2.1.3 门店信息获取

2.1.4 保持连接

2.2 文件处理功能

2.2.1 文件上传和下载

2.2.2 文件校验

2.3 数据管理功能

2.3.1 品牌批量创建

2.3.2 客户信息修改

2.3.3 客户信息删除

2.3.4 车辆信息删除

2.3.5 历史记录删除

2.4 BI任务功能

2.5 工作流自动化

3. 技术架构

3.1 系统架构

3.2 核心组件

3.2.1 应用入口 (main.py)

3.2.2 路由层 (app/api/routes.py)

3.2.3 业务模块层

3.2.4 任务处理层

3.2.5 核心工具层

3.3 数据流

3.3.1 同步任务流程

3.3.2 后台任务流程

3.4 技术选型

4. 部署运维

4.1 环境要求

4.2 安装步骤

4.3 生产环境部署

4.3.1 使用 Gunicorn + Uvicorn Workers

4.3.2 使用 systemd 管理服务（Linux）

4.3.3 使用 Nginx 反向代理

4.4 监控和日志

4.4.1 日志管理

4.4.2 健康检查

4.4.3 性能监控

4.5 备份和恢复

4.5.1 数据备份

4.5.2 恢复步骤

5. 安全说明

5.1 认证和授权

5.2 数据安全

5.3 网络安全

5.4 安全建议

6. 故障排查

6.1 常见问题

问题1: 服务启动失败

问题2: 登录失败

问题3: 文件上传失败

问题4: 后台任务未执行

6.2 日志分析

6.3 性能优化

7. 扩展开发

7.1 添加新功能模块

7.2 添加新的API端点

7.3 添加新的后台任务

8. 附录

8.1 API接口清单

8.2 操作类型清单

8.3 配置文件说明

8.4 目录结构说明

18 KiB

Raw Blame History