feat: 新增设备 API 拉取采集及配套处理能力

- 接入 NDRServer 告警和流量日志，支持凭据与任务管理
- 支持分页拉取、窗口拆分、调度优先级及 WAL 持久化后推进断点
- 增加迟到告警规则重放，优化多条泛化规则选择和事件时间处理
- 补充回归测试、数据库升级脚本及部署文档

haobang-security-dm/upgrade-doc/v2/development/设备API适配器开发说明.md

@@ -0,0 +1,66 @@
+# 设备 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 启动测试通过。