开发指南

本指南面向希望了解、修改或扩展美团店铺数据处理工具的开发者。

📁 项目结构

完整目录结构

美团店铺数据处理工具/
├── 🔥 核心程序
│   ├── gui_fluent.py              # 主界面程序 (1401行)
│   ├── malatang_processor.py      # 数据处理核心 (443行)
│   ├── gui_processor.py           # GUI处理器
│   ├── config.py                  # 配置文件
│   └── requirements.txt           # 依赖清单
│
├── 🎨 图标系统
│   ├── icons/
│   │   ├── app.ico               # 主图标文件 (美团橙色主题)
│   │   ├── app.png               # 备用PNG图标
│   │   ├── app_*x*.png           # 各种尺寸图标
│   │   └── README.md             # 图标说明
│   ├── create_icon.py            # 图标生成工具
│   └── verify_icon.py            # 图标验证工具
│
├── 📦 打包系统
│   ├── simple_build.py           # 简化打包脚本 (推荐)
│   ├── minimal_build.py          # 最简打包脚本
│   ├── quick_build.bat           # 批处理打包
│   ├── gui_fluent_with_icon.spec # Spec配置文件
│   └── install_build_deps.py     # 依赖安装脚本
│
├── 🖥️ 多版本界面
│   ├── gui_main.py               # 基础GUI (812行)
│   ├── gui_enhanced.py           # 增强版GUI (655行)
│   └── run_gui.py                # GUI启动器
│
├── 🎨 UI美化系统
│   ├── styles/modern_theme.py    # 现代化主题
│   ├── ui_enhancements.py        # UI增强功能
│   └── demo_ui_enhancements.py   # 美化演示
│
├── 🔧 工具脚本
│   ├── convert_images.py         # 图片格式转换
│   ├── verify_names.py           # 文件名验证
│   ├── demo.py                   # 功能演示
│   └── test_*.py                 # 各种测试脚本
│
├── 🚀 启动文件
│   ├── run.bat                   # GUI启动 (推荐)
│   ├── launcher.py               # 命令行菜单
│   ├── run_cli.bat               # 命令行启动
│   └── run.ps1                   # PowerShell启动
│
├── 📊 输出目录
│   ├── output/                   # Excel文件输出
│   ├── images/                   # 图片文件输出
│   ├── logs/                     # 日志文件
│   └── dist/                     # 打包输出目录
│
└── 📖 文档系统
    ├── README.md                 # 项目主文档
    ├── 项目总结.md               # 项目总结
    ├── GUI使用指南.md            # GUI使用说明
    └── 各种技术文档...

核心文件说明

文件	行数	功能	重要性
`gui_fluent.py`	1401	Fluent Design主界面	⭐⭐⭐⭐⭐
`malatang_processor.py`	443	数据处理核心逻辑	⭐⭐⭐⭐⭐
`gui_processor.py`	-	GUI专用处理器	⭐⭐⭐⭐
`config.py`	-	配置管理	⭐⭐⭐⭐
`gui_main.py`	812	基础GUI界面	⭐⭐⭐
`gui_enhanced.py`	655	增强版GUI界面	⭐⭐⭐

🛠️ 开发环境搭建

1. 环境要求

基础要求:

Python 3.7+
Git
代码编辑器 (推荐 VS Code)

推荐配置:

Python 3.9+
PyCharm Professional 或 VS Code
Windows 10/11 (主要目标平台)

2. 克隆项目

bash

# 克隆仓库
git clone https://github.com/your-org/meituan-data-processor.git
cd meituan-data-processor

# 创建虚拟环境
python -m venv venv

# 激活虚拟环境
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

3. 安装依赖

bash

# 安装开发依赖
pip install -r requirements.txt

# 安装开发工具
pip install pytest black flake8 mypy

# 安装打包工具
pip install PyInstaller

4. 验证安装

bash

# 运行测试
python -m pytest tests/

# 启动应用
python gui_fluent.py

# 检查代码风格
black --check .
flake8 .

🏗️ 架构理解

设计模式

1. MVC模式

python

# Model - 数据模型
class MalatangProcessor:
    """业务逻辑层"""
    pass

# View - 视图层
class MalatangFluentGUI:
    """用户界面层"""
    pass

# Controller - 控制器
class GUIProcessor:
    """控制器层"""
    pass

2. 观察者模式

python

# 文件监控 - 观察者模式
class QFileSystemWatcher:
    def fileChanged(self, file_path):
        # 通知所有观察者
        self.notify_observers(file_path)

