# 接口列表与 CURL 验证（紫云HES对接）

## 1. 基础信息
- 服务基址（直连）：`http://<HES-host>:8845`
- 当前项目路径前缀：`/api/queue/**`
- 统一返回结构：`{"code":200|500|401,...,"msg":"...","data":...}`
- 全链路追踪：请求传入 `traceId`，响应原样回传；`traceId` 放置层级（顶层或 `map`）待定稿。

## 2. 公网统一入口规范
本项目部署形态：`HES(pad-api)` 仅在内网

### 2.1 调用模式说明
- 外部调用方仅访问公网：`POST /xxx/public`
- 公网网关根据 `tag` 映射到内网 `HES(pad-api)` 具体接口
- `map` 使用结构化键承载参数：`head`（请求元信息）、`path`、`query`、`body`。

### 2.2 公共请求报文（建议定稿）
```json
{
  "tag": "pad.auth",
  "map": {
    "traceId": "",
    "head": {},
    "path": "",
    "query": {},
    "body": {}
  }
}
```

> 说明：
> - `tag` 作为路由标识，网关按 `tag` 映射到固定内网接口（`method + path`）。
> - `map.head` 放请求元信息，`map.path` 使用字符串承载子路径（如 `/login`、`/main`），`map.query/body` 分别承载查询参数、请求体参数；GET 接口建议 `body` 为空，POST/PUT/PATCH 业务参数放 `body`。
> - `traceId` 用于全链路追踪，建议响应报文原样回传；`traceId` 放置层级（顶层或 `map`）待定稿。

| 字段 | 位置 | 必填 | 说明 |
|---|---|---|---|
| tag | 顶层 | 是 | 路由标签，如 `pad.auth` |
| traceId | 顶层或map（待定） | 是 | 链路追踪号，响应需原样返回 |
| head | map | 否 | 请求元信息（如 `method`、`contentType`、`authorization`） |
| path | map | 否 | 子路径字符串（如 `/login`） |
| query | map | 否 | 查询参数对象 |
| body | map | 否 | 请求体对象 |

### 2.3 公共响应报文（建议定稿）
```json
{
  "code": 200,
  "msg": "OK",
  "traceId": "",
  "data": {}
}
```

### 2.4 关键约束
- 走公网统一入口时：统一包 `tag/map`
- `tag` 为对外契约，不随内部路径调整而频繁变更
- `traceId` 放置层级（顶层或 `map`）待与第三方确认后定稿

## 3. PAD 统一入口路由约定
> 对外统一入口：`POST /xxx/public`  
> 路由规则：后端按 `tag + map.path` 进行函数转发；`map.head.method` 用于参数校验与审计。

| Tag | map.path（示例） | 说明 |
|---|---|---|
| `pad.auth` | `/login` | 认证相关 |
| `pad.menu` | `/main` | 菜单相关 |
| `pad.appointment` | `/time-slots` | 预约相关 |
| `pad.hallSystem` | `/list` | 大厅配置 |
| `pad.business` | `/enabled` | 业务类型 |
| `pad.ticket` | `/list` | 票号相关 |
| `pad.window` | `/list` | 窗口相关 |
| `pad.print` | `/printers` | 打印相关 |
| `pad.callTerminal` | `/call` | 呼号终端动作 |

> 说明：模块内新增接口时，保持 `tag` 不变，仅新增对应 `map.path` 映射即可。


## 4. CURL 验证模板（公网统一入口）
> 对外联调统一使用公网入口：`POST http://<gateway-host>/xxx/public`

### 4.1 登录样例（pad.auth -> /api/queue/pad/auth/login）
```bash
curl -X POST "http://<gateway-host>/xxx/public" \
  -H "Content-Type: application/json" \
  -d "{
    \"tag\":\"pad.auth\",
    \"map\":{
      \"traceId\":\"202603061430001234\",
      \"head\":{\"method\":\"POST\",\"contentType\":\"application/json\"},
      \"path\":\"/login\",
      \"query\":{},
      \"body\":{\"loginMode\":\"QUEUE\",\"clientType\":\"PAD\",\"username\":\"demo\",\"password\":\"123456\"}
    }
  }"
```

### 4.2 菜单样例（pad.menu -> /api/queue/pad/menu/main）
```bash
curl -X POST "http://<gateway-host>/xxx/public" \
  -H "Content-Type: application/json" \
  -d "{
    \"tag\":\"pad.menu\",
    \"map\":{
      \"traceId\":\"202603061430001235\",
      \"head\":{\"method\":\"GET\",\"contentType\":\"application/json\"},
      \"path\":\"/main\",
      \"query\":{},
      \"body\":{}
    }
  }"
```
## 5 错误码（pad-api HES）
| code | 名称 | 说明 |
|---|---|---|
| 200 | SUCCESS | 操作成功 |
| 400 | BAD_REQUEST | 请求参数错误 |
| 401 | UNAUTHORIZED | 未授权访问 |
| 403 | FORBIDDEN | 权限不足 |
| 404 | NOT_FOUND | 资源不存在 |
| 500 | INTERNAL_ERROR | 服务器内部错误 |