docs(specs): 新增现场勘察业务相关 spec 文档

- rework-survey-equipment-tree：勘察设备树明细模式重构 - fix-equipment-topology-display：设备拓扑图完整显示修复 - survey-detail-building-select：勘察明细所属建筑下拉 - generate-floor-options-from-building：按建筑楼层生成楼层下拉 - survey-progress-track-detail：进度跟踪跳转勘察明细页 - survey-complete-to-tech-review：勘察完成提交技术复核与复核按钮改名
2026-10-25 02:34:18 +08:00
1 parent dff366a823
commit 7c915f8946
@@ -0,0 +1,34 @@
+# Checklist
+
+## 数据层变更
+- [x] `customer_equipment` 迁移包含 `parent_id`（自引用）与索引，幂等可重跑
+- [x] `survey_detail` 迁移包含 `equip_id`（关联 customer_equipment）与索引
+- [x] `equip_type` 注释/文档/枚举包含「配电柜」
+- [x] `db_init.sql` 与 `系统设计/表结构新增及变更.md` 已同步
+
+## 后端能力
+- [x] `customer_equipment` 实体含 `parentId`，`survey_detail` 实体含 `equipId`
+- [x] `GET /api/customer-equipments/tree` 返回按 parent_id 组装的嵌套树，权限过滤与 list 一致
+- [x] create/update 支持 `parentId` 且校验父设备同客户、非自身/子节点（防循环）
+- [x] `saveDetails` 接收 `equipId` 并校验设备属于工单客户；DTO 校验对齐
+- [x] 工单详情接口返回设备树数据（供拓扑图渲染）
+
+## 前端：向导迁移与两步化
+- [x] 新建向导路由迁移至 `/customer/visit/survey/create`，旧 `/dispatch/survey/create` 移除
+- [x] 向导为 2 步（基本信息 / 指派电工与服务报酬），无「勘察明细」步骤，提交不含 details
+- [x] 台账页头无「发起勘察派单」按钮，访问 `/dispatch/survey?customerId=xx` 不再自动跳转
+- [x] 客户拜访「一键发起勘察派单」直跳新向导路由并预填客户
+- [x] 台账行操作「更多」含「勘察明细」菜单项，跳 `/dispatch/survey/:id/details`
+
+## 前端：勘察明细页面与拓扑图
+- [x] `/dispatch/survey/:id/details` 页面：左侧设备树渲染正确（调 tree 接口）
+- [x] 支持新增/编辑/删除设备，父节点可选，类型含「配电柜」
+- [x] 设备节点照片/备注保存走 `saveDetails`（equipId + photos + remark）且成功后树/明细刷新
+- [x] 台账详情弹窗按拓扑图展示勘察明细（节点带照片/备注），无数据时空态
+- [x] 设备管理台账 `equipTypeOptions` 含「配电柜」，支持父设备选择
+
+## 验证
+- [x] server 编译通过、client 构建通过
+- [x] 接口实测通过（tree、saveDetails、create 带 parentId）
+- [x] 浏览器端到端验证通过（发起派单 → 两步向导；台账明细页 → 设备树维护；详情拓扑图）
+- [x] 生产库迁移已应用（经确认后）
@@ -0,0 +1,90 @@
+# 勘察派单重构：设备树形化 + 向导迁移 + 勘察明细页面 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**: 明细维护通过台账「更多 → 勘察明细」进入新页面完成。
@@ -0,0 +1,50 @@
+# Tasks
+
+## 数据层变更
+- [x] Task 1: DB 表结构变更（树形化 + 配电柜 + 明细关联设备）
+  - [x] 1.1 新增 `database/migrations/2026xxxx_survey_equipment_tree.sql`：`customer_equipment` 增 `parent_id BIGINT REFERENCES customer_equipment(id)` + 索引；`survey_detail` 增 `equip_id BIGINT REFERENCES customer_equipment(id)` + 索引；更新 `equip_type` 注释含「配电柜」；幂等可重跑
+  - [x] 1.2 同步 `database/db_init.sql` 的建表语句与注释
+  - [x] 1.3 更新 `server/src/entity/customer_equipment.entity.ts`（加 parentId 列）与 `server/src/entity/survey_detail.entity.ts`（加 equipId 列）
+  - [x] 1.4 同步设计文档 `系统设计/表结构新增及变更.md`
+
+## 后端能力
+- [x] Task 2: customer_equipment 树接口与父级校验
+  - [x] 2.1 `customer_equipment.service.ts`：create/update 支持 `parentId`，校验父设备存在、同属客户、非自身/非子节点（防循环）；新增 `tree(customerId)` 组装嵌套树，权限过滤与 list 一致
+  - [x] 2.2 `customer_equipment.controller.ts`：注册 `GET /api/customer-equipments/tree`（置于 `/:id` 之前）
+- [x] Task 3: survey_detail 关联设备 + 详情返回设备树
+  - [x] 3.1 `survey_order.service.ts` 的 `saveDetails` 接收 `equipId`，校验设备属于该工单客户，全量替换明细
+  - [x] 3.2 详情接口返回时附带该工单的设备树数据（供拓扑图渲染）
+  - [x] 3.3 `dto/survey_order.dto.ts` 增加/调整明细校验（equipId 必填、photos/remark 约束）
+
+## 前端：向导迁移与两步化
+- [x] Task 4: 向导路由迁移 + 两步化 + 台账入口收敛（可并行，但依赖路由与表单同改）
+  - [x] 4.1 `router/index.ts`：新增 `/customer/visit/survey/create`（meta 父级=客户拜访），移除 `/dispatch/survey/create`；保留 `/dispatch/survey/edit/:id`
+  - [x] 4.2 `views/dispatch/survey/form.vue`：STEPS 改 2 步，删除第2步「勘察明细」区块与明细表单/`buildDetails`，提交不再携带 details
+  - [x] 4.3 `views/customer/visit/index.vue`：`handleSurvey` 直跳 `/customer/visit/survey/create?customerId=xx`
+  - [x] 4.4 `views/dispatch/survey/index.vue`：移除页头「发起勘察派单」按钮（handleAdd）与 onMounted 的 `?customerId` 自动跳转；行操作「更多」新增「勘察明细」菜单项（跳 `/dispatch/survey/:id/details`）
+
+## 前端：勘察明细页面（新）
+- [x] Task 5: 新建勘察明细页 `views/dispatch/survey/detail.vue`（参考空间拓扑与用电架构模式）
+  - [x] 5.1 左侧设备树：调用 `GET /customer-equipments/tree?customerId=` 渲染树
+  - [x] 5.2 中间拓扑图 + 右侧节点属性：设备详情、照片/备注维护（保存走 `saveDetails(id, [{equipId, photos, remark}])`）
+  - [x] 5.3 新增/编辑/删除设备：支持选择父节点、设备类型含「配电柜」；新增接口带 parentId
+  - [x] 5.4 路由 `/dispatch/survey/:id/details` 注册；如缺 `api/customerEquipment.ts` 则补齐 tree/CRUD API
+- [x] Task 6: 台账详情拓扑图
+  - [x] 6.1 `views/dispatch/survey/index.vue` 详情弹窗：新增拓扑图区块，按设备树渲染勘察明细（节点带照片/备注），无数据时给空态
+- [x] Task 7: 设备管理台账类型扩展
+  - [x] 7.1 `views/device/equipment/index.vue`：`equipTypeOptions` 增加「配电柜」；设备新增/编辑表单支持选择父设备（parentId）
+
+## 验证
+- [x] Task 8: 编译 + 接口 + 浏览器端到端验证
+  - [x] 8.1 `server` 编译通过；`client` 构建通过
+  - [x] 8.2 接口实测：tree 接口、带 equipId 的 saveDetails、create 带 parentId
+  - [x] 8.3 浏览器验证：客户拜访发起派单直跳两步向导；台账无发起按钮、行内「勘察明细」进入新页并新增/维护设备；详情弹窗拓扑图正确显示
+  - [x] 8.4 生产库应用迁移（经确认后）
+
+# Task Dependencies
+- Task 2 依赖 Task 1（表结构/实体先行）
+- Task 3 依赖 Task 1（survey_detail 实体加列）
+- Task 4 依赖 Task 1（后端不动，可并行；路由与表单同批改动）
+- Task 5 依赖 Task 2、3（tree 接口、saveDetails equipId）
+- Task 6 依赖 Task 3（详情返回设备树）
+- Task 8 依赖全部 Task