3. 策略模式

python

# 多界面策略
interface_strategies = {
    'fluent': gui_fluent.MalatangFluentGUI,
    'basic': gui_main.MalatangGUI,
    'enhanced': gui_enhanced.EnhancedGUI
}

组件通信

信号槽机制

python

class ProcessorThread(QThread):
    # 定义信号
    log_signal = pyqtSignal(str, str)
    progress_signal = pyqtSignal(int)
    finished_signal = pyqtSignal(dict)
    
    def run(self):
        # 发送信号
        self.log_signal.emit("处理开始", "INFO")
        self.progress_signal.emit(50)
        self.finished_signal.emit(results)

# 连接信号槽
thread.log_signal.connect(self.add_log)
thread.progress_signal.connect(self.update_progress)

🔧 核心组件开发

1. 数据处理组件

扩展数据提取器

python

class CustomDataExtractor(DataExtractor):
    """自定义数据提取器"""
    
    def extract_custom_field(self, item):
        """提取自定义字段"""
        return item.get('custom_field', '')
    
    def _extract_single_product(self, item):
        """重写商品提取逻辑"""
        product = super()._extract_single_product(item)
        if product:
            product['custom_field'] = self.extract_custom_field(item)
        return product

添加新的数据源

python

class NewDataSource:
    """新数据源处理器"""
    
    def parse_data(self, file_path):
        """解析新格式数据"""
        # 实现新的解析逻辑
        pass
    
    def convert_to_standard_format(self, data):
        """转换为标准格式"""
        # 转换逻辑
        pass

2. 界面组件开发

创建新的界面组件

python

from qfluentwidgets import CardWidget, BodyLabel

class CustomStatsCard(CardWidget):
    """自定义统计卡片"""
    
    def __init__(self, title, value, icon):
        super().__init__()
        self.title = title
        self.value = value
        self.icon = icon
        self.init_ui()
    
    def init_ui(self):
        """初始化界面"""
        layout = QVBoxLayout(self)
        
        # 添加图标
        icon_label = QLabel(self.icon)
        layout.addWidget(icon_label)
        
        # 添加标题
        title_label = BodyLabel(self.title)
        layout.addWidget(title_label)
        
        # 添加数值
        value_label = BodyLabel(str(self.value))
        layout.addWidget(value_label)
    
    def update_value(self, new_value):
        """更新数值"""
        self.value = new_value
        # 更新界面显示

扩展主界面

python

class ExtendedMalatangGUI(MalatangFluentGUI):
    """扩展的主界面"""
    
    def __init__(self):
        super().__init__()
        self.add_custom_features()
    
    def add_custom_features(self):
        """添加自定义功能"""
        # 添加新的菜单项
        self.add_custom_menu()
        
        # 添加新的工具栏
        self.add_custom_toolbar()
        
        # 添加新的状态栏
        self.add_custom_statusbar()

3. 插件系统开发

插件接口定义

python

from abc import ABC, abstractmethod

class PluginInterface(ABC):
    """插件接口"""
    
    @abstractmethod
    def get_name(self) -> str:
        """获取插件名称"""
        pass
    
    @abstractmethod
    def get_version(self) -> str:
        """获取插件版本"""
        pass
    
    @abstractmethod
    def process_data(self, data: Dict) -> Dict:
        """处理数据"""
        pass
    
    @abstractmethod
    def get_ui_component(self) -> QWidget:
        """获取UI组件"""
        pass

插件管理器

python

class PluginManager:
    """插件管理器"""
    
    def __init__(self):
        self.plugins = {}
    
    def load_plugin(self, plugin_path: str):
        """加载插件"""
        # 动态导入插件
        spec = importlib.util.spec_from_file_location("plugin", plugin_path)
        module = importlib.util.module_from_spec(spec)
        spec.loader.exec_module(module)
        
        # 实例化插件
        plugin = module.Plugin()
        self.plugins[plugin.get_name()] = plugin
    
    def get_plugin(self, name: str) -> PluginInterface:
        """获取插件"""
        return self.plugins.get(name)
    
    def list_plugins(self) -> List[str]:
        """列出所有插件"""
        return list(self.plugins.keys())

🧪 测试开发

1. 单元测试

测试数据处理组件

python

import pytest
from malatang_processor import DataExtractor

