receipt-printer/docs/api.md

# API 规范

## 基础信息

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

## 端点列表

### 1. 打印

#### 执行打印

```
POST /print/:templateId
```

**请求体：**

```json
{
  "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)：**

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

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

```json
{
  "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
```

**响应：**

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

#### 获取单个模板

```
GET /templates/:id
```

**响应：**

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

#### 创建模板

```
POST /templates
```

**请求体：**

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

**响应：**

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

#### 更新模板

```
PUT /templates/:id
```

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

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

#### 删除模板

```
DELETE /templates/:id
```

**响应：**

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

---

### 3. 模板 Schema

#### 获取模板数据 Schema

```
GET /templates/:id/schema
```

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

**响应：**

```json
{
  "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
```

**响应：**

```json
{
  "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
```

**响应：**

```json
{
  "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
```

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

**响应：**

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

#### 更新打印机配置

```
POST /printer/config
```

**请求体：**

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

---

## 认证（可选）

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

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

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

```
X-API-Key: your-secret-key
```

未提供或错误的 Key 返回：

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

---

## WebSocket 实时状态（可选）

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

```
ws://localhost:3000/ws
```

**事件类型：**

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

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