ElectronClient/tax-guidance/pad-gateway-api-params(2).md

# PAD 接口文档

## 1. 基础信息

- 服务默认端口：`8845`
- 默认基础地址：`http://<host>:8845`
- 直连接口统一前缀：`/api/queue/**`
- 本文范围：
  - `pad.*` 标签对应的直连接口
  - 虽然路径不在 `/api/queue/pad/**` 下，但 Swagger 标签仍属于 `pad.*` 的配套接口
  - `/public` 统一网关映射

## 2. 统一返回结构

### 2.1 直连接口返回结构

绝大多数直连接口返回统一结构 `R<T>`：

```json
{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}
```

字段说明：

| 字段 | 类型 | 说明 |
|---|---|---|
| `code` | `int` | 状态码，成功通常为 `200` |
| `msg` | `string` | 返回消息 |
| `data` | `object/array/null` | 具体业务数据 |

### 2.2 `/public` 网关返回结构

`/public` 返回 `PublicGatewayResponseVo<T>`，比 `R<T>` 多一个 `traceId`：

```json
{
  "code": 200,
  "msg": "OK",
  "traceId": "202604210001",
  "data": {}
}
```

## 3. 接口清单

> 说明：
> - `Header.Authorization` 表示请求头 `Authorization: Bearer <token>`
> - `path.xxx` 表示路径参数
> - `query.xxx` 表示查询参数
> - `body.xxx` 表示 JSON 请求体字段
> - `未接入` 表示当前不能通过 `/public` 的 `tag + map.path` 转发

### 3.1 `pad.auth`

| 方法 | 请求地址 | 网关调用(tag/path) | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|---|
| `POST` | `/api/queue/pad/auth/login` | `pad.auth` + `/login` | `body.username`、`body.password`；`body.tenantId` 可选 | `R<LoginResponse>` | 登录 |
| `POST` | `/api/queue/pad/auth/refresh` | 未接入 | `body.refreshToken` | `R<LoginResponse>` | 刷新令牌 |
| `POST` | `/api/queue/pad/auth/logout` | 未接入 | `Header.Authorization` | `R<AuthLogoutVo>` | 用户退出 |
| `GET` | `/api/queue/pad/auth/profile` | 未接入 | `Header.Authorization` | `R<AuthProfileVo>` | 当前用户信息 |
| `POST` | `/api/queue/pad/auth/sign` | `pad.auth` + `/sign` | `body.tag`、`body.path`、`body.timestamp`、`body.nonce`；`body.query`、`body.body` 可选 | `R<SignResponseVo>` | 生成签名 |
| `GET` | `/api/queue/pad/auth/validate` | 未接入 | `Header.Authorization` | `R<TokenValidationVo>` | 校验令牌 |

### 3.2 `pad.business`

| 方法 | 请求地址 | 网关调用(tag/path) | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|---|
| `GET` | `/api/queue/pad/business` | 未接入 | 无 | `R<List<Business>>` | 查询所有业务类型 |
| `POST` | `/api/queue/pad/business` | 未接入 | `body.name`；`body.prefix` 可选但必须唯一；`body.enabled`、`body.type`、`body.handleCount`、`body.isSpecial` 可选 | `R<Business>` | 创建业务类型 |
| `GET` | `/api/queue/pad/business/{uid}` | 未接入 | `path.uid` | `R<Business>` | 按 UID 查询 |
| `PUT` | `/api/queue/pad/business/{uid}` | 未接入 | `path.uid`、`body.name`；其他字段同创建 | `R<Business>` | 更新业务类型 |
| `DELETE` | `/api/queue/pad/business/{uid}` | 未接入 | `path.uid` | `R<BusinessOperationVo>` | 删除业务类型 |
| `PATCH` | `/api/queue/pad/business/{uid}/enabled` | 未接入 | `path.uid`、`query.enabled` | `R<BusinessOperationVo>` | 更新启用状态 |
| `GET` | `/api/queue/pad/business/enabled` | `pad.business` + `/enabled` | 无 | `R<List<Business>>` | 查询启用业务类型 |
| `POST` | `/api/queue/pad/business/health-reopt/url` | 未接入 | `body.id`；`body.swjgMc`、`body.swjgDm` 可选 | `R<HealthReportUrlVo>` | 生成健康报告查询 URL |
| `GET` | `/api/queue/pad/business/page` | 未接入 | `query.page` 默认 `1`、`query.size` 默认 `10` | `R<BusinessPageVo>` | 分页查询 |
| `GET` | `/api/queue/pad/business/search` | 未接入 | `query.name` | `R<List<Business>>` | 名称模糊查询 |
| `GET` | `/api/queue/pad/business/special` | 未接入 | 无 | `R<List<Business>>` | 查询特殊业务 |
| `GET` | `/api/queue/pad/business/statistics` | 未接入 | 无 | `R<BusinessStatisticsVo>` | 业务统计 |
| `GET` | `/api/queue/pad/business/type/{type}` | 未接入 | `path.type` | `R<List<Business>>` | 按类型查询 |
| `GET` | `/api/queue/pad/business/validate/name` | 未接入 | `query.name`；`query.excludeUid` 可选 | `R<BusinessValidationVo>` | 校验名称唯一性 |
| `GET` | `/api/queue/pad/business/validate/prefix` | 未接入 | `query.prefix`；`query.excludeUid` 可选 | `R<BusinessValidationVo>` | 校验前缀唯一性 |

