goods/tools/bypos-collector/使用说明.md

中心库商品采集器 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