# 设备 API 适配器开发说明

API 拉取代码放在 `syslog-serve`，不单独建 Maven 模块。

如果只是接入当前 NDRServer，不需要重新写整套拉取程序。先核对现有适配器是否缺少字段或接口参数，有差异时只修改 NDR 适配器。

## NDRServer

现有代码：

```text
syslog-serve/src/main/java/com/haobang/apipull/adapter/ndr/NdrServerApiAdapter.java
```

测试代码：

```text
syslog-serve/src/test/java/com/haobang/apipull/adapter/ndr/NdrServerApiAdapterTest.java
syslog-serve/src/test/java/com/haobang/apipull/adapter/ndr/NdrServerSpringWiringTest.java
```

现有 NDR 拉取实现如需补充特殊参数或字段处理，直接修改上述适配器和测试。定时任务、线程池、checkpoint 和 Kafka Producer 使用项目公共实现。

## 新厂商

新建厂商目录：

```text
syslog-serve/src/main/java/com/haobang/apipull/adapter/<vendor>/
```

实现 `ApiPullAdapter` 并加上 `@Component`。Spring 启动后会自动注册。

接口方法的作用：

| 方法 | 要返回什么 |
| --- | --- |
| `type()` | 厂商和协议版本的固定名称，例如 `VENDOR_X_V1` |
| `version()` | 当前代码的协议版本号 |
| `streams()` | 支持的日志类型，例如告警、流量日志 |
| `minimumWindowSeconds()` | 设备允许查询的最小时间范围 |
| `validateConfig()` | 检查地址、分页大小和超时时间 |
| `pull()` | 查询指定时间范围中的一页数据 |

适配器负责以下内容：

- 认证和 Token；
- 请求地址、参数和时间格式；
- 单页数据查询；
- 响应解析和厂商错误码；
- 事件时间、设备侧 ID 和平台事件 ID；
- 原始 JSON 及必要的兼容字段。

调度、并发、窗口拆分、checkpoint、WAL 和 Kafka 由公共代码处理。适配器不要直接写 Kafka，也不要自行推进 checkpoint。

如果新厂商不是 AppKey/AppSecret 认证，还需要一起调整凭据 DTO、`ApiCredentialService`、`DatabaseCredentialProvider` 和数据库脚本。

开发完成后至少检查：

1. 认证成功、认证失败和 Token 过期；
2. 接口返回空数据时任务能够正常推进；
3. 多页数据没有漏页；
4. 事件时间来自设备日志，不使用接口响应时间；
5. 同一条设备日志重复拉取时 `eventId` 保持不变；
6. 接口异常时 checkpoint 不推进；
7. 单元测试和 Spring 启动测试通过。