# 数模式正式检测完成后通知第三方 checksquare 接口设计

## 背景

当前系统在数模式正式检测完成后，已经具备：

- 正式检测上下文管理能力
- 检测结果、监测点状态、装置状态入库能力
- 装置检测开始时间与结束时间落库能力

现在需要在数模式正式检测成功完成后，调用第三方接口 `POST /steady/checksquare/create`，通知第三方系统开始后续处理。

第三方接口当前为免 token 模式，请求头仅需：

- `Content-Type: application/json`

## 目标

- 仅在数模式正式检测成功完成后触发第三方通知
- 仅在 `SourceOperateCodeEnum.ALL_TEST.getValue().equals(FormalTestManager.reCheckType)` 时触发
- 请求体中的 `lineIds`、`timeStart`、`timeEnd` 使用当前批次正式检测数据
- `indicatorCodes` 固定传空数组
- 调用采用异步方式，不阻塞当前正式检测完成主流程
- 调用失败后按 `2^failCount` 秒退避重试，最多重试 3 次
- 同一批次检测在单次进程生命周期内只通知一次

## 非目标

- 不处理比对式检测
- 不处理异常结束、失败结束或中断结束路径
- 不解析第三方响应体中的 `taskId`、`taskNo`、`taskStatus`
- 不把第三方响应体落库
- 不引入数据库任务表、消息队列或持久化幂等机制
- 不保证服务重启后的跨进程幂等

## 已确认决策

- 方案采用纯内存幂等标记 + `@Async` 异步调用与重试
- 第三方调用方法放在 `com.njcn.gather.result.service` 层
- 触发位置不放在 `PqDevServiceImpl`
- 触发位置放在数模式正式检测完成后的成功收口点
- 第三方调用成功判定只看 HTTP 调用成功且未抛异常
- 失败重试规则为最多 3 次，间隔分别为 2 秒、4 秒、8 秒

## 触发边界

### 唯一触发范围

本次功能只覆盖数模式正式检测成功完成路径。

推荐触发位置：

- [SocketDevResponseService](D:\njcn\test\CN_Gather\detection\src\main\java\com\njcn\gather\detection\handler\SocketDevResponseService.java)

具体挂接点：

- 在数模式正式检测最终成功分支中
- `iPqDevService.updateResult(param.getDevIds(), valueType, param.getCode(), param.getUserId(), param.getTemperature(), param.getHumidity(), true)` 执行完成之后
- `CnSocketUtil.quitSend(param)` 之前调用结果服务的第三方通知入口

### 为什么不放在 `PqDevServiceImpl`

- `PqDevServiceImpl` 是通用状态汇总与入库层，不等价于正式检测生命周期结束
- 该类会被多条业务链路复用，挂接后容易误触发
- 本次需求明确要求“正式检测完成后”触发，因此应挂在正式检测成功收口边界

## 架构设计

### 入口职责

在 `result` service 层新增一个对外入口，例如：

```java
void tryNotifyThirdPartyAfterFormalTest(PreDetectionParam param)
```

建议实现位置：

- [IResultService](D:\njcn\test\CN_Gather\detection\src\main\java\com\njcn\gather\result\service\IResultService.java)
- [ResultServiceImpl](D:\njcn\test\CN_Gather\detection\src\main\java\com\njcn\gather\result\service\impl\ResultServiceImpl.java)

该入口负责：

- 校验当前是否满足触发条件
- 组装幂等 key
- 做内存去重
- 触发异步第三方调用

### 异步职责

在 `ResultServiceImpl` 中新增 `@Async` 方法，负责：

- 发起第三方 HTTP 请求
- 捕获异常
- 按指数退避重试
- 更新内存中的执行状态
- 记录成功或失败日志

## 触发条件

只有同时满足以下条件时才允许发起第三方通知：

