api_document_tree_inspection.md 10.5 KB

Edit Raw Blame History


行道树巡查需求改造 - 前端接口对接文档

更新日期：2026-06-05

后端开发：已完成，编译通过

涉及模块：一树一档案、行道树巡检与风险评估


一、字段变更总览
1.1 一树一档案（garden_tree）


变更类型
字段名
说明


⚠️ 废弃
estimationtreeage
估测树龄，不再使用，保留兼容


✅ 新增
plantingDate
栽种年月，格式 yyyy-MM，如 "2015-06"


✅ 新增
treeSpeciesType
树种类型，字典值，字典类型：tree_species_type


1.2 巡检记录（garden_tree_inspection）


变更类型
字段名
说明


⚠️ 废弃
weight.plantingYears
栽植年限文本选择，不再使用，由系统自动计算


✅ 新增
weight.plantingDate
栽植年月，格式 yyyy-MM，如 "2015-06"


1.3 字典配置


字典类型
字典值
标签


tree_species_type
1
深根性树种


tree_species_type
2
浅根性树种


前端通过通用字典接口获取：GET /garden/common/dict-type?dict_type=tree_species_type


二、一树一档案相关接口变更
2.1 新增/编辑行道树
接口：POST /garden/tree/create 或 PUT /garden/tree/update

请求体新增字段：
{
  "id": 1024,
  "treenumber": "D0001-P1-0001",
  "treetype": "香樟",
  "dbh": "30",

  "plantingDate": "2015-06",
  "treeSpeciesType": "1",

  "estimationtreeage": null
}


字段
类型
必填
说明


plantingDate
String
否
栽种年月，格式 yyyy-MM，替代原 estimationtreeage


treeSpeciesType
String
否
树种类型字典值（1=深根性，2=浅根性）


estimationtreeage
String
否
已废弃，前端应改用 plantingDate


2.2 获取行道树详情
接口：GET /garden/tree/get?id={id}

响应新增字段：
{
  "code": 0,
  "data": {
    "id": 1024,
    "treenumber": "D0001-P1-0001",
    "estimationtreeage": "10",

    "plantingDate": "2015-06",
    "treeSpeciesType": "1",

    "...": "其他字段不变"
  }
}


注意：详情页中原"预估年龄/估测树龄"改为显示"栽种年月"，取 plantingDate 字段值。treeSpeciesType 用字典翻译显示。

2.3 行道树列表分页（PC端）
接口：GET /garden/tree/page

新增查询参数：


参数
类型
说明


treeSpeciesType
String
树种类型筛选，传字典值（1 或 2）


示例：
GET /garden/tree/page?pageNo=1&pageSize=20&treeSpeciesType=1


列表中在"胸径"后面新增"树种类别"展示列，值通过字典翻译。

2.4 一树一档案修改记录
接口：GET /garden/tree-change-log/page?treeid={treeid}

返回数据或请求参数已支持新字段：


请求参数新增：plantingDate (栽种年月), treeSpeciesType (树种类型字典值) 用于过滤检索。
响应对象（TreeChangeLogRespVO）已补齐：


plantingDate: 栽种年月，格式 yyyy-MM
treeSpeciesType: 树种类型字典值


💡 业务说明：当行道树通过“新增/编辑”以及“巡检记录自动回写”时，系统均会自动向修改记录表中插入一条变更快照。


三、巡检记录相关接口变更
3.1 提交巡检记录
接口：POST /garden/tree-inspection/create

weight 对象变更：
{
  "treeId": 1024,
  "inspectionTime": "2026-06-05 14:30:00",
  "root": { "disease": 0, "anchorage": 0, "cutting": 0 },
  "collar": { "woodDamage": 5, "barkDamage": 0, "loosening": 0 },
  "trunk": { "woodDamage": 0, "tilt": 0, "barkDamage": 0 },
  "crown": { "looseBranch": 0, "collarAbnormal": 0, "ventilationBalance": 0 },
  "weight": {
    "treeSpeciesType": "深根性树种",
    "plantingDate": "2015-06",
    "isWindCorridor": false,
    "treePoolType": "联通树池",
    "treePoolWidthDbhRatio": "7 倍及以上"
  },
  "result": {
    "isEmergency": false,
    "windPower": null,
    "defectScore": 5,
    "normalResult": { "score": 5.0, "level": "I级 (基本无风险)" },
    "emergencyResult": null
  },
  "status": {
    "photos": ["https://xxx.com/photo1.jpg"]
  }
}


weight 对象字段说明：


字段
类型
必填
说明


treeSpeciesType
String
是
树种类型文本："深根性树种" 或 "浅根性树种"


plantingDate
String
否
栽植年月，格式 yyyy-MM。填写后系统自动计算年限和权重


plantingYears
String
否
已废弃，无需传入。后端根据 plantingDate 自动计算


isWindCorridor
Boolean
是
是否处于风口


treePoolType
String
是
树池类型


treePoolWidthDbhRatio
String
是
树池宽度与胸径比


后端自动行为：


根据 plantingDate 自动计算栽植年限（10年以内/10-30年/30年以上）和对应权重
提交成功后，自动将 treeSpeciesType 和 plantingDate 回写到一树一档案详情

3.2 获取巡检详情
接口：GET /garden/tree-inspection/get?id={id}

