功能说明
覆盖全景浏览、社区安全、运营管理、监控录像的数据接口与模型联动支持。
关联任务
- 关联设计：[设计] iot大屏页面设计
- 关联前端：[前端] iot大屏页面开发
- 关联测试：[测试-后端] iot大屏接口测试
接口1：GET 全景数据总览
| 请求方式 | GET |
| 请求路径 | /api/v1/panorama/overview |
| 对应功能 | 全景浏览-数据总览面板 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| communityId | string | 是 | 小区ID | 路由/全局配置 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| area | number | 占地面积 | 总览卡片 |
| greenRate | number | 绿化率% | 总览卡片 |
| houseTotal | number | 房屋总数 | 总览卡片+运营联动 |
| personTotal | number | 人员总数 | 总览卡片+人员分析 |
| vehicleTotal | number | 车辆总数 | 总览卡片+车辆分析 |
| facilities | array | 配套设施列表 | 地图点位/列表 |
详细业务逻辑
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | 校验communityId | 必填，长度36以内 | 缺失返回4001 |
| 2.权限检查 | 校验用户对社区的查看权限 | 角色：管理员/安保/运营 | 无权限返回4031 |
| 3.数据查询 | 查社区基础表、房屋表、人员表、车辆表、设施表 | 按communityId汇总统计 | 无数据返回空统计0 |
| 4.业务处理 | 计算绿化率、合并设施分布 | 绿化率保留两位；设施按类型聚合 | 计算失败记录告警并使用默认0 |
| 5.数据组装 | 组装为总览对象 | 字段映射响应结构 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 4001 | 参数缺失 | 缺少communityId |
| 4031 | 无权限 | 无访问权限 |
| 5001 | 内部异常 | 服务暂不可用 |
接口2：GET 楼栋详情
| 请求方式 | GET |
| 请求路径 | /api/v1/panorama/buildings/{id} |
| 对应功能 | 楼栋点击查看 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| id | string | 是 | 楼栋ID | 模型点击 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| occupancyRate | number | 入住率% | 楼栋卡片 |
| houseTypeDist | object | 房屋类型分布 | 饼图 |
| personTypeDist | object | 人员分类 | 饼图 |
| vehicles | array | 登记车辆列表 | 列表 |
详细业务逻辑
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | 校验id | 必填，UUID | 缺失返回4001 |
| 2.权限检查 | 检查楼栋访问权限 | 角色同社区 | 无权限4031 |
| 3.数据查询 | 查楼栋、房屋、人员、车辆表 | 按buildingId聚合 | 无数据返回4041 |
| 4.业务处理 | 计算入住率、分布 | 入住率=已入住/可售；分布按类型计数 | 计算失败默认0 |
| 5.数据组装 | 组装字段 | 映射前端 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 4041 | 楼栋不存在 | 未找到楼栋 |
接口3：GET 房屋搜索定位
| 请求方式 | GET |
| 请求路径 | /api/v1/panorama/search-house |
| 对应功能 | 房屋搜索定位 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| keyword | string | 是 | 房号/住户名 | 搜索框 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| houseId | string | 房屋ID | 模型定位 |
| coord | object | 坐标 | 相机飞行 |
| detail | object | 房屋/住户信息 | 详情卡片 |
详细业务逻辑
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | keyword | 必填，长度1-50 | 缺失4001 |
| 2.权限检查 | 社区访问权限 | 角色同上 | 无权限4031 |
| 3.数据查询 | 索引房屋/住户表 | 按房号/姓名模糊匹配 | 无结果返回空数组 |
| 4.业务处理 | 返回最相关结果 | 按匹配度排序 | 异常5001 |
| 5.数据组装 | 组装坐标+详情 | 字段映射 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 4001 | 参数缺失 | 请输入搜索内容 |
接口4：GET 设备总览与分布
| 请求方式 | GET |
| 请求路径 | /api/v1/security/devices |
| 对应功能 | 社区安全-设备信息监控 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| type | string | 否 | 设备类型过滤 | 类型点击 |
| communityId | string | 是 | 社区 | 全局 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| total | number | 总数 | 总览 |
| byType | array | 按类型统计 | 类型分布图 |
| items | array | 设备列表含坐标 | 模型定位 |
详细业务逻辑
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | communityId,type | communityId必填；type在枚举内 | 非法4002 |
| 2.权限检查 | 设备查看权限 | 管理员/安保 | 无权4031 |
| 3.数据查询 | 设备表/状态表 | 按社区过滤，类型可选 | 无数据返回0 |
| 4.业务处理 | 统计按类型聚合 | 分布含在线率 | 异常5001 |
| 5.数据组装 | 返回total/byType/items | 坐标用于定位 | - |
接口5：GET 实时报警
| 请求方式 | GET |
| 请求路径 | /api/v1/security/alarms |
| 对应功能 | 社区安全-实时安全监测 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| status | string | 否 | 待确认/已确认/误报 | 筛选 |
| page | number | 否 | 页码 | 分页 |
| pageSize | number | 否 | 每页 | 分页 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| stats | object | 待确认/已确认/误报统计 | 看板 |
| list | array | 报警列表含时间、点位、内容、坐标 | 列表+定位 |
| total | number | 总数 | 分页 |
详细业务逻辑
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | status,page,pageSize | status枚举，分页范围1-100 | 非法4002 |
| 2.权限检查 | 报警查看 | 管理员/安保 | 4031 |
| 3.数据查询 | 报警表 | 按状态/时间倒序 | 无数据返回空 |
| 4.业务处理 | 统计分类占比；附点位坐标 | 比例保留1位 | 异常5001 |
| 5.数据组装 | 返回stats+list+total | 列表用于滚动播报 | - |
接口6：GET 运营分析
| 请求方式 | GET |
| 请求路径 | /api/v1/operation/dashboard |
| 对应功能 | 运营管理-入住/人员/车辆/工单/投诉分析 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| range | string | 否 | 时间范围 | 筛选 |
| communityId | string | 是 | 社区 | 全局 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| houseOccupancy | array | 入住率趋势 | 折线 |
| personDist | object | 人员分布 | 饼图 |
| vehicleDist | object | 车辆占比 | 饼图 |
| orders | array | 工单分类+最新列表 | 列表 |
| complaints | array | 投诉分析+最新 | 列表 |
详细业务逻辑
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | range,communityId | range在7/30/90d或custom | 非法4002 |
| 2.权限检查 | 运营数据查看 | 管理员/运营 | 4031 |
| 3.数据查询 | 房屋/人员/车辆/工单/投诉表 | 按时间范围聚合 | 无数据返回空结构 |
| 4.业务处理 | 趋势计算、占比、AI投诉分类 | 调用AI分类服务 | AI失败降级为关键词分类 |
| 5.数据组装 | 组装各模块数据 | 字段映射响应 | - |
接口7：GET 监控画面列表
| 请求方式 | GET |
| 请求路径 | /api/v1/video/streams |
| 对应功能 | 监控录像-多画面 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| area | string | 否 | 区域过滤 | 区域切换 |
| limit | number | 否 | 最大路数 | 布局 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| streams | array | 摄像头列表含播放地址/封面 | 多画面播放 |
详细业务逻辑
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | limit | limit<=16 | 超限4002 |
| 2.权限检查 | 视频查看 | 管理员/安保 | 4031 |
| 3.数据查询 | 摄像头表+播放URL | 按area过滤 | 无数据空列表 |
| 4.业务处理 | 裁剪到limit | 按优先级排序 | 异常5001 |
| 5.数据组装 | 返回streams | 含封面/坐标 | - |