### 3.3 `pad.menu`

| 方法 | 请求地址 | 网关调用(tag/path) | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|---|
| `GET` | `/api/queue/pad/menu/business-types` | 未接入 | 无 | `R<BusinessMenuVo>` | 获取业务类型菜单 |
| `GET` | `/api/queue/pad/menu/main` | `pad.menu` + `/main` | 无 | `R<MenuPageVo>` | 获取主菜单 |

### 3.4 `pad.print`

| 方法 | 请求地址 | 网关调用(tag/path) | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|---|
| `GET` | `/api/queue/pad/print/printers` | `pad.print` + `/printers` | 无 | `R<List<String>>` | 获取打印机列表 |
| `POST` | `/api/queue/pad/print/text` | `pad.print` + `/text` | `body.content`；`body.printerName` 可选 | `R<Boolean>` | 打印文本 |

### 3.5 `pad.test`

| 方法 | 请求地址 | 网关调用(tag/path) | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|---|
| `POST` | `/api/queue/pad/test/medical-report/url` | 未接入 | `body.id`、`body.swjgMc`、`body.swjgDm` | `R<MedicalReportUrlVo>` | 测试用医保报告 URL |

### 3.6 `pad.ticket`

| 方法 | 请求地址 | 网关调用(tag/path) | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|---|
| `GET` | `/api/queue/pad/business/list` | 未接入 | 无 | `R<List<Business>>` | 虽然路径不在 `/ticket` 下，但 Swagger Tag 属于 `pad.ticket` |
| `GET` | `/api/queue/pad/ticket/{uid}` | 未接入 | `path.uid` | `R<Ticket>` | 按 UID 查询票号 |
| `PATCH` | `/api/queue/pad/ticket/{uid}/assign-window` | 未接入 | `path.uid`、`query.winId` | `R<TicketAssignWindowVo>` | 指派窗口 |
| `GET` | `/api/queue/pad/ticket/{uid}/status` | 未接入 | `path.uid` | `R<TicketStatusVo>` | 按 UID 查询状态 |
| `PATCH` | `/api/queue/pad/ticket/{uid}/status` | 未接入 | `path.uid`、`query.status` | `R<TicketStatusUpdateVo>` | 更新票号状态 |
| `GET` | `/api/queue/pad/ticket/business/{bizUid}` | 未接入 | `path.bizUid` | `R<List<Ticket>>` | 按业务类型查询票号 |
| `POST` | `/api/queue/pad/ticket/call/{ticketNumber}` | 未接入 | `path.ticketNumber`、`query.windowNumber` | `R<TicketCallVo>` | 指定票号叫号 |
| `POST` | `/api/queue/pad/ticket/call/next` | 未接入 | `body.windowUid`；`body.empUid` 可选 | `R<TicketCallResultVo>` | 叫下一号 |
| `POST` | `/api/queue/pad/ticket/call/specific/{ticketUid}` | 未接入 | `path.ticketUid`、`query.windowUid`；`query.empUid` 可选 | `R<TicketCallResultVo>` | 叫指定票 |
| `POST` | `/api/queue/pad/ticket/create-jump` | 未接入 | `body.bizUid`；`body.rankUserName`、`body.rankUserPhone`、`body.idCard`、`body.tktId` 可选 | `R<TakeTicketResponse>` | 创建插队票 |
| `GET` | `/api/queue/pad/ticket/list` | `pad.ticket` + `/list` | `query.page` 默认 `1`、`query.size` 默认 `10`；`query.status`、`query.businessType`、`query.tabType` 可选 | `R<TicketPageVo>` | 票号列表 |
| `GET` | `/api/queue/pad/ticket/list-by-status/{status}` | 未接入 | `path.status` | `R<List<Ticket>>` | 按状态码查询 |
| `POST` | `/api/queue/pad/ticket/resume` | 未接入 | `body.resumeToken`；`body.targetPosition` 可选，默认 `3` | `R<TicketResumeResultVo>` | 复号 |
| `POST` | `/api/queue/pad/ticket/verify/search` | 未接入 | `body.name`、`body.idCard`、`body.phone` 至少传一个；三者均按包含匹配；`body.page` 默认 `1`、`body.size` 默认 `10` | `R<TicketVerifyQueryPageVo>` | 模糊查询 `ticket_verify` 并判断是否已完成实名/人脸比对 |
| `POST` | `/api/queue/pad/ticket/skip/{ticketNumber}` | 未接入 | `path.ticketNumber` | `R<TicketSkipVo>` | 跳过票号 |
| `GET` | `/api/queue/pad/ticket/status/{ticketNumber}` | 未接入 | `path.ticketNumber` | `R<TicketStatusDetailVo>` | 按票号字符串查询状态 |
| `POST` | `/api/queue/pad/ticket/suspend` | 未接入 | `body.ticketUid`；`body.windowUid`、`body.empUid`、`body.idCard`、`body.phone` 可选 | `R<TicketSuspendResultVo>` | 挂起票号 |
| `GET` | `/api/queue/pad/ticket/suspend/info/{token}` | 未接入 | `path.token` | `R<SuspendedTicketDetailVo>` | 查询挂起详情 |
| `POST` | `/api/queue/pad/ticket/take` | `pad.queue` + `/ticket/take` | `body.bizUid`，且 `body.idCard` / `body.rankUserPhone` 至少传一个；`body.rankUserName`、`body.enterpriseId`、`body.appointmentUid`、`body.tktId` 可选 | `R<TakeTicketVo>` | 取号 |
| `POST` | `/api/queue/pad/ticket/take-by-appointment` | 未接入 | `body.bizUid`、`body.appointmentUid` | `R<TakeTicketVo>` | 预约换号 |
| `GET` | `/api/queue/pad/ticket/today_unified_tickets` | 未接入 | `query.page` 默认 `1`、`query.size` 默认 `10` | `R<TicketPageVo>` | 今日统一票号列表 |
| `GET` | `/api/queue/pad/ticket/waiting-count` | 未接入 | `query.bizUid` 可选 | `R<WaitingCountVo>` | 查询等待人数 |

