# API 接口文档 - 行道树巡检记录与安全风险评估 本文档用于指导微信小程序前端开发人员对接行道树巡检记录与安全风险评估接口。 为完美契合小程序详情页中按部位折叠面板的设计，接口设计采用了**分层嵌套结构**。 --- ## 接口基础信息 * **接口协议**：HTTP / HTTPS * **请求格式**：`application/json;charset=utf-8` * **响应格式**：`application/json;charset=utf-8` * **接口基地址**：`/app-api/garden/tree-inspection` 或 `/app-api/business/tree-inspection` * **认证方式**：请求头中需携带 `Authorization: Bearer ` --- ## 1. 提交巡检记录并进行风险评估 小程序在巡检人员填写完成表单，点击提交按钮（图3）时调用该接口。 * **接口路径**：`POST /create` * **请求方法**：`POST` ### 请求 JSON 参数说明 (`TreeInspectionSaveReqVO`) | 一级属性名 | 二级字段名 | 类型 | 是否必填 | 枚举值 / 说明 | 字段描述 | | :--- | :--- | :--- | :--- | :--- | :--- | | **treeId** | - | Long | 是 | 关联的树木档案 ID，如 `1024` | 树木 ID | | **inspectionTime** | - | String | 是 | 格式 `"yyyy-MM-dd HH:mm:ss"` | 巡检发生的时间 | | **root** | - | Object | 是 | 对应“树根部位”折叠面板 | 树根评估指标组 | | | **disease** | Integer | 是 | `0`（无真菌危害/腐朽）, `8`（存在危害/腐朽） | 是否存在病害？ | | | **anchorage** | Integer | 是 | `0`（良好无盘根隆起）, `7`（存在隆起或盘根） | 根系下扎情况 | | | **cutting** | Integer | 是 | `0`（无工程切根）, `5`（存在工程切根） | 是否存在工程切根 | | **collar** | - | Object | 是 | 对应“根颈部位”折叠面板 | 根颈评估指标组 | | | **woodDamage** | Integer | 是 | `0`（无）, `5`（<10%）, `15`（10%-30%）, `25`（30%-50%）, `70`（>=50% 一票否决） | 根颈木质部受损 | | | **barkDamage** | Integer | 是 | `0`（<10%）, `2`（10%-30%）, `4`（30%-50%）, `6`（>=50%） | 根颈树皮受损 | | | **loosening** | Integer | 是 | `0`（不存在松动）, `100`（存在松动 一票否决） | 根颈是否松动 | | **trunk** | - | Object | 是 | 对应“主干部位”折叠面板 | 主干评估指标组 | | | **woodDamage** | Integer | 是 | `0`（无）, `5`（<10%）, `12`（10%-30%）, `20`（30%-50%）, `70`（>=50% 一票否决） | 主干木质部受损 | | | **tilt** | Integer | 是 | `0`（<10°）, `3`（10°-20°）, `8`（20°-30°）, `70`（>=30° 一票否决） | 主干倾斜度 | | | **barkDamage** | Integer | 是 | `0`（<10%）, `1`（10%-30%）, `3`（30%-50%）, `5`（>=50%） | 主干树皮受损 | | **crown** | - | Object | 是 | 对应“树冠部位”折叠面板 | 树冠评估指标组 | | | **looseBranch** | Integer | 是 | `0`（无易落枝）, `2`（占比<1/10）, `3`（占比>=1/10） | 观察是否存在易落枝 | | | **collarAbnormal** | Integer | 是 | `0`（无异常）, `3`（龟裂/卷皮）, `5`（腐烂尚未成洞）, `70`（空洞/蛀干 一票否决） | 枝干结合部异常 | | | **ventilationBalance**| Integer | 是 | `0`（好不偏冠）, `1`（偏冠或透风差不偏冠）, `2`（偏冠冠幅适中）, `5`（透风差冠幅大不偏冠）, `8`（透风差大且偏冠） | 树冠透风与平衡性 | | **weight** | - | Object | 是 | 对应“权重因子评估”面板 | 生理与生境权重因子组 | | | **treeSpeciesType** | String | 是 | `"深根性树种"`, `"浅根性树种"` | 树种类型 (深根性1.0 / 浅根性1.1) | | | **plantingYears** | String | 是 | `"栽植 10 年以内"`, `"栽植 10-30 年"`, `"栽植 30 年以上"` | 栽植年限 (对应 1.0, 1.1, 1.2) | | | **isWindCorridor** | Boolean | 是 | `true`（是）, `false`（否） | 是否处于风口 (对应权重 2.0 / 1.0) | | | **treePoolType** | String | 是 | `"联通树池"`, `"独立树池"`, `"树池硬化"` | 树池类型 (对应 1.0, 1.2, 1.5) | | | **treePoolWidthDbhRatio**| String| 是 | `"7 倍及以上"`, `"5 倍-7 倍"`, `"3 倍-5 倍"`, `"3 倍以下"` | 树池宽胸径比 (对应 1.0-1.3) | | **result** | - | Object | 是 | 对应“风险评估结果”面板 | 风险评估结果表单项 | | | **isEmergency** | Boolean | 是 | `true`（是）, `false`（否） | 是否展开应急评估 | | | **windPower** | String | 否 | `"7 级及以下"`, `"8-9 级"`, `"10 级"`, `"10 级以上"` | 极端风力等级（`isEmergency`为`true`时必填） | | | **defectScore** | Integer | 否 | 输入缺陷总分，如 `9` （若前端已计算则优先以前端为准） | 缺陷总得分 | | | **normalResult** | Object | 否 | 常规风险评估计算结果对象 | 常规安全评估结果组 | | | **normalResult.score**| Double | 否 | 常规安全评估得分，如 `10.89` | 常规安全得分 | | | **normalResult.level**| String | 否 | 常规安全风险等级，如 `"II级 (轻度风险)"` | 常规风险等级 | | | **emergencyResult**| Object | 否 | 应急风险评估计算结果对象 | 应急安全评估结果组 | | | **emergencyResult.score**| Double| 否 | 应急安全评估得分，如 `16.34` | 应急安全得分 | | | **emergencyResult.level**| String| 否 | 应急安全风险等级，如 `"II级 (轻度风险)"` | 应急风险等级 | | **status** | - | Object | 是 | 对应“现状及处理措施”面板 | 现状及处理措施数据组 | | | **photos** | List | 否 | 数组，最多 5 个图片 URL，超过 5 个会报错拦截 | 现场采集照片 (限制最多5张) | ### 请求示例 JSON ```json { "treeId": 1024, "inspectionTime": "2026-05-26 13:17:00", "root": { "disease": 0, "anchorage": 0, "cutting": 0 }, "collar": { "woodDamage": 5, "barkDamage": 0, "loosening": 0 }, "trunk": { "woodDamage": 0, "tilt": 3, "barkDamage": 0 }, "crown": { "looseBranch": 0, "collarAbnormal": 0, "ventilationBalance": 1 }, "weight": { "treeSpeciesType": "深根性树种", "plantingYears": "栽植 10-30 年", "isWindCorridor": false, "treePoolType": "联通树池", "treePoolWidthDbhRatio": "5 倍（含）-7 倍（不含）" }, "result": { "isEmergency": true, "windPower": "8-9 级", "defectScore": 9, "normalResult": { "score": 10.89, "level": "II级 (轻度风险)" }, "emergencyResult": { "score": 16.34, "level": "II级 (轻度风险)" } }, "status": { "photos": [ "https://example.com/images/tree_whole.jpg", "https://example.com/images/tree_detail1.jpg" ] } } ``` ### 响应示例 JSON ```json { "code": 0, "data": 12, "msg": "" } ``` *(注：返回的 `data` 值为新建的巡检评估记录 ID。)* --- ## 2. 获得层级嵌套的巡检记录详情 进入巡检历史记录详情页（图2）时，获取该记录所有计算指标及打分结果。该接口返回完全**层次分明、与表单高度对称的结构**，并额外输出每项计算的权重常数、各分类得分与最终安全等级描述。 * **接口路径**：`GET /get` * **请求方法**：`GET` * **请求参数**： | 参数名 | 类型 | 是否必填 | 说明 | | :--- | :--- | :--- | :--- | | **id** | Long | 是 | 巡检记录 ID，例如 `12` | ### 响应示例 JSON ```json { "code": 0, "data": { "id": 12, "treeId": 1024, "treenumber": "D0001-P1-0001", "inspectionTime": "2026-05-26 13:17:00", "inspectorId": 10001, "inspectorName": "张三", "root": { "disease": 0, "anchorage": 0, "cutting": 0 }, "collar": { "woodDamage": 5, "barkDamage": 0, "loosening": 0 }, "trunk": { "woodDamage": 0, "tilt": 3, "barkDamage": 0 }, "crown": { "looseBranch": 0, "collarAbnormal": 0, "ventilationBalance": 1 }, "weight": { "treeSpeciesType": "深根性树种", "treeSpeciesWeight": 1.0, "plantingYears": "栽植 10-30 年", "plantingYearsWeight": 1.1, "isWindCorridor": false, "windCorridorWeight": 1.0, "treePoolType": "联通树池", "treePoolWeight": 1.0, "treePoolWidthDbhRatio": "5 倍（含）-7 倍（不含）", "treePoolRatioWeight": 1.1 }, "result": { "isEmergency": true, "windPower": "8-9 级", "windPowerWeight": 1.5, "defectScore": 9, "normalResult": { "score": 10.89, "level": "II级 (轻度风险)" }, "emergencyResult": { "score": 16.34, "level": "II级 (轻度风险)" } }, "status": { "photos": [ "https://example.com/images/tree_whole.jpg", "https://example.com/images/tree_detail1.jpg" ] } }, "msg": "" } ``` --- ## 3. 分页查询单株树木的历史巡检记录 对应“巡检记录列表”原型图（图1），按历史巡检时间倒序分页加载。 * **接口路径**：`GET /page` * **请求方法**：`GET` * **请求参数**： | 参数名 | 类型 | 是否必填 | 示例值 | 说明 | | :--- | :--- | :--- | :--- | :--- | | **treeId** | Long | 是 | `1024` | 对应树木档案 ID | | **pageNo** | Integer | 否 | `1` | 页码，从 1 开始 | | **pageSize** | Integer | 否 | `10` | 每页行数 | ### 响应示例 JSON ```json { "code": 0, "data": { "list": [ { "id": 12, "treeId": 1024, "treenumber": "D0001-P1-0001", "inspectionTime": "2026-05-26 13:17:00", "inspectorName": "张三", "normalLevel": "II级 (轻度风险)", "emergencyLevel": "II级 (轻度风险)", "isEmergency": true, "isTreated": false }, { "id": 2, "treeId": 1024, "treenumber": "D0001-P1-0001", "inspectionTime": "2026-05-06 13:23:23", "inspectorName": "李四", "normalLevel": "I级 (基本无风险)", "emergencyLevel": null, "isEmergency": false, "isTreated": true } ], "total": 2 }, "msg": "" } ``` --- ## 3. 管理后台 - 行道树巡检与风险评估接口 管理后台的“巡检记录”页签（如图所示）包含“巡检历史列表（左侧）”和“单条巡检详情面板（右侧）”。这两个功能可以直接调用本组管理后台 API： * **接口基地址**：`/admin-api/garden/tree-inspection` * **权限标识**：`garden:tree-inspection:query`（需在管理后台的角色权限中进行配置） ### 3.1 获得单条巡检评估详情 对应管理后台点击左侧列表时，右侧展示的全部缺陷分、常规评估、应急评估以及现场照片（右侧详情面板）。 * **接口路径**：`GET /get` * **请求方法**：`GET` * **请求参数**：同小程序端，根据主键 `id` 检索。 * **返回 JSON 结构**：与小程序端 `GET /get` 的响应示例格式**完全一致**。返回分层嵌套的 7 大模块，高度契合后台页面树根、根颈、主干、树冠、权重评估、风险评估结果、现状及照片的区块设计。 ### 3.2 分页查询单株树木的历史巡检记录 对应管理后台中左侧用于折叠展示的多次巡检历史简要列表。 * **接口路径**：`GET /page` * **请求方法**：`GET` * **请求参数**：同小程序端 `GET /page`，按 `treeId` 进行分页拉取。 * **返回 JSON 结构**：与小程序端 `GET /page` 的响应示例格式**完全一致**，按巡检时间由近及远倒序排列。 --- ## 常见错误返回状态码 | HTTP状态码 / code 码 | 错误提示内容 | 触发原因 | | :--- | :--- | :--- | | 400 | `status.photos: 最多只能上传5张现场照片` | 现场采集照片 `photos` 数组长度大于 5 时级联强校验报错 | | 400 | `treeId: 关联树木ID不能为空` | 请求体中缺失 `treeId` | | 400 | `inspectionTime: 巡检时间不能为空` | 请求体中缺失 `inspectionTime` | | 403 | `Forbidden` | 管理后台用户未被授权 `garden:tree-inspection:query` 权限 | | 500 / `1-100-008-001` | `巡检评估记录不存在` | 查询详情时 ID 在数据库中被标记删除或不存在 |