scbank-sync/README.md

# 四川银行权益商城自动化工具 (SCBank Tool)

本项目用于自动化处理四川银行权益商城的订单数据，包含数据采集（Collector）和数据处理与上传（Processor）两个主要功能。

## 核心功能

1.  **数据采集 (Collector)**:
    - 自动启动 Chromium 浏览器，监听网络请求。
    - 自动识别并捕获“列表”和“详情”数据包，保存为 `.jsonl` 格式。
    - 自动翻页和点击详情，无需人工干预。
    - 数据保存在 `data/` 目录下。

2.  **数据处理 (Processor)**:
    - 扫描 `data/` 目录下的原始数据。
    - 智能合并列表数据与详情数据。
    - 对接内部实物系统 API，自动上传订单。
    - 导出处理结果为 Excel 文件至 `output/` 目录。
    - 自动归档已处理文件至 `data/archive/` 目录。

## 文件说明

- `main.py`: 程序入口，提供交互式菜单。
- `scbank_collector.py`: 采集模块，负责浏览器自动化和数据抓取。
- `scbank_processor.py`: 处理模块，负责数据清洗、API 上传和 Excel 导出。
- `requirements.txt`: Python 依赖列表。
- `build_portable.ps1`: Windows 打包脚本。

## 运行方式 (源码运行)

### 前置要求
1.  安装 Python 3.8 或以上版本。
2.  确保电脑上已安装 **Google Chrome** 或 **Microsoft Edge** 浏览器。
3.  安装依赖包：
    ```bash
    pip install -r requirements.txt
    ```

### 启动程序
```bash
python main.py
```
按提示选择功能：
- 输入 `1` 启动采集。程序会自动寻找本机安装的 Chrome 或 Edge 浏览器。
- 输入 `2` 启动处理。

## 配置文件

- `product_map.txt`: 商品名称映射配置文件。
  - 程序首次运行时会自动生成此文件。
  - 用于解决商城商品名称与货易通系统商品名称不一致的问题。
  - 格式：`商城商品名=内部商品名`，每行一条。
  - 支持 `#` 开头的注释。

## Windows 打包指南 (便携式打包 - 无需安装Python)

如果你不想在 Windows 系统中安装 Python，可以使用以下脚本进行一次性打包。
脚本会自动下载一个临时的 Python 环境，打包完成后自动删除，不会污染你的系统。

### 1. 执行打包脚本
在 Windows 中双击运行项目根目录下的 `build_portable.ps1` 文件。
或者在 PowerShell 中运行：
```powershell
.\build_portable.ps1
```

该脚本会自动执行以下操作：
1.  下载 Python 3.10 便携版 (Embeddable Package)。
2.  配置临时的 pip 环境。
3.  安装依赖库 (pandas, playwright, pyinstaller 等)。
4.  执行打包命令。
5.  清理临时文件。

### 2. 获取结果
打包完成后，可执行文件位于：
`dist\scbank_tool\scbank_tool.exe`

### 3. 运行注意事项
- **网络连接**: 脚本需要下载 Python (约 20MB) 和依赖包，请确保网络畅通。
- **权限**: 脚本需要在当前目录创建临时文件夹，请确保有写入权限。

## 常见问题

- **Q: 运行时提示 `KeyError: 'pageDataList'` 或类似错误？**
  - A: 可能是网页结构发生变化。请检查 `scbank_collector.py` 中的 Hook 逻辑。

- **Q: 上传订单失败？**
  - A: 请检查 `scbank_processor.py` 中的 `InternalApiClient` 类，确认 `app_id` 和 API 地址是否正确。

- **Q: 打包后运行闪退？**
  - A: 请在命令行中运行 exe 文件，查看具体报错信息。常见原因是缺少依赖或路径问题。