### 3.7 `pad.appointment`

| 方法 | 请求地址 | 网关调用(tag/path) | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|---|
| `GET` | `/api/queue/pad/appointment/time-slots` | `pad.appointment` + `/time-slots` | 无 | `R<List<AppointmentTimeSlotVo>>` | 可用时间段 |
| `GET` | `/api/queue/pad/appointment/today` | 未接入 | `query.page` 默认 `1`、`query.size` 默认 `10`；`query.status`、`query.businessType`、`query.keyword` 可选 | `R<AppointmentPageVo>` | 今日预约列表 |
| `DELETE` | `/api/queue/pad/appointment/{appointmentId}` | 未接入 | `path.appointmentId` | `R<AppointmentActionVo>` | 取消预约 |
| `PUT` | `/api/queue/pad/appointment/{appointmentId}/status` | 未接入 | `path.appointmentId`、`query.status` | `R<AppointmentActionVo>` | 更新预约状态 |
| `GET` | `/api/queue/pad/appointment/statistics` | 未接入 | `query.date` 可选 | `R<AppointmentStatisticsVo>` | 预约统计 |

### 3.8 `pad.window`

| 方法 | 请求地址 | 网关调用(tag/path) | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|---|
| `GET` | `/api/queue/pad/window/list` | `pad.window` + `/list` | `query.page` 默认 `1`、`query.size` 默认 `10`；`query.enabled`、`query.name` 可选 | `R<WindowPageVo>` | 窗口列表 |
| `GET` | `/api/queue/pad/window/monitor/list` | `pad.window` + `/monitor/list` | 无 | `R<WindowMonitorListVo>` | 窗口监控列表 |
| `POST` | `/api/queue/pad/window/create` | 未接入 | `body.name`；`body.sid` 可选但必须唯一；`body.enabled`、`body.ledAddress`、`body.ledText`、`body.rankMode`、`body.rankAddress` 可选 | `R<WindowActionVo>` | 创建窗口 |
| `PUT` | `/api/queue/pad/window/{windowId}` | 未接入 | `path.windowId`、`body.name`；其他字段同创建 | `R<WindowActionVo>` | 更新窗口 |
| `PUT` | `/api/queue/pad/window/{windowId}/status` | 未接入 | `path.windowId`、`query.enabled` | `R<WindowActionVo>` | 切换窗口状态 |
| `GET` | `/api/queue/pad/window/{windowId}` | 未接入 | `path.windowId` | `R<WindowDetailVo>` | 窗口详情 |
| `GET` | `/api/queue/pad/window/{windowId}/business` | 未接入 | `path.windowId` | `R<WindowBusinessListVo>` | 获取窗口业务关联 |
| `POST` | `/api/queue/pad/window/{windowId}/business` | 未接入 | `path.windowId`；`body` 为数组，元素至少要有 `businessId`，`priority`、`enabled` 可选 | `R<WindowActionVo>` | 设置窗口业务关联 |
| `POST` | `/api/queue/pad/window/{windowId}/led` | 未接入 | `path.windowId`、`query.text` | `R<WindowActionVo>` | LED 显示控制 |
| `DELETE` | `/api/queue/pad/window/{windowId}` | 未接入 | `path.windowId` | `R<WindowActionVo>` | 删除窗口 |

