自动报价是微客AI助手微信客服渠道的核心场景之一客户问价AI 除了回一段文字还要把报价单 PDF 作为附件发过去。链路打通的当天我们在自己机器上预览一切正常结果发出去之后被客户告知文档里所有中文都是方块。这篇复盘三个叠在一起的坑。## 事故现场开发者预览正常客户手机上是方块先说故障形状这个形状本身就有信息量。同一份 PDF在生成它的服务器上打开中文显示正常发到客户手机上打开中文全部变成方块俗称豆腐块。如果两个设备上都是方块那说明文字根本没写进去一个正常一个方块说明文字数据在但字体没带上——查看器在自己系统里找不到可用的中文字形只能画占位方块。方向立刻收敛到字体嵌入环节。## 根因一字体文件是 TTC生成库根本不吃服务器上配的中文字体是系统里的微软雅黑文件后缀 .ttc。问题就在这个后缀上。TTC 是 TrueType Collection一个文件里打包了多套字体同一族的不同字重。而 pdfkit 这类生成库的字体解析器只认单字体的 TTF 和 OTF遇到 TTC 直接跳过注册而且不报错——注册函数静默失败后续所有按字体名取字形的调用拿到空回落写出来的 PDF 只留文字编码不嵌字形。这就解释了服务器正常、手机方块服务器上装了微软雅黑PDF 查看器回退到系统字体渲染看起来没问题客户手机上没有这套字体PDF 里又没有内嵌字形方块。“我机器上看着正常在这类故障里完全不能作为验收证据必须把文件发到没有该字体的环境里验证——手机、网页查看器、老版本 Office三个环境都过才算数。修法换成单个 simhei.ttf 文件注册配合子集化嵌入只打包文档实际用到的字形控制体积。改完之后客户手机实测中文正常。## 根因二画完表格画布的横坐标没有复位字体修好紧接着暴露第二个问题从第二页开始文字整体往右偏移越往后越离谱后段的段落甚至被裁掉半行。排查渲染代码发现报价单主体是一张价格表表格的绘制逻辑在每一列画完后会把文档的内部横坐标一路往右推进表格结束的时候没有人把这个坐标拨回页边距。后续段落全部从表格末尾的横坐标起笔自然整体右飘。修法是表格绘制结束后显式把 x 复位到页边距值当时算出来是 56并加了一条断言每页渲染完成时检查光标横坐标不等于页边距就告警。这类共享可变状态跨段泄漏的 bug 在文档生成代码里很常见绘制上下文是全局的谁改动过谁负责还原——约定不清就会互相踩。## 根因三附件通道的三道尺寸闸PDF 内容对了发送环节还有最后一个坑。报价单走的是企业微信的素材上传接口附件有大小上限超限直接拒。麻烦在于这个上限在三个地方各写了一遍前端上传组件的校验、桥接服务的校验、企微接口本身的限制。三处数值没对齐时会出现前端放行、服务端拒或反过来用户看到的就是发送失败但不知道卡在哪一层。我们把三处统一成同一个常量来源并在素材入库时加了体积预检超限先压字体子集再试仍超限才回退成纯文字报价。另外两个配套细节报价单文件先入租户自己的媒体库按租户隔离A 客户的机器人拿不到 B 客户的文件入库记录直插数据库后要走一次缓存失效通知否则桥接服务读到旧快照会报文件不存在”发送消息的自动化标记有白名单机制报价单这类业务文件要在白名单里显式放行不然会被当成营销素材拦下。## 泛化三段链路的验收口径把这次事故拆开看三个坑分别属于生成层、渲染层、传输层而它们的共同点是每一层都存在局部正常的假象生成层字体注册静默失败渲染层表格画完不还原状态传输层三处闸值各自为政。任何一层的单元测试都抓不到整条链的问题。有效的验收只有一种在真实通道里走一次完整往返——生成、上传、手机接收、打开、检查字形和版式。我们现在把这条做成报价单模板变更后的固定回归项。## 渠道侧还有三道闸字体和排版修好之后PDF 要真正送到客户手上还有渠道层的三件事。上传接口和素材库是两套上限。企微侧对上传媒体有单文件体积限制我们自己的素材表又有一道校验两处限制必须口径一致还有一处在前端。三处里任何一处改动没同步就会出现这边传得过去、那边落不了库或者反过来的割裂。这类跨层常量改的时候要把所有消费点列出来逐个核对不能只改自己熟的那处。机器人角标的白名单。产品规矩是 AI 生成的回复要带标记但报价单这类人工维护的素材被误标成机器人内容客户观感很差。解决办法是给媒体素材建白名单走人工渠道的文件不贴角标判断依据写在素材来源字段里不在渲染层做模糊猜测。素材入库走了运维直路。报价单 PDF 入库用的是数据库直插加缓存主动失效的组合绕开后台界面的上传链路。这不是偷懒而是当时后台上传入口对超大 PNG 转码有兼容问题直插路径可控且可回滚。临时方案要有退出计划这个问题排期修复后要归位不能让直路变永久通道。## 上线纪律以真机实收为准验收口径最终固化为一条生成端自检页数、有无空白、有无方块只算内部步骤以真实设备上收到的文件为准。发布前的走查方式是直接对线上版本发起一次真实收发从文字回复到附件送达逐项确认任何一环只出在我机器上都算没修完。这条纪律在这次事故之后救过我们后来有一版字体子集化工具升级生成端自检全绿但真机验收当场发现新文件在手机阅读器里目录页不跳转又回炉了一轮。自检只能说明生成没报错真机能证明客户看到什么。## 小结PDF 中文方块先查字体嵌入而不是字体本身TTC 和 TTF 是两种东西共享绘制状态用完必须还原尺寸闸值单一定义三处引用。微客AI助手的报价单链路修完之后已经稳定服务希望这篇帮你少走我们走过的弯路。## 参考文章- 微信常见问题自动应答知识库这么搭就够了- 企业微信自动回复设置从接入到转人工的完整方案