0. 【前置分析】遵循现有REST风格，错误码：200成功，4xx参数/权限，5xx系统错误；统一返回{code,msg,data}
功能说明
全景总览、楼栋详情、房屋搜索、数据联动定位
关联任务
- 关联前端任务：[前端] 中控大屏前端开发
- 关联测试任务：[测试-后端] 全量接口测试
接口1：全景数据总览
| 请求方式 | GET |
| 请求路径 | /api/v1/overview/summary |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|---|---|---|---|
| communityId | number | 是 | 小区ID | 路由/配置 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|---|---|---|
| area | number | 占地面积㎡ | 概况展示 |
| greeningRate | number | 绿化率% | 概况展示 |
| houseTotal | number | 房屋/户数 | 数据跳转 |
| personTotal | number | 人员总数 | 数据跳转 |
| vehicleTotal | number | 车辆总数 | 数据跳转 |
| facilityCount | number | 公共设施数 | 图标展示 |
业务逻辑
- 校验communityId
- 权限校验
- 汇总统计并返回
错误处理
| 错误码 | 场景 | 前端提示 |
|---|---|---|
| 4001 | 参数缺失 | 参数错误 |
| 4031 | 无权限 | 无权限访问 |
接口2：楼栋详情
| 请求方式 | GET |
| 请求路径 | /api/v1/buildings/{id} |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|---|---|---|---|
| id | number | 是 | 楼栋ID | 模型点击 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|---|---|---|
| occupancyRate | number | 入住率% | 卡片展示 |
| houseTypeDist | array | 房屋类型分布 | 图表 |
| personDist | array | 人员分类统计 | 图表 |
| vehicles | array | 登记车辆 | 列表 |
业务逻辑
- 校验楼栋存在
- 权限校验
- 聚合分布数据
错误处理
| 错误码 | 场景 | 前端提示 |
|---|---|---|
| 4041 | 楼栋不存在 | 数据不存在 |
接口3：房屋搜索定位
| 请求方式 | GET |
| 请求路径 | /api/v1/units/search |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|---|---|---|---|
| keyword | string | 是 | 房号关键字 | 搜索框 |
| buildingId | number | 否 | 限定楼栋 | 下拉 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|---|---|---|
| unitId | number | 房屋ID | 定位参数 |
| buildingId | number | 楼栋ID | 联动 |
| label | string | 房号 | 列表展示 |
| coords | object | 模型坐标 | 高亮定位 |
业务逻辑
- 校验keyword
- 模糊搜索
- 返回坐标
错误处理
| 错误码 | 场景 | 前端提示 |
|---|---|---|
| 4002 | keyword为空 | 请输入房号 |
接口4：数据联动定位
| 请求方式 | GET |
| 请求路径 | /api/v1/map/locate-by-entity |
请求参数
| 参数名 | 类型 | 必填 | 说明 | 前端来源 |
|---|---|---|---|---|
| entityType | string | 是 | building/unit/device/person/vehicle | 面板点击 |
| entityId | number | 是 | 实体ID | 面板点击 |
响应字段
| 字段名 | 类型 | 说明 | 前端用途 |
|---|---|---|---|
| coords | object | 模型坐标 | 定位 |
| extra | object | 附加摘要 | 信息展示 |
业务逻辑
- 校验类型与ID
- 查映射坐标
- 返回定位信息
错误处理
| 错误码 | 场景 | 前端提示 |
|---|---|---|
| 4042 | 实体不存在 | 无法定位 |