docs(03-device-system): 创建 Phase 3 设备体系完善计划（2个Plan）

2026-03-28 11:24:31 +08:00
parent ce6aa62fd6
commit 8a4c6f3cee
3 changed files with 813 additions and 1 deletions
--- a/.planning/phases/03-device-system/03-02-PLAN.md
+++ b/.planning/phases/03-device-system/03-02-PLAN.md
@@ -0,0 +1,405 @@
+---
+phase: 03-device-system
+plan: "02"
+type: execute
+wave: 2
+depends_on:
+  - "03-01"
+files_modified:
+  - internal/service/asset/service.go
+  - internal/bootstrap/services.go
+  - internal/store/postgres/device_sim_binding_store.go
+autonomous: true
+requirements:
+  - DEVICE-04
+
+must_haves:
+  truths:
+    - "调用设备刷新接口后，设备的在线状态、固件版本、当前使用卡从 Gateway 实时更新"
+    - "同一设备同一时刻只有一条 is_current=true 的绑定记录（事务原子更新）"
+    - "sync-info 调用失败时不阻断刷新流程，仅记录 Warn 日志"
+    - "go build ./... 编译通过"
+  artifacts:
+    - path: "internal/service/asset/service.go"
+      provides: "updateDeviceFromSyncInfo 私有函数 + Refresh device 分支 sync-info 调用"
+      contains: "updateDeviceFromSyncInfo"
+    - path: "internal/bootstrap/services.go"
+      provides: "asset.Service 注入 gatewayClient"
+    - path: "internal/store/postgres/device_sim_binding_store.go"
+      provides: "UpdateIsCurrentByDeviceID Store 方法（事务两步更新）"
+  key_links:
+    - from: "internal/service/asset/service.go:Refresh"
+      to: "internal/gateway/device.go:SyncDeviceInfo"
+      via: "s.gatewayClient.SyncDeviceInfo()"
+      pattern: "gatewayClient\\.SyncDeviceInfo"
+    - from: "internal/service/asset/service.go:updateDeviceFromSyncInfo"
+      to: "internal/store/postgres/device_sim_binding_store.go:UpdateIsCurrentByDeviceID"
+      via: "事务原子更新 is_current"
+      pattern: "UpdateIsCurrentByDeviceID"
+---
+
+<objective>
+将 Gateway sync-info 接口接入设备 Refresh 流程（DEVICE-04）：在设备刷新完成绑定卡后，调用 SyncDeviceInfo 同步设备自身状态（在线状态、固件版本、is_current 当前卡标识）。
+
+Purpose: 使设备详情页展示真实的 online_status、software_version、is_current 等字段（Phase 3 成功标准 2、4）
+Output: updateDeviceFromSyncInfo 私有函数 + Refresh device 分支追加 sync-info 调用
+</objective>
+
+<execution_context>
+@$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md
+@$HOME/.config/opencode/get-shit-done/templates/summary.md
+</execution_context>
+
+<context>
+@.planning/PROJECT.md
+@.planning/ROADMAP.md
+@.planning/STATE.md
+@.planning/phases/03-device-system/03-CONTEXT.md
+@.planning/phases/03-device-system/03-01-SUMMARY.md
+
+<interfaces>
+<!-- 本 Plan 依赖 Plan 01 产出的接口，executor 直接使用 -->
+
+**Plan 01 产出的类型（internal/gateway/models.go）：**
+```go
+type SyncDeviceInfoReq struct {
+    CardNo string `json:"card_no"`
+}
+type SyncDeviceInfoResp struct {
+    CurrentIccid    string `json:"current_iccid"`
+    SoftwareVersion string `json:"software_version"`
+    SwitchMode      string `json:"switch_mode"`
+    OnlineStatus    int    `json:"online_status"`   // 1=在线, 2=离线
+    LastOnlineTime  string `json:"last_online_time"` // ISO 8601 字符串
+    LastUpdateTime  string `json:"last_update_time"` // ISO 8601 字符串
+    // ... 其他字段
+}
+```
+
+**Plan 01 产出的方法（internal/gateway/device.go）：**
+```go
+func (c *Client) SyncDeviceInfo(ctx context.Context, req *SyncDeviceInfoReq) (*SyncDeviceInfoResp, error)
+```
+
+**Plan 01 产出的模型字段（internal/model/device.go）：**
+```go
+OnlineStatus      int        // gorm:"column:online_status"
+LastOnlineTime    *time.Time // gorm:"column:last_online_time"
+SoftwareVersion   string     // gorm:"column:software_version"
+SwitchMode        string     // gorm:"column:switch_mode"
+LastGatewaySyncAt *time.Time // gorm:"column:last_gateway_sync_at"
+```
+
+**Plan 01 产出的模型字段（internal/model/device_sim_binding.go）：**
+```go
+IsCurrent bool // gorm:"column:is_current"
+```
+
+**internal/service/asset/service.go 现有 Refresh device 分支（约 295-340 行）：**
+```go
+case "device":
+    // 检查冷却期
+    cooldownKey := constants.RedisDeviceRefreshCooldownKey(id)
+    if s.redis.Exists(ctx, cooldownKey).Val() > 0 {
+        return nil, errors.New(errors.CodeTooManyRequests, "刷新过于频繁，请30秒后再试")
+    }
+
+    // 查所有绑定卡，逐一刷新
+    bindings, err := s.deviceSimBindingStore.ListByDeviceID(ctx, id)
+    if err != nil {
+        return nil, errors.Wrap(errors.CodeInternalError, err, "查询绑定卡失败")
+    }
+    for _, b := range bindings {
+        card, cardErr := s.iotCardStore.GetByID(ctx, b.IotCardID)
+        if cardErr != nil {
+            logger.GetAppLogger().Warn("刷新设备绑定卡失败：查卡失败", ...)
+            continue
+        }
+        if refreshErr := s.iotCardService.RefreshCardDataFromGateway(ctx, card.ICCID); refreshErr != nil {
+            logger.GetAppLogger().Warn("刷新设备绑定卡失败：网关调用失败", ...)
+        }
+    }
+
+    // 设置冷却 Key
+    s.redis.Set(ctx, cooldownKey, 1, constants.DeviceRefreshCooldownDuration)
+
+    return s.GetRealtimeStatus(ctx, "device", id)
+```
+
+**internal/service/asset/service.go 现有 Service 结构体（需要追加 gatewayClient）：**
+```go
+type Service struct {
+    db                    *gorm.DB
+    deviceStore           *postgres.DeviceStore
+    iotCardStore          *postgres.IotCardStore
+    packageUsageStore     *postgres.PackageUsageStore
+    packageStore          *postgres.PackageStore
+    packageSeriesStore    *postgres.PackageSeriesStore
+    deviceSimBindingStore *postgres.DeviceSimBindingStore
+    shopStore             *postgres.ShopStore
+    redis                 *redis.Client
+    iotCardService        IotCardRefresher
+    // 追加：
+    // gatewayClient *gateway.Client
+}
+
+// New() 函数目前签名（需要追加 gatewayClient 参数）：
+func New(
+    db *gorm.DB,
+    deviceStore *postgres.DeviceStore,
+    iotCardStore *postgres.IotCardStore,
+    packageUsageStore *postgres.PackageUsageStore,
+    packageStore *postgres.PackageStore,
+    packageSeriesStore *postgres.PackageSeriesStore,
+    deviceSimBindingStore *postgres.DeviceSimBindingStore,
+    shopStore *postgres.ShopStore,
+    redisClient *redis.Client,
+    iotCardService IotCardRefresher,
+) *Service
+```
+
+**internal/bootstrap/services.go 现有 asset.New 调用（需要追加 deps.GatewayClient）：**
+```go
+Asset: assetSvc.New(deps.DB, s.Device, s.IotCard, s.PackageUsage, s.Package, s.PackageSeries, s.DeviceSimBinding, s.Shop, deps.Redis, iotCard),
+```
+
+**内置 import 路径参考：**
+- `"github.com/break/junhong_cmp_fiber/internal/gateway"`
+- `"time"` 包用于 Parse ISO 8601 字符串
+
+**ISO 8601 时间格式参考（来自 Gateway 文档示例）：**
+- `last_online_time: "2026-03-23T16:53:18+08:00"`
+- Parse 用 `time.Parse(time.RFC3339, str)` 即可处理带时区的 ISO 8601
+
+**DeviceSimBindingStore 现有方法（store 层，需新增 UpdateIsCurrentByDeviceID）：**
+```go
+func (s *DeviceSimBindingStore) ListByDeviceID(ctx context.Context, deviceID uint) ([]*model.DeviceSimBinding, error)
+// 其他方法：Create, GetByID, GetByDeviceAndCard, Unbind, CountByDeviceID...
+// 无 UpdateIsCurrentByDeviceID，需要新增
+```
+</interfaces>
+</context>
+
+<tasks>
+
+<task type="auto">
+  <name>Task 1: DeviceSimBindingStore 新增 UpdateIsCurrentByDeviceID 方法</name>
+  <files>
+    internal/store/postgres/device_sim_binding_store.go
+  </files>
+  <action>
+在 `internal/store/postgres/device_sim_binding_store.go` 末尾追加以下方法：
+
+```go
+// UpdateIsCurrentByDeviceID 原子更新设备当前使用的卡标识
+// 使用事务两步操作：先全部设为 false，再将 currentIccid 对应行设为 true
+// currentIccid 为空字符串时，仅执行全部清空（无当前卡的情况）
+func (s *DeviceSimBindingStore) UpdateIsCurrentByDeviceID(ctx context.Context, deviceID uint, currentIccid string) error {
+    return s.db.WithContext(ctx).Transaction(func(tx *gorm.DB) error {
+        // 第一步：将该设备所有活跃绑定的 is_current 设为 false
+        if err := tx.Model(&model.DeviceSimBinding{}).
+            Where("device_id = ? AND bind_status = 1", deviceID).
+            Update("is_current", false).Error; err != nil {
+            return err
+        }
+
+        // 第二步：将当前 ICCID 对应的绑定记录设为 is_current = true
+        if currentIccid == "" {
+            return nil
+        }
+        // 通过子查询找到对应的 iot_card_id（避免跨表 JOIN 更新）
+        var iotCardID uint
+        if err := tx.Table("tb_iot_card").
+            Select("id").
+            Where("iccid = ? AND deleted_at IS NULL", currentIccid).
+            Scan(&iotCardID).Error; err != nil {
+            return err
+        }
+        if iotCardID == 0 {
+            // 未找到对应卡记录，不更新（可能卡尚未入库）
+            return nil
+        }
+        return tx.Model(&model.DeviceSimBinding{}).
+            Where("device_id = ? AND iot_card_id = ? AND bind_status = 1", deviceID, iotCardID).
+            Update("is_current", true).Error
+    })
+}
+```
+
+确保文件顶部已有 `"gorm.io/gorm"` import（已有，无需新增）。
+  </action>
+  <verify>
+    <automated>go build ./internal/store/postgres/...</automated>
+  </verify>
+  <done>
+    - `UpdateIsCurrentByDeviceID` 方法存在于 device_sim_binding_store.go
+    - 事务内两步操作：先全清 false，再按 ICCID 设 true
+    - go build 编译通过
+  </done>
+</task>
+
+<task type="auto">
+  <name>Task 2: Asset Service 注入 gatewayClient + 实现 updateDeviceFromSyncInfo + Refresh 接入 sync-info</name>
+  <files>
+    internal/service/asset/service.go,
+    internal/bootstrap/services.go
+  </files>
+  <action>
+## 步骤 1：internal/service/asset/service.go — 结构体 + 构造函数 + Refresh 分支 + 新函数
+
+**① import 块追加**（在现有 import 中添加）：
+```go
+"github.com/break/junhong_cmp_fiber/internal/gateway"
+"time"
+```
+注意：`time` 可能已有，检查后选择性添加。
+
+**② Service 结构体追加字段**（per D-13，D-15 决策）：
+在 `iotCardService IotCardRefresher` 行之后追加：
+```go
+gatewayClient *gateway.Client // 用于调用 sync-info 同步设备信息（可为 nil，失败时仅记录日志）
+```
+
+**③ New() 函数签名追加参数**：
+在 `iotCardService IotCardRefresher,` 参数之后追加：
+```go
+gatewayClient *gateway.Client,
+```
+并在 return 的结构体字面量中追加：
+```go
+gatewayClient: gatewayClient,
+```
+
+**④ Refresh device 分支追加 sync-info 调用**（per D-3，D-15 决策）：
+在 `s.redis.Set(ctx, cooldownKey, 1, constants.DeviceRefreshCooldownDuration)` 之后、`return s.GetRealtimeStatus(ctx, "device", id)` 之前插入：
+
+```go
+// 刷新设备自身信息（在线状态、当前卡、固件版本等），失败不阻断刷新流程（per D-15）
+if s.gatewayClient != nil {
+    device, devErr := s.deviceStore.GetByID(ctx, id)
+    if devErr == nil {
+        // IMEI 优先，无则用 SN（per D-3 注释说明）
+        cardNo := device.IMEI
+        if cardNo == "" {
+            cardNo = device.SN
+        }
+        if cardNo != "" {
+            if syncResp, syncErr := s.gatewayClient.SyncDeviceInfo(ctx, &gateway.SyncDeviceInfoReq{
+                CardNo: cardNo,
+            }); syncErr == nil {
+                s.updateDeviceFromSyncInfo(ctx, id, syncResp)
+            } else {
+                logger.GetAppLogger().Warn("sync-info 调用失败",
+                    zap.Uint("device_id", id),
+                    zap.Error(syncErr))
+            }
+        }
+    }
+}
+```
+
+**⑤ 新增 updateDeviceFromSyncInfo 私有函数**（per D-13，D-14 决策）：
+在 `Refresh` 函数之后追加：
+
+```go
+// updateDeviceFromSyncInfo 根据 Gateway sync-info 响应更新设备状态字段和当前卡标识
+// 失败时只记录日志，不返回错误（非关键步骤）
+func (s *Service) updateDeviceFromSyncInfo(ctx context.Context, deviceID uint, resp *gateway.SyncDeviceInfoResp) {
+    now := time.Now()
+
+    // 解析 LastOnlineTime（ISO 8601 字符串 → *time.Time）
+    var lastOnlineTime *time.Time
+    if resp.LastOnlineTime != "" {
+        if t, err := time.Parse(time.RFC3339, resp.LastOnlineTime); err == nil {
+            lastOnlineTime = &t
+        }
+    }
+
+    // 更新设备 5 个存储字段
+    updates := map[string]any{
+        "online_status":        resp.OnlineStatus,
+        "software_version":     resp.SoftwareVersion,
+        "switch_mode":          resp.SwitchMode,
+        "last_gateway_sync_at": now,
+    }
+    if lastOnlineTime != nil {
+        updates["last_online_time"] = lastOnlineTime
+    }
+
+    if err := s.db.WithContext(ctx).
+        Model(&model.Device{}).
+        Where("id = ?", deviceID).
+        Updates(updates).Error; err != nil {
+        logger.GetAppLogger().Warn("sync-info 更新设备字段失败",
+            zap.Uint("device_id", deviceID),
+            zap.Error(err))
+        return
+    }
+
+    // 更新 is_current 标识（事务原子操作，per D-14 决策）
+    if err := s.deviceSimBindingStore.UpdateIsCurrentByDeviceID(ctx, deviceID, resp.CurrentIccid); err != nil {
+        logger.GetAppLogger().Warn("sync-info 更新 is_current 失败",
+            zap.Uint("device_id", deviceID),
+            zap.Error(err))
+    }
+}
+```
+
+## 步骤 2：internal/bootstrap/services.go — Asset.New 追加 deps.GatewayClient
+
+找到以下行：
+```go
+Asset: assetSvc.New(deps.DB, s.Device, s.IotCard, s.PackageUsage, s.Package, s.PackageSeries, s.DeviceSimBinding, s.Shop, deps.Redis, iotCard),
+```
+
+替换为：
+```go
+Asset: assetSvc.New(deps.DB, s.Device, s.IotCard, s.PackageUsage, s.Package, s.PackageSeries, s.DeviceSimBinding, s.Shop, deps.Redis, iotCard, deps.GatewayClient),
+```
+
+## 最终验证
+
+执行 `go build ./...` 确认编译无错误。
+  </action>
+  <verify>
+    <automated>go build ./...</automated>
+  </verify>
+  <done>
+    - `asset.Service` 含 `gatewayClient *gateway.Client` 字段
+    - `asset.New()` 新增 `gatewayClient` 参数，bootstrap 调用处已追加 `deps.GatewayClient`
+    - `updateDeviceFromSyncInfo` 函数存在：更新 5 个 device 字段 + 调用 UpdateIsCurrentByDeviceID
+    - `Refresh` device 分支在绑定卡刷新后追加 sync-info 调用（nil guard + Warn 日志）
+    - `go build ./...` 零新增编译错误
+  </done>
+</task>
+
+</tasks>
+
+<verification>
+```bash
+# 1. 编译验证
+go build ./...
+
+# 2. Gateway 方法确认
+grep -n "SyncDeviceInfo\|updateDeviceFromSyncInfo" internal/service/asset/service.go
+
+# 3. Store 方法确认
+grep -n "UpdateIsCurrentByDeviceID" internal/store/postgres/device_sim_binding_store.go
+
+# 4. Bootstrap 注入确认
+grep -n "GatewayClient" internal/bootstrap/services.go | grep -i asset
+```
+</verification>
+
+<success_criteria>
+- [ ] `go build ./...` 零新增编译错误
+- [ ] `internal/service/asset/service.go` 含 `updateDeviceFromSyncInfo` 函数
+- [ ] `internal/service/asset/service.go` Refresh device 分支含 `gatewayClient.SyncDeviceInfo()` 调用
+- [ ] `internal/store/postgres/device_sim_binding_store.go` 含 `UpdateIsCurrentByDeviceID` 方法
+- [ ] `internal/bootstrap/services.go` asset.New() 调用传入了 `deps.GatewayClient`
+- [ ] sync-info 失败时只记录 Warn，不影响 Refresh 主流程
+</success_criteria>
+
+<output>
+完成后创建 `.planning/phases/03-device-system/03-02-SUMMARY.md`
+</output>