wkandClaude Sonnet 4.6 noreply@anthropic.com
cf0a0d4d31
Co-Authored-By: Claude Sonnet 4.6 noreply@anthropic.com
47 lines
5.5 KiB
Markdown
47 lines
5.5 KiB
Markdown
# 智电改造网关台账（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
|
||
（无既有功能被修改）
|