# 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 使用示例
   - 部署指南

## 示例模板使用

```bash
# 打印每日待办
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
```