docs(03.1): 补充 D-12 AssetResolveResponse 5字段扩展决策

This commit is contained in:
2026-03-28 13:04:35 +08:00
parent d0ef3bb712
commit debe8f6edc

View File

@@ -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-07GetRealtimeStatus 实时 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)*