receipt-printer/docs/api.md

API 规范

基础信息

Base URL: http://localhost:3000/api
Content-Type: application/json

端点列表

1. 打印

执行打印

POST /print/:templateId

请求体：

{
  "data": {
    "date": "2025-02-12",
    "tasks": [
      {"status": "☐", "title": "修复 Bug #123"},
      {"status": "☑", "title": "代码审查"}
    ]
  },
  "options": {
    "copies": 1,
    "cutPaper": true
  }
}

参数说明：

字段	类型	必填	说明
data	object	是	模板数据，结构由模板 Schema 定义
options.copies	number	否	打印份数，默认 1
options.cutPaper	boolean	否	是否切纸，默认 true

成功响应 (200)：

{
  "success": true,
  "jobId": "job_abc123",
  "status": "queued",
  "estimatedTime": "5s"
}

错误响应 (400/404/500)：

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "数据验证失败",
    "details": [
      "tasks: 必填字段缺失"
    ]
  }
}

错误码说明：

错误码	HTTP 状态	说明
TEMPLATE_NOT_FOUND	404	模板不存在
VALIDATION_ERROR	400	数据验证失败
PRINTER_OFFLINE	503	打印机离线
TEMPLATE_RENDER_ERROR	500	模板渲染失败
PRINT_FAILED	500	打印失败

---

2. 模板管理

列出所有模板

GET /templates

响应：

{
  "success": true,
  "templates": [
    {
      "id": "daily-todo",
      "name": "每日待办",
      "description": "打印今日待办事项列表",
      "updatedAt": "2025-02-12T07:00:00Z"
    }
  ]
}

获取单个模板

GET /templates/:id

响应：

{
  "success": true,
  "template": {
    "id": "daily-todo",
    "name": "每日待办",
    "config": { /* 完整模板配置 */ }
  }
}

创建模板

POST /templates

请求体：

{
  "id": "food-order",
  "name": "餐饮订单",
  "description": "打印餐饮订单小票",
  "config": {
    "name": "餐饮订单",
    "width": "80mm",
    "blocks": [ /* 块定义 */ ]
  }
}

响应：

{
  "success": true,
  "template": {
    "id": "food-order",
    "name": "餐饮订单",
    "createdAt": "2025-02-12T07:00:00Z"
  }
}

更新模板

PUT /templates/:id

请求体：（同创建，可部分更新）

{
  "name": "新的名称",
  "config": { /* 新配置 */ }
}

删除模板

DELETE /templates/:id

响应：

{
  "success": true,
  "message": "模板已删除"
}

---

3. 模板 Schema

获取模板数据 Schema

GET /templates/:id/schema

用于获取模板所需的数据结构和示例。

响应：

{
  "success": true,
  "templateId": "food-order",
  "schema": {
    "type": "object",
    "required": ["orderId", "items"],
    "properties": {
      "orderType": {
        "type": "string",
        "description": "订单类型"
      },
      "orderId": {
        "type": "string",
        "description": "订单编号"
      },
      "items": {
        "type": "array",
        "description": "商品列表",
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "quantity": { "type": "number" },
            "price": { "type": "number" }
          }
        }
      }
    }
  },
  "example": {
    "orderType": "外带",
    "orderId": "35205-1",
    "items": [
      { "name": "双层吉士堡", "quantity": 1, "price": 22 }
    ]
  }
}

---

4. 打印任务

查询任务状态

GET /jobs/:jobId

响应：

{
  "success": true,
  "job": {
    "id": "job_abc123",
    "templateId": "daily-todo",
    "status": "completed",
    "createdAt": "2025-02-12T07:00:00Z",
    "startedAt": "2025-02-12T07:00:01Z",
    "completedAt": "2025-02-12T07:00:05Z"
  }
}

状态值：

• queued - 排队中
• printing - 打印中
• completed - 完成
• failed - 失败
• cancelled - 已取消

列出最近任务

GET /jobs?limit=10&status=completed

查询参数：

参数	类型	说明
limit	number	返回数量，默认 10
status	string	按状态筛选
templateId	string	按模板筛选

取消任务

DELETE /jobs/:jobId

仅可取消 queued 状态的任务。

---

5. 打印机管理

获取打印机状态

GET /printer/status

响应：

{
  "success": true,
  "printer": {
    "name": "XP-80C",
    "ip": "192.168.1.100",
    "port": 9100,
    "status": "online",
    "paperStatus": "ok",
    "coverStatus": "closed",
    "queueLength": 0
  }
}

状态值：

• online - 在线
• offline - 离线
• error - 错误（查看 errorCode）

打印测试页

POST /printer/test

打印一张测试页，用于检查连接和打印质量。

响应：

{
  "success": true,
  "jobId": "job_test_123"
}

更新打印机配置

POST /printer/config

请求体：

{
  "ip": "192.168.1.100",
  "port": 9100,
  "width": 80
}

---

认证（可选）

如需简单保护，在配置文件中启用 API Key：

security:
  enabled: true
  apiKey: "your-secret-key"

启用后，所有请求需携带 Header：

X-API-Key: your-secret-key

未提供或错误的 Key 返回：

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "无效的 API Key"
  }
}

---

WebSocket 实时状态（可选）

如需实时推送打印状态，可连接 WebSocket：

ws://localhost:3000/ws

事件类型：

// 任务状态更新
{
  "type": "jobUpdate",
  "data": {
    "jobId": "job_abc123",
    "status": "printing"
  }
}

// 打印机状态更新
{
  "type": "printerUpdate",
  "data": {
    "status": "online",
    "paperStatus": "low"
  }
}