# dataflow-json-to-excel

**Repository Path**: lonlier/dataflow-json-to-excel

## Basic Information

- **Project Name**: dataflow-json-to-excel
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-08
- **Last Updated**: 2026-07-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# dataflow-json-to-excel

将旧商城 JSON 商品数据转换为新商城 Excel 导入格式。

---

## 两种使用方式

### 方式一：免安装直接使用（推荐）

下载 `dist/` 目录下的以下文件，放在同一文件夹：

| 文件 | 说明 |
|------|------|
| `dataflow-json-to-excel.exe` | 数据转换主程序 |
| `preview.exe` | 商品详情预览工具 |
| `validate.exe` | 对照表校验工具 |
| `config.py` | 配置文件（编辑此文件） |

编辑 `config.py` 配置路径后，双击对应 exe 即可运行，无需安装 Python。

### 方式二：源码运行

```bash
pip install openpyxl orjson beautifulsoup4

python main.py       # 数据转换
python preview.py    # 预览商品详情
python validate.py   # 校验对照表
```

---

## 快速开始

### 1. 配置

编辑 `config.py`，切换商城时**只需改此文件**。

**路径配置**（必须修改）：

| 配置项 | 说明 |
|--------|------|
| `JSON_ROOT` | JSON 文件根目录 |
| `BRAND_MAP_XLSX` | 品牌对照表路径 |
| `CATEGORY_MAP_XLSX` | 分类对照表路径 |
| `PRODUCTLINE_MAP_XLSX` | 产品线类别对照表路径 |
| `TEMPLATE_XLSX` | 空白导入模板路径 |
| `OUTPUT_XLSX` | 输出文件路径 |

### 2. 数据转换

```
dataflow-json-to-excel.exe        # exe 方式
python main.py                    # 源码方式
```

### 3. 预览商品详情

在正式转换前，可预览商品详情列的 HTML 渲染效果：

```
preview.exe                                   # exe 方式：交互模式选择文件
preview.exe 11444104.json                     # 预览指定文件
preview.exe 11444104.json 2                   # 预览指定文件的第3个SKU
preview.exe --all                             # 预览全部文件
preview.exe --search BTK                      # 按文件名搜索预览

python preview.py ...                         # 源码方式：参数同上
```

### 4. 校验对照表

转换前校验 JSON 数据的品牌、产品线、类别等是否能在对照表中匹配：

```
validate.exe                                  # exe 方式：校验全部JSON文件
validate.exe --search BTK                     # 按文件名搜索校验
validate.exe --report my_report               # 指定报告文件名

python validate.py ...                        # 源码方式：参数同上
```

校验结果输出到 `validate_report.txt`，包含：
- 按类型统计（品牌未匹配、产品线未匹配、分类未匹配、结构错误）
- 每个问题的文件路径、SPU索引、商品名、具体原因
- 缺失品牌、缺失产品线、缺失分类的去重汇总

### 5. 断点续传

程序自动保存进度到 `progress.json`，中断后重跑自动恢复。手动指定起始位置：

```python
START_INDEX = 50   # 从第51个文件开始（设为 0 从头开始，设为 None 自动恢复）
```

---

## 输出列（A-X）

| 列 | 字段 | 来源 |
|----|------|------|
| A | 品牌 | 对照表自动填充 |
| B | 产品线 | 对照表自动填充 |
| C | 类别 | 对照表自动填充 |
| D | 货号 | `extract_product_code` |
| E | CAS号 | `extract_cas` |
| F | 浓度 | `extract_concentration` |
| G | 纯度 | `extract_purity` |
| H | 规格 | `extract_spec` |
| I | 商品名称 | `extract_name` |
| J | 商品详情介绍 | `extract_description` → 渲染为 HTML |
| K | 商品参数 | 默认空 |
| L | 售后保障 | `extract_after_sales` |
| M | 原厂官网查看地址 | `extract_official_url` |
| N | 平台分类 | 对照表自动填充 |
| O | 商品标签 | 对照表自动填充 |
| P | 目录价 | `extract_directory_price` |
| Q | 库存 | 默认 "999" |
| R | 销售包装单位 | 默认 "pcs" |
| S | 交货期 | `extract_delivery` |
| T | 储藏条件 | `extract_storage` |
| U | 图片 | `extract_images` |
| V | 附件 | `extract_attachments` |
| W | 聚合规则 | `extract_factory_sn`（取 goodsSn） |
| X | 导入商城 | 默认 "univ" |

**字段值优先级：** `DEFAULTS` → 提取函数返回值 → 空字符串

---

## SPU/SKU 过滤

`config.py` 中支持两级过滤：

| 函数 | 作用域 | 说明 |
|------|--------|------|
| `should_skip_product(product, top_cat, bottom_cat)` | SPU 级 | 返回 True 跳过整个商品及所有 SKU |
| `should_skip_sku(product, sku, top_cat, bottom_cat)` | SKU 级 | 返回 True 只跳过当前规格 |

---

## 商品详情 HTML 渲染

