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

Tasks

• Task 1: 数据库层：新建迁移 database/migrations/20261024_icc_gateway.sql 建 electric_gateway（字段集经需求方确认），并把建表/菜单/角色菜单/定时任务种子同步进 db_seed.sql；幂等（IF NOT EXISTS / ON CONFLICT）
  • SubTask 1.1: 核对生产库是否已有 electric_gateway，避免重复；确认 sys_menu 现有最大 id（迁移用 id=62 并 setval）—— 已核对：表无先例、菜单 id 62 空闲；迁移已执行到远程生产库
  • SubTask 1.2: 迁移内容：建表 electric_gateway（自增 id；icc_imei/device_code 唯一；customer_id→customer；equip_id→customer_equipment 可空；org_code/org_name/manufacturer_code/manufacturer_name/type_code/type_name/product_model/is_online/synced_at/created_at；索引 customer_id/equip_id/icc_imei）；菜单 62「智电改造网关台账」挂设备监控(4)（permission device:list）；ADMIN role_menu；sys_job 种子 icc_gateway_sync（cron */10 * * * *）
  • SubTask 1.3: db_seed.sql 同步对应语句（保持幂等一致）—— 已追加段落（451-522 行）
• Task 2: 后端实体与映射器：
  • SubTask 2.1: server/src/entity/electric_gateway.entity.ts（timestamps:false，结构对齐迁移文件）
  • SubTask 2.2: server/src/task/icc_gateway_mapper.ts：集中配置端点 /evo-apigw/evo-fdbu/{version}/device/subsystem/page、DeviceInfoVO 字段映射（id/imei/deviceCode/deviceName/orgCode/orgName/manufacturerCode/manufacturerName/typeCode/typeName/productModel/isOnline）、分页响应解析（PageVO{nextPage,totalCount,pageData}）
• Task 3: 后端同步服务 server/src/service/icc_gateway_sync.service.ts：
  • SubTask 3.1: 复用 icc_customer_auth.ts 的 getIccAccessToken/iccFetch 真实鉴权；读取 .env（ICC_BASE_URL/ICC_VERSION），配置缺失视为失败仅记日志
  • SubTask 3.2: POST 分页拉取（pageSize=50、不传 typeCode、循环至短页、最大页数保护），预取 orgCode→customer(id) 映射（customer.icc_code）
  • SubTask 3.3: 按 icc_imei（缺省 device_code）幂等 upsert；缺 imei 与 device_code 或匹配不到客户则跳过；更新 synced_at；写 icc_sync_log（sync_type=electric_gateway）；拉取失败仅记录不抛业务错误 —— 实测同步成功（pulled=2），重跑 updated=2 幂等
• Task 4: 后端查询服务/Controller/DTO + RBAC：
  • SubTask 4.1: server/src/service/electric_gateway.service.ts（list/detail，过滤：keyword=device_name/device_code/icc_imei、customer_id、equip_id、is_online；非 ADMIN 按 salesmanId 限定客户范围；decorate 补全客户/设备展示字段）
  • SubTask 4.2: server/src/dto/electric_gateway.dto.ts（查询/同步入参校验）
  • SubTask 4.3: server/src/controller/electric_gateway.controller.ts：GET /api/electric-gateways、GET /:id、POST /sync
  • SubTask 4.4: rbac.middleware.ts 追加 /api/electric-gateways → device:list
• Task 5: 定时任务注册：
  • SubTask 5.1: server/src/task/icc_gateway_sync.task.ts（jobKey=icc_gateway_sync，默认 cron */10 * * * *，handler 调 runtime.syncIccGateways）
  • SubTask 5.2: job_registry.ts：JobRuntime 增加 syncIccGateways，BUILTIN_JOBS 追加 iccGatewaySyncJob
  • SubTask 5.3: job_scheduler.service.ts buildRuntime 增加 syncIccGateways（匿名上下文注入 IccGatewaySyncService）
  • SubTask 5.4: server/.env 补全 ICC 网关同步凭据 —— 已确认 .env 中配置齐全（ICC_BASE_URL=https://222.243.55.92:1443、ICC_VERSION=1.0.0、ICC_CLIENT_ID=xtzdapp、ICC_CLIENT_SECRET、ICC_USERNAME=XTZD接口、ICC_PASSWORD）
• Task 6: 前端：
  • SubTask 6.1: client/src/api/device.ts 新增 electricGatewayApi.list/get/sync
  • SubTask 6.2: client/src/views/device/gateway/index.vue（搜索栏+同步按钮+表格+在线状态 tag+分页，样式对齐 views/device/line/index.vue）
  • SubTask 6.3: client/src/router/index.ts 注册 /device/gateway（挂 device 目录）
• Task 7: 验证：
  • SubTask 7.1: 后端 tsc --noEmit、前端 vue-tsc -b 类型检查通过 —— 均通过（exit 0）
  • SubTask 7.2: 启动服务：无 token 401（实测 401）、admin 列表 200（实测 total=2）、POST /sync 真实拉取成功（pulled=2→落库→重跑 updated=2）、定时任务 icc_gateway_sync 已注册（调度器加载 6 个任务，含 icc_gateway_sync cron */10 * * * *）
  • SubTask 7.3: 浏览器验证菜单出现、页面渲染、筛选/分页/同步按钮可用 —— 实测：菜单出现、9 列表格渲染 2 条、同步按钮提示"拉取 2 条，新增 0，更新 2"并刷新、关键词筛选/重置正常

Task Dependencies

• Task 2/6 依赖 Task 1（表存在）
• Task 3 依赖 Task 2（映射器）
• Task 4 依赖 Task 1/2
• Task 5 依赖 Task 3
• Task 6 依赖 Task 4（接口可用）
• Task 7 依赖全部