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

> 更新日期：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`

请求体新增字段：

```json
{
  "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}`

响应新增字段：

```json
{
  "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` 对象变更：

```json
{
  "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": "1",
    "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 | **是** | 树种类型字典值：`"1"` (深根性树种) 或 `"2"` (浅根性树种) |
| `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` 对象新增字段：

```json
{
  "code": 0,
  "data": {
    "id": 100,
    "treeId": 1024,
    "inspectionTime": "2026-06-05 14:30:00",
    "weight": {
      "treeSpeciesType": "1",
      "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 |

**响应**：

```json
{
  "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": "1",
      "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`。

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

---

## 四、前端改造要点清单

### 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`，若有数据则预填表单

---

## 五、注意事项

1. `estimationtreeage` 和 `plantingYears` 字段虽然废弃但**后端仍保留兼容**，前端可以分阶段迁移
2. 巡检提交接口、一树一档案以及历史变更记录中的 `treeSpeciesType` 均已统一使用**字典值**（`"1"`=深根性，`"2"`=浅根性），读取接口也同样输出该字典值。
3. `plantingDate` 格式必须严格为 `yyyy-MM`（如 `"2015-06"`），否则后端解析会失败并降级处理
4. `/latest` 接口返回 `data` 为 `null` 时表示无历史巡检记录，前端应展示空表单