商品详情列（J列）的值是 HTML，由 `config.py` 中的 `_build_description_sections()` 构建数据，`render.py` 中的 `render_description()` 渲染。

### 区段数据格式

`_build_description_sections()` 返回一个区段列表，每个区段是以下两种类型之一：

**表格区段：**
```python
{"type": "table", "groups": [
    {"groupName": "产品信息", "fieldList": [
        {"fieldName": "荧光素标记", "fieldValue": "Unconjugated"},
        {"fieldName": "纯度", "fieldValue": ">95%"},
    ]},
    {"groupName": "储藏", "fieldList": [...]},
]}
```

**段落区段：**
```python
{"type": "paragraph", "paraTitle": "基本介绍", "paraStyle": "html", "paraContent": "<p>...</p>"}
```

- `paraStyle` 为 `"html"` 时，内容原样输出
- `paraStyle` 为 `"text"` 时，内容会被智能渲染（转义、换行转 `<br>`）

区段数量不限，表格和段落可交替排列。只需在 `config.py` 的 `_build_description_sections()` 中按格式整理数据即可。

### 数据来源

表格区段支持从 SPU 和 SKU 两个层级提取字段：

| 来源 | 函数 | 说明 |
|------|------|------|
| SPU `templateFieldList` | `_extract_template_field_list()` | SPU 级模板字段 |
| SKU `templateFieldList` | `_extract_template_field_list()` | SKU 级模板字段 |
| SKU `attr` 指定字段 | `_extract_sku_attr_group()` | 由 `SKU_ATTR_FIELDS` 配置 |

`SKU_ATTR_FIELDS` 在 `config.py` 中配置：

```python
SKU_ATTR_FIELDS = {
    "spec": "规格",
    "sign": "标记",
    "purity": "纯度",
    "concentration": "浓度",
    "molecular_weight": "分子量",
    "other_name": "别名",
}
```

### 智能内容渲染

所有字段值和段落内容都经过 `_render_rich_content()` 智能处理：

| 内容类型 | 处理方式 |
|----------|---------|
| JSON 含 `imgUrl`/`url` | 解析并渲染为 `<img>` 标签 + 描述 |
| JSON 列表/字典 | 递归渲染为键值表或逗号分隔 |
| HTML 标签 | 直接输出（`<img>`、`<p>` 等自然渲染） |
| 纯文本 | 转义特殊字符，换行转 `<br>` |

---

## 对照表格式

### 品牌对照表

| A列：旧品牌名 | B列：新品牌ID | C列：新品牌名 |
|---|---|---|
| BD Pharmingen | 101 | 碧迪生物 |

- 第1行列名，数据从第2行开始

### 产品线类别对照表

| A列：旧品牌名 | B列：旧顶层分类名 | C-H列：新产品线/类别信息 |
|---|---|---|

- 第1行列名，数据从第2行开始
- 查询键：(旧品牌名, 旧顶层分类名)

### 分类对照表

| A列：序号 | B-E列：旧分类层级 | F-H列：新分类/标签信息 |
|---|---|---|

- 前3行列名，数据从第4行开始
- 支持3级/4级目录混合

---

## JSON 结构适配

`get_product_list()` 支持两种 JSON 格式：

```python
# 格式1：商品列表（多个 SPU）
{"product": [spu1, spu2, ...]}

# 格式2：单个商品（一个 SPU，多个 SKU）
{"product": {spu_dict}}
```

程序会自动识别并统一为列表处理。

---

## 打包为 exe

将程序打包为 exe（供没有 Python 环境的用户使用）：

```bash
python build.py
```

输出到 `dist/` 目录：

| 文件 | 说明 |
|------|------|
| `dataflow-json-to-excel.exe` | 数据转换主程序 |
| `preview.exe` | 商品详情预览工具 |
| `validate.exe` | 对照表校验工具 |
| `config.py` | 配置文件（用户编辑此文件） |

所有 exe 共享同一份 `config.py`，放在同一目录即可使用。

---

## 错误处理

- 单个 SKU 出错时跳过该行，继续处理
- 错误日志写入 `error.log`，格式：`[时间] ERROR | 文件夹 | 文件 | SPU索引 | SKU索引 | 错误`
- Excel 写入时自动过滤非法 XML 控制字符，避免 `IllegalCharacterError`
- 不会因单个错误中断程序

---

## 项目文件说明

| 文件 | 说明 |
|------|------|
| `config.py` | 旧商城配置（**切换商城只改此文件**） |
| `main.py` | 入口：遍历 JSON、调度处理、断点续传 |
| `extract.py` | 字段提取引擎 + SKU 匹配帮助函数 |
| `render.py` | 商品详情 HTML 渲染（表格/段落/图片） |
| `preview.py` | 浏览器预览商品详情渲染效果 |
| `validate.py` | 对照表校验工具 |
| `writer.py` | Excel 增量写入（含非法字符过滤） |
| `lookup.py` | 对照表加载与查询 |
| `progress.py` | 断点续传管理 |
| `build.py` | 打包脚本（生成 3 个 exe + config.py） |