class TestDataExtractor:
    """数据提取器测试"""
    
    def setup_method(self):
        """测试前准备"""
        self.extractor = DataExtractor(None)
    
    def test_parse_valid_json(self):
        """测试解析有效JSON"""
        # 准备测试数据
        test_data = {
            "data": {
                "spuListVos": [
                    {
                        "name": "测试商品",
                        "price": 1000,
                        "discountPrice": 800
                    }
                ]
            }
        }
        
        # 执行测试
        products = self.extractor.extract_products(test_data)
        
        # 验证结果
        assert len(products) == 1
        assert products[0]['name'] == "测试商品"
        assert products[0]['price'] == 10.0  # 分转元
    
    def test_parse_invalid_json(self):
        """测试解析无效JSON"""
        with pytest.raises(Exception):
            self.extractor.parse_json_file("invalid.json")

测试GUI组件

python

import pytest
from PyQt5.QtWidgets import QApplication
from gui_fluent import MalatangFluentGUI

@pytest.fixture
def app():
    """创建QApplication实例"""
    return QApplication([])

class TestMalatangFluentGUI:
    """主界面测试"""
    
    def test_window_creation(self, app):
        """测试窗口创建"""
        window = MalatangFluentGUI()
        assert window.windowTitle() == "美团店铺数据处理工具"
        assert window.size().width() == 1400
        assert window.size().height() == 1244
    
    def test_button_functionality(self, app):
        """测试按钮功能"""
        window = MalatangFluentGUI()
        
        # 模拟按钮点击
        window.start_btn.click()
        
        # 验证状态变化
        assert not window.start_btn.isEnabled()
        assert window.stop_btn.isEnabled()

2. 集成测试

端到端测试

python

class TestEndToEnd:
    """端到端测试"""
    
    def test_complete_workflow(self):
        """测试完整工作流程"""
        # 准备测试数据
        test_json = self.create_test_json()
        
        # 创建处理器
        processor = MalatangProcessor()
        
        # 执行处理
        processor.process_file()
        
        # 验证输出
        assert os.path.exists("malatang_products.xlsx")
        assert os.path.exists("images/")
        
        # 验证Excel内容
        df = pd.read_excel("malatang_products.xlsx")
        assert len(df) > 0
        assert "商品名称" in df.columns

3. 性能测试

压力测试

python

import time
import psutil

class TestPerformance:
    """性能测试"""
    
    def test_large_data_processing(self):
        """测试大数据处理性能"""
        # 生成大量测试数据
        large_data = self.generate_large_dataset(1000)
        
        # 监控内存使用
        process = psutil.Process()
        initial_memory = process.memory_info().rss
        
        # 执行处理
        start_time = time.time()
        processor = MalatangProcessor()
        processor.extract_products(large_data)
        end_time = time.time()
        
        # 检查性能指标
        processing_time = end_time - start_time
        final_memory = process.memory_info().rss
        memory_usage = final_memory - initial_memory
        
        # 断言性能要求
        assert processing_time < 60  # 处理时间小于60秒
        assert memory_usage < 500 * 1024 * 1024  # 内存使用小于500MB

📦 打包和部署

1. 开发环境打包

创建开发版本

bash

# 安装打包依赖
python install_build_deps.py

# 执行开发版打包
python simple_build.py --dev

# 测试打包结果
python test_exe.py

自定义打包配置

python

# custom_build.py
import PyInstaller.__main__

def custom_build():
    """自定义打包配置"""
    PyInstaller.__main__.run([
        '--onefile',
        '--windowed',
        '--name=美团数据处理工具-开发版',
        '--icon=icons/app.ico',
        '--add-data=config.py;.',
        '--add-data=styles;styles',
        '--hidden-import=qfluentwidgets',
        '--exclude-module=tkinter',
        'gui_fluent.py'
    ])

if __name__ == "__main__":
    custom_build()

2. 生产环境部署

版本管理

python

# version.py
VERSION = "2.0.0"
BUILD_DATE = "2024-01-01"
COMMIT_HASH = "abc123"

def get_version_info():
    """获取版本信息"""
    return {
        'version': VERSION,
        'build_date': BUILD_DATE,
        'commit_hash': COMMIT_HASH
    }

自动化部署脚本

bash

#!/bin/bash
# deploy.sh

echo "开始部署流程..."

# 1. 运行测试
python -m pytest tests/
if [ $? -ne 0 ]; then
    echo "测试失败，停止部署"
    exit 1
fi

# 2. 代码质量检查
black --check .
flake8 .

# 3. 打包应用
python simple_build.py

# 4. 验证打包结果
python verify_icon.py

# 5. 创建发布包
zip -r "美团数据处理工具-v2.0.0.zip" dist/ README.md

