功能说明
覆盖全景浏览、社区安全、运营管理、监控录像的数据接口与联动逻辑。
关联任务
- 关联设计：[设计] iot大屏页面设计
- 关联前端：[前端] iot大屏页面开发
- 关联测试：[测试-后端] iot大屏接口测试
接口1：全景数据总览
| 请求方式 | GET |
| 请求路径 | /api/v1/community/overview |
| 对应功能 | 全景浏览-数据总览面板 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| communityId | string | 是 | 小区ID | 全局上下文 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| area | number | 占地总面积 | 概况卡片 |
| greeningRate | number | 绿化率 | 概况卡片 |
| houseTotal | number | 房屋总数 | 数据总览 |
| peopleTotal | number | 人员总数 | 数据总览 |
| vehicleTotal | number | 车辆总数 | 数据总览 |
| facilitySummary | array | 配套设施统计 | 配套列表 |
详细业务逻辑（必须与需求功能点对应）
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | 校验communityId | 必填，长度1-64 | 缺失返回400001 |
| 2.权限检查 | 校验用户是否可访问该community | 角色需绑定该小区 | 无权限返回403001 |
| 3.数据查询 | 查社区表、房屋表、人员表、车辆表、设施表 | 按communityId聚合 | 无数据返回404001 |
| 4.业务处理 | 计算绿化率、统计各总数 | 绿化率=绿地面积/总面积 | 异常记录日志，返回500001 |
| 5.数据组装 | 组装指标与设施列表 | 字段映射响应结构 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 400001 | 参数缺失/格式错误 | 参数错误 |
| 403001 | 无权限 | 暂无权限 |
| 404001 | 社区不存在 | 数据不存在 |
| 500001 | 内部异常 | 服务异常 |
接口2：楼栋详情
| 请求方式 | GET |
| 请求路径 | /api/v1/community/buildings/{buildingId} |
| 对应功能 | 全景浏览-楼栋点击卡片 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| buildingId | string | 是 | 楼栋ID | 模型点选 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| occupancyRate | number | 入住率 | 卡片展示 |
| houseTypeDist | array | 房屋类型分布 | 饼图 |
| peopleCategory | array | 人员分类统计 | 柱状图 |
| vehicles | array | 登记用车信息 | 列表 |
详细业务逻辑（必须与需求功能点对应）
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | 校验buildingId | 必填，UUID格式 | 缺失/非法返回400001 |
| 2.权限检查 | 校验用户对楼栋所属小区权限 | 需匹配用户小区列表 | 无权限403001 |
| 3.数据查询 | 查楼栋、房屋、住户、车辆表 | 通过buildingId关联 | 无数据404001 |
| 4.业务处理 | 计算入住率、分布统计 | 入住率=已入住房屋/总房屋 | 计算异常500001 |
| 5.数据组装 | 返回统计及车辆列表 | 格式化字段名称 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 400001 | 参数错误 | 参数错误 |
| 403001 | 无权限 | 暂无权限 |
| 404001 | 楼栋不存在 | 数据不存在 |
| 500001 | 内部异常 | 服务异常 |
接口3：实时报警与设备
| 请求方式 | GET |
| 请求路径 | /api/v1/security/alerts |
| 对应功能 | 社区安全-报警数据看板、设备类型分布 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| communityId | string | 是 | 小区ID | 全局上下文 |
| status | string | 否 | 待确认/已确认/误报 | 筛选控件 |
| limit | number | 否 | 返回报警条数 | 滚动区域 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| alertStats | object | 各状态数量 | 看板数字 |
| alerts | array | 报警列表 | 滚动播报 |
| deviceTypeDist | array | 设备类型分布 | 饼图/柱状图 |
详细业务逻辑（必须与需求功能点对应）
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | communityId、status、limit | communityId必填；status枚举；limit 1-200 | 非法返回400001 |
| 2.权限检查 | 检查用户安防数据权限 | 需安防或管理员角色 | 无权限403001 |
| 3.数据查询 | 查报警表、设备表 | 按communityId、status过滤 | 无数据返回空列表 |
| 4.业务处理 | 统计各状态数量，按时间排序，计算设备类型分布 | 状态统计聚合，设备类型分组 | 处理异常500001 |
| 5.数据组装 | 组装stats、列表、分布 | 字段统一命名 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 400001 | 参数错误 | 参数错误 |
| 403001 | 无权限 | 暂无权限 |
| 500001 | 内部异常 | 服务异常 |
接口4：运营分析数据
| 请求方式 | GET |
| 请求路径 | /api/v1/operation/analytics |
| 对应功能 | 运营管理-房屋入住、人员、车辆、工单、投诉、值班 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| communityId | string | 是 | 小区ID | 全局上下文 |
| dateRange | array | 否 | 查询时间范围 | 筛选控件 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| houseOccupancyTrend | array | 入住率趋势 | 折线图 |
| peopleComposition | array | 人员构成 | 饼图 |
| vehicleStats | array | 车辆占比 | 饼图 |
| abnormalPass | array | 异常通行记录 | 列表 |
| workOrders | array | 最新工单 | 滚动列表 |
| complaints | array | 投诉分析 | 列表 |
| dutyRoster | array | 值班信息 | 排班表 |
详细业务逻辑（必须与需求功能点对应）
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | communityId、dateRange | communityId必填；dateRange最多180天 | 非法400001 |
| 2.权限检查 | 运营数据权限 | 运营/管理员角色 | 无权限403001 |
| 3.数据查询 | 查入住、人员、车辆、工单、投诉、值班表 | 按communityId和时间过滤 | 无数据返回空结构 |
| 4.业务处理 | 计算趋势、占比、异常统计，AI投诉分类 | 占比按总量分组，投诉调用AI服务 | 处理异常500001 |
| 5.数据组装 | 组装趋势、分布、列表 | 字段对齐前端展示 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 400001 | 参数错误 | 参数错误 |
| 403001 | 无权限 | 暂无权限 |
| 500001 | 内部异常 | 服务异常 |
接口5：监控流列表
| 请求方式 | GET |
| 请求路径 | /api/v1/monitor/streams |
| 对应功能 | 监控录像-多画面监控/切换 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| communityId | string | 是 | 小区ID | 全局上下文 |
| area | string | 否 | 区域过滤 | 区域选择 |
| count | number | 否 | 返回流数量 | 多画面数量 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| streams | array | 流列表（id,name,url,protocol,area,isKeyPoint） | 播放器列表 |
详细业务逻辑（必须与需求功能点对应）
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | communityId、area、count | communityId必填；count 1-16 | 非法400001 |
| 2.权限检查 | 视频查看权限 | 安防/管理员 | 无权限403001 |
| 3.数据查询 | 查摄像头表或视频平台 | 按communityId、area过滤，按重点区域优先 | 无数据返回空列表 |
| 4.业务处理 | 组装播放地址与鉴权token | 协议HLS/RTC按配置 | 取token失败500002 |
| 5.数据组装 | 返回streams数组 | 字段统一 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 400001 | 参数错误 | 参数错误 |
| 403001 | 无权限 | 暂无权限 |
| 500002 | 鉴权失败 | 获取播放地址失败 |
| 500001 | 内部异常 | 服务异常 |