smart_grid_iot/.trae/specs/add-icc-gateway-sync/spec.md

智电改造网关台账（ICC 消防物联设备同步）Spec

Why

系统缺少"智电改造网关设备"台账。网关设备数据由 ICC 平台消防物联设备接口（/evo-apigw/evo-fdbu/{version}/device/subsystem/page）提供，需定时拉取并落库到新建的 electric_gateway 表，运营侧可按客户查看网关设备台账、手动触发同步。本表在设计文档中未定义，需依据接口文档新增表结构（已与需求方确认字段集）。

What Changes

• 新增 electric_gateway 表（数据库迁移 + db_seed.sql 同步）：自增主键 id、icc_imei/device_code 双唯一键、device_name、customer_id（→ customer，由接口 orgCode→customer.icc_code 解析）、equip_id（→ customer_equipment，可空，同步不填充）、org_code/org_name、manufacturer_code/manufacturer_name、type_code/type_name、product_model、is_online、synced_at、created_at；不含 companyId/companyName/dcpsId/softwareVersion/systemAddress/address/description（经需求方确认）
• 新增 ICC 网关设备同步：IccGatewaySyncService 复用真实 OAuth2 鉴权（icc_customer_auth.ts 的 getIccAccessToken + iccFetch，走 .env 已配置凭据），POST 分页拉取消防物联设备全量数据（pageNum/pageSize=50，循环至短页，全量不传 typeCode），按 imei（缺省时 deviceCode）幂等 upsert，写 icc_sync_log（sync_type=electric_gateway）
• 新增 后端接口：GET /api/electric-gateways 列表、GET /api/electric-gateways/:id 详情、POST /api/electric-gateways/sync 手动同步
• 新增 定时任务：注册 icc_gateway_sync（job_registry + job_scheduler buildRuntime + db_seed.sql sys_job 种子，默认 cron */10 * * * *，与既有 ICC 同步任务口径一致）
• 新增 RBAC 映射：/api/electric-gateways → device:list
• 新增 前端"智电改造网关台账"页面（views/device/gateway/index.vue），路由 /device/gateway，含"同步网关"手动按钮；菜单挂设备监控目录（parent=4）
• 新增 .env ICC 网关同步配置（ICC_BASE_URL=https://222.243.55.92:1443、ICC_VERSION=1.0.0、ICC_CLIENT_ID/ICC_CLIENT_SECRET/ICC_USERNAME/ICC_PASSWORD，取自接口文档）
• 安全：全部 SQL 走 Sequelize 参数绑定；前端不用 v-html（防 XSS）；接口返回统一 code/message/data

Impact

• Affected specs: 设备监控（设备台账、智电改造线路台账）、ICC 数据同步、RBAC 权限
• Affected code: server/src（entity/dto/service/controller/task/middleware）、client/src（api/router/views）、database（db_seed.sql、migrations/）

ADDED Requirements

Requirement: 网关台账查询（JWT+RBAC）

系统 SHALL 提供网关台账列表与详情查询，仅登录且有 device:list 权限的用户可访问；查询支持按 customer_id/equip_id/status(在线状态)/关键词（device_name/device_code/icc_imei）过滤分页；非 ADMIN 业务员按客户归属自动限定数据范围。

Scenario: 成功查询

• WHEN 已登录用户 GET /api/electric-gateways?page=1&pageSize=10&customerId=1
• THEN 返回 code=0,data{list,total}，含设备名称/编码/imei/客户/设备型号/主机类型/厂商/在线状态/同步时间；无 token 返回 401，无权限返回 403

Requirement: ICC 网关设备拉取同步（真实鉴权 + 定时 + 手动）

系统 SHALL 提供 ICC 网关设备拉取同步能力：IccGatewaySyncService 读取 .env 的 ICC 配置（复用 icc_customer_auth 真实 OAuth2 密码模式鉴权），POST /evo-apigw/evo-fdbu/{version}/device/subsystem/page 分页拉取消防物联设备全量数据（不传 typeCode，pageSize 50，循环至短页，带最大页数保护），字段映射集中在 icc_gateway_mapper，按 icc_imei（缺省用 device_code）幂等 upsert 写入 electric_gateway，customer_id 由 orgCode→customer.icc_code 解析（匹配不到或缺 icc_imei 与 device_code 则跳过），更新 synced_at，写 icc_sync_log（sync_type=electric_gateway，status/record_count/error_message）。同步入口：① 定时任务（jobKey=icc_gateway_sync，默认 */10 * * * *）；② 手动 POST /api/electric-gateways/sync（JWT+RBAC device:list）。

Scenario: 定时/手动拉取成功

• WHEN 定时任务触发或运营点击"同步网关"
• THEN 拉取 ICC 数据并 upsert 对应网关行，icc_sync_log 记录成功；返回 code=0,data{pulled,synced,inserted,updated,skipped}

Scenario: 手动同步鉴权失败

• WHEN 未登录或无 device:list 权限调用 /api/electric-gateways/sync
• THEN 返回 401/403，不触发拉取

Scenario: ICC 拉取失败（不可达/鉴权失败/接口异常）

• WHEN ICC 地址不可达或返回异常
• THEN 同步日志记录失败状态与错误信息，业务接口不报错，仅返回已拉取计数

Requirement: 前端网关台账页

系统 SHALL 提供 /device/gateway 页面：搜索栏（设备名称/编码/imei、客户、在线状态）、"同步网关"按钮（调 /api/electric-gateways/sync，成功后刷新）、表格（设备名称/编码/imei/客户/厂商/主机类型/设备型号/在线状态 tag/同步时间）、分页；样式与智电改造线路台账一致，全部文本经 Vue 插值转义。

Scenario: 打开页面

• WHEN 有 device:list 权限的用户访问设备监控→智电改造网关台账
• THEN 渲染列表并展示分页与筛选

MODIFIED Requirements

（无既有功能被修改）