用户手册

本手册详细介绍美团店铺数据处理工具的所有功能和使用方法。

🖥️ 界面布局详解

主界面结构

美团店铺数据处理工具采用现代化的Fluent Design界面，窗口尺寸为1400x1244像素，确保所有内容完全可见。

1. 标题区域

应用图标: 🍲 美团橙色主题图标
标题: "美团店铺数据处理工具"
副标题: "智能化商品数据提取与图片处理 - 基于QFluentWidgets"

2. 状态仪表板

实时显示处理统计信息的卡片式布局：

统计项	说明	图标
已处理商品	当前会话处理的商品总数	📦
已下载图片	成功下载的图片数量	🖼️
成功率	图片下载成功率百分比	✅

3. 应用信息卡片

显示开发者信息和使用声明：

功能简介: 工具核心功能概述
开发者: 呈尚策划运营部
使用声明: 美工专用
版权: 仅供公司内部学习使用

4. 文件处理区域

核心操作区域，包含文件选择和配置选项：

文件选择组件:

数据文件: 选择JSON格式的商品数据文件
Excel输出路径: 设置Excel文件保存位置
图片保存目录: 设置图片文件保存目录

处理选项:

☑️ 转换图片格式为JPG: 自动将WebP等格式转换为JPG
☑️ 启用文件监控: 监控文件变化并自动重新处理

5. 控制按钮区域

主要操作按钮：

按钮	功能	状态变化
开始处理	启动数据处理流程	处理中变为"停止处理"
停止处理	中断当前处理任务	仅在处理中可用
🌙 主题切换	切换深色/浅色主题	图标随主题变化
打开输出目录	打开文件输出目录	始终可用

6. 日志显示区域

高度: 280-450px，确保完整显示
功能: 实时显示处理进度、状态信息和错误日志
特性: 支持彩色日志显示和自动滚动
颜色编码:
- INFO (黑色): 正常处理信息
- WARNING (橙色): 警告信息
- ERROR (红色): 错误信息
- SUCCESS (绿色): 成功信息

📁 文件操作详解

支持的文件格式

输入文件

格式: JSON格式的文本文件
扩展名: .txt, .json
编码: UTF-8
大小限制: 建议不超过100MB

标准数据结构:

json

{
  "data": {
    "spuListVos": [
      {
        "name": "商品名称",
        "price": 原价(分),
        "discountPrice": 折扣价(分),
        "monthSale": 月销量,
        "wmProductPicVos": [
          {
            "picUrl": "图片URL",
            "picLargeUrl": "高清图片URL"
          }
        ]
      }
    ]
  }
}

输出文件

Excel文件:

格式: .xlsx
编码: UTF-8
结构: 标准化表格格式

图片文件:

输入格式: WebP, PNG, JPG, JPEG, BMP, TIFF
输出格式: JPG (统一转换)
质量: 95% (高质量)
背景: 透明背景自动替换为白色

文件选择操作

1. 选择数据文件

点击 [选择文件] 按钮
→ 打开文件对话框
→ 筛选显示 .txt 和 .json 文件
→ 选择目标文件
→ 确认文件路径显示

文件验证:

检查文件是否存在
验证文件格式是否正确
确认文件可读权限

2. 设置输出路径

Excel输出路径:

默认: malatang_products.xlsx
支持相对路径和绝对路径
自动创建不存在的目录
支持追加模式

图片保存目录:

默认: images/
建议使用相对路径
自动创建目录结构
支持自定义命名

文件监控功能

启用监控

勾选 "启用文件监控" 选项
点击 "开始处理" 按钮
系统自动启用文件监控

监控机制

技术: QFileSystemWatcher
延迟: 文件变化后延迟2秒处理
范围: 仅监控选定的数据文件
触发: 文件修改、保存操作

监控状态

📁 文件监控已启用: malatang.txt
🔄 文件监控已启动，等待文件变化...
💡 提示: 修改文件后保存即可自动触发处理

自动处理流程

文件变化检测
↓
延迟2秒等待写入完成
↓
自动启动处理线程
↓
增量数据处理
↓
更新Excel和图片
↓
继续监控

🔄 数据处理流程

完整处理步骤

步骤1: JSON文件解析

🔍 开始解析JSON文件...
→ 读取文件内容
→ 验证JSON格式
→ 提取数据结构
→ 错误处理和日志记录

可能的错误:

文件不存在或无法读取
JSON格式错误
数据结构不匹配

步骤2: 商品信息提取

📦 提取商品信息...
→ 遍历商品列表
→ 提取基本信息 (名称、价格、销量)
→ 处理图片信息
→ 数据清洗和验证

提取字段:

name: 商品名称
price: 原价 (分转元)
discountPrice: 折扣价 (分转元)
monthSale: 月销量
picUrl/picLargeUrl: 图片链接

步骤3: Excel数据管理

📊 检查现有Excel数据...
→ 加载现有Excel文件
→ 提取已有商品名称
→ 过滤重复商品
→ 准备新增数据

去重逻辑:

以商品名称为唯一标识
跳过已存在的商品
只处理新增商品

步骤4: Excel文件生成

💾 保存数据到Excel...
→ 创建或打开Excel文件
→ 添加新商品数据
→ 设置时间戳
→ 保存文件

Excel表格结构:

列名	数据类型	说明
商品名称	文本	商品的完整名称
原价	数值	商品原始价格(元)
折扣价	数值	商品折扣后价格(元)
月售数量	整数	商品月销售数量
图片链接	文本	商品图片的原始URL
图片文件名	文本	下载后的图片文件名
更新时间	日期时间	数据添加时间

步骤5: 图片下载处理