1. 当前链路属于数模式正式检测最终成功收口点
2. `SourceOperateCodeEnum.ALL_TEST.getValue().equals(FormalTestManager.reCheckType)`
3. `FormalTestManager.checkStartTime` 不为空
4. `param.getPlanId()` 不为空
5. `param.getDevIds()` 非空
6. 当前批次幂等 key 未处于 `RUNNING` 或 `SUCCESS`

任一条件不满足时直接返回，不抛业务异常。

## 请求设计

### 接口

- 方法：`POST`
- 路径：`/steady/checksquare/create`
- 头：`Content-Type: application/json`

### 请求体

```json
{
  "lineIds": ["LINE_001", "LINE_002"],
  "indicatorCodes": [],
  "timeStart": "2026-06-13 00:00:00",
  "timeEnd": "2026-06-13 01:00:00"
}
```

### 字段来源

- `lineIds`
  - 取 `FormalTestManager.monitorIdListComm`
  - 含义为当前批次正式检测涉及的监测点 ID 集合

- `indicatorCodes`
  - 固定传空数组 `[]`

- `timeStart`
  - 取 `FormalTestManager.checkStartTime`
  - 格式化为 `yyyy-MM-dd HH:mm:ss`

- `timeEnd`
  - 根据 `param.getDevIds()` 查询本批次装置对应的 `PqDevSub.checkEndTime`
  - 取最大值作为本批次装置写入的最终结束时间
  - 只统计本次 `devIds` 对应装置，不扫描其他无关装置

## 时间结束值设计

`timeEnd` 不取通知触发时刻，也不取计划级别推导值，而取本批次装置已写入数据库的最终结束时间。

原因：

- 更符合“状态修改入库后再通知”的业务语义
- 可以避免异步线程调度延迟导致结束时间被人为拉晚
- 可以保证第三方拿到的是本次批次真实落库完成时间

## 内存幂等设计

### 幂等键

同一批次检测的内存幂等 key 定义为：

`planId + "|" + sortedDevIds + "|" + timeStart + "|" + reCheckType`

说明：

- `planId` 标识所属计划
- `sortedDevIds` 标识当前批次参与检测的装置集合，排序后再拼接，避免顺序影响
- `timeStart` 标识本轮正式检测开始时间
- `reCheckType` 用于区分全部检测与其他复检类型

### 内存状态

建议在 `ResultServiceImpl` 内维护一个 `ConcurrentHashMap<String, NotifyState>`。

`NotifyState` 至少包含：

- `status`：`RUNNING`、`SUCCESS`、`FAIL`
- `failCount`：失败次数
- `lastError`：最后一次异常摘要
- `triggerTime`：首次触发时间

### 幂等规则

- key 已存在且状态为 `RUNNING`：直接返回，不重复发起
- key 已存在且状态为 `SUCCESS`：直接返回，不重复发起
- key 不存在：创建 `RUNNING` 状态并进入异步调用
- key 为 `FAIL`：本轮进程内不自动重新发起新一轮通知

该规则保证：

- 同一批次在单次进程生命周期内只会成功进入一次通知流程
- 重试逻辑只在同一次异步流程内部进行，不因业务代码重复命中而再次启动

## 重试设计

### 执行方式

异步方法第一次立即发起调用。

如果失败，则在异步方法内部串行重试，不再额外启动新的业务线程入口。

### 退避规则

失败后按 `2^failCount` 秒等待后重试：

- 第 1 次失败后，等待 2 秒
- 第 2 次失败后，等待 4 秒
- 第 3 次失败后，等待 8 秒

总重试上限：

- 最多重试 3 次

### 成功判定

以下条件同时满足即可判定为成功：

- HTTP 请求成功发出
- 未抛出异常

不要求：

- 解析响应体业务字段
- 校验 `taskStatus`
- 保存 `taskId` 或 `taskNo`

### 失败处理

连续失败 3 次后：