响应 weight 对象新增字段：
{
  "code": 0,
  "data": {
    "id": 100,
    "treeId": 1024,
    "inspectionTime": "2026-06-05 14:30:00",
    "weight": {
      "treeSpeciesType": "深根性树种",
      "treeSpeciesWeight": 1.0,
      "plantingYears": "栽植 10-30 年",
      "plantingYearsWeight": 1.1,
      "plantingDate": "2015-06",
      "isWindCorridor": false,
      "windCorridorWeight": 1.0,
      "treePoolType": "联通树池",
      "treePoolWeight": 1.0,
      "treePoolWidthDbhRatio": "7 倍及以上",
      "treePoolRatioWeight": 1.0
    },
    "...": "其他字段不变"
  }
}


新增字段
类型
说明


weight.plantingDate
String
栽植年月（用户填写的原始值）


weight.plantingYears
String
系统自动计算的栽植年限文本


3.3 ⭐ 获取最近一次巡检记录（新增接口）
接口：GET /garden/tree-inspection/latest?treeId={treeId}

用途：汛期频繁巡检场景，用户提交第一次巡检后，后续每次打开新增界面时调用此接口，自动带入上一次填写记录，用户可修改后再提交。

请求参数：


参数
类型
必填
说明


treeId
Long
是
一树一档案ID


响应：
{
  "code": 0,
  "data": {
    "id": 100,
    "treeId": 1024,
    "treenumber": "D0001-P1-0001",
    "inspectionTime": "2026-06-05 14:30:00",
    "inspectorId": 10001,
    "inspectorName": "张三",
    "root": { "disease": 0, "anchorage": 0, "cutting": 0 },
    "collar": { "woodDamage": 5, "barkDamage": 0, "loosening": 0 },
    "trunk": { "woodDamage": 0, "tilt": 0, "barkDamage": 0 },
    "crown": { "looseBranch": 0, "collarAbnormal": 0, "ventilationBalance": 0 },
    "weight": {
      "treeSpeciesType": "深根性树种",
      "treeSpeciesWeight": 1.0,
      "plantingYears": "栽植 10-30 年",
      "plantingYearsWeight": 1.1,
      "plantingDate": "2015-06",
      "isWindCorridor": false,
      "windCorridorWeight": 1.0,
      "treePoolType": "联通树池",
      "treePoolWeight": 1.0,
      "treePoolWidthDbhRatio": "7 倍及以上",
      "treePoolRatioWeight": 1.0
    },
    "result": {
      "isEmergency": false,
      "windPower": null,
      "windPowerWeight": 1.0,
      "defectScore": 5,
      "normalResult": { "score": 5.0, "level": "I级 (基本无风险)" },
      "emergencyResult": null
    },
    "status": {
      "photos": ["https://xxx.com/photo1.jpg"]
    }
  }
}


特殊情况：如果该树木没有任何巡检记录，data 返回 null。


前端处理逻辑：


用户点击"新增巡检"时，调用 GET /latest?treeId=xxx
如果 data 不为 null，将返回的各字段值预填到表单中（注意不要预填 id、inspectionTime、inspectorId、inspectorName 等系统字段）
用户可在预填基础上修改，最终提交的数据以用户最后修改为准


四、前端改造要点清单
4.1 PC端-行道树新增/编辑页

[ ] "估测年龄"字段 → 改为"栽种年月"，使用年月选择器（yyyy-MM），绑定 plantingDate
[ ] 新增"树种类型"字段，使用下拉选择，数据源为字典 tree_species_type，绑定 treeSpeciesType，必选

4.2 PC端-行道树详情页

[ ] "估测树龄"字段 → 改为显示"栽种年月"，取 plantingDate 值
[ ] 新增"树种类型"展示，treeSpeciesType 通过字典翻译显示

4.3 PC端-行道树列表页

[ ] 检索区域新增"树种类型"筛选项（下拉，数据源为字典 tree_species_type）
[ ] 列表表头在"胸径"后新增"树种类别"列，值通过字典翻译

4.4 PC端-巡检记录展示

[ ] 第13项"该行道树属于什么树种？"展示 weight.treeSpeciesType
[ ] 第14项"该行道树的栽植年限属于哪一种？"改为展示 weight.plantingDate（栽植年月）+ weight.plantingYears（自动计算的年限）

4.5 小程序端-树木详情页

[ ] "预估年龄" → 改为"栽植年月"，取 plantingDate 值
[ ] 非必填项中去掉"请输入"三个字的占位文本

4.6 小程序端-新增行道树录入

[ ] "预估年龄" → 改为"栽种年月"，使用年月选择器，绑定 plantingDate
[ ] 新增"树种类型"选择，字典 tree_species_type

4.7 小程序端-巡检表单

[ ] 第13项"该行道树属于什么树种？"保持单选（深根性/浅根性），绑定 weight.treeSpeciesType
[ ] 第14项"该行道树的栽植年限？"原三选一 → 改为年月选择器，绑定 weight.plantingDate，系统自动显示计算出的年限
[ ] 汛期预填：进入新增巡检页面时，调用 GET /latest?treeId=xxx，若有数据则预填表单


五、注意事项

estimationtreeage 和 plantingYears 字段虽然废弃但后端仍保留兼容，前端可以分阶段迁移
巡检提交接口中 weight.treeSpeciesType 传的是文本（"深根性树种"/"浅根性树种"），不是字典值；而一树一档案中 treeSpeciesType 存的也是相同文本
plantingDate 格式必须严格为 yyyy-MM（如 "2015-06"），否则后端解析会失败并降级处理
/latest 接口返回 data 为 null 时表示无历史巡检记录，前端应展示空表单