有赞零售小票打印跨平台解决方案
作者：王前、林昊（鱼干）
一、背景
零售商家的日常经营中，小票打印的场景无处不在，顾客的每笔消费都会收到商家打印出的消费小票，这个是顾客的消费凭证，所以小票的内容对顾客和商家都尤为重要。对于有赞零售应用软件来说，小票打印功能也是必不可少的，诸多业务场景都需要提供相应的小票打印能力。
- 打印需求端
- 小票业务场景
- 小票打印机设备类型
过去我们存在的痛点：
- 每个端各自实现一套打印流程，方案不统一。导致每次修改都会三端修改，而且 iOS 和 Android 必须依赖发版才可上线，不具有动态性，而且研发效率比较低。
- 打印小票的业务场景比较多，每个业务都自己实现模板封装及打印逻辑，模板及逻辑不统一，维护成本大。
- 多种小票设备的适配，对于每个端来说都要适配一遍。
其中最主要的痛点还是在于第一点，多端的不统一问题。由于不统一，导致开发和维护的成本成倍级增长。
针对以上痛点，小票打印技术方案需要解决的三个主要问题：
- iOS 、安卓和网页端的零售软件都需要提供小票样式设置和打印的能力，如何降低小票打印代码的维护和更新成本。
- 如何定制显示不同业务场景的小票内容：不同业务场景下的小票信息都不尽相同，比如购物小票和退款小票，商品信息的样式是一样的，但是支付信息是不一样的，购物小票应当显示顾客的支付信息，退款小票显示商家退款信息。
- 如何更灵活的适配多种多样的小票打印机，从连接方式上分为蓝牙连接和 WIFI 连接，从纸张样式分为 80mm 和 58mm 两种宽度。
二、整体解决方案
针对以上三个问题，我们提出了一个涉及前端、移动端和服务端的跨平台解决方案，
- 架构图
架构设计的核心在于通过 JS 实现支持跨平台的小票解析脚本，并具有动态更新的优势；通过服务端下发可编辑的样式模板实现小票内容的灵活定制；客户端启动 JS 执行器执行 JS 小票脚本引擎（以下简称：JS 引擎）并负责打印机设备的连接管理。
1 、JS 引擎设计
JS 引擎主要能力就是处理小票模版和业务数据，将业务数据整合到模版中（处理不了的交给移动端处理，比如图片），然后将整合模版数据转换成打印指令返给移动端。
- 整体处理流程图
- 结构设计
- 小票格式中，打印机是一行一行的输出。那么基本输出布局单位，我们定义为 layout
- 默认一行有一个内容块，即一个 layout 里面有一个 content object
- 当一行有多列内容的时候，即一个 layout 里面包含 N 个 content object 。 各自内容块有 pagerWeight 代表每个内容的宽度占比
- 每一行的后面的是一个占位符，用数据模型的 key 做占位
小票 layout 样式描述：
content block 内容块：
不同类型内容所支持的能力：
- 模版编译
这里使用了 HandleBars.js 作为模板编译的库。此外，目前还额外提供了部分能力支持。
自定义能力：
- 打印机设备适配
主要进行适配指令集解析适配，根据连接不同设备进行不同指令解析。目前已适配设备：365wifi 、 sunmi 、 sprt80 、 sprt58 、 wangpos 、 aclas 、 xprinter 。如果连接未适配的设备抛出找不到相应打印机解析器 error。
- 调用对应打印机的 parser 指令解析流程
-
兼容性问题
- 切纸：支持外部传入是否需要切纸，防止外部发送打印指令时加入切纸指令后重复切纸问题，默认加切纸指令。
- 一机多尺寸打印：存在一台打印机支持两种纸张打印（ 80mm 、 58mm ），这时需要从外部传入打印尺寸，默认 80mm 。比如，sunmiT1 支持 80mm 和 58mm 打印，默认是 80mm 。
-
容错处理
- 由于模版解析有一定格式要求，所以一些特殊字符及转移字符存在数据中会存在解析错误。所以 JS 在传入数据时，做了一层过滤，将 “\\” 、 “\n” 、 “\b” … 等字符去掉或替换，保证打印。
- 如果在解析过程中存在错误，将抛出异常给移动端捕获。
2 、模板管理服务
小票模板的动态编辑和下发，模版动态配置信息存储和各业务全量模版存储，提供移动端动态配置信息接口，拉取业务小票模版接口，各业务方业务数据接口。
- 整体处理流程图
- 小票基础模版库存储示例
shopId：店铺 ID
business：业务方
type：打印内容类型
content：layout 中 content 内容
sortWeight：排序比重，用于输出模板 layout 顺序
- 动态设置数据存储示例
shopId：店铺 ID
business：业务方
type：打印内容类型
params：需要替换填充的内容
- 接口返回整合后的小票模版 json
{
"business": "shopping",
"shopId": 111111,
"id": 321,
"version": 0,
"layouts": [{
"name": "LOGO",
"content": "[{\"content\":\"http://www.test.com/test.jpg\",\"contentType\":\"image\",\"textAlign\":\"center\",\"width\":45}]"
},{
"name": "电话",
"content": "[{\"content\":\"电话：{{mobile}}\",\"contentType\":\"text\",\"textAlign\":\"left\",\"fontSize\":\"default\",\"pagerWeight\":1}]"
},...]
}
其中相关动态数据后端已经做过整合替换，需要替换的业务数据保留在模板 json 中，等获取业务数据后由 JS 引擎进行替换。
上面 json 中 http://www.test.com/test.jpg 就是动态整合替换数据，{{mobile}} 是一个需要替换的业务数据。
3 、移动端
移动端除了动态模版配置之外，主要的就是打印流程。移动端只需要关心需要打印什么业务小票，然后去后端拉取业务小票模版和业务数据，将拉取到的数据传给 JS 引擎进行预处理，返回模版中处理不了的图片 url 信息，然后移动端进行下载图片，进行二值转换，输出像素的 16 进制字符串，替换原来模版中的 url ，最后将连接的打印机类型和处理后的模版传给 JS 引擎进行打印指令转换返回给打印机打印。
- 动态模版配置
动态配置小票内容，支持 LOGO 、店铺数据、营销活动配置等。左侧为在 80mm 和 58mm 上预览样式。通过动态配置模版，实现后端接口模版更新，然后可以实时同步修改打印内容。网页零售软件上动态配置内容和移动端一样。
- 打印业务流程
该业务流程，移动端完全脱离数据，只需要做一些额外能力以及传输功能，有效解决了业务数据修改依赖移动端发版的问题。 Android 和 iOS 流程统一。
三、移动端功能设计
1 、动态化
动态化在本解决方案里是必不可少的一环，实时更新业务数据模板依赖于后端，但是 JS 解析引擎的下发要依靠移动端来实现，为了及时修复发现的 JS 问题或者快速适配新设备等功能。更新流程图如下：
这里说明一下，因为可能会出现执行 JS 的过程中，正在执行本地 JS 文件更新，导致执行 JS 出错。所以在完成本地更新后会发送一个通知，告知业务方 JS 已更新完成，这时业务方可根据自身需求做逻辑处理，比如重新加载 JS 进行处理业务。
2 、JS 执行器
iOS 使用 JavaScriptCore 框架，Android 使用 J2V8 框架，具体框架的介绍这里就不说明了。JS 执行器设计包含加载指定 JS 文件，调用 JS 方法，获取 JS 属性，JS 异常捕获。
/**
初始化 JSExecutor
@param fileName JS 文件名
@return JSExecutor
*/
- (instancetype)initWithScriptFile:(NSString *)fileName;
/**
加载 JS 文件
@param fileName JS 文件名
*/
- (void)loadSriptFile:(NSString *)fileName;
/**
执行 JS 方法
@param functionName 方法名
@param args 入参
@return 方法返回值
*/
- (JSValue *)runJSFunction:(NSString *)functionName args:(NSArray *)args;
/**
获取 JS 属性
@param propertyName 属性名
@return 属性值
*/
- (JSValue *)getJSProperty:(NSString *)propertyName;
/**
JS 异常捕获
@param handler 异常捕获回调
*/
- (void)catchExceptionWithHandler:(JSExceptionHandler)handler;
加载 JS 文件方法，可以加载动态下发的 JS 。逻辑是先判断本地下发的文件是否存在，如果存在就加载下发 JS ，否则加载 app 中 bundle 里面的 JS 文件。
- (void)loadSriptFile:(NSString *)fileName{
NSArray *paths = NSSearchPathForDirectoriesInDomains(NSDocumentDirectory, NSUserDomainMask, YES);
if (paths.count > 0) {
NSString *docDir = [paths objectAtIndex:0];
NSString *docSourcePath = [docDir stringByAppendingPathComponent:[NSString stringWithFormat:@"%@.js", fileName]];
NSFileManager *fm = [NSFileManager defaultManager];
if ([fm fileExistsAtPath:docSourcePath]) {
NSString *jsString = [NSString stringWithContentsOfFile:docSourcePath encoding:NSUTF8StringEncoding error:nil];
[self.content evaluateScript:jsString];
return;
}
}
NSString *sourcePath = [[YZCommonBundle bundle] pathForResource:fileName ofType:@"js"];
NSAssert(sourcePath, @"can't find jscript file");
NSString *jsString = [NSString stringWithContentsOfFile:sourcePath encoding:NSUTF8StringEncoding error:nil];
[self.content evaluateScript:jsString];
}
这时候可能会有人疑问，为什么这里是直接强制加载本地下发 JS ，而不是对比版本优先加载。这里主要有两点原因：
- 动态下发 JS 文件，就是为了补丁或者优化更新，所以一般新版本下发配置不会存在
- 为了支持 JS 版本回滚
JS 异常捕获功能，将异常抛出给业务方，可以让调用者各自实现逻辑处理。
3 、缓存优化
由于模板和数据都在后端，需要拉取两次接口进行打印，所以需要提供一套缓存机制来提高打印体验。由于业务数据需要实时拉取，所以必须走接口，模板相对于业务数据来说，可以允许一定的延迟。所以，模板采用本地文件缓存，业务数据采用和业务打印页面挂钩的内存缓存，业务数据只需要第一次打印是请求接口，重新打印直接使用。
流程图：
本缓方案存会存在偶现的模板不同步问题，在即将打印时，如果网页后台修改了模板，就会出现本次打印模板不是最新的，但是在下一次打印时就会是最新的了。由于出现的几率比较低，模板也允许有一点延迟，所以不会影响整体流程。
对于离线场景，我们在 app 中存放一个最小可用模板，专门用于离线下小票打印使用。为什么是最小可用模板，因为离线下，业务数据及一些其他数据有可能不全，所以最小可用模板可以保证打印出来的数据准确性。
4 、图片处理
由于 JS 引擎是不能解析图片文件的，所以在最初模板中存在图片链接时，全部由移动端进行处理，然后进行替换。图片处理主要就是下载图片，图片压缩，二值图处理，图片像素点压缩（打印指令要求），每个字节转换成 16 进制，拼接 16 进制字符串。
- 下载图片
采用 SDWebImage 进行下载缓存，创建并行队列进行多图片下载，每下载成功一张后回到主线程进行后续的相关处理。所有图片都处理完成或，回调给 JS 引擎进行指令解析。
- 图片压缩
根据 JS 引擎模板要求的 width（必须是 8 的倍数，后续说明），进行等比例压缩，转换成 jpg 格式，过滤掉 alpha 通道。
- 二值图处理
遍历每一个像素点，进行 RGB 取值，然后算出 RGB 均值与 255 的比值，根据比值进行取值 0 或 255 。这里没有使用直方图寻找阈值 T 的方式进行处理，是出于性能和时间考虑。
- 像素点压缩
由于打印机指令要求，需要对转换成二值后的每个点进行 width 上压缩，需要将 8 个字节压缩到 1 个字节，这里也是为什么图片压缩时 width 必须是 8 的倍数的原因，否则打印出来的图片会错位。
- 16 进制字符串
因为打印机打印图片接收的是 16 进制字符串，所以需要将处理后的每个字节转换成 16 进制字符，然后拼成一个字符串。
5 、实现多次打印
由于业务场景需要，需要自动打印多张小票，所以设计了多次打印逻辑。由于每次打印都是异步线程中，所以不可以直接循环打印，这里使用信号量 dispatch_semaphore_t ，在异步线程中创建和 wait 信号量，每次打印完成回调线程中 signal 信号量，实现多次打印，保证每次打印依次进行。如果中途打印出错，则终止后续打印。
dispatch_async(dispatch_get_global_queue(0, 0), ^{
dispatch_semaphore_t semaphore = dispatch_semaphore_create(0);
for (int i = 1; i <= printCount; i++) {
if (stop) {
break;
}
[self print:template andCompletionBlock:^(State state, NSString *errorStr) {
dispatch_async(dispatch_get_main_queue(), ^{
if (errorStr.length > 0 || i == printCount) {
if (completion) {
completion(state, errorStr);
}
stop = YES;
}
dispatch_semaphore_signal(semaphore);
});
}];
dispatch_semaphore_wait(semaphore, dispatch_time(DISPATCH_TIME_NOW, 15*NSEC_PER_SEC));
}
});
四、总结与展望
本方案已经实施，在零售 app 中使用来看，已经满足目前大部分业务场景及需求，后续的开发及维护成本也会大幅度降低，提高了研发效率，接入新业务小票也比较方便。客户使用上来说，使用体验和以前没有较大差别，同时在处理客户反映的问题来说，也可以做到快速修改，实时下发等。不过目前还存在一些不足点，比如说图片打印的功能，还不能完全满足所有图片都做到完美打印，毕竟图片处理考虑到性能体验方面；还有模板后续可以增加版本号，这样在模板存在异常时也可以回滚或兼容处理等；再者就是缓存优化可以后续进一步优化体验，比如加入模板推送，本地缓存优化等。
参考链接
- HandleBars, by wycats
- date-fns, by date-fns
- lodash, by Lodash
- JavaScriptCore, by Apple
- J2V8, by eclipsesource