- 内存状态更新为 `FAIL`
- 记录错误日志
- 停止继续重试
- 不影响正式检测主流程结果

## 配置设计

建议在 [application.yml](D:\njcn\test\CN_Gather\entrance\src\main\resources\application.yml) 中新增：

```yaml
third-party:
  checksquare:
    enabled: true
    url: http://third-party-host/steady/checksquare/create
    connect-timeout-ms: 3000
    read-timeout-ms: 5000
    max-retries: 3
```

说明：

- `enabled`
  - 联调和现场排障时可快速关闭能力
- `url`
  - 第三方接口地址
- `connect-timeout-ms`
  - 建连超时
- `read-timeout-ms`
  - 读超时
- `max-retries`
  - 默认值为 3，与当前需求一致

## HTTP 调用方式

项目内已存在 `RestTemplateUtil` 使用习惯，本次设计延续现有风格，不引入新的 HTTP 客户端框架。

调用建议：

- 复用项目现有 `RestTemplateUtil`
- 以 JSON 方式发送请求体
- 设置合理超时

## 日志设计

建议至少记录以下日志信息：

- 幂等 key
- `planId`
- `devIds`
- `lineIds` 数量
- `timeStart`
- `timeEnd`
- 当前重试次数
- 最终结果：成功或失败
- 异常摘要

日志用途：

- 排查重复触发
- 定位请求失败原因
- 还原本次批次通知上下文

## 测试与验收设计

至少覆盖以下场景：

### 单元验证

- `reCheckType` 不是 `ALL_TEST` 时不触发
- 幂等 key 已为 `RUNNING` 时不重复发起
- 幂等 key 已为 `SUCCESS` 时不重复发起
- `lineIds` 正确来自 `FormalTestManager.monitorIdListComm`
- `indicatorCodes` 固定为空数组
- `timeStart` 正确来自 `FormalTestManager.checkStartTime`
- `timeEnd` 正确取本批次装置 `checkEndTime` 最大值

### 异步重试验证

- 第一次失败、第二次成功时，发生一次重试并最终标记 `SUCCESS`
- 连续失败 3 次时，最终标记 `FAIL`
- 重复进入正式检测完成收口点时，不会对同一 key 再次起新的通知流程

### 集成验证

- 数模式正式检测成功完成后，第三方接口被调用 1 次
- 同一批次重复命中成功收口逻辑时，第三方仍只收到 1 轮调用流程
- 比对式检测不触发该接口

## 风险与限制

- 纯内存幂等仅在单次服务进程生命周期内有效，服务重启后无法保证已通知批次不重复
- 如果 `FormalTestManager` 上下文在成功收口时已丢失，则无法安全构造请求体，应直接放弃通知并记录日志
- 如果数据库中某个装置的 `checkEndTime` 未正确写入，`timeEnd` 可能无法按预期构造，应视为不满足触发条件
- 失败状态不持久化，因此无法跨重启继续重试

## 实施边界

本设计确认后，实施阶段仅应完成以下内容：

- `result` service 层新增第三方通知入口
- 数模式正式检测成功收口点接入该入口
- 第三方请求体组装
- 内存幂等控制
- `@Async` 异步调用与指数退避重试
- 必要的配置项与测试

不应在本次实现中额外引入：

- 任务表
- MQ
- Redis 幂等
- 跨进程重试恢复
- 比对式适配

## 当前结论

本需求的最终设计为：

- 仅覆盖数模式正式检测成功完成场景
- 触发点放在 `SocketDevResponseService` 正式检测成功收口处
- 第三方调用入口放在 `com.njcn.gather.result.service` 层
- 使用纯内存 `ConcurrentHashMap` 做单进程幂等
- 使用 `@Async` 执行第三方调用
- 失败后按 2 秒、4 秒、8 秒重试，最多 3 次
- `indicatorCodes` 固定空数组
- `timeEnd` 使用本批次装置写入数据库的最大 `checkEndTime`