这套系统的目标，是让用户在打印机旁扫描二维码，在微信小程序里上传文件、选择打印参数、完成支付，然后由对应的实体打印机自动出纸。本文是整个工程的总入口，既记录已经真实完成的部分，也明确哪些部分仍属于生产化建设。

当前真实结论

单台 Epson L3250 的小程序上传、服务端下单、门店电脑领取任务、Windows 打印队列提交和结果回传链路已经跑通。随后用户在手机外网环境操作后反馈可以正常使用；系统侧记录为完成，但没有归档样张或设备传感器证据，因此该结论属于用户现场反馈，不等同于独立物理出纸验收。当前版本证明了技术链路可行，但真实微信支付、多打印机调度、云数据库、正式域名、管理后台和长期无人值守运维仍需继续建设。

一、这套系统由什么组成

完整系统分成五层：

  1. 微信小程序：扫码、登录、上传文件、设置参数、查看报价、支付和查询打印状态。
  2. 中心云平台：用户鉴权、文件管理、服务端定价、订单状态、支付回调、任务调度和管理后台。
  3. 对象存储与数据库：保存短期打印文件，以及订单、支付、任务、设备和审计记录。
  4. 门店边缘代理：安装在门店 Windows 电脑上，主动从云端领取任务，下载校验文件，再调用本地打印队列。
  5. 实体打印机：通过官方驱动接受打印任务。每台打印机都有独立平台编号、Windows 队列名和二维码。

推荐的生产拓扑是：

微信小程序
    │ HTTPS
    ▼
中心云平台 ── PostgreSQL / 对象存储 / 可靠队列 / 微信支付
    ▲
    │ 门店代理主动出站 HTTPS
    │
门店 Windows 代理
    ├── 打印机 A 的 Windows 队列
    ├── 打印机 B 的 Windows 队列
    └── 打印机 C 的 Windows 队列

打印机和门店电脑不需要开放公网端口。中心数据库是订单与支付的业务账本，门店代理的本地回执是物理执行的重要证据。

二、研发全过程

1. 识别现场打印机

首先确认电脑当前连接的是 Epson L3250 系列打印机，检查 Windows 队列、驱动和设备能力。该设备适合 A4、黑白和彩色、单面打印的试点，不具备 A3 和自动双面能力。

2. 判断小程序接入是否可行

打印机本身不直接理解微信小程序请求，因此确定采用“小程序 + 云端 API + 门店代理 + Windows 打印队列”的桥接方案。小程序不直连 USB 或打印机端口。

3. 建立单机原型

完成微信小程序页面、Node.js/Fastify API、SQLite 数据库、文件上传目录、Node.js/PowerShell 门店代理、SumatraPDF 和 Epson 官方驱动的组合。第一阶段先支持 PDF、JPG、JPEG 和 PNG。

4. 加入安全边界

系统增加文件大小、扩展名、文件魔数、PDF 真实页数、图片尺寸和 SHA-256 校验；加入用户请求幂等键、任务尝试号、处理租约、打印租约和 attention_required 人工确认状态。

5. 完成真实打印测试

先完成两个受控 Windows 队列级打印作业，每次提交参数均为 A4、彩色、单面、1 份。之后用户在手机外网环境操作后反馈可以正常使用，系统中的订单与打印任务进入完成状态，打印队列清空。原验收报告形成于这次用户反馈之前，因此仍记录“实体出纸待现场确认”；当前没有归档样张，正式验收还应补充脱敏订单、样张照片和现场确认记录。

6. 解决真机域名限制

真机曾出现 request:fail url not in domain list，原因是微信小程序只允许访问后台配置的 HTTPS 合法域名。开发阶段的临时地址只能用于受控测试；生产应使用固定域名 print-api.munvor.com，并在微信公众平台分别配置请求、上传和下载域名。

7. 形成生产化方案

在单机链路跑通后，继续设计多门店、多打印机、真实微信支付、中心数据库、对象存储、可靠队列、设备身份、管理后台、告警、退款对账和门店维护体系。

三、系列文档目录

四、完整 PDF 手册

在线文章适合搜索、持续更新和手机阅读；PDF 适合归档、评审、打印和线下交接。

下载《臻好印无人自助打印系统工程设计、部署与运维手册》PDF

PDF 共 27 页，包含架构图、状态机、API、数据模型、支付、设备接入、DNS、安全、运维、故障手册、验收矩阵和上线清单。PDF 与在线文档均不包含 AppSecret、支付私钥或临时测试地址。

五、目前可以做什么，不能做什么

项目 当前状态
微信小程序上传 PDF/图片 系统记录完成，用户现场反馈真机可用
Windows 门店代理领取任务 已完成
Epson L3250 打印队列提交 已完成 Windows 队列级测试
外网手机上传并打印 系统记录完成，用户反馈可用；待补归档样张
文件哈希、页数和限制校验 已完成基础版本
固定生产域名 已规划，仍需正式云端部署
真实微信支付 尚未完成，当前为模拟支付
多门店、多打印机调度 已完成工程设计，尚需改造代码
管理后台、告警、退款、对账 尚需生产化建设
长期公开无人值守收费运营 尚未达到上线条件

六、最重要的工程原则

  • 价格和页数必须由服务端计算，不能相信小程序提交的金额。
  • 订单、支付和打印任务必须有幂等键与数据库唯一约束。
  • 每台打印机同一时间只允许一个物理提交，不同打印机可以并行。
  • 下载和状态回报可以安全重试，但可能已经提交到实体打印机后不能自动重试。
  • Windows 队列清空不等于纸张一定完整输出；结果不确定时进入人工确认。
  • 文件默认短期保留、对象存储私有，日志不记录文件正文。
  • 门店代理只主动出站，不把打印机端口、Windows 共享或远程桌面暴露到公网。
  • AppSecret、微信支付私钥和 API v3 密钥只能保存在服务端密钥管理系统。

七、继续建设的正确顺序

  1. 固化当前单机版本和可重复部署步骤。
  2. 部署固定域名、HTTPS、PostgreSQL 和对象存储。
  3. 接入真实微信支付、退款和对账。
  4. 把所有“默认第一台打印机”和进程级全局锁改造成显式设备路由与每机独立锁。
  5. 建设设备注册、管理后台、告警和门店 SOP。
  6. 用 3—5 台设备进行真实营业试点，连续稳定后再扩到 10—50 台。
  7. 达到数百台规模前，再建设分区调度、自动升级、灾备和专门的运营体系。

这套系统真正困难的部分不是“让打印机出一张纸”，而是让资金、数字状态和物理出纸在网络中断、进程崩溃、缺纸、卡纸和回调重复的情况下仍然可解释、可恢复、可审计，并尽量阻止自动重复提交；任何不确定结果都转入人工确认。