# EdgeGuard 第三方开放接口

## 1. 查询区域及摄像头关系

```http
GET /open/edgeguard/regions?corpId={corpId}
```

`corpId` 非必填：传入时查询指定企业，不传时查询当前调用方租户下全部企业。接口只返回 `ENABLED` 区域，以及区域下 `BOUND` 状态的摄像头和当前有效的授权人员。

区域中的 `users` 仅包含权限状态为 `ACTIVE`、已到生效开始时间、未到有效结束时间且用户仍处于启用状态的人员；已撤销、已过期、未生效或已停用用户均不返回。

摄像头字段来自海康 `/videopatrol/fixedCamera/videoSelectList`：

| 开放字段 | 海康字段 | 说明 |
| --- | --- | --- |
| `cameraId` | `indexCode` | 摄像头唯一编码 |
| `cameraName` | `name` | 摄像头名称 |
| `cameraRegionName` | `regionName` | 海康平台所属区域名称快照 |
| `cameraSource` | 后台固定 | 当前为 `HIKVISION` |

`users` 人员字段：

| 字段 | 说明 |
| --- | --- |
| `userId` | 被授权人员用户 ID |
| `userName` | 人员姓名 |
| `permissionType` | 权限类型：`TEMPORARY`（临时）或 `FIXED`（固定） |
| `effectiveStartTime` | 授权生效开始时间，格式 `yyyy-MM-dd HH:mm:ss` |
| `effectiveEndTime` | 授权生效结束时间；固定权限为 `null` |
| `authorizationSource` | 授权来源：`MANUAL`、`IMPORT` 或 `API` |

响应示例：

```json
{
  "success": true,
  "data": [{
    "regionId": 1001,
    "regionCode": "8d9d07f4d9db4c49906a7a891474f3af",
    "regionName": "仓库东区",
    "corpId": 2001,
    "parentId": 0,
    "treePath": "/",
    "treeLevel": 1,
    "sortNo": 10,
    "coordinateSystem": "GCJ02",
    "fencePoints": [
      {"seq": 1, "longitude": 113.1, "latitude": 23.1},
      {"seq": 2, "longitude": 113.2, "latitude": 23.1},
      {"seq": 3, "longitude": 113.2, "latitude": 23.2},
      {"seq": 4, "longitude": 113.1, "latitude": 23.2}
    ],
    "regionStatus": "ENABLED",
    "cameras": [{
      "cameraSource": "HIKVISION",
      "cameraId": "CAMERA-001",
      "cameraName": "东门摄像头",
      "cameraRegionName": "海康园区一层"
    }],
    "users": [{
      "userId": 3001,
      "userName": "张三",
      "permissionType": "TEMPORARY",
      "effectiveStartTime": "2026-09-03 08:00:00",
      "effectiveEndTime": "2026-09-03 18:00:00",
      "authorizationSource": "MANUAL"
    }]
  }]
}
```

## 2. 接收第三方报警

```http
POST /open/edgeguard/alarms
Content-Type: application/json
```

请求字段：

| 字段 | 必填 | 最大长度 | 说明 |
| --- | --- | --- | --- |
| `alarmNo` | 是 | 128 | 第三方报警唯一编号 |
| `sourceSystem` | 是 | 64 | 报警来源系统编码 |
| `recognitionResult` | 是 | 100 | 识别结论，例如“已知人员无权限”或“无法匹配的陌生人员” |
| `alarmTime` | 是 | - | `yyyy-MM-dd HH:mm:ss`，东八区 |
| `regionCode` | 是 | 64 | 区域查询接口返回的稳定编码 |
| `cameraSource` | 是 | 64 | 当前海康摄像头传 `HIKVISION` |
| `cameraId` | 是 | 128 | 区域查询接口返回的摄像头编码 |
| `alarmAddress` | 否 | 500 | 报警位置描述 |
| `alarmImageUrl` | 否 | 1000 | 报警截图地址 |
| `remarks` | 否 | 255 | 补充说明 |

请求示例：

```json
{
  "alarmNo": "ALARM-20260903-000001",
  "sourceSystem": "FACE_AI",
  "recognitionResult": "已知人员无权限",
  "alarmTime": "2026-09-03 10:30:00",
  "regionCode": "8d9d07f4d9db4c49906a7a891474f3af",
  "cameraSource": "HIKVISION",
  "cameraId": "CAMERA-001",
  "alarmAddress": "仓库东区入口",
  "alarmImageUrl": "https://files.example.com/alarm/001.jpg",
  "remarks": "人员进入限制区域"
}
```

后台使用 `regionCode + cameraSource + cameraId` 校验摄像头确实绑定在该区域，并从本地数据补充企业、区域和摄像头名称快照。`receivedTime` 和 `disposalStatus=PENDING` 由后台生成。

`sourceSystem + alarmNo` 是幂等键。重复推送返回第一次保存的报警，不重复入库：

```json
{
  "success": true,
  "data": {
    "alarmId": 5001,
    "alarmNo": "ALARM-20260903-000001",
    "receivedTime": "2026-09-03 10:30:02",
    "duplicate": false
  }
}
```

## 3. 接入约束

- 两个开放接口都必须携带平台签发的 `token` 请求头。框架认证过滤器解析 token 后把租户信息写入 `AuthContext`，业务接口不接受第三方自行传入的 `tenantId` 作为身份依据。
- 开放接口上线前必须在网关配置第三方应用鉴权、签名、防重放及企业授权范围。
- `corpId` 只作为可选查询条件；不传时按鉴权上下文中的租户范围查询，最终允许访问的企业范围以应用授权为准。
- 第三方报警中的区域和摄像头组合必须来自区域查询接口。
- 报警图片接口只保存 URL，不同步下载图片，URL 中禁止携带永久明文密钥。