# 勘察派单重构：设备树形化 + 向导迁移 + 勘察明细页面 Spec

## Why
现场勘察流程中，客户设备（`customer_equipment`）为扁平结构，无法表达配电层级（配电间→配电箱/井/柜）；勘察明细（`survey_detail` 的建筑/楼层/房间）与客户设备树无关联，台账详情无法按拓扑直观展示。同时勘察派单入口分散（台账"发起勘察派单"按钮 + 客户拜访"一键发起勘察派单"），向导 3 步流程中的"勘察明细"步骤与新设备树维护职责重叠。

## What Changes
- **BREAKING（表结构）**：`customer_equipment` 新增 `parent_id`（自引用树形，支持多级嵌套）；设备类型枚举新增「配电柜」（现有：配电间/配电井/配电箱）。
- **BREAKING（表结构）**：`survey_detail` 新增 `equip_id`（关联 `customer_equipment`），保留 `photos`/`remark` 并挂接到设备节点下；原 building/floor/room 字段保留为可空（兼容历史数据）。
- 勘察派单向导迁至「项目管理 → 客户拜访」，路由 `/customer/visit/survey/create`；向导由 3 步改为 2 步（第1步 勘察基本信息与现场环境；第2步 指派电工与服务报酬），**取消原第2步「勘察明细」**。
- 现场勘察派单台账（`/dispatch/survey`）移除「发起勘察派单」按钮及 `?customerId` 自动跳转逻辑；勘察派单仅能通过客户拜访的「一键发起勘察派单」进入。
- 台账行操作「更多」新增「勘察明细」菜单项，打开新的勘察明细页面 `/dispatch/survey/:id/details`（参考「空间拓扑与用电架构」模式：左侧设备树 + 中间拓扑图 + 右侧节点属性），支持新增客户设备并按树形结构显示。
- 台账「查看详情」弹窗增加按拓扑图（设备树 + 明细附件）形式展示勘察明细数据。

## Impact
- Affected specs: 无（新建 change-id，不与既有 spec 冲突）
- Affected code:
  - DB：`database/db_init.sql`、新增 `database/migrations/2026xxxx_survey_equipment_tree.sql`、`系统设计/表结构新增及变更.md`
  - 后端：`server/src/entity/customer_equipment.entity.ts`、`server/src/entity/survey_detail.entity.ts`、`server/src/service/customer_equipment.service.ts`、`server/src/controller/customer_equipment.controller.ts`、`server/src/service/survey_order.service.ts`、`server/src/dto/survey_order.dto.ts`
  - 前端：`client/src/router/index.ts`、`client/src/views/dispatch/survey/form.vue`、`client/src/views/dispatch/survey/index.vue`、`client/src/views/customer/visit/index.vue`、新增 `client/src/views/dispatch/survey/detail.vue`、`client/src/api/surveyOrder.ts`、`client/src/api/customerEquipment.ts`（如存在）、`client/src/views/device/equipment/index.vue`

## ADDED Requirements

### Requirement: customer_equipment 树形结构
系统 SHALL 为 `customer_equipment` 增加 `parent_id`（自引用，指向同表设备 id，支持多级嵌套），并提供按客户聚合的树接口。

#### Scenario: 获取客户设备树
- **WHEN** 用户调用 `GET /api/customer-equipments/tree?customerId=xx`
- **THEN** 返回该客户下按 parent_id 组装的嵌套树结构（根节点 parent_id 为空），数据权限过滤与现有 list 一致

#### Scenario: 新增子设备
- **WHEN** 用户新建设备并指定 `parentId`
- **THEN** 校验父设备存在、属于同一客户且非自身，创建成功后该设备挂到父节点下

### Requirement: 勘察明细关联设备
系统 SHALL 让 `survey_detail` 通过 `equip_id` 关联 `customer_equipment`，明细照片与备注挂接到设备节点。

#### Scenario: 保存勘察明细
- **WHEN** 用户调用 `PUT /api/survey-orders/:id/details`，明细含 `equipId`、`photos`、`remark`
- **THEN** 校验工单状态、`equipId` 对应的设备属于该工单客户，随后全量替换该工单明细

### Requirement: 勘察明细页面（按拓扑模式）
系统 SHALL 提供勘察明细页面 `/dispatch/survey/:id/details`，参考「空间拓扑与用电架构」：左侧设备树 + 中间拓扑图 + 右侧节点属性，可新增/编辑/删除客户设备并按树显示，设备类型含「配电柜」。

#### Scenario: 新增设备到树
- **WHEN** 用户在勘察明细页新增设备（选择父节点、类型含配电柜）
- **THEN** 调用 `customer_equipment` 创建接口写入设备，树即时刷新

#### Scenario: 维护明细附件
- **WHEN** 用户为设备节点填写照片/备注并保存
- **THEN** 调用 `saveDetails` 保存为 `survey_detail`（equip_id + photos + remark）

### Requirement: 台账详情拓扑图
系统 SHALL 在台账「查看详情」中以拓扑图形式展示勘察明细数据（设备树 + 明细附件）。

#### Scenario: 查看工单详情
- **WHEN** 用户在台账点击工单编号/查看详情
- **THEN** 详情弹窗内渲染设备拓扑图，节点带明细照片与备注信息

## MODIFIED Requirements

### Requirement: 勘察派单向导（迁移 + 两步化）
勘察派单向导 SHALL 从 `/dispatch/survey/create` 迁至 `/customer/visit/survey/create`（父级「客户拜访」，归属项目管理菜单），向导步骤由 3 步改为 2 步：第1步 勘察基本信息与现场环境、第2步 指派电工与服务报酬；原第2步「勘察明细」取消，创建/更新请求不再携带明细数据。

#### Scenario: 从客户拜访发起勘察派单
- **WHEN** 客户拜访列表满足 `canSurvey` 的记录点击「一键发起勘察派单」
- **THEN** 直接跳转 `/customer/visit/survey/create?customerId=xx`，向导预填客户

#### Scenario: 编辑既有工单
- **WHEN** 台账行操作「编辑」打开向导
- **THEN** 走 2 步向导（基本信息 + 电工报酬），不含勘察明细步骤

### Requirement: 台账入口收敛
现场勘察派单台账 SHALL 移除「发起勘察派单」按钮与 `?customerId` 自动跳转；勘察派单仅能从客户拜访发起。行操作「更多」SHALL 新增「勘察明细」入口。

#### Scenario: 台账无新建入口
- **WHEN** 用户打开现场勘察派单台账
- **THEN** 页头无「发起勘察派单」按钮，访问 `/dispatch/survey?customerId=xx` 不再自动跳转新建

### Requirement: 设备类型枚举扩展
`customer_equipment.equip_type` 取值 SHALL 包含 配电间/配电井/配电箱/配电柜；前端设备管理台账选项同步增加「配电柜」。

## REMOVED Requirements

### Requirement: 台账「发起勘察派单」按钮与自动跳转
**Reason**: 勘察派单入口收敛至客户拜访，避免双入口不一致。
**Migration**: 由客户拜访「一键发起勘察派单」承担新建入口（直跳新向导路由）。

### Requirement: 向导第2步「勘察明细」
**Reason**: 勘察明细维护迁移至台账行操作「勘察明细」独立页面（按设备树维护），向导聚焦基本信息与电工指派。
**Migration**: 明细维护通过台账「更多 → 勘察明细」进入新页面完成。