smart_grid_iot/.trae/specs/device-management-module/spec.md

设备管理模块 Spec

Why

现有系统仅有 customer_equipment（客户设备台账）和 smart_device（智电设备型号目录）两张数据库表及 /device 占位路由（Placeholder.vue），设备管理功能尚未实现。需依据系统设计文档构建设备管理模块的完整前后端实现，统一安全管理并兼容 APP 调用。

What Changes

• 新增客户设备台账模块：设备 CRUD、按客户关联过滤、展示归属建筑/楼层/位置、设备照片上传。
• 新增智电设备型号目录模块：型号 CRUD、类型字典。
• 新增空间拓扑与用电架构：复用现有 customer/topology 页面，将设备台账按建筑/楼层进行拓扑化展示（前端展示为主，复用现有设备数据接口）。
• 替换 /device 占位路由为真实的设备管理页面入口。
• 后端接口统一 JWT + RBAC 鉴权（覆盖所有设备模块端点），接口保持标准 RESTful JSON（兼容 APP）。
• 安全基线：防 SQL 注入（参数化查询/Sequelize 参数绑定、禁止字符串拼 SQL），防 XSS（前端统一转义输出、后端对输入做校验与白名单）。
• 前端页面样式参考客户管理模块样式（client/src/views/customer/**）。

Impact

• 影响数据库表：现有 customer_equipment、smart_device（不新增表，不强改已有字段，若需补充字段走 migration）。
• 新增后端文件：customer_equipment 与 smart_device 的 controller / service / dto / entity。
• 新增前端文件：设备台账页面、设备型号目录页面、对应 api 封装、路由调整。
• 复用现有：customer_building、customer_room、鉴权中间件（auth/rbac）、上传能力。

ADDED Requirements

Requirement: 客户设备台账管理

系统 SHALL 提供客户设备台账的增删改查、分页列表、按客户过滤、按建筑/楼层/位置筛选。

• 设备字段：设备编码（唯一）、客户ID、设备名称、设备类型（配电间/配电井/配电箱）、所属建筑、楼层、位置、描述、备注、照片。
• 设备编码唯一性校验，重复需返回明确错误。

Scenario: 查询列表

• WHEN 用户带 customerId 与分页参数请求设备台账列表
• THEN 返回该客户下已关联的设备分页数据，并按创建时间倒序

Scenario: 创建/更新设备

• WHEN 用户提交设备表单
• THEN 系统校验必填字段与设备编码唯一性后写入数据库，并关联客户

Scenario: 删除设备

• WHEN 用户删除某设备
• THEN 系统删除该设备记录

Requirement: 智电设备型号目录

系统 SHALL 提供智电设备型号的增删改查与分页列表，类型字段使用设备类型字典（网关/探测器/采集器等）。

Scenario: 型号列表与维护

• WHEN 用户访问型号目录并执行 CRUD
• THEN 型号数据正确维护，类型展示为可读字典名称

Requirement: 空间拓扑与用电架构

系统 SHALL 提供设备在空间（建筑→楼层→位置）下的拓扑化展示，复用现有拓扑页面能力，设备数据来源于设备台账接口。

Scenario: 查看某客户空间拓扑

• WHEN 用户进入某客户的空间拓扑页
• THEN 按建筑/楼层聚合展示设备位置与用电结构

Requirement: 接口鉴权与 APP 兼容

系统 SHALL 对所有设备相关 /api/* 端点启用 JWT + RBAC 鉴权；接口保持标准 RESTful JSON 返回，兼容后端 web 前端与 APP 直接调用。

Scenario: 未授权访问

• WHEN 请求未携带有效 token
• THEN 返回 401，不返回业务数据

Scenario: 无权限访问

• WHEN 已登录但角色无对应权限码
• THEN 返回 403

Requirement: 防 SQL 注入与防 XSS

系统 SHALL 使用参数化查询（Sequelize 参数绑定），禁止通过字符串拼接 SQL；对所有用户可控输入在写入前做校验与过滤，前端展示输出统一转义以防 XSS。

Scenario: 恶意输入处理

• WHEN 用户提交含 SQL 注入或脚本片段的输入
• THEN 输入被当作普通数据安全落库或拦截，前端展示不执行任何脚本

MODIFIED Requirements

Requirement: 设备监控占位路由

client/src/router/index.ts 中 /device（name: Device, permission: device:list）占位组件从 Placeholder.vue 替换为真实设备管理入口。

REMOVED Requirements

（无）

参考实现

• 后端结构参考：server/src/controller/customer.controller.ts 及 service/dto/entity 目录。
• 前端样式参考：client/src/views/customer/info/index.vue、client/src/api/customer.ts。
• 鉴权中间件：server/src/middleware/auth.middleware.ts、server/src/middleware/rbac.middleware.ts。