🖼️ 开始下载图片...
→ 遍历商品图片链接
→ 生成文件名
→ 下载图片文件
→ 格式转换 (如需要)
→ 保存到指定目录

下载特性:

并发下载提高效率
自动重试机制 (最多3次)
超时控制 (30秒)
进度实时显示

图片处理详解

文件命名规则

图片文件名与商品名称保持完全一致，只替换Windows文件系统不支持的字符：

原字符	替换字符	说明
`<`	`＜`	全角小于号
`>`	`＞`	全角大于号
`:`	`：`	全角冒号
`"`	`"`	全角引号
`/`	`／`	全角斜杠
`\`	`＼`	全角反斜杠
`	`	`｜`
`?`	`？`	全角问号
`*`	`＊`	全角星号

保留内容:

所有emoji表情符号
中文字符和标点
数字和英文字母
其他特殊符号

格式转换

自动转换 (默认启用):

输入格式: WebP, PNG, BMP, TIFF, GIF
输出格式: JPG
图片质量: 95% (高质量)
背景处理: 透明背景替换为白色

转换过程:

python

# 伪代码示例
image = Image.open(input_file)
if image.mode in ('RGBA', 'LA', 'P'):
    # 处理透明背景
    background = Image.new('RGB', image.size, (255, 255, 255))
    background.paste(image, mask=image.split()[-1])
    image = background
image.save(output_file, 'JPEG', quality=95)

下载状态跟踪

实时进度显示:

🖼️ 下载图片 (1/8): 麻辣鸡锁骨(小份).jpg
✅ 下载成功: 麻辣鸡锁骨(小份).jpg (245KB)
🖼️ 下载图片 (2/8): 炸鸡翅根(2个).jpg
⚠️ 下载失败: 网络超时，正在重试...
✅ 重试成功: 炸鸡翅根(2个).jpg (312KB)

统计信息:

总下载数量
成功下载数量
失败下载数量
跳过数量 (已存在)
总文件大小

⚙️ 配置选项

界面配置

主题切换

浅色主题: 默认主题，适合白天使用
深色主题: 护眼主题，适合夜间使用
切换方式: 点击 🌙 主题切换按钮
保存设置: 自动记住用户选择

窗口设置

固定尺寸: 1400x1244像素
最小化: 支持最小化到任务栏
关闭行为: 直接退出程序
图标显示: 任务栏和标题栏显示自定义图标

处理配置

可以通过修改 config.py 文件自定义处理参数：

python

# 基本配置
OUTPUT_EXCEL = "malatang_products.xlsx"   # 输出Excel文件名
IMAGES_DIR = "images"                     # 图片保存目录
LOG_FILE = "malatang_processor.log"       # 日志文件名

# 网络配置
REQUEST_TIMEOUT = 30                      # 请求超时时间（秒）
MAX_RETRIES = 3                           # 最大重试次数

# 图片转换配置
CONVERT_TO_JPG = True                     # 是否转换为JPG格式
JPG_QUALITY = 95                          # JPG图片质量 (1-100)
JPG_BACKGROUND_COLOR = (255, 255, 255)   # 透明背景替换颜色

📋 日志系统

日志级别

级别	颜色	用途	示例
INFO	黑色	正常处理信息	"开始处理数据..."
WARNING	橙色	警告信息	"商品已存在，跳过处理"
ERROR	红色	错误信息	"图片下载失败"
SUCCESS	绿色	成功信息	"处理完成!"

日志输出

界面显示

实时更新: 处理过程中实时显示日志
自动滚动: 自动滚动到最新日志
颜色编码: 不同级别使用不同颜色
时间戳: 每条日志包含时间信息

文件记录

文件位置: malatang_processor.log
格式: 时间 - 级别 - 消息
编码: UTF-8
轮转: 支持日志文件轮转

日志文件示例:

2024-01-01 12:00:00,123 - INFO - 开始处理麻辣烫数据...
2024-01-01 12:00:00,456 - INFO - 找到 8 个商品
2024-01-01 12:00:01,789 - INFO - 成功提取 8 个商品信息
2024-01-01 12:00:02,012 - WARNING - 商品"麻辣鸡锁骨"已存在，跳过处理
2024-01-01 12:00:03,345 - INFO - 下载图片: 炸鸡翅根.jpg
2024-01-01 12:00:04,678 - INFO - 数据处理完成

使用建议

定期查看日志文件了解处理详情
遇到问题时优先查看ERROR级别日志
建议保留日志文件用于问题排查

注意事项

大量数据处理时日志文件可能较大
建议定期清理旧的日志文件
重要错误信息请及时截图保存

用户手册 ​

🖥️ 界面布局详解 ​

主界面结构 ​

1. 标题区域 ​

2. 状态仪表板 ​

3. 应用信息卡片 ​

4. 文件处理区域 ​

5. 控制按钮区域 ​

6. 日志显示区域 ​

📁 文件操作详解 ​

支持的文件格式 ​

输入文件 ​

输出文件 ​

文件选择操作 ​

1. 选择数据文件 ​

2. 设置输出路径 ​

文件监控功能 ​

启用监控 ​

监控机制 ​

监控状态 ​

自动处理流程 ​

🔄 数据处理流程 ​

完整处理步骤 ​

步骤1: JSON文件解析 ​

步骤2: 商品信息提取 ​

步骤3: Excel数据管理 ​

步骤4: Excel文件生成 ​

步骤5: 图片下载处理 ​

图片处理详解 ​

文件命名规则 ​

格式转换 ​

下载状态跟踪 ​

⚙️ 配置选项 ​

界面配置 ​

主题切换 ​

窗口设置 ​

处理配置 ​

📋 日志系统 ​

日志级别 ​

日志输出 ​

界面显示 ​

文件记录 ​