WooCommerce 管理器 - Flutter 跨平台应用

WooCommerce本地管理器的Flutter跨平台应用版本，支持 Windows、Android 平台。

功能特性

• 连接管理: 安全连接WooCommerce API，支持配置保存和连接测试
• 商品管理: 搜索、浏览商品，查看价格、库存等详细信息
• 订单管理: 按状态筛选订单，查看订单详情
• 客户管理: 搜索客户，查看客户信息和历史记录
• 扫码查询: 支持摄像头扫描SKU/条码，快速查询商品
• 扫码枪支持: 支持 USB/蓝牙扫码枪全局监听，快速查询商品
• 离线模式: 基于本地缓存的离线浏览功能
• 扫描历史: 记录所有扫描记录，支持导出

技术栈

• 框架: Flutter 3.x
• 状态管理: Provider
• 网络请求: Dio
• 本地存储: Hive + SharedPreferences
• 扫码功能: mobile_scanner
• 架构: MVVM + Repository Pattern

项目结构

lib/
├── main.dart                    # 应用入口
├── models/                      # 数据模型
│   ├── product.dart            # 商品模型
│   ├── order.dart              # 订单模型
│   ├── customer.dart           # 客户模型
│   ├── config.dart             # 配置模型
│   └── scan_record.dart        # 扫描记录模型
├── providers/                   # 状态管理
│   └── app_provider.dart       # 主应用Provider
├── services/                    # 业务逻辑
│   ├── woocommerce_api.dart    # WooCommerce API封装
│   └── storage_service.dart    # 本地存储服务
├── screens/                     # 页面
│   ├── config_screen.dart      # 配置页面
│   ├── products_screen.dart    # 商品管理页面
│   ├── orders_screen.dart      # 订单管理页面
│   ├── customers_screen.dart   # 客户管理页面
│   └── scan_screen.dart        # 扫码查询页面
├── widgets/                     # 组件
│   └── product_card.dart       # 商品卡片组件
└── utils/                       # 工具类
    ├── constants.dart          # 常量定义
    └── connectivity_helper.dart # 网络检测工具

快速开始

环境要求

通用:

• Flutter SDK 3.0.0 或更高版本
• Dart SDK 3.0.0 或更高版本
• Android Studio / VS Code

Android 平台:

• Android SDK (API 21+)

Windows 平台:

• Visual Studio 2022 (Community 或更高版本)
• 必须安装 "使用 C++ 的桌面开发" (Desktop development with C++) 工作负载
• Windows 10 SDK 或 Windows 11 SDK

安装步骤

1. 克隆项目

cd woo_manager_app

2. 安装依赖

flutter pub get

3. 生成Hive适配器

flutter pub run build_runner build --delete-conflicting-outputs

4. 运行应用

Android 平台:

flutter run -d <android_device_id>
# 或使用提供的构建脚本
.\build.bat

Windows 平台:

# 首先需要安装 Visual Studio（见下方 Windows 平台配置）
flutter config --enable-windows-desktop
flutter run -d windows
# 或使用提供的构建脚本
.\build_windows.bat

Windows 平台配置

1. 安装 Visual Studio

1. 下载 Visual Studio Community 2022（免费）:

   • 访问: https://visualstudio.microsoft.com/downloads/

2. 安装时必须选择工作负载:

   • ✅ 使用 C++ 的桌面开发 (Desktop development with C++)

3. 确保包含以下组件:

   • ✅ MSVC v143 - VS 2022 C++ x64/x86 生成工具
   • ✅ Windows 10 SDK 或 Windows 11 SDK
   • ✅ C++ CMake 工具

2. 启用 Windows 桌面支持

flutter config --enable-windows-desktop

3. 验证安装

flutter doctor

应该看到:

[√] Visual Studio - develop Windows apps

flutter devices

应该看到:

Windows (desktop) • windows • windows-x64

4. 构建和运行

运行调试版本:

flutter run -d windows

构建发布版本:

flutter build windows --release

输出位置: build\windows\x64\runner\Release\woo_manager_app.exe

Windows 平台注意事项