### 3.9 `tag.hallSystem`

> Swagger 中标签名是 `tag.hallSystem`，但 `/public` 网关调用时实际 tag 要传 `pad.hallSystem`。

| 方法 | 请求地址 | 网关调用(tag/path) | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|---|
| `GET` | `/api/queue/pad/hallSystem/list` | `pad.hallSystem` + `/list` | `query.prefix` 可选 | `R<HallSystemListVo>` | 获取大厅配置列表 |
| `POST` | `/api/queue/pad/hallSystem/value` | `pad.hallSystem` + `/value` | `body.key`；`body.value` 可选 | `R<Boolean>` | 更新大厅配置 |
| `GET` | `/api/queue/pad/hallSystem/overview/metrics` | `pad.hallSystem` + `/overview/metrics`；`pad.queue` + `/overview/metrics` | 无 | `R<PadOverviewMetricsVo>` | 实时概览指标 |
| `GET` | `/api/queue/pad/hallSystem/overview/metrics/trend` | `pad.hallSystem` + `/overview/metrics/trend`；`pad.queue` + `/overview/metrics/trend` | `query.startTime`、`query.endTime` 可选，格式 `yyyy-MM-dd HH:mm:ss` | `R<PadOverviewMetricsTrendVo>` | 概览趋势 |

### 3.10 `pad.window` 配套 caller 窗口接口

| 方法 | 请求地址 | 网关调用(tag/path) | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|---|
| `GET` | `/api/queue/caller/windows/list` | 未接入 | `Header.Authorization` | `R<CallerWindowBindingResponse>` | 当前账号可绑定窗口列表 |
| `POST` | `/api/queue/caller/windows/select` | 未接入 | `Header.Authorization`、`body.windowUid` | `R<CallerWindowBindingResponse>` | 绑定窗口 |

### 3.11 `pad.callTerminal`

