0. 【前置分析】沿用统一返回结构与权限校验
功能说明
安全设备总览、报警列表、实时播报、人员/车辆实时统计
关联任务
- 关联前端任务：[前端] 中控大屏前端开发
- 关联测试任务：[测试-后端] 全量接口测试
接口1：安全设备总览
| 请求方式 | GET |
| 请求路径 | /api/v1/security/devices |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|---|---|---|---|
| communityId | number | 是 | 小区ID | 配置 |
| type | string | 否 | 设备类型过滤 | 类型点击 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|---|---|---|
| total | number | 设备总数 | 总览 |
| distribution | array | 类型分布 | 图表 |
| list | array | 设备列表含坐标 | 点击定位 |
业务逻辑
- 校验社区/权限
- 按类型聚合
- 返回坐标
错误处理
| 错误码 | 场景 | 前端提示 |
|---|---|---|
| 4003 | 参数错误 | 参数错误 |
接口2：报警统计与列表
| 请求方式 | GET |
| 请求路径 | /api/v1/security/alarms |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|---|---|---|---|
| status | string | 否 | pending/confirmed/false | 筛选 |
| limit | number | 否 | 条数 | 下拉 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|---|---|---|
| stats | object | 各状态数量 | 看板 |
| list | array | 报警列表含时间/点位 | 列表、定位 |
业务逻辑
- 校验过滤
- 统计并分页
- 附带坐标
错误处理
| 错误码 | 场景 | 前端提示 |
|---|---|---|
| 4004 | 状态非法 | 状态错误 |
接口3：实时报警滚动
| 请求方式 | GET |
| 请求路径 | /api/v1/security/alarms/realtime |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|---|---|---|---|
| since | string | 否 | ISO时间戳 | 轮询参数 |
| limit | number | 否 | 返回条数 | 配置 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|---|---|---|
| list | array | 最新报警 | 滚动播报 |
业务逻辑
- 按时间过滤
- 按最新排序
错误处理
| 错误码 | 场景 | 前端提示 |
|---|---|---|
| 4291 | 请求过频 | 请稍后 |
接口4：人员实时统计
| 请求方式 | GET |
| 请求路径 | /api/v1/security/personnel-stats |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|---|---|---|---|
| communityId | number | 是 | 小区ID | 配置 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|---|---|---|
| resident | number | 住户数 | 卡片 |
| visitor | number | 访客数 | 卡片 |
| staff | number | 员工数 | 卡片 |
| stranger | number | 陌生人 | 重点提示 |
接口5：车辆实时统计
| 请求方式 | GET |
| 请求路径 | /api/v1/security/vehicle-stats |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|---|---|---|---|
| communityId | number | 是 | 小区ID | 配置 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|---|---|---|
| private | number | 私家车 | 卡片 |
| monthly | number | 月卡 | 卡片 |
| temp | number | 临时 | 卡片 |
| temporaryStop | number | 临停 | 卡片 |
| whitelist | number | 白名单 | 卡片 |