📚 使用知识库
面向新手：从安装到制单、配置文件含义，以及「改哪里会影响什么」。
1. 第一次使用（推荐流程）
新用户建议按下面顺序准备，再开始制单。程序与发布包需已解压，同级有 configs/、templates/、数据库.xlsx。
-
完善数据库 — 先填三张「基础表」
用 Excel 打开
数据库.xlsx，优先维护：- 产品数据库：每个 SKU 的申报价、中英文品名、海关编码、重量等（见 各子表说明）。
- 渠道表数据库：物流商 + 国家 + 渠道 → 渠道名称；「平台」列须能匹配后续备货里的「海外仓」。
- VAT数据库：欧洲国家需要的 VAT 号、EORI 号等（发往欧洲时必填）。
海外仓地址库也建议同期维护好仓库代码与收件地址，否则发票选址会失败。
-
在「备货物流信息」填写货件
按实际出货录入：货件号、skuId、物流商、目的国、渠道、海外仓、目的仓、箱数、数量、合同单号、出厂时间等。同一货件号可多行（每行一个 SKU）。保存 Excel 后，在软件菜单「工具 → 重新加载数据库」。
-
使用发票配置编辑器，建立物流商映射
主界面菜单「工具 → 发票配置编辑器」：为各物流商新建或复制
configs/invoice/物流商.json，绑定 Excel 模板路径，配置单元格与字段映射、业务规则（仓库、报关类型等）。详见 发票配置说明。 -
制作发票
主界面 → 制作工具 → 发票制作 →「发票生成器V2(输入)」或「发票生成器V2(列表)」：输入货件号或按出厂日期批量生成。成品默认在
output/，可用菜单「文件 → 打开输出目录」查看。
提示：改完
数据库.xlsx 或 configs/invoice/ 后，建议重新加载数据库或重启对应工具，避免仍用旧缓存。
注意：编辑数据库时不要用 WPS/Excel 长期占用文件的同时点「重新加载」，容易报文件被锁定。
2. 数据库.xlsx 总览
程序启动后会把 数据库.xlsx 里所有子表读入本地缓存（与 Excel 表名必须完全一致）。
列名也须与表头一致（多空格会导致读不到列）。
维护习惯：改完 Excel → 保存并关闭占用 → 菜单「工具 → 重新加载数据库」。
多数情况下保存文件后再次打开工具也会自动同步，但以重新加载最稳妥。
必备子表（缺一张无法加载）
| 子表名（须完全一致） | 用途简述 | 主键/索引列（建议每行有值） |
|---|---|---|
| 备货物流信息 | 每票货件 + 每个 SKU 一行，是发票、报关、API、地址查询的核心 | 货件号、合同单号、出厂时间 |
| 产品数据库 | 按 SKU 存申报价、中英文品名、海关编码、重量尺寸等 | 产品SKU |
| 海外仓地址库 | 按仓库代码存收件人地址，发票与地址校验用 | 仓库代码 |
| 渠道表数据库 | 物流商 + 国家 + 渠道 → 标准渠道名称（API 渠道 code 也依赖） | 物流商、国家、渠道 |
| VAT数据库 | 按国家/平台存 VAT、EORI（欧洲国家发票必填） | 国家、平台 |
可选子表
| 子表名 | 说明 |
|---|---|
| 商检数据库 | 缺表不影响发票；商检单生成、商检预录单校验必须有此表且 SKU 有对应行 |
表与表怎么关联
备货物流信息.skuId→产品数据库.产品SKU（一行 SKU 对应一行产品资料）备货物流信息.目的仓→海外仓地址库.仓库代码（可有多行地址候选）备货.物流商 + 目的国 + 渠道 + 海外仓→渠道表数据库（还须匹配「平台」列）备货.目的国 + 海外仓→VAT数据库.国家 + 平台备货.合同单号→ 报关/商检按合同归并多货件
3. 各子表字段说明
下列「常见列」来自当前团队使用的 数据库.xlsx；多出来的列一般不影响程序，少掉必填列会在对应功能报错。
备货物流信息
结构：同一货件号可多行，每行一个 SKU（skuId）。货件级信息（物流商、目的国等）在同一货件的多行中应保持一致。
| 列名 | 含义 | 是否程序必填 |
|---|---|---|
| 货件号 | FBA/IBR/IP 等，各工具查询主键 | 是（不能为空、不能填错） |
| skuId | 与产品数据库「产品SKU」一致 | 是（发票、报关、商检） |
| 物流商 | 如皓鹏、德立迅，对应发票配置与 API | 是（发票 ） |
| 目的国 | 申报/渠道/VAT 国家 | 是（发票 ） |
| 渠道 | 与渠道表「渠道」列一致 | 是（发票 ） |
| 海外仓 | 平台名：FBA、FBT、Winit 等，须与渠道表「平台」匹配 | 是（发票 ） |
| 目的仓 | 仓库代码，关联海外仓地址库 | 是（发票 ） |
| 箱数、数量 | 该 SKU 箱数与件数 | 是（发票、报关、商检） |
| 合同单号 | 报关/商检按合同归并 | 是（报关资料制作） |
| 出厂时间 | 批量筛选、发票日期；无此列时可改用「出厂日期」列名 | 批量/列表功能需要其一 |
| 货件追踪编码 | FBA 货件 PO 号来源 | FBA 发票必填 |
| 报关类型 | 影响发票业务规则（如 0110 / 买单） | 按货代配置，建议填写 |
| 产品、颜色规格、备注、ETD/ETA 等 | 跟单、统计用 | 否（程序不强制） |
产品数据库
每个 产品SKU 一行；备货里的 skuId 必须能在这里找到。
| 列名 | 含义 | 是否程序必填 |
|---|---|---|
| 产品SKU | 主键，与备货 skuId 一致 | 是（列必须存在） |
| 发票单价、发票中文名称、发票英文名称 | 商业发票金额与品名 | 是（发票 ） |
| 海关编码、单箱毛重、采购成本、单箱数量 | 申报与成本 | 是（发票 ） |
| 报关名称、报关单价、第一法定单位、申报单位、产品净重 | 报关资料用 | 是（报关资料制作） |
| 品牌、材质、用途、申报型号、长宽高、体积、是否带电/带磁 等 | 发票明细扩展、规则判断 | 发票常用，建议填全 |
| 图片URL | 若发票配置插图且不用远程 URL | 否（配合 product_images 文件夹） |
海外仓地址库
同一 仓库代码 可有多行（不同地址编码）；发票选址时会按配置自动选一行。
| 列名 | 含义 | 是否程序必填 |
|---|---|---|
| 仓库代码 | 与备货「目的仓」一致 | 是 |
| 联系人、地址一、城市、邮编、国家 | 收件地址核心字段 | 是（发票选址后校验） |
| 公司名、联系电话、地址二/三、省/洲 | 完整地址与联系信息 | 建议填写 |
| 平台、国家 | 分类、筛选 | 建议与业务一致 |
列名别名：程序也认「地址1→地址一」「省/州→省/洲」「电话→联系电话」「邮政编码→邮编」。
渠道表数据库
| 列名 | 含义 | 是否程序必填 |
|---|---|---|
| 物流商、国家、渠道 | 与备货三字段等值匹配 | 是 |
| 平台 | 以 / 分隔，须包含备货「海外仓」之一段（如 FBA/FBT） | 是（列必须存在） |
| 渠道名称 | 写入发票、皓鹏 API 映射的展示名 | 是（命中行后用于下单） |
| 目的仓 | 为空不限制；有值时须与备货「目的仓」一致或在其 / 分隔列表中 | 按业务选填 |
VAT数据库
| 列名 | 含义 | 是否程序必填 |
|---|---|---|
| 国家、平台 | 与备货目的国、海外仓匹配查询 | 欧洲国家必须有记录 |
| VAT号、EORI号 | 欧盟清关常用 | 是（目的国为欧洲时） |
| VAT公司英文名、VAT注册地址 等 | 发票抬头信息 | 建议填写 |
商检数据库
| 列名 | 含义 | 是否程序必填 |
|---|---|---|
| 产品SKU | 与备货 skuId 一致 | 是（商检功能） |
| 商检名称、单箱数量、净重、毛重 | 生成商检单文件名与数量重量 | 是 |
| PRICE (CNY/PCS) 或 PRICE (USD/PCS) | 按生成器选择的币种填对应列 | 是（二选一） |
| 海关编码、品名、材质、规格 等 | 申报要素 | 建议填写 |
4. 按功能汇总：最少要填什么
| 功能 | 备货物流信息 | 产品数据库 | 其它表 |
|---|---|---|---|
| 发票生成器 | 货件号、skuId、物流商、目的国、渠道、海外仓、目的仓、箱数、数量；FBA 另需货件追踪编码 | 产品SKU + 发票单价/中英文名称/海关编码/单箱毛重/采购成本/单箱数量 | 地址库有该目的仓；渠道表能命中；欧洲需 VAT |
| 报关资料制作 | 合同单号、skuId、数量、箱数、目的国 | 海关编码、报关名称、第一法定单位、申报单位、报关单价、产品净重 | — |
| 商检单生成 | 合同单号、skuId、箱数 | — | 商检库有该 SKU 且商检名称/单价/重量齐全 |
| 地址查询 / 校验 | 货件号或目的仓 | — | 海外仓地址库 |
| API 下单 | 同发票 + 渠道能在 configs 映射到 service code | 同发票 | 渠道表、地址库、API 配置 JSON |
| 发票列表 / 批量建文件夹 / 箱唛下载 | 出厂时间或出厂日期、货件号、合同单号等 | 视功能而定 | — |
修改数据库会影响什么？
| 你改了什么 | 会影响的功能 |
|---|---|
| 货件号、渠道、目的仓、海外仓 | 发票 、地址查询、API 下单收件与渠道 code |
| 合同单号 | 报关资料、商检单、预录单校验 |
| 出厂时间 / 出厂日期 | 发票列表批量、批量建文件夹、箱唛下载筛选 |
| skuId、箱数、数量 | 发票行数、报关合并、货件解析、唛头校验 |
| 产品库申报价/品名/海关编码 | 发票金额与品名、报关单价与 HS |
| 渠道表「渠道名称」或皓鹏映射 | API 下单 service 字段是否匹配 |
货件号与平台：可在
configs/invoice/invoice_settings.json 配置 FBA→FBA、IBR→FBT 等前缀规则；
备货「海外仓」与货件号前缀不一致时，发票 会拦截。
5. 各工具怎么用（小白版）
📝 制作工具
发票生成器 （输入）
- 主界面 → 制作工具 → 发票制作 →「发票生成器(输入)」
- 输入货件号（或按界面提示选择），确认渠道/地址候选（配置为 strict_single 时会自动收敛）
- 生成后到
output/或工具提示的路径查看 xlsx
发票生成器 （列表）
按出厂日期列出待处理货件，勾选多条批量生成。适合一天多票统一出票。
报关资料 / 商检单
一般输入合同号，程序按 configs/报关资料.json、configs/商检单.json 填模板。输出目录可在 configs/tools_config.json 对应节点修改。
🔍 校验工具
- 地址查询：输入货件号或仓库代码，对比数据库中的标准地址。
- 报关/商检预录单校验：选择 PDF，与数据库字段比对差异。
- 唛头校验：扫描货件文件夹，检查是否缺少唛头类文件（扫描目录见 tools_config）。
🔧 辅助工具
- 批量创建文件夹：按出厂日期 + 国家归类规则建目录（路径在 tools_config → folder_creator）。
- 归类文件：从下载目录按关键词把文件复制/移动到目标货件文件夹。
- 图片压缩：批量处理 SKU 图，默认与
product_images/相关。
✨ 独特小功能
- FBA/FBT 货件解析：粘贴平台货件文本，解析 SKU 与箱数（不强制数据库）。
- 解压重命名：批量解压 zip，按货件号+规则重命名（规则在 tools_config → zip_extractor）。
- 标签复制：为每个 FBA 货件号复制一份产品标签文件。
🌐 API 工具
- API 下单：从数据库组装数据，按物流商调用皓鹏/德立迅/集浩接口；凭证与渠道 code 在
configs/api/。 - 箱唛仓单下载：按出厂日期批量拉取面单/入仓单（依赖对应 API 配置与 token）。
6. 配置文件总览（都在程序目录下）
| 路径 | 作用 | 主要影响的功能 |
|---|---|---|
数据库.xlsx |
业务数据源 | 几乎所有需数据库的工具 |
configs/tools_config.json |
各辅助工具的目录、关键词、映射 | 建文件夹、归类、压缩、校验默认路径、解压重命名规则等 |
configs/invoice/*.json |
各物流商发票 规则 | 发票生成器 、API 下单中的发票字段组装 |
configs/invoice/invoice_settings.json |
发票全局：货件号校验、国家别名 | 发票生成时的平台/国家校验逻辑 |
configs/报关资料.json |
报关模板映射 | 报关资料制作 |
configs/商检单.json |
商检模板映射 | 商检单生成 |
configs/api/*.json |
物流商 API 地址、token、渠道 code | API 下单、箱唛下载、入仓单 |
configs/api/api_config.json |
国家代码映射、已启用 API 的物流商名单 | API 能否下单、目的国 code 转换 |
configs/window_positions.json |
窗口位置记忆 | 仅影响界面布局，不影响业务结果 |
templates/ |
Excel 模板文件 | 发票、报关、商检的输出样式 |
product_images/ |
SKU 图片 | 发票中嵌入本地图片（见 invoice 里 image_settings） |
菜单「工具 → 发票配置编辑器」可图形化编辑部分发票 JSON，适合不熟悉格式的用户。
7. configs/tools_config.json — 改一项会怎样
该文件按工具名分块，改错路径通常只会导致「找不到文件夹」，不会损坏数据库。
| 配置块 | 关键字段 | 修改后的效果 |
|---|---|---|
folder_creator |
output_dir、country_folders、product_name_mapping |
批量建文件夹的根目录、国家归类到「欧洲/美国」等父文件夹、产品名显示映射 |
file_classifier |
source_dir1/2、target_dir、keywords |
归类工具从哪读文件、复制到哪、用哪些关键词识别文件类型 |
customs_generator |
output_dir、merge_mode |
报关资料输出位置；合并模式（如按 SKU）影响 sheet 结构 |
inspection_generator |
output_dir |
商检单生成保存位置 |
preentry_validator / inspection_preentry_validator |
last_dir |
下次打开校验对话框时默认选中的文件夹 |
mark_validator |
scan_dir、check_* |
唛头校验扫描根目录及检查项开关 |
image_compressor |
quality、max_width/height、output_dir |
压缩质量、是否缩放、输出目录与是否覆盖原图 |
zip_extractor |
scan_dir、rename_rules |
解压扫描目录；平台 PDF 原名 → 统一后缀（如「平台箱唛」） |
label_duplicator |
scan_dir、label_keywords |
标签复制工具的搜索目录与识别「产品标签」的关键词 |
8. configs/invoice/ — 发票配置详解
每个物流商一个 JSON（如 皓鹏.json、德立迅.json）。改错会导致发票单元格错位、渠道选错或 API 组装失败。
| 字段 | 含义 | 改了会怎样 |
|---|---|---|
logistics_name |
物流商名称，须与数据库渠道对应 | 对不上时可能选错配置或生成失败 |
template / sheet |
模板路径与工作表名 | 换模板可改版式；sheet 名错会报找不到表 |
selection_policy |
地址/渠道多候选时如何自动选 | 影响是否弹窗；strict_single 要求数据唯一 |
business_rules |
条件规则（如渠道含「空派」→ 深圳仓） | 改变发票上仓库、报关类型等推导结果 |
fixed_values |
固定写入单元格的常量 | 直接改变对应格子内容（如备注） |
mappings.single_cells |
单格：cell + source 字段路径 | 改 cell 会写错位置；改 source 会换数据来源列 |
mappings.tables |
明细表区域、行展开方式 | 影响 SKU 行数、列映射、合计行 |
image_settings |
图片列、本地目录 | 控制是否插图、从 product_images 哪张图 |
invoice_settings.json（全局）
shipment_validation：FBA/IBR 等前缀与平台是否匹配 — 开启后数据不符会拦截生成。country_aliases：国家名多种写法统一 — 影响地址/国家一致性校验。
9. configs/api/ — API 与面单配置
| 文件 | 关键项 | 修改影响 |
|---|---|---|
api_config.json |
api_enabled_logistics、country_name_to_code |
名单外的物流商无法走 API 下单；国家映射错会导致目的国 code 错误 |
haopeng_api_config.json |
gateway、access_token、haopeng_service_code_by_channel |
认证失败无法下单；渠道名与数据库不一致时 service code 匹配失败 |
delixun_api_config.json |
客户号、密钥、渠道映射 | 德立迅下单/箱唛接口鉴权与渠道选择 |
jihaoyiqipin_api_config.json |
OAuth、环境地址 | 集浩入库/面单；环境必须与 token 一致 |
label_downloader_config.json |
下载网关、输出规则 | 箱唛仓单批量下载的目标与命名 |
安全：
access_token 等敏感信息请勿提交到公开仓库。泄露后请在物流商后台轮换密钥并更新 JSON。
10. 常见问题
提示「加载数据库失败」？
确认 数据库.xlsx 在 exe 同级；关闭占用该文件的 Excel；路径含特殊字符时尝试移到英文路径。
发票生成成功但格子是空的？
检查对应 configs/invoice/物流商.json 的 source 是否与数据库列名一致；检查货件是否在库中存在。
API 下单报渠道找不到？
数据库「渠道」列必须与配置里 *_service_code_by_channel 的键名一致（皓鹏尤其要注意用 code 而非中文渠道名填 service 字段）。
改配置后要重启吗？
多数 JSON 下次打开工具时会重新读取；数据库改完用菜单「重新加载数据库」。窗口位置改 window_positions.json 后部分窗口需重启生效。
还有问题？
请到 反馈 BUG 页面提交，并注明使用的功能与配置路径。