1. 摄像头权限: Windows 上不需要配置摄像头权限（会自动请求）
2. 扫码枪: 完全支持 USB/蓝牙扫码枪
3. 窗口大小: 默认窗口大小，可自由调整
4. 键盘快捷键: 完全支持键盘操作
5. 文件路径: 使用 Windows 路径格式

构建 Android APK

Debug版本

flutter build apk --debug

输出位置: build/app/outputs/flutter-apk/app-debug.apk

Release版本

1. 创建签名密钥

keytool -genkey -v -keystore ~/upload-keystore.jks -keyalg RSA -keysize 2048 -validity 10000

2. 创建 key.properties 文件

在 android/ 目录下创建 key.properties 文件：

storePassword=your_password
keyPassword=your_password
keyAlias=upload
storeFile=/path/to/your/upload-keystore.jks

3. 配置签名（已完成）

• android/app/build.gradle 已配置签名相关代码
• android/key.properties 需要手动创建

4. 构建Release APK

flutter build apk --release

输出位置: build/app/outputs/flutter-apk/app-release.apk

构建App Bundle (用于Google Play)

flutter build appbundle --release

输出位置: build/app/outputs/bundle/release/app-release.aab

使用说明

首次配置

1. 启动应用后，点击右上角设置图标
2. 填写WooCommerce站点信息：
   • 站点URL (如: https://yourstore.com)
   • Consumer Key (在WooCommerce后台获取)
   • Consumer Secret (在WooCommerce后台获取)
3. 点击"测试连接"验证配置
4. 点击"保存配置"

获取WooCommerce API密钥

1. 登录WordPress后台
2. 进入 WooCommerce -> 设置 -> 高级 -> REST API
3. 点击"添加密钥"
4. 填写描述、选择权限（建议选择"读取"）
5. 生成后会显示Consumer Key和Secret

主要功能

商品管理

• 点击"同步数据"下载所有商品到本地
• 使用搜索框按名称/SKU/EAN码搜索
• 点击商品卡片查看详情

订单管理

• 选择订单状态筛选
• 查看订单详情和商品清单

客户管理

• 按姓名或邮箱搜索客户
• 查看客户订单历史和消费总额

扫码查询

• 点击扫描框开始扫描条码（使用摄像头）
• 或手动输入SKU/条码
• Windows 平台特别支持: 使用 USB/蓝牙扫码枪直接扫描
• 查看扫描历史记录

权限说明

Android 平台:

• INTERNET: 访问WooCommerce API
• CAMERA: 扫码功能使用摄像头
• ACCESS_NETWORK_STATE: 检测网络状态

Windows 平台:

• INTERNET: 访问WooCommerce API
• CAMERA: 扫码功能使用摄像头（首次运行时自动请求）
• 无需额外权限配置

离线模式

当网络不可用时，应用会自动切换到离线模式：

• 商品: 使用本地缓存数据
• 订单: 需要联网访问
• 客户: 需要联网访问
• 扫码: 使用本地缓存查询

故障排查

构建失败

flutter clean
flutter pub get
flutter run

Hive适配器未生成

flutter pub run build_runner build --delete-conflicting-outputs

网络连接问题

• 检查URL格式是否正确 (需包含 http:// 或 https://)
• 确认API密钥权限配置正确
• 检查防火墙设置

配置文件

应用信息

• 应用名称: WooCommerce管理器
• 包名: com.woo_manager.woo_manager_app
• 版本: 1.0.0

Android配置

• 最低SDK: 21 (Android 5.0)
• 目标SDK: 34 (Android 14)
• 编译SDK: 34

许可证

本项目仅供学习和个人使用。

技术支持

如有问题，请检查：

1. Flutter环境是否正确配置
2. 依赖是否完整安装
3. WooCommerce API密钥是否有效
4. 网络连接是否正常

更新日志

v1.0.0 (2026-01-12)

• 初始版本发布
• 支持商品、订单、客户管理
• 支持扫码查询功能
• 支持 Android 和 Windows 平台
• 支持 USB/蓝牙扫码枪全局监听
• 支持离线模式
• 支持扫描历史记录导出
• 支持商品名称、SKU、EAN 码搜索
• 添加应用 Logo