receipt-printer/PROJECT.md

Receipt Printer 项目

项目概述

一个基于 WiFi ESC/POS 协议的 80mm 小票打印系统，支持：

• 可视化模板配置（YAML + 实时预览）
• REST API 调用打印
• 自动从模板提取数据 Schema
• 多种排版元素（文本、表格、图片、条码等）

技术栈

• Runtime: Bun
• Web 框架: Hono
• 模板引擎: Mustache
• 配置格式: YAML

项目结构

receipt-printer/
├── README.md              # 项目说明
├── package.json           # 依赖配置
├── docs/
│   ├── design.md          # 系统设计文档
│   └── api.md             # API 规范
├── templates/examples/    # 示例模板
│   ├── daily-todo.yaml    # 每日待办
│   ├── food-order-simple.yaml  # 餐饮订单
│   ├── fancy-receipt.yaml # 精致账单
│   ├── ticket-list.yaml   # Ticket 列表
│   └── long-text.yaml     # 长文阅读
└── src/                   # 源码目录（待开发）

核心设计决策

1. 模板配置格式

使用 YAML 而非 JSON：

• 支持注释
• 多行字符串更友好
• 编辑器支持语法高亮

2. Schema 自动生成

• 从模板中的 {{变量}} 自动提取
• 无需手动维护数据结构
• API 可 introspect 获取数据要求

3. 块类型系统

类型	用途
text	普通文本（支持样式）
row	多列行布局
table	多列表格
list	循环渲染数组
divider	分隔线
image	图片
barcode	条码/二维码
space	空行

4. 样式支持

• 对齐：left/center/right
• 字体大小：small/normal/large/xlarge
• 文本样式：bold/italic/underline
• 间距：lineHeight/marginTop/marginBottom

API 设计概览

POST   /api/print/:templateId      # 打印
GET    /api/templates              # 列出模板
GET    /api/templates/:id          # 获取模板
POST   /api/templates              # 创建模板
PUT    /api/templates/:id          # 更新模板
DELETE /api/templates/:id          # 删除模板
GET    /api/templates/:id/schema   # 获取数据 Schema
GET    /api/jobs/:id               # 查询任务状态
GET    /api/printer/status         # 打印机状态
POST   /api/printer/test           # 打印测试页

下一步开发计划

1. 核心引擎

   • YAML 模板解析
   • Mustache 数据绑定
   • ESC/POS 指令生成

2. 打印驱动

   • WiFi 打印机连接
   • 指令发送队列
   • 状态轮询

3. Web 服务

   • Hono HTTP 服务
   • REST API 实现
   • 静态文件服务

4. 配置界面

   • YAML 编辑器（CodeMirror）
   • 实时预览（HTML 模拟）
   • 数据模拟器

5. 示例与文档

   • 更多模板示例
   • API 使用示例
   • 部署指南

示例模板使用

# 打印每日待办
curl -X POST http://localhost:3000/api/print/daily-todo \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "date": "2025-02-12",
      "tasks": [
        {"status": "☐", "title": "修复 Bug #123"},
        {"status": "☑", "title": "代码审查"}
      ],
      "completedCount": 1
    }
  }'

# 获取模板 Schema
curl http://localhost:3000/api/print/daily-todo/schema