echo "部署完成!"

📝 代码规范

1. Python代码规范

命名规范

python

# 类名：大驼峰命名
class MalatangProcessor:
    pass

# 函数名：小写+下划线
def process_file():
    pass

# 变量名：小写+下划线
product_name = "商品名称"

# 常量：大写+下划线
MAX_RETRY_COUNT = 3

文档字符串

python

def extract_products(self, data: Dict) -> List[Dict]:
    """
    提取商品信息
    
    Args:
        data (Dict): 解析后的JSON数据
        
    Returns:
        List[Dict]: 商品信息列表
        
    Raises:
        ValueError: 当数据格式不正确时
        
    Example:
        >>> extractor = DataExtractor()
        >>> products = extractor.extract_products(data)
        >>> print(len(products))
        8
    """

2. 代码质量工具

配置文件

ini

# setup.cfg
[flake8]
max-line-length = 88
exclude = venv,build,dist
ignore = E203,W503

[mypy]
python_version = 3.7
warn_return_any = True
warn_unused_configs = True
disallow_untyped_defs = True

toml

# pyproject.toml
[tool.black]
line-length = 88
target-version = ['py37']
include = '\.pyi?$'
exclude = '''
/(
    \.git
  | \.venv
  | build
  | dist
)/
'''

3. Git工作流

分支策略

main          # 主分支，稳定版本
├── develop   # 开发分支
├── feature/* # 功能分支
├── hotfix/*  # 热修复分支
└── release/* # 发布分支

提交规范

feat: 添加新功能
fix: 修复bug
docs: 更新文档
style: 代码格式调整
refactor: 代码重构
test: 添加测试
chore: 构建过程或辅助工具的变动

示例:
feat: 添加图片批量转换功能
fix: 修复文件监控内存泄漏问题
docs: 更新API文档

开发建议

遵循现有的代码风格和架构模式
编写充分的测试用例
及时更新文档
使用类型提示提高代码可读性

注意事项

修改核心逻辑前请先编写测试
新功能需要考虑向后兼容性
GUI修改需要在多个分辨率下测试
打包前务必进行完整测试

开发指南 ​

📁 项目结构 ​

完整目录结构 ​

核心文件说明 ​

🛠️ 开发环境搭建 ​

1. 环境要求 ​

2. 克隆项目 ​

3. 安装依赖 ​

4. 验证安装 ​

🏗️ 架构理解 ​

设计模式 ​

1. MVC模式 ​

2. 观察者模式 ​

3. 策略模式 ​

组件通信 ​

信号槽机制 ​

🔧 核心组件开发 ​

1. 数据处理组件 ​

扩展数据提取器 ​

添加新的数据源 ​

2. 界面组件开发 ​

创建新的界面组件 ​

扩展主界面 ​

3. 插件系统开发 ​

插件接口定义 ​

插件管理器 ​

🧪 测试开发 ​

1. 单元测试 ​

测试数据处理组件 ​

测试GUI组件 ​

2. 集成测试 ​

端到端测试 ​

3. 性能测试 ​

压力测试 ​

📦 打包和部署 ​

1. 开发环境打包 ​

创建开发版本 ​

自定义打包配置 ​

2. 生产环境部署 ​

版本管理 ​

自动化部署脚本 ​

📝 代码规范 ​

1. Python代码规范 ​

命名规范 ​

文档字符串 ​

2. 代码质量工具 ​

配置文件 ​

3. Git工作流 ​

分支策略 ​

提交规范 ​

开发指南

📁 项目结构

完整目录结构

核心文件说明

🛠️ 开发环境搭建

1. 环境要求

2. 克隆项目

3. 安装依赖

4. 验证安装

🏗️ 架构理解

设计模式

1. MVC模式

2. 观察者模式

3. 策略模式

组件通信

信号槽机制

🔧 核心组件开发

1. 数据处理组件

扩展数据提取器

添加新的数据源

2. 界面组件开发

创建新的界面组件

扩展主界面

3. 插件系统开发

插件接口定义

插件管理器

🧪 测试开发

1. 单元测试

测试数据处理组件

测试GUI组件

2. 集成测试

端到端测试

3. 性能测试

压力测试

📦 打包和部署

1. 开发环境打包

创建开发版本

自定义打包配置

2. 生产环境部署

版本管理

自动化部署脚本

📝 代码规范

1. Python代码规范

命名规范

文档字符串

2. 代码质量工具

配置文件

3. Git工作流

分支策略

提交规范