135 lines
4.8 KiB
Markdown
135 lines
4.8 KiB
Markdown
# 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 中禁止携带永久明文密钥。
|