| 方法 | 请求地址 | 网关调用(tag/path) | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|---|
| `POST` | `/api/queue/caller/call-terminal/init` | 未接入 | `body.windowUid`；`body.empUid` 可选 | `R<CallTerminalActionResponse>` | 初始化评价器 |
| `POST` | `/api/queue/caller/call-terminal/call` | `pad.callTerminal` + `/call` | `body.windowUid`；`body.ticketUid`、`body.empUid` 可选 | `R<CallTerminalActionResponse>` | 叫号 |
| `POST` | `/api/queue/caller/call-terminal/recall` | 未接入 | `body.ticketUid`；`body.windowUid` 可选 | `R<CallTerminalActionResponse>` | 重呼 |
| `POST` | `/api/queue/caller/call-terminal/start` | 未接入 | `body.ticketUid`；`body.windowUid`、`body.empUid` 可选 | `R<CallTerminalActionResponse>` | 开始办理 |
| `POST` | `/api/queue/caller/call-terminal/complete` | 未接入 | `body.ticketUid` | `R<CallTerminalActionResponse>` | 办结 |
| `POST` | `/api/queue/caller/call-terminal/abandon` | 未接入 | `body.ticketUid` | `R<CallTerminalActionResponse>` | 弃号 |
| `POST` | `/api/queue/caller/call-terminal/transfer` | 未接入 | `body.ticketUid`、`body.targetWindowUid` | `R<CallTerminalActionResponse>` | 转移 |
| `POST` | `/api/queue/caller/call-terminal/pause` | 未接入 | `body.windowUid`、`body.empUid`、`body.pauseReason` | `R<CallTerminalActionResponse>` | 暂停窗口 |
| `POST` | `/api/queue/caller/call-terminal/resume` | 未接入 | `body.windowUid`、`body.empUid` | `R<CallTerminalActionResponse>` | 恢复窗口 |
| `POST` | `/api/queue/caller/call-terminal/evaluate` | 未接入 | `body.ticketUid`；如果提交评分，`body.rank` 必须在 `0-6` | `R<CallTerminalActionResponse>` | 发起评价或回写评价 |
| `GET` | `/api/queue/caller/call-terminal/is-rank` | 未接入 | `query.ticketUid` | `R<Map<String,Object>>` | 是否已评价 |
| `GET` | `/api/queue/caller/call-terminal/queue-count` | 未接入 | `query.windowUid` | `R<Map<String,Object>>` | 当前窗口排队人数 |
| `GET` | `/api/queue/caller/call-terminal/pool` | 未接入 | `query.winUid`；`query.keyword`、`query.keywords`、`query.status`、`query.page`、`query.size`、`query.pageSize`、`query.pagesize` 可选 | `R<CallTerminalTicketPoolResponse>` | 可叫号票池 |

`pad.callTerminal` 常见可选字段：

- `customText`
- `serviceUrl`
- `forward`
- `read`
- `driver`
- `clients`
- `rankUserName`
- `rankUserPhone`
- `idCard`
- `phone`

#### `pad.ticket` - 实名核验查询示例

请求示例：

```json
{
  "name": "张",
  "idCard": "3301",
  "phone": "138",
  "page": 1,
  "size": 10
}
```

模糊查询规则：

- `name`：`LIKE %name%`
- `idCard`：`LIKE %idCard%`
- `phone`：`LIKE %phone%`
- 多个条件同时传入时按 `AND` 组合
- `takeTicketVerified` 复用当前取号实名校验逻辑，仅在传入 `idCard` 或 `phone` 时返回
- `faceComparePassed` 基于当前最新精确匹配记录的 `compareValue == 1` 判断

返回示例：

```json
{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "page": 1,
    "size": 10,
    "total": 1,
    "matched": true,
    "takeTicketVerified": true,
    "faceComparePassed": true,
    "records": [
      {
        "uid": 1,
        "ticketUid": 101,
        "name": "张三",
        "idCard": "330102199001011234",
        "phone": "13800138000",
        "compareCode": "IDC",
        "compareValue": 1,
        "compareResult": "verified",
        "faceComparePassed": true,
        "verifyTime": "2026-04-22T10:00:00"
      }
    ]
  }
}
```

## 4. `/public` 统一网关

