148 lines
4.9 KiB
Markdown
148 lines
4.9 KiB
Markdown
# Phase 03.1: 设备 sync-info 读取链路修复 - Discussion Log
|
||
|
||
> **仅供审计参考。** 不用于规划、研究或执行 Agent 的输入。
|
||
> 决策结论见 CONTEXT.md — 本日志保留了讨论过程中的备选项。
|
||
|
||
**Date:** 2026-03-28
|
||
**Phase:** 03.1-sync-info-phase-3-dto
|
||
**Areas discussed:** Plan 分组策略、IsCurrent 实现细节、作用域完整性确认（C 端 stub + 实时数据架构）
|
||
|
||
---
|
||
|
||
## Plan 分组策略
|
||
|
||
| 选项 | 说明 | 选中 |
|
||
|------|------|------|
|
||
| 1 Plan 合并 | 3 修复点同属 DTO 映射缺口，统一处理 | ✓ |
|
||
| 2 Plans 分离 | device/service 系 + asset/service 系拆分 | |
|
||
|
||
**用户选择：** 1 Plan 合并
|
||
**备注：** 修复性质单一（DTO 映射缺落），无依赖分拆理由
|
||
|
||
---
|
||
|
||
## IsCurrent 实现方式
|
||
|
||
| 选项 | 说明 | 选中 |
|
||
|------|------|------|
|
||
| isCurrentMap 标准扩展 | 与 slotMap 同构，在 bindings 遍历时同时构建 | ✓ |
|
||
| 直接引用 binding.IsCurrent | 无 map，在 BoundCardInfo 构建时直接访问外层 binding | |
|
||
|
||
**用户选择：** isCurrentMap 标准扩展
|
||
**备注：** 与 asset/service.go 的 slotMap 保持风格一致
|
||
|
||
---
|
||
|
||
## 作用域完整性：C 端 stub
|
||
|
||
| 选项 | 说明 | 选中 |
|
||
|------|------|------|
|
||
| 一并修复 C 端 stub | 替换 buildMockDeviceRealtime() 为真实 Gateway 数据 | ✓ |
|
||
| 仅修复管理端 | C 端 stub 留待后续 Phase | |
|
||
|
||
**用户选择：** 一并修复
|
||
|
||
---
|
||
|
||
## C 端 DeviceRealtimeInfo 修复粒度
|
||
|
||
| 选项 | 说明 | 选中 |
|
||
|------|------|------|
|
||
| 只补 DB 存储字段 (3 个) | OnlineStatus/SwitchMode/SoftwareVersion，其余 nil | |
|
||
| 完整替换：调用 Gateway | 实时调用 sync-info，返回所有可用字段 | ✓ |
|
||
| 推迟到独立 Phase | C 端 stub 修复是独立需求 | |
|
||
|
||
**用户选择：** 完整替换，调用 Gateway
|
||
|
||
---
|
||
|
||
## 设备实时数据架构（新增议题）
|
||
|
||
**用户补充说明（原文）：**
|
||
> "不管是C端还是后台管理或者哪里,查询设备资产的时候其实都是需要实时数据的,这部分实时数据是很关键的...设备不一样,设备他具有离线,在线实时的特性,所以我们直接存没有什么意义,必然只能实时查询"
|
||
|
||
**架构原则确认：**
|
||
- 单卡资产上游属性 → 轮询系统同步到 DB → 查询 DB
|
||
- 设备资产上游属性 → 实时从 Gateway 查询（不缓存）
|
||
- 设备管理列表 → DB 缓存字段（不需要实时）
|
||
- 设备资产详情（B 端 + C 端）→ 实时 Gateway
|
||
|
||
---
|
||
|
||
## 关键实时字段优先级
|
||
|
||
**用户原文：**
|
||
> "实时状态要的东西也不多,主要是在线状态,连接设备数,网络信号强度,设备电量"
|
||
> "哦还有Wi-Fi密码跟Wi-Fi名称"
|
||
|
||
**关键字段列表：**
|
||
1. 在线状态 (OnlineStatus)
|
||
2. 网络信号强度 (Rsrp/Rsrq/Rssi/Sinr)
|
||
3. 连接设备数 (MaxClients)
|
||
4. 设备电量 (BatteryLevel)
|
||
5. WiFi 名称 (SSID)
|
||
6. WiFi 密码 (WifiPassword)
|
||
7. 当前使用卡 ICCID (CurrentIccid)
|
||
|
||
---
|
||
|
||
## Gateway 失败处理
|
||
|
||
| 选项 | 说明 | 选中 |
|
||
|------|------|------|
|
||
| 返回部分数据 | DeviceRealtime = null，其他资产信息正常返回 | ✓ |
|
||
| 返回错误 | 设备离线/Gateway 超时直接报错 | |
|
||
|
||
**用户选择：** 返回部分数据
|
||
**备注：** 与现有卡资产处理逻辑一致
|
||
|
||
---
|
||
|
||
## 查询范围（设备列表 vs 详情）
|
||
|
||
**用户原文：**
|
||
> "除了列表,因为列表要实时状态没有什么意义,但是像详情跟C端我就很需要实时数据了"
|
||
|
||
**决策：**
|
||
- 设备管理列表 → DB 缓存字段（toDeviceResponse 补全 5 字段即可）
|
||
- 设备资产详情（GetRealtimeStatus）→ 实时 Gateway
|
||
|
||
---
|
||
|
||
## 统一资产视图架构
|
||
|
||
**用户原文（核心说明）：**
|
||
> "我们有设备资产跟单卡资产两种,按照之前的做法其实是大家各有各的详情,我嫌弃麻烦而且不符合业务的要求,所以我们做成统一的口子,这个口子可以看到任意资产的完整生态信息"
|
||
|
||
**影响：**
|
||
- 统一口子 = `asset/service.GetRealtimeStatus()`（管理端）+ `assetService.Resolve()`（C 端）
|
||
- 设备详情不走 `device/service.Get()`，走资产视图
|
||
|
||
---
|
||
|
||
## B 端 vs C 端 DTO 结构
|
||
|
||
| 选项 | 说明 | 选中 |
|
||
|------|------|------|
|
||
| 共享同一结构体 | B/C 端复用 DeviceRealtimeInfo | |
|
||
| 独立结构体 | B 端 DeviceGatewayInfo + C 端 DeviceRealtimeInfo | ✓ |
|
||
|
||
**用户原文：**
|
||
> "不能是同一个结构体,要考虑到未来后台管理可能展示的信息在C端不展示的情况"
|
||
|
||
**决策：** 独立结构体
|
||
- B 端：`DeviceGatewayInfo`（asset_dto.go）
|
||
- C 端：`DeviceRealtimeInfo`（client_asset_dto.go，已存在）
|
||
|
||
---
|
||
|
||
## Agent's Discretion
|
||
|
||
- `DeviceGatewayInfo` B 端字段集合的最终范围（包含全量还是仅关键字段）
|
||
- 防高频调用冷却 Key 策略（C 端每次进详情页都调 Gateway）
|
||
|
||
## Deferred Ideas
|
||
|
||
- 设备 Refresh 接口语义重评（"刷新接口对设备意义不大"）→ Phase 4+ 评估
|
||
- 防高频调用优化 → Phase 4 运营阶段评估
|