功能说明
覆盖全景浏览、社区安全、运营管理、监控录像的数据接口与联动逻辑。
关联任务
- 关联设计：[设计] 小区IoT中控大屏页面设计
- 关联前端：[前端] 小区IoT中控大屏页面开发
- 关联测试：[测试-后端] 小区IoT中控大屏接口测试
接口1：全景数据总览
| 请求方式 | GET |
| 请求路径 | /api/v1/panorama/summary |
| 对应功能 | 全景浏览-数据总览面板 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| communityId | string | 是 | 小区ID | 全局上下文 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| area | number | 占地面积 | 展示 |
| greenRate | number | 绿化率 | 展示 |
| houses | number | 房屋总量 | 展示 |
| persons | number | 人员总量 | 展示 |
| cars | number | 车辆总量 | 展示 |
| facilities | number | 配套设施数 | 展示 |
详细业务逻辑（必须与需求功能点对应）
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | 校验communityId | 必填，UUID格式 | 缺失返回400 |
| 2.权限检查 | 校验用户对communityId访问权限 | 角色：物业经理/安防/运营 | 无权限403 |
| 3.数据查询 | 查询社区信息表、房屋表、人员表、车辆表、设施表 | 按communityId汇总 | 无数据返回0值 |
| 4.业务处理 | 计算绿化率、总量 | 绿化率=绿地面积/总面积 | 计算异常返回500 |
| 5.数据组装 | 组装 summary 字段 | 字段映射响应 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 400001 | 参数缺失 | 缺少必要参数 |
| 403001 | 无访问权限 | 无权限 |
| 500001 | 内部错误 | 服务异常 |
接口2：楼栋详情及模型点位
| 请求方式 | GET |
| 请求路径 | /api/v1/buildings/{id}/detail |
| 对应功能 | 楼栋点击查看 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| id | string | 是 | 楼栋ID | 模型点击 |
| communityId | string | 是 | 小区ID | 上下文 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| occupancyRate | number | 入住率 | 卡片展示 |
| houseTypes | array | 房屋类型分布 | 图表 |
| personStats | array | 人员分类统计 | 图表 |
| cars | array | 登记用车信息 | 列表 |
| modelPosition | object | 模型坐标 | 定位高亮 |
详细业务逻辑（必须与需求功能点对应）
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | 校验id、communityId | 必填，UUID | 400返回 |
| 2.权限检查 | 校验楼栋访问权限 | 角色：物业/安防 | 403返回 |
| 3.数据查询 | 楼栋、房屋、人员、车辆、模型表 | 按楼栋ID关联 | 无楼栋404 |
| 4.业务处理 | 计算入住率、分类统计 | 入住率=入住房屋/总房屋 | 异常500 |
| 5.数据组装 | 组装卡片数据+模型坐标 | 字段映射响应 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 404001 | 楼栋不存在 | 数据不存在 |
| 403001 | 无权限 | 无权限 |
| 500002 | 计算异常 | 服务异常 |
接口3：房屋搜索定位
| 请求方式 | GET |
| 请求路径 | /api/v1/houses/search |
| 对应功能 | 房屋搜索定位 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| communityId | string | 是 | 小区ID | 上下文 |
| keyword | string | 是 | 房号/楼栋/单元关键词 | 搜索框 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| houseId | string | 房屋ID | 点击高亮 |
| displayName | string | 楼栋-单元-室号 | 结果列表 |
| modelPosition | object | 坐标 | 定位高亮 |
| personCarInfo | object | 关联人员/车辆 | 详情弹窗 |
详细业务逻辑（必须与需求功能点对应）
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | 校验communityId、keyword | keyword 1-50字符 | 400返回 |
| 2.权限检查 | 校验查询权限 | 允许物业/安防/客服 | 403返回 |
| 3.数据查询 | 房屋表模糊匹配，关联模型坐标 | 按关键词LIKE，限制50条 | 无数据返回空数组 |
| 4.业务处理 | 补充关联人员车辆信息 | 最近登记车辆、住户信息 | 关联失败忽略 |
| 5.数据组装 | 组装列表 | 字段映射 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 400002 | keyword非法 | 请输入有效房号 |
| 403002 | 无权限 | 无权限 |
| 500003 | 查询异常 | 服务异常 |
接口4：报警实时与统计
| 请求方式 | GET |
| 请求路径 | /api/v1/security/alarms |
| 对应功能 | 社区安全-报警数据处理 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| communityId | string | 是 | 小区ID | 上下文 |
| status | string | 否 | 待确认/已确认/误报 | 筛选 |
| page | number | 否 | 页码 | 分页 |
| pageSize | number | 否 | 每页 | 分页 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| stats | object | 各状态数量 | 统计看板 |
| list | array | 报警列表 | 待处理列表 |
| scroll | array | 滚动播报最新报警 | 滚动区域 |
详细业务逻辑（必须与需求功能点对应）
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | 校验分页、status | page>=1,pageSize<=100 | 400返回 |
| 2.权限检查 | 校验报警查看权限 | 安防/值班可见 | 403返回 |
| 3.数据查询 | 查询报警表，按时间倒序，统计状态 | 过滤communityId | 查询失败500 |
| 4.业务处理 | 滚动列表取最新100条，列表按分页 | 状态过滤优先 | 异常记录跳过 |
| 5.数据组装 | stats+list+scroll | 字段映射 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 400003 | 分页非法 | 分页参数错误 |
| 403003 | 无权限 | 无权限 |
| 500004 | 查询异常 | 服务异常 |
接口5：运营数据分析
| 请求方式 | GET |
| 请求路径 | /api/v1/operation/analytics |
| 对应功能 | 运营管理-房屋/人员/车辆/工单/投诉 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| communityId | string | 是 | 小区ID | 上下文 |
| dateRange | array | 否 | 时间范围 | 筛选控件 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| houseOccupancy | array | 入住/空置趋势 | 图表 |
| personComposition | array | 人员类型分布 | 图表 |
| vehicleStats | array | 车辆占比 | 图表 |
| workOrders | array | 工单分类、最新工单 | 列表 |
| complaints | array | 投诉分类、最新投诉 | 列表 |
详细业务逻辑（必须与需求功能点对应）
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | 校验communityId，dateRange | dateRange最多90天 | 超出返回400 |
| 2.权限检查 | 校验运营数据查看权限 | 运营分析员/经理 | 403返回 |
| 3.数据查询 | 房屋、人员、车辆、工单、投诉、AI分类服务 | 按时间过滤 | 外部调用失败记录 |
| 4.业务处理 | 计算趋势、占比，调用AI分类 | 缺数据填0 | AI失败降级不展示分类 |
| 5.数据组装 | 组装各模块数据 | 字段映射 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 400004 | 时间范围非法 | 请选择90天内时间 |
| 403004 | 无权限 | 无权限 |
| 500005 | 数据查询失败 | 服务异常 |
接口6：监控流列表
| 请求方式 | GET |
| 请求路径 | /api/v1/monitor/streams |
| 对应功能 | 监控录像多画面 |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|
| communityId | string | 是 | 小区ID | 上下文 |
| limit | number | 否 | 返回流数量 | 配置 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|
| streams | array | 流地址、类型、优先级 | 监控画面 |
详细业务逻辑（必须与需求功能点对应）
| 步骤 | 处理内容 | 规则说明 | 异常处理 |
|---|
| 1.参数校验 | 校验communityId、limit | limit默认9，最大16 | 非法400 |
| 2.权限检查 | 监控查看权限 | 安防/经理 | 403 |
| 3.数据查询 | 查询监控点位表、流媒体服务 | 按优先级排序 | 无流返回空 |
| 4.业务处理 | 生成可播放URL，过滤离线 | 离线标记状态 | 离线流不返回URL |
| 5.数据组装 | 组装streams | 包含坐标、名称 | - |
错误处理
| 错误码 | 触发场景 | 前端提示 |
|---|
| 400005 | 参数非法 | 参数错误 |
| 403005 | 无权限 | 无权限 |
| 500006 | 流服务异常 | 视频不可用 |