# 入站 Webhook（`xlyInterface`）

`xlyInterface` 是三个 Spring Boot WAR 中最小的一个。它的职责是**接收第三方系统推送进来的 HTTP 请求**，例如微信、伙伴工厂、供应商门户，并把它们路由到 xly 处理器。入口类为 `xlyInterface/src/main/java/com/xly/InterfaceApplicationBoot.java`，context-path 为 `/xlyInterface`。

这是三个服务里唯一内置 **Swagger UI** 的服务，因为面向伙伴的受众最适合使用可交互的试调文档。构建依赖 `io.springfox:springfox-swagger-ui:2.9.2` 和 `io.springfox:springfox-swagger2:2.9.2`。服务运行后，UI 使用 SpringFox 默认地址：

```text
http://<host>/xlyInterface/swagger-ui.html
```

等价的 JSON 描述位于 `http://<host>/xlyInterface/v2/api-docs`。

> **注意：** 项目拉取了 SpringFox jar，但没有注册 `Docket` bean（`xly-src` 中没有 `@EnableSwagger2`，也没有 `@Bean Docket api()`）。`swagger-ui.html` shell 会从 jar 的静态资源中被服务出来，但 `/v2/api-docs` 返回的描述基本为空。这里的 UI 是“依赖自带页面”，不是“已填充的 try-it-out 控制台”。如果维护人员希望列出真实 API，需要补一个 `Docket` bean。

## 数据驱动接收器：`/interfaceDefine/*`

它和[外部 API 的 `/api/invoke`](external.md) 模式对应，但用于入站调用：

| 端点 | 方法 | 用途 |
|---|---|---|
| `/interfaceDefine/invoke/{interfaceInvoke}` | POST | 将入站载荷分发给 `{interfaceInvoke}` 命名的处理器。 |
| `/interfaceDefine/callthirdparty/{interfaceInvoke}` | POST | 转发到已配置的出站端点。同一个 URL 在 `xlyApi` 的 `InterfaceController` 上也存在；这种重复是有意的，两个服务共享数据驱动分发器模式。 |

处理器：`xlyInterface/src/main/java/com/xly/web/InterfaceController.java`。

`{interfaceInvoke}` 路径变量会查找一条元数据行，该行声明要运行的 SQL 或存储过程、参数映射和响应形状。它和 xly 其他部分一样遵循数据驱动思路：新增入站端点靠插入数据行，而不是写 Java。

## 硬编码的供应商接收器

少量接收器不会经过 `/interfaceDefine`，因为它们必须匹配合作方固定的 URL 规格。

| 端点 | 方法 | 用途 |
|---|---|---|
| `/Push` | POST | 供应商（微信 / 类似系统）推送接收器。 |
| `/Pull` | POST | 供应商拉取模式接收器。 |
| `/getKey/{key}` | GET | 按伙伴命名的 `key` 获取公钥。 |
| `/getKeyTest` | GET | `/getKey` 的测试模式变体。 |
| `/send/sendQw` | POST | 企业微信出站消息。**当前分支是空实现**：`SendQwController` 中方法体只是 `return "ok";`；已搭好 token 获取脚手架，但未完成。 |

处理器：`xlyInterface/src/main/java/com/xly/web/WX_VendorWeb.java` 和 `xlyInterface/src/main/java/com/xly/wechat/test/SendQwController.java`。

## 认证

Webhook 认证方式按伙伴而异。这里没有统一的 token 签发端点（不同于 `xlyApi`）。每个处理器选择自己的方案：签名 header、查询参数 secret，或基于 `sysapibrand` 的预共享 key 校验。接入前需要阅读对应控制器。

## 元数据放在哪里

`/interfaceDefine/*` 分发器会查询命名入站处理器的元数据行。可检查 `sysapi` 表族（`sysapi`、`sysapibrand`、`sysapithirdparty`）以及当前 schema 自动目录中的任何 `interface*` 表。账本信息和[外部 API](external.md) 有重叠：两个服务共享 API 定义数据，只是暴露在不同 URL 上。

## 这个服务不是什么

- **不是用 xly 的 session cookie 认证。** 第三方调用方没有用户 session。认证是每个处理器自己的事情，不是框架级统一机制。
- **不是出站调用通道。** 出站分发（xly 调用伙伴）走 `xlyApi` 的 `/interfaceDefine/callthirdparty/*` 或 `/thirdparty/*` 控制器。这里有重复是有意为之：入站和出站有完全不同的安全姿态。