andyesfly
f72644c24f
新增客户用电回路表及相关数据库迁移、后端服务、控制器、DTO、实体类和权限配置；新增前端API封装，同时调整路由名称以匹配新业务模块，复用现有菜单权限避免403错误。
8.8 KiB
空间拓扑与用电架构 · 实现计划
Context（为什么做）
现有「空间拓扑与用电架构」页面（client/src/views/customer/topology/index.vue）只实现了「客户 → 建筑 → 房间」三层树 + 建筑/房间增删改，"用电架构"部分完全缺失：数据库与后端没有任何承载"用电回路"的表或接口，页面上也没有配电拓扑可视化。
设计稿 系统设计/UI/空间拓扑与用电架构/code.html 定义了三栏工业级布局（左空间树 / 中配电单线拓扑流 / 右节点属性面板）。本次目标：在新表 + 新后端接口的基础上，把该页面补齐为三栏结构，让"空间"与"用电回路"打通。
已确认的边界（用户决策）
| 项 | 结论 |
|---|---|
| 目标形态 | 按设计稿做完整三栏（左树 / 中单线图 / 右属性面板） |
| 左树层级 | 客户 → 建筑 → 楼层 → 房间 → 回路（不要"配电箱"层） |
| 楼层 | 由房间/回路按 floor_no 分组生成的虚拟层，不建表 |
| 中间图上层 | 进线柜 / 变压器：只读展示，不落库、不做 CRUD |
| 中间图末端 | 回路卡片（一个回路一张卡） |
| 实时电气量 | 电压/电流/功率/温度等一律占位（显示 —），不造假数据、不接采集 |
| ICC 映射 | 不做（设计稿里的网关层、ICC 设备码、告警阈值联动均不实现） |
| 覆盖端 | 仅 Web 管理端 client/ |
| 数据来源 | 新建表 + 后端 CRUD 接口 |
数据模型（新增 1 张表）
customer_circuit（客户用电回路）—— 参照 customer_room 的建表风格（database/db_init.sql#L364-L387）：
| 字段 | 类型 | 说明 |
|---|---|---|
| id | BIGSERIAL PK | |
| customer_id | BIGINT NOT NULL | → customer(id) |
| building_id | BIGINT NOT NULL | → customer_building(id) |
| room_id | BIGINT NULL | → customer_room(id)，允许挂建筑/楼层而不挂房间 |
| floor_no | VARCHAR(16) | 楼层（冗余，便于按楼层分组） |
| circuit_code | VARCHAR(64) NOT NULL | 回路编号，全局唯一 |
| circuit_name | VARCHAR(128) NOT NULL | 回路名称 |
| loop_spec | VARCHAR(128) | 回路规格（如 三相380V / 铜芯4×25+1×16） |
| load_type | VARCHAR(32) | 负荷类型（照明/动力/空调/插座…） |
| rated_voltage | VARCHAR(32) | 额定电压（配置值） |
| rated_current | VARCHAR(32) | 额定电流（配置值） |
| rated_power | NUMERIC(10,2) | 额定功率 kW（配置值） |
| status | SMALLINT DEFAULT 1 | 1 正常 / 0 停用 |
| remark | TEXT | 备注 |
| sort_order | INT DEFAULT 0 | 排序 |
| created_at | TIMESTAMP |
索引：customer_id、building_id、room_id、唯一键 circuit_code。
命名跟随现有习惯：表
customer_circuit、entityCustomerCircuit、路由/api/customer-circuits、权限码customer:circuit（与customer:building/customer:room同级）。
后端改动（Midway.js + sequelize-typescript）
参照样板：customer_room 全链路。
-
迁移：
database/migrations/20261011_customer_circuit.sql（幂等CREATE TABLE IF NOT EXISTS），并在database/db_init.sql同步该表定义。 -
Entity：
server/src/entity/customer_circuit.entity.ts（照抄customer_building.entity.ts的@Table/@Column/@BelongsTo/@CreatedAt写法）。 -
DTO：
server/src/dto/customer_circuit.dto.ts（Query/Create/Update，class-validator 风格照抄customer_room.dto.ts）。 -
Service：
server/src/service/customer_circuit.service.ts-
list/detail/create/update/delete（照抄customer_room.service.ts，统一返回{ code, message, data }）。 -
topology(customerId)：一次请求返回整棵「建筑 → 楼层 → 房间 → 回路」结构，避免前端 N+1（现有页面是逐建筑拉房间）。返回形如：{ "buildings": [ { "id":1, "buildingName":"…", "floors":[ { "floorNo":"2", "rooms":[ { "id":9, "roomName":"…", "circuits":[…] } ], "circuits":[…] } ] } ] }
-
-
Controller：
server/src/controller/customer_circuit.controller.ts（@Controller("/api/customer-circuits")，含GET /topology）。 -
权限注册：
server/src/middleware/rbac.middleware.ts的PERMISSION_MAP新增"/api/customer-circuits": "customer:circuit"。 -
菜单/权限种子：在
database/db_seed.sql复用现有「空间拓扑与用电架构」菜单（id=32,/customer/topology, 权限码customer:topology），并参照customer:room的登记方式新增按钮级权限customer:circuit。
前端改动（Vue3 + Ant Design Vue）
-
新增 API 封装
client/src/api/customerCircuit.ts：照抄customerRoom.ts风格（getList/getDetail/create/update/delete/getTopology+ 类型定义 + 常量：负荷类型选项）。 -
重写
client/src/views/customer/topology/index.vue为三栏：-
顶部：面包屑 + 客户切换器 + 指标条 + 「新增回路」按钮。指标只展示可由现有数据算出的项（已接入建筑数、监测用电回路数、空间建模覆盖率 = 有回路的房间数/房间总数）；无数据源的项（变电所/配电室、ICC 边缘网关）不展示。
-
左栏（≈280px）：
a-tree渲染「客户 → 建筑 → 楼层 → 房间 → 回路」；节点徽章显示回路数；节点悬停操作：建筑/房间沿用现有增删改（customerBuildingApi/customerRoomApi），回路可新增/编辑/删除。 -
中栏：单线图。上层为只读示意（10kV 进线柜 → 变压器 → 低压母线，按客户/建筑信息填充文案）、下层为回路卡片网格（编号/名称/所属房间/规格/额定参数，点击选中；实时电气量显示
—）。用 div 网格 + 内联 SVG 母线渲染（与设计稿一致），不引入新依赖（echarts 已在依赖中但不必要）。 -
右栏（≈320px）：选中节点的属性面板（回路基本信息可编辑并保存；房间/建筑节点展示只读属性）。
-
样式沿用页面既有基线：背景
#eef3f8、主色#0054cd、卡片圆角12px、等宽字体用Consolas/Menlo。
-
-
路由/权限：沿用现有
customer/topology路由与customer:topology菜单，不新增页面路由。
不做（明确排除）
-
ICC 网关节点、ICC 设备码映射、告警阈值联动、下发同步
-
实时电气量采集与展示（一律
—） -
「从 ICC 同步拓扑」「CAD/BIM 导入」「导出高清拓扑图」按钮 → 先不实现（可留占位，若留则点击提示"暂未开放"）
-
「空间三维映射」视图切换
-
配电箱/配电柜层
-
Flutter 管理端
假设（如不认可请指出）
- 中间图的上层（进线柜/变压器）纯前端静态示意，文案按所选客户/建筑动态填充，不落库。
circuit_code全局唯一（与设备台账equip_code一致）；若你希望"客户内唯一"，需改唯一约束。- 回路可以不挂房间（只挂建筑+楼层），以适应公共区域回路。
- 顶部指标只做能算出来的 3 项，其余留白而非显示假数据。
验证方式
-
执行迁移：
database/migrations/20261011_customer_circuit.sql（以及 db_seed 的权限登记），确认表与权限数据落库。 -
后端：启动
server/，用带 token 的请求验证GET /api/customer-circuits/topology?customerId=1、以及 create/update/delete；无 token 应 401、无权限应 403。 -
前端：
client/执行npm run check（vue-tsc）通过；npm run dev后进入「客户管理 → 空间拓扑与用电架构」：-
选客户 → 左树按「建筑 → 楼层 → 房间 → 回路」正确展开；
-
新增/编辑/删除回路后树与中间卡片同步刷新；
-
点击回路卡片 → 右栏属性正确回填、可保存；
-
中间图上层的进线柜/变压器为只读示意。
-
-
回归：确认原有建筑/房间增删改仍可用（房间功能未被破坏）。