diff --git a/.planning/phases/03.1-sync-info-phase-3-dto/03.1-CONTEXT.md b/.planning/phases/03.1-sync-info-phase-3-dto/03.1-CONTEXT.md index 09921e2..95b2cbe 100644 --- a/.planning/phases/03.1-sync-info-phase-3-dto/03.1-CONTEXT.md +++ b/.planning/phases/03.1-sync-info-phase-3-dto/03.1-CONTEXT.md @@ -14,6 +14,7 @@ Phase 3 完成了设备数据的**写入侧**(sync-info 调用 + DB 字段写 - `toDeviceResponse` 5 个字段未映射 → 影响设备管理列表/详情 - `ListBindings` IsCurrent 未映射 → 影响设备绑卡列表接口 - `BoundCardInfo` IsCurrent 未映射(2 处)→ 影响资产 Resolve/Refresh 响应 + - `AssetResolveResponse` 缺 5 个 DB 缓存字段 → 影响 admin 资产解析接口 2. **设备实时数据架构对齐**(统一视图的上游属性必须实时查询) - 设备上游属性(在线状态/信号/电量/WiFi/当前卡)具有实时特性,存 DB 无意义,必须实时从 Gateway 拉取 @@ -46,6 +47,12 @@ Phase 3 完成了设备数据的**写入侧**(sync-info 调用 + DB 字段写 - 实现方式:在 `bindings` 遍历中同时构建 `isCurrentMap[b.IotCardID] = b.IsCurrent`(与 `slotMap` 同构) - 构建 `BoundCardInfo` 时追加 `IsCurrent: isCurrentMap[c.ID]` +- **D-12:** `asset_dto.go:AssetResolveResponse` 新增 5 个 DB 缓存字段,同步更新 `asset/service.go:buildDeviceResolveResponse()` 映射 + - 新增字段:`OnlineStatus int`、`LastOnlineTime *time.Time`、`SoftwareVersion string`、`SwitchMode string`、`LastGatewaySyncAt *time.Time` + - 这些是 DB 存储值(Phase 3 写入,上次 sync-info 的快照),不触发 Gateway 调用 + - 适用场景:admin 资产 Resolve 接口(`/api/admin/assets/resolve/:identifier`)快速展示设备上次已知状态 + - 与 D-07(GetRealtimeStatus 实时 Gateway 调用)互补:Resolve = 快速快照,Realtime = 精确实时 + ### 设备实时数据架构原则 - **D-05:** 设备上游属性(在线/信号/电量/WiFi/当前卡)**不缓存,必须实时查询 Gateway**。原因:设备具有在线/离线实时特性,存 DB 的值在设备离线后立即过时,无法代表真实状态。 @@ -109,7 +116,7 @@ Phase 3 完成了设备数据的**写入侧**(sync-info 调用 + DB 字段写 - `internal/service/device/service.go` — `toDeviceResponse()`:补全 5 个字段 - `internal/service/device/binding.go` — `ListBindings()`:补全 IsCurrent - `internal/service/asset/service.go` — `GetRealtimeStatus()`:新增 Gateway 调用;Resolve/Refresh 两处 BoundCardInfo:补全 IsCurrent -- `internal/model/dto/asset_dto.go` — 新增 `DeviceGatewayInfo`;`AssetRealtimeStatusResponse` 新增 `DeviceRealtime` 字段 +- `internal/model/dto/asset_dto.go` — 新增 `DeviceGatewayInfo`;`AssetRealtimeStatusResponse` 新增 `DeviceRealtime` 字段;`AssetResolveResponse` 新增 5 个 DB 缓存字段(D-12) - `internal/model/dto/device_dto.go` — 已有字段,无需新增(确认映射即可) - `internal/gateway/models.go` — `SyncDeviceInfoResp` 补全缺失字段 - `internal/handler/app/client_asset.go` — 删除 `buildMockDeviceRealtime()` stub,改为调用服务 + 映射 @@ -160,4 +167,4 @@ Phase 3 完成了设备数据的**写入侧**(sync-info 调用 + DB 字段写 --- *Phase: 03.1-sync-info-phase-3-dto* -*Context gathered: 2026-03-28* +*Context gathered: 2026-03-28 (updated: 2026-03-28, added D-12)*