概述
本文档主要介绍面单打印业务的基础信息、相关配置、打印流程以及常见问题处理。
1. 面单打印基础信息
1.1 涉及系统
面单打印功能涉及多个前端系统：主管理系统、驿站系统、订单追踪系统
1.2 面单类型
系统支持多种面单类型的打印，包括：
- Fleet Order 面单、Transportation Order 面单、LineHaul 面单、Assignment Task 面单
- Route-easy 打标
- 寄件单、取件单、收款凭证
1.3 面单信息
面单包含的主要信息：买卖双方信息 、订单基础信息 、其他业务关联信息等
1.4 打印工具 - Printer
- 自研的 Windows 端插件，完成安装后即可使用
- 承载面单打印的核心功能
1.5 业务场景
主要应用场景：
- 卖家未贴面单
- 面单损坏需重新打印
- 部分市场需张贴逆向面单
系统入口：
- 主管理系统
- 入口："异常处理" =》 "面单打印"（正向 / 逆向面单打印入口统一）
- 正向打印：Admin/SOC/FMHUB/HUB 站点的订单，均按正向匹配对应模板
- 部分市场支持在入库收货页面直接打印
- 驿站系统
- "订单管理" =》"面单打印"
- "入库管理" =》"收货操作"（表格操作栏打印功能）
- "入库管理" =》"卖家收货" =》"面单打印"
- 订单追踪系统
- 首页设有面单打印专属入口
1.6 名词解释
| 名词 | 含义 |
|---|---|
| AWB | Air Waybill（航空运单） |
| AWB BFF | 处理面单打印字段逻辑的后端服务 |
| Basic Service | 底层服务，存储面单模板相关配置，提供与面单平台的交互接口 |
| Order Account | 订单来源 |
| Template Direction | 订单运输类型，分为正向、逆向 |
2. 相关配置
2.1 面单配置平台
该平台为面单模板相关信息的专属配置载体，核心配置规则与内容如下：
配置说明：
- 常规由业务人员操作配置，开发人员无需介入
- 模板唯一标识：global_id（即 template_id）
配置内容：
- 面单所有字段均在平台配置，可直接调用面单接口提供的基础字段
- 若涉及业务专属逻辑或特殊字段，需由业务系统自行处理字段相关信息
接口参考：面单接口字段详情，参考面单平台提供的接口文档
2.2 面单打印尺寸管理
用于配置不同面单类型的打印尺寸，核心配置宽（width）、高（height）参数，
各系统具体配置规则：
- 主管理系统
- "主站点（统一管理所有具体站点）统一预览"
- "具体站点支持本站点打印尺寸独立配置"
- 驿站系统
- 支持按站点维度配置面单打印尺寸
- 订单追踪系统
- 仅部分市场开放面单打印功能，直接沿用主管理系统默认尺寸配置
- 部分市场由面单平台团队接入打印功能，调用业务系统提供的相关接口
2.3 面单打印机配置
可以配置为"不同面单类型打印时默认使用的打印机"，核心配置项如下：
- type：面单类型
- printer：打印机名称，由打印工具提供的 API 从 Windows 电脑中获取"已连接的打印机"列表
各系统配置：
- 主管理系统：支持打印机配置功能
- 驿站系统：支持打印机配置功能
- 订单追踪系统：暂未开放打印机配置功能
3. 打印流程
3.1 涉及服务
面单打印全流程涉及的核心服务及核心职责如下：
- 面单 BFF 服务：提供与前端的交互接口，承接并处理前端打印请求
- 订单服务 ：提供订单基础数据信息
- 面单平台服务 ：提供面单模板配置和订单详细数据信息
- Basic Service 服务 ：存储 "订单来源 " 与 "面单模板 ID " 的匹配关系，提供与 AWB 面单打印服务交互的统一接口
- AWB 面单打印服务 ：根据业务数据和模板渲染，生成面单 PDF
3.2 打印请求的核心参数
- shipment_ids：运单 ID 列表
- template_direction：订单运输类型（正向 / 逆向）
3.3 打印工具（Printer）提供 4 个核心接口
/api/health：健康检查接口，校验打印工具是否成功安装/api/version：版本检查接口，确认打印工具版本是否符合业务要求/api/print：打印接口，执行面单打印的核心接口/api/printer_list：打印机列表接口，获取 Windows 电脑已连接的打印机列表
3.4 面单打印全流程
整体分为 "前端请求发起 =》后端数据处理 =》面单生成存储 =》打印工具执行" 四大阶段，核心执行步骤如下
- 前端发起打印请求：用户点击打印按钮，前端向 "面单 BFF 服务" 发起打印请求
- 接收并预处理请求："面单 BFF 服务" 接收请求后，完成接口参数处理与相关权限校验
- 获取订单基础信息：根据 shipment_ids 获取 "订单服务" 存储的订单基础信息，剔除失败订单，仅保留成功订单继续处理
- 获取订单详细信息：根据 "订单服务 " 返回成功订单的面单编号，从 "面单平台服务 " 获取 "订单详细数据信息"
- . 生成 "基础面单数据 "：根据 "订单详细数据信息 "，整合生成 "基础面单数据 "(包含地址信息、面单平台数据、自定义字段三部分)
- 获取 "面单模板 ID "：调用 "Basic Service 服务 " 获取 "订单来源 " 匹配的 template_id
- 处理 "基础面单数据 " 的自定义字段：根据 template_id 从"面单平台服务 " 读取 "面单模板配置 "，完成 "自定义字段" 部分的处理
- 生成 "面单 PDF "：聚合处理后的 "基础面单数据 " 及 "其他相关参数 " 作为入参，调用 "Basic Service 服务 "，由 "Basic Service 服务 " 转发请求至 "AWB 面单打印服务 "，生成 "面单 PDF"
- 存储 "面单 PDF " 并回传 "面单相关数据"（url / width / height 等） ："AWB 面单打印服务 " 将 "面单 PDF " 存储至 "对象存储平台 "，并把 "面单相关数据 " 返回至 "面单 BFF 服务"
- 回传 "面单相关数据 " 至前端："面单 BFF 服务 " 将 "面单相关数据" 回传至前端（作为后续前端调用的各种校验与打印接口的入参）
- 校验打印工具是否安装：前端调用
/api/health校验打印工具是否安装 - 校验打印工具版本：健康检查通过后，调用
/api/version确认打印工具版本是否符合要求 - 执行打印操作：版本校验通过，前端调用
/api/print，将所有参数传递至打印工具 - 完成面单打印：打印工具根据 "面单相关数据 " 里的 "url " 从 "对象存储平台 " 下载 "面单 PDF"，调用打印机完成实际打印
3.5 实际操作示例（从前端的角度来看）
前端对接打印工具的实际操作步骤，核心为数据获取 =》工具校验 =》执行打印三步：
- 点击打印按钮，前端调用后端接口，获取 "面单相关数据"
- 调用
/api/health接口，校验打印工具插件是否完成安装 - 调用
/api/version接口，校验打印工具的版本是否符合要求 - 调用
/api/print接口，传入参数执行面单打印
4. 打印测试
4.1 面单打印预览测试
核心验证以下内容：
- 面单数据准确性
- 面单模板匹配性
- 面单尺寸正确性
4.2 面单实际打印测试
核心验证以下内容：
- 打印工具运行状态
- 打印机配置正确性
- 打印效果是否符合要求
5. 常见问题处理
5.1 PDF 多页时，如何设置打印多页？
调用 /api/print 接口，通过 end_page 参数设置打印页数（建议将参数值设为大于 PDF 实际页数，打印工具将自动仅打印有内容的页面）
5.2 如何设置面单的打印方向（横向 / 竖向）？
调用 /api/print 接口，通过 pdf_tools 参数配置打印方向；
默认为竖向打印，当面单 width > height 时，需设置 pdf_tools: 'xypython' 实现横向打印
5.3 订单无法获取面单，导致打印操作无法执行，该如何处理？
可能的原因及对应的解决方案：
- "面单平台服务 " 侧无该订单信息
- 核查订单面单编号的正确性
- 确认订单已同步至面单平台
- "Basic Service 服务 " 侧未配置该 "订单来源 " 匹配的 "面单模板 ID "
- 检查 "订单来源 " 与 "面单模板 ID" 的匹配关系是否完成配置
- 核实 "面单模板 ID" 的正确性
- 生成 "面单 PDF " 的必填字段未传递
- 检查 "基础面单数据" 的完整性
- 确认所需的必填字段（"其他相关参数"）均已正常传递
6. 关键要点总结
6.1 打印流程要点
- ✅ 核心流程：前端发起请求 → BFF 处理 → 拉取订单数据 → 获取模板 → 生成面单 → 存储文件 → 调用打印工具 → 完成打印
- ✅ 打印前需要校验打印工具是否安装及版本是否符合要求
- ✅ 面单数据需要包含地址信息、面单平台数据、自定义字段三部分
6.2 配置要点
- ✅ 面单模板在配置平台进行配置
- ✅ 面单尺寸需要根据实际打印需求进行配置
- ✅ 打印机配置需要根据站点和面单类型进行设置
6.3 问题排查要点
- ✅ 检查订单数据是否完整
- ✅ 检查模板配置是否正确
- ✅ 检查打印工具是否正常安装
- ✅ 检查打印机配置是否正确