# 中心库商品采集器 bypos-collector 使用说明

一个单文件 Windows 小程序,通过云店「新增商品」用到的同一个中心商品库
(`zc.bypos.net`)按条码批量采集商品档案(品名/规格/单位/产地/厂商/建议进价/建议零售价),
存到本地,供后续导入天工(goods)系统。

## 一、运行

1. 把 `bypos-collector.exe` 放到任意空文件夹(采集结果会生成在同一文件夹)。
2. 双击运行。会弹出一个黑色命令行窗口(不要关它),并自动打开浏览器控制台
   `http://127.0.0.1:8765/`。
   - 若没自动打开,手动在浏览器输入上面这个地址。
3. 用完直接关掉那个命令行窗口即可退出。

## 二、采集

控制台分四步:

**① 规划采集范围** —— 两种方式二选一:
- **按条码范围**:EAN-13 国标条码共 13 位,最后一位是校验位,程序自动算。
  你只填**前 12 位**的起止区间。可在「快捷填充前缀」里填如 `690100`,
  点按钮自动生成区间(`690100000000` ~ `690100999999`)。
- **按条码清单**:直接粘贴一批条码(每行一个,或空格/逗号分隔)。

**② 采集参数**:
- 并发数(默认 3)、请求间隔(默认 300ms):**越慢越安全**,上游可能对账号限频。
- 输出文件名(默认 `products.jsonl`)。
- 「同时记录未命中/无效条码」:默认只存命中的;勾上会把未命中也记下来。

**③ 运行**:点「开始采集」。进度、命中/未命中/错误实时显示。
已经采过的条码会自动跳过(可随时停了再开,断点续采)。

**④ 实时结果**:最近 60 条滚动显示。

## 三、导出

- 「下载 JSONL」:原始数据(每行一个 JSON),用于导入天工系统。
- 「导出 CSV」:Excel 可直接打开查看。

## 四、字段说明(JSONL 每行)

| 字段 | 含义 |
| --- | --- |
| barcode | 条码(GTIN/EAN-13) |
| name | 品名 |
| spec | 规格 |
| unit | 单位 |
| area | 产地/地区 |
| manufacturer | 生产企业(常为空) |
| license | 生产许可(常为空) |
| in_price | 建议进价 |
| sell_price | 建议零售价 |
| status | hit=命中 / miss=不存在 / invalid=非国标条码 / error=请求出错 |
| fetched_at | 采集时间 |

## 五、注意

- 这是用云店账号授权去查上游中心库,**批量自动**比页面里一条条查更"重",
  上游厂商可能对账号做频控/限额。请低速、分批("一点点采"),发现大量报错就降速。
- 全量 69 段是个天文数字,不要无脑全跑;建议按你关心的品牌/品类前缀分批。

## 六、命令行参数(可选)

```
bypos-collector.exe -addr 127.0.0.1:8765   # 改监听端口
bypos-collector.exe -no-open               # 不自动开浏览器
bypos-collector.exe -sdogid 137966         # 指定中心库账号 id
```