### 4.1 入口

| 方法 | 请求地址 | 请求参数 | 返回值 | 备注 |
|---|---|---|---|---|
| `POST` | `/public` | 请求体为加密后的字符串；解密后结构见下文 | `PublicGatewayResponseVo<T>` | 统一网关入口 |

### 4.2 解密后的请求体结构

```json
{
  "tag": "pad.ticket",
  "map": {
    "traceId": "202604210001",
    "head": {
      "method": "GET",
      "contentType": "application/json",
      "timestamp": 1710000000000,
      "nonce": "n-1",
      "signature": "hex-signature"
    },
    "path": "/list",
    "query": {},
    "body": {}
  }
}
```

字段说明：

| 字段 | 说明 |
|---|---|
| `tag` | 路由标签，例如 `pad.auth`、`pad.ticket` |
| `map.traceId` | 链路跟踪号 |
| `map.head.method` | 请求方法；建议显式传 |
| `map.head.timestamp` | 签名时间戳 |
| `map.head.nonce` | 签名随机串 |
| `map.head.signature` | HMAC-SHA256 签名 |
| `map.path` | 子路径，例如 `/login`、`/list` |
| `map.query` | 查询参数对象 |
| `map.body` | 请求体对象 |

### 4.3 当前已接入 `/public` 的接口

| 网关 tag | `map.path` | 实际分发到的直连接口 | 直连接口返回 |
|---|---|---|---|
| `pad.auth` | `/login` | `POST /api/queue/pad/auth/login` | `R<LoginResponse>` |
| `pad.auth` | `/sign` | `POST /api/queue/pad/auth/sign` | `R<SignResponseVo>` |
| `pad.menu` | `/main` | `GET /api/queue/pad/menu/main` | `R<MenuPageVo>` |
| `pad.appointment` | `/time-slots` | `GET /api/queue/pad/appointment/time-slots` | `R<List<AppointmentTimeSlotVo>>` |
| `pad.hallSystem` | `/list` | `GET /api/queue/pad/hallSystem/list` | `R<HallSystemListVo>` |
| `pad.hallSystem` | `/value` | `POST /api/queue/pad/hallSystem/value` | `R<Boolean>` |
| `pad.hallSystem` | `/overview/metrics` | `GET /api/queue/pad/hallSystem/overview/metrics` | `R<PadOverviewMetricsVo>` |
| `pad.hallSystem` | `/overview/metrics/trend` | `GET /api/queue/pad/hallSystem/overview/metrics/trend` | `R<PadOverviewMetricsTrendVo>` |
| `pad.queue` | `/ticket/take` | `POST /api/queue/pad/ticket/take` | `R<TakeTicketVo>` |
| `pad.queue` | `/overview/metrics` | `GET /api/queue/pad/hallSystem/overview/metrics` | `R<PadOverviewMetricsVo>` |
| `pad.queue` | `/overview/metrics/trend` | `GET /api/queue/pad/hallSystem/overview/metrics/trend` | `R<PadOverviewMetricsTrendVo>` |
| `pad.business` | `/enabled` | `GET /api/queue/pad/business/enabled` | `R<List<Business>>` |
| `pad.ticket` | `/list` | `GET /api/queue/pad/ticket/list` | `R<TicketPageVo>` |
| `pad.window` | `/list` | `GET /api/queue/pad/window/list` | `R<WindowPageVo>` |
| `pad.window` | `/monitor/list` | `GET /api/queue/pad/window/monitor/list` | `R<WindowMonitorListVo>` |
| `pad.print` | `/printers` | `GET /api/queue/pad/print/printers` | `R<List<String>>` |
| `pad.print` | `/text` | `POST /api/queue/pad/print/text` | `R<Boolean>` |
| `pad.callTerminal` | `/call` | `POST /api/queue/caller/call-terminal/call` | `R<CallTerminalActionResponse>` |

### 4.4 `/public` 调用规则

- 除 `pad.auth /login` 和 `pad.auth /sign` 外，其余已接入网关的接口都需要 `map.head.timestamp`、`map.head.nonce`、`map.head.signature`
- `POST` 类接口建议显式传 `map.head.method`
- `pad.auth /sign` 在实际使用时还需要 Bearer Token

