ElectronClient/tax-guidance/ZIYUN_PAD(HES)接口清单与CURL验证.md

接口列表与 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 公共请求报文（建议定稿）

{
  "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 公共响应报文（建议定稿）

{
  "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）

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）

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	服务器内部错误