docs/%E5%9F%8E%E5%B8%82%E9%83%A8%E4%BB%B6-%E5%8A%9F%E8%83%BD%E8%AE%BE%E8%AE%A1%E6%96%B9%E6%A1%88.md

# 城市部件 — 功能设计方案
> 基于「西单项目一物一码模型命名规则」设计。资产 ID 编码规则参考西单北大街一物一码属性信息表。
---
## 一、菜单结构
```
城市部件（一级目录）
├── 城市部件类型（二级菜单）
│   ├── 查询   garden:city-component-type:query
│   ├── 新增   garden:city-component-type:create
│   ├── 修改   garden:city-component-type:update
│   └── 删除   garden:city-component-type:delete
└── 城市部件管理（二级菜单）
    ├── 查询   garden:city-component:query
    ├── 新增   garden:city-component:create
    ├── 修改   garden:city-component:update
    ├── 删除   garden:city-component:delete
    └── 导出   garden:city-component:export
```
---
## 二、部件编码规则（一物一码）
### 2.1 资产 ID 格式
```
{城市代码}{城区代码}{街道代码}_{道路编码}_{类型编码}_{顺序号}
```
**示例**：`110102001_02_0211_0001`
| 段 | 值 | 含义 |
|----|-----|------|
| 110 | 北京市 | 城市代码 |
| 102 | 西城区 | 城区代码 |
| 001 | 西长安街街道 | 街道代码 |
| 02 | 西单北大街 | 道路编码 |
| 0211 | 公共设施>照明灯>路灯 | 三级类型编码 |
| 0001 | 第1个 | 顺序号（4位，同前缀递增） |
### 2.2 类型编码层级规则
| 层级 | 位数 | 示例 | 规则 |
|------|------|------|------|
| 一级 | 2位 | `02` | 公共设施要素 |
| 二级 | 3位 | `021` | 照明灯 = 一级编码 `02` + 序号 `1` |
| 三级 | 4位 | `0211` | 路灯 = 二级编码 `021` + 序号 `1` |
### 2.3 一级分类（来自命名规则）
| 编码 | 名称 |
|------|------|
| 01 | 建筑要素 |
| 02 | 公共设施要素 |
| 03 | 园林绿化要素 |
| 04 | 道路交通要素 |
### 2.4 二级/三级分类示例（公共设施要素 `02` 下）
| 二级编码 | 二级名称 | 三级编码 | 三级名称 |
|----------|----------|----------|----------|
| 021 | 照明灯 | 0211 | 路灯 |
| | | 0212 | 投光灯 |
| 022 | 摄像头 | 0221 | 球机 |
| | | 0222 | 枪机 |
| | | 0223 | 半球 |
| 023 | 井盖 | 0231 | 电力 |
| | | 0232 | 污水 |
| | | ... | ... |
| 024 | 宣传栏 | 0241 | 立式 |
| | | 0242 | 壁挂式 |
| 025 | 垃圾桶 | 0251 | 单桶 |
| | | 0252 | 双桶 |
| 026 | 下水道口 | 0261 | 平篦 |
| | | 0262 | 立篦 |
| 027 | 路障 | 0271 | 隔离墩 |
| | | 0272 | 防撞桶 |
| 028 | 变电箱 | 0281 | 配电箱 |
| | | 0282 | 变电箱 |
| | | 0283 | 控制箱 |
| 029 | 街道家具 | 0291 | 座椅 |
| | | 0292 | 花箱 |
| | | ... | ... |
---
## 三、数据库设计
### 3.1 城市部件类型表 `garden_city_component_type`
| 字段 | 类型 | 说明 |
|------|------|------|
| id | bigint PK | 主键 |
| type_code | varchar(32) UNIQUE | 类型编码（2/3/4位数字，如 02、021、0211） |
| type_name | varchar(64) | 类型名称 |
| level | tinyint | 1=一级(2位), 2=二级(3位), 3=三级(4位) |
| parent_code | varchar(32) | 父级编码（一级为 NULL） |
| sort | int | 排序 |
| status | tinyint | 1启用 0禁用 |
| remark | varchar(512) | 备注 |
| + 通用字段 | — | creator/create_time/updater/update_time/deleted/tenant_id |
**编码生成规则**：
- 一级：`{01..99}`，取当前最大一级编码+1（如已有 01~04，新增为 05）
- 二级：`{父级编码}{1..9}`，如父级 `02`，取当前最大二级序号+1
- 三级：`{父级编码}{1..9}`，如父级 `021`，取当前最大三级序号+1
### 3.2 城市部件管理表 `garden_city_component`
| 字段分组 | 字段 | 类型 | 说明 |
|----------|------|------|------|
| **编码** | component_code | varchar(64) UNIQUE | 资产 ID（一物一码） |
| **类型** | level_one_type_code | varchar(32) | 一级类型编码 |
| | level_one_type_name | varchar(64) | 一级类型名称（冗余） |
| | level_two_type_code | varchar(32) | 二级类型编码 |
| | level_two_type_name | varchar(64) | 二级类型名称（冗余） |
| | level_three_type_code | varchar(32) | 三级类型编码 |
| | level_three_type_name | varchar(64) | 三级类型名称（冗余） |
| **行政区划** | city_code | varchar(16) | 城市代码 |
| | district_code | varchar(16) | 城区代码 |
| | street_code | varchar(16) | 街道代码 |
| **位置** | area | varchar(128) | 所属区域 |
| | road_code | varchar(16) | 道路编码 |
| | road_name | varchar(128) | 道路名称 |
| | x_coord | decimal(12,8) | X（WGS84 经度） |
| | y_coord | decimal(12,8) | Y（WGS84 纬度） |
| | z_coord | decimal(10,4) | Z（高程） |
| | longitude_amap | decimal(12,8) | 高德经度（GCJ02，自动转换） |
| | latitude_amap | decimal(12,8) | 高德纬度（GCJ02，自动转换） |
| | install_orientation | varchar(32) | 安装方位（人行道/车行道/绿化带） |
| | grid | varchar(128) | 所属网格 |
| **设备** | brand | varchar(128) | 品牌/厂家 |
| | model_spec | varchar(128) | 型号规格 |
| | material | varchar(64) | 材质 |
| | length/width/height | decimal(10,2) | 长/宽/高(cm) |
| | dbh | decimal(10,2) | 胸径(cm，树木专用) |
| **生命周期** | install_date | date | 安装/种植时间 |
| | asset_status | varchar(32) | 资产状态 |
| | management_unit | varchar(128) | 管理单位 |
| | responsible_person | varchar(64) | 责任人 |
| | service_years | decimal(4,1) | 投入年限 |
| | maintenance_deadline | date | 维保到期日 |
| | procurement_batch | varchar(128) | 采购批次/项目名称 |
| **巡检** | inspection_cycle | varchar(32) | 巡检周期（日/周/月/季） |
| | last_inspection_time | datetime | 最近巡检时间 |
| | inspector | varchar(64) | 巡检人员 |
| | inspection_result | varchar(32) | 巡检结果（正常/异常/损坏/丢失） |
| | abnormal_description | varchar(512) | 异常描述 |
| **维修** | repair_order_no | varchar(64) | 报修工单编号 |
| | repair_complete_time | datetime | 维修完成时间 |
| | repair_unit | varchar(128) | 维修单位 |
| **其他** | remark | varchar(512) | 备注 |
| | qr_code_url | varchar(512) | 二维码 URL |
| **通用** | — | — | creator/create_time/updater/update_time/deleted/tenant_id |
---
## 四、后端接口
### 4.1 城市部件类型
| 方法 | URL | 说明 |
|------|-----|------|
| POST | `/garden/city-component-type/create` | 新增 |
| PUT | `/garden/city-component-type/update` | 修改 |
| DELETE | `/garden/city-component-type/delete?id=` | 删除 |
| GET | `/garden/city-component-type/get?id=` | 详情 |
| GET | `/garden/city-component-type/page` | 分页列表（级联筛选） |
| GET | `/garden/city-component-type/list-by-parent` | 按父级查子级 |
| GET | `/garden/city-component-type/generate-next-code` | 生成下级编码 |
| GET | `/garden/city-component-type/tree` | 完整三级树 |
### 4.2 城市部件管理
| 方法 | URL | 说明 |
|------|-----|------|
| POST | `/garden/city-component/create` | 新增（自动坐标转换） |
| PUT | `/garden/city-component/update` | 修改 |
| DELETE | `/garden/city-component/delete?id=` | 删除 |
| GET | `/garden/city-component/get?id=` | 详情 |
| GET | `/garden/city-component/page` | 分页列表 |
| GET | `/garden/city-component/export-excel` | 导出 Excel |
| GET | `/garden/city-component/generate-qr` | 生成二维码 |
---
## 五、坐标转换
- 复用 `GisCoordinateUtil.wgs84ToGcj02(x, y)` 将 WGS84 转 GCJ02
- create/update 时若 X/Y 有值，自动计算高德经纬度
---
## 六、文件清单
### 后端（garden 模块）
**类型**：`CityComponentTypeDO` / `CityComponentTypeMapper` / `CityComponentTypeService` / `CityComponentTypeServiceImpl` / `CityComponentTypeController` + 3 个 VO
**部件**：`CityComponentDO` / `CityComponentMapper` / `CityComponentService` / `CityComponentServiceImpl` / `CityComponentController` + 4 个 VO
### 前端
**类型**：`src/api/garden/cityComponentType/index.ts` + `src/views/garden/cityComponentType/` (index.vue + form)
**部件**：`src/api/garden/cityComponent/index.ts` + `src/views/garden/cityComponent/` (index.vue + form)
### SQL
- `docs/城市部件-建表SQL.sql`
- `docs/城市部件-菜单SQL.sql`
---
## 七、实现顺序
1. 建表 DDL
2. 城市部件类型后端 + 编译验证
3. 城市部件类型前端
4. 城市部件管理后端 + 编译验证
5. 城市部件管理前端
6. 菜单 SQL
7. 整体验证