126 lines
3.2 KiB
Markdown
126 lines
3.2 KiB
Markdown
# 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
|
||
```
|