|
|
# 接口列表与 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 | 服务器内部错误 |
|