## 5. 常见返回字段说明

### 5.1 `LoginResponse`

主要字段：

- `access_token`
- `refresh_token`
- `tokenType`
- `expire_in`
- `refresh_expire_in`
- `client_id`
- `scope`
- `openid`
- `userInfo`

`userInfo` 主要字段：

- `id`
- `uid`
- `username`
- `realName`
- `role`
- `tenantId`
- `image`

### 5.2 `Business`

主要字段：

- `uid`
- `prefix`
- `name`
- `enabled`
- `type`
- `handleCount`
- `isSpecial`

### 5.3 `TakeTicketVo` / `TakeTicketResponse`

主要字段：

- `uid`
- `tktId`
- `tktIntid`
- `status`
- `bizUid`
- `bizName`
- `bizPrefix`
- `waitingCount`
- `waitingAhead`
- `estimatedWaitMinutes`
- `tktDate`
- `tktTime`
- `hallName`
- `windowNames`
- `message`

### 5.4 `TicketPageVo`

主要字段：

- `list`
- `total`
- `page`
- `size`

`list` 元素类型为 `UnifiedTicketVo`

### 5.5 `TicketStatusVo`

主要字段：

- `uid`
- `tktId`
- `status`
- `statusText`
- `waitingAhead`
- `estimatedWaitMinutes`

### 5.6 `TicketStatusDetailVo`

主要字段：

- `ticketNumber`
- `uid`
- `businessUid`
- `status`
- `rank`
- `customerName`
- `customerPhone`
- `generateTime`
- `windowId`

### 5.7 `WaitingCountVo`

主要字段：

- `waitingCount`
- `estimatedWaitMinutes`
- `bizUid`

### 5.8 `WindowPageVo`

主要字段：

- `list`
- `total`
- `page`
- `size`
- `enabled`
- `name`

### 5.9 `WindowActionVo`

主要字段：

- `windowId`
- `name`
- `ledAddress`
- `enabled`
- `createTime`
- `displayText`
- `businessCount`

### 5.10 `WindowDetailVo`

主要字段：

- `windowId`
- `name`
- `ledAddress`
- `ledText`
- `enabled`
- `sid`
- `rankMode`
- `rankAddress`
- `currentTicket`
- `todayServed`

### 5.11 `WindowBusinessListVo`

主要字段：

- `windowId`
- `list`

### 5.12 `WindowMonitorListVo`

主要字段：

- `list`
- `idleCount`
- `busyCount`
- `pausedCount`

### 5.13 `HallSystemListVo`

主要字段：

- `list`
- `total`

`list` 元素 `HallSystemItemVo` 主要字段：

- `key`
- `value`
- `memo`

### 5.14 `PadOverviewMetricsVo`

主要字段：

- `waitingCount`
- `todayAppointmentCount`
- `idleWindowCount`
- `idleKioskCount`
- `serverTime`

### 5.15 `PadOverviewMetricsTrendVo`

主要字段：

- `startTime`
- `endTime`
- `list`

### 5.16 `AppointmentPageVo`

主要字段：

- `list`
- `total`
- `page`
- `size`

### 5.17 `AppointmentActionVo`

主要字段：

- `appointmentId`
- `newStatus`

### 5.18 `AppointmentStatisticsVo`

主要字段：

- `totalAppointments`
- `todayAppointments`
- `completedAppointments`
- `cancelledAppointments`
- `timeSlotStats`

### 5.19 `CallerWindowBindingResponse`

主要字段：

- `locked`
- `needSelect`
- `selectedWindowUid`
- `selectedWindowCode`
- `selectedWindowName`
- `nextStep`
- `windows`

### 5.20 `CallTerminalActionResponse`

主要字段：

- `action`
- `success`
- `message`
- `ticketUid`
- `ticketNo`
- `ticketStatus`
- `ticketStatusText`
- `windowUid`
- `windowName`
- `resumeToken`
- `led`
- `taxerName`
- `taxerPhone`
- `waitSeconds`

### 5.21 `CallTerminalTicketPoolResponse`

主要字段：

- `winUid`
- `keyword`
- `status`
- `page`
- `size`
- `total`
- `returnedCount`
- `list`