# 设备管理模块 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`。