docs(03-02): 完成设备体系 sync-info 接入计划（DEVICE-04）

- 新增 03-02-SUMMARY.md，记录 updateDeviceFromSyncInfo 实现细节 - STATE.md：Phase 3 完成标记，追加 DEVICE-04 决策，Next Action 更新为 Phase 4 - ROADMAP.md：Phase 3 进度更新为 Complete（2/2 plans） - REQUIREMENTS.md：DEVICE-04 标记完成
2026-03-28 11:40:04 +08:00
parent 15dbf8dc66
commit 129a38f942
4 changed files with 98 additions and 12 deletions
--- a/.planning/REQUIREMENTS.md
+++ b/.planning/REQUIREMENTS.md
@@ -50,7 +50,7 @@
 - [x] **DEVICE-01**: 设备模型字段扩展 — DB 迁移新增 `online_status / last_online_time / software_version / switch_mode / last_gateway_sync_at`
 - [x] **DEVICE-02**: Gateway sync-info 同步接口对接 — `internal/gateway/device.go` 新增 `SyncDeviceInfo()` 方法
 - [x] **DEVICE-03**: `tb_device_sim_binding` 新增 `is_current` 字段 — DB 迁移 + Model + 更新逻辑
- [ ] **DEVICE-04**: 设备 Refresh + 详情接入 sync-info — `RefreshDevice()` 在刷新卡数据后调用 `SyncDeviceInfo()`，更新设备在线状态/固件版本/当前卡标识
+- [x] **DEVICE-04**: 设备 Refresh + 详情接入 sync-info — `RefreshDevice()` 在刷新卡数据后调用 `SyncDeviceInfo()`，更新设备在线状态/固件版本/当前卡标识

 ### REFUND — 退款完整功能（方案 I）

@@ -145,7 +145,7 @@
 | DEVICE-01 | Phase 3 | Complete |
 | DEVICE-02 | Phase 3 | Complete |
 | DEVICE-03 | Phase 3 | Complete |
-| DEVICE-04 | Phase 3 | Pending |
+| DEVICE-04 | Phase 3 | Complete |
 | REFUND-01 | Phase 4 | Pending |
 | REFUND-02 | Phase 4 | Pending |
 | REFUND-03 | Phase 4 | Pending |
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -12,7 +12,7 @@

 - [x] **Phase 1: P0 紧急修复** — 修复所有阻塞主链路的 P0 Bug，使充值→购包→佣金→实名激活全链路可跑通 (completed 2026-03-27)
 - [x] **Phase 2: 权限/财务/实名/轮询修复** — 补全企业权限、提现财务流程、实名激活架构重构、轮询系统小修 (completed 2026-03-28)
- [ ] **Phase 3: 设备体系完善** — 扩展设备模型字段、对接 Gateway sync-info、完善绑卡标识
+- [x] **Phase 3: 设备体系完善** — 扩展设备模型字段、对接 Gateway sync-info、完善绑卡标识 (completed 2026-03-28)
 - [ ] **Phase 4: 退款 + 支付 + 运营修复** — 实现退款完整流程、补全富友支付接口、修复运营逻辑
 - [ ] **Phase 5: 代码质量清理** — 消除技术债务：佣金断链可观测、删废弃代码、修复权限不一致、迁移分层
 - [ ] **Phase 6: 流量体系改革（低峰期）** — 破坏性变更：日粒度流量表 + Redis 增量缓存 + 每日落盘任务
@@ -74,7 +74,7 @@ Plans:

 Plans:
 - [x] 03-01-PLAN.md — DEVICE-01/02/03：DB 迁移 + 模型扩展 + Gateway SyncDeviceInfo + DTO 字段（Wave 1）
- [ ] 03-02-PLAN.md — DEVICE-04：Asset Service 接入 sync-info，Refresh 追加设备状态同步（Wave 2）
+- [x] 03-02-PLAN.md — DEVICE-04：Asset Service 接入 sync-info，Refresh 追加设备状态同步（Wave 2）

 ---

@@ -128,7 +128,7 @@ Plans:
 |-------|----------------|--------|-----------|
 | 1. P0 紧急修复 | 5/5 | Complete   | 2026-03-27 |
 | 2. 权限/财务/实名/轮询修复 | 2/2 | Complete    | 2026-03-28 |
-| 3. 设备体系完善 | 1/2 | In Progress|  |
+| 3. 设备体系完善 | 2/2 | Complete   | 2026-03-28 |
 | 4. 退款 + 支付 + 运营修复 | 0/TBD | Not started | - |
 | 5. 代码质量清理 | 0/TBD | Not started | - |
 | 6. 流量体系改革（低峰期）| 0/TBD | Not started | - |
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -3,12 +3,12 @@ gsd_state_version: 1.0
 milestone: v1.0
 milestone_name: milestone
 status: unknown
-last_updated: "2026-03-28T03:33:58.201Z"
+last_updated: "2026-03-28T03:39:07.174Z"
 progress:
  total_phases: 6
-  completed_phases: 2
+  completed_phases: 3
  total_plans: 9
-  completed_plans: 8
+  completed_plans: 9
 ---

 # Project State — 君鸿卡管系统
@@ -52,7 +52,7 @@ Progress: [ 1 ]──[ 2 ]──[ 3 ]──[ 4 ]──[ 5 ]──[ 6 ]
 |-------|------|--------------|--------|
 | 1 | P0 紧急修复 | CRITICAL-01~08（8项） | ✓ Complete (2026-03-28) |
 | 2 | 权限/财务/实名/轮询修复 | PERM-01~02, FIN-01~03, REALNAME-01~05, POLL-01~04（14项） | ✓ Complete (2026-03-28) |
-| 3 | 设备体系完善 | DEVICE-01~04（4项） | ○ Not started |
+| 3 | 设备体系完善 | DEVICE-01~04（4项） | ✓ Complete (2026-03-28) |
 | 4 | 退款 + 支付 + 运营修复 | REFUND-01~03, PAY-01~04, OPS-01~02（9项） | ○ Not started |
 | 5 | 代码质量清理 | CLEAN-01~06（6项） | ○ Not started |
 | 6 | 流量体系改革（低峰期）| TRAFFIC-01~05（5项） | ○ Not started |
@@ -72,6 +72,7 @@ Progress: [ 1 ]──[ 2 ]──[ 3 ]──[ 4 ]──[ 5 ]──[ 6 ]

 ---
 | Phase 03-device-system P01 | 8min | 2 tasks | 10 files |
+| Phase 03-device-system P02 | 10min | 2 tasks | 3 files |

 ## Execution Log

@@ -95,8 +96,10 @@ Progress: [ 1 ]──[ 2 ]──[ 3 ]──[ 4 ]──[ 5 ]──[ 6 ]
 - REALNAME-01~05 是原子重构，必须在一个 plan 内完整执行，不可拆分
 - REFUND 退款佣金回扣（REFUND-03）必须使用整数算术，禁用 float64
 - CRITICAL-02 依赖 CRITICAL-01，CRITICAL-05 依赖 CRITICAL-04
- DEVICE-02/03/04 依赖 DEVICE-01（字段扩展先行）
+- DEVICE-02/03/04 依赖 DEVICE-01（字段扩展先行）✓ Phase 03 完成
 - REFUND-02/03 依赖 REFUND-01（数据模型先行）
+- DEVICE-04: gatewayClient nil guard 可选注入，sync-info 失败仅记 Warn 不阻断 Refresh 主流程
+- UpdateIsCurrentByDeviceID 事务两步原子更新 is_current，保证同一设备唯一 is_current=true

 ### Architecture Notes

@@ -117,7 +120,7 @@ Progress: [ 1 ]──[ 2 ]──[ 3 ]──[ 4 ]──[ 5 ]──[ 6 ]

 ## Session Continuity

-**Next Action:** Run `/gsd-plan-phase 3` to create detailed plan for Phase 3 (设备体系完善)
+**Next Action:** Run `/gsd-plan-phase 4` to create detailed plan for Phase 4 (退款 + 支付 + 运营修复)

 **Context Files:**

@@ -128,4 +131,4 @@ Progress: [ 1 ]──[ 2 ]──[ 3 ]──[ 4 ]──[ 5 ]──[ 6 ]
 - `.sisyphus/plans/修正业务-完整方案.md` — 每个 Bug 的完整修复规格（含代码片段）

 ---
-*State initialized: 2026-03-27 | Last phase completed: Phase 2 (2026-03-28)*
+*State initialized: 2026-03-27 | Last phase completed: Phase 3 (2026-03-28)*
--- a/.planning/phases/03-device-system/03-02-SUMMARY.md
+++ b/.planning/phases/03-device-system/03-02-SUMMARY.md
@@ -0,0 +1,83 @@
+---
+phase: 03-device-system
+plan: "02"
+subsystem: device
+tags: [service, gateway, sync-info, store, bootstrap]
+dependency_graph:
+  requires:
+    - Plan 03-01（tb_device 5字段 + tb_device_sim_binding.is_current + Gateway SyncDeviceInfo 方法）
+  provides:
+    - DeviceSimBindingStore.UpdateIsCurrentByDeviceID（事务原子更新 is_current）
+    - asset.Service.updateDeviceFromSyncInfo（私有函数，同步 5 个设备字段 + is_current）
+    - asset.Service.Refresh device 分支接入 SyncDeviceInfo（nil guard + Warn 日志）
+    - asset.Service 注入 gatewayClient
+  affects:
+    - DEVICE-04 需求（设备 Refresh + 详情接入 sync-info）
+tech_stack:
+  added: []
+  patterns:
+    - GORM Transaction 两步原子更新模式
+    - Service nil guard 可选依赖注入模式
+    - ISO 8601 字符串 → time.Time（time.RFC3339）
+key_files:
+  created: []
+  modified:
+    - internal/store/postgres/device_sim_binding_store.go
+    - internal/service/asset/service.go
+    - internal/bootstrap/services.go
+decisions:
+  - "gatewayClient 使用 nil guard（而非断言非 nil），允许 bootstrap 传入 nil 依然安全运行"
+  - "sync-info 失败只记 Warn 日志，不阻断 Refresh 主流程（非关键步骤，D-15 决策）"
+  - "UpdateIsCurrentByDeviceID 事务两步：先全清 false，再按 ICCID 设 true（原子保证唯一 is_current）"
+metrics:
+  duration: "10min"
+  completed_date: "2026-03-28"
+  tasks: 2
+  files: 3
+---
+
+# Phase 03 Plan 02: Gateway sync-info 接入 Refresh 流程 Summary
+
+**一句话总结：** 在设备 Refresh 流程末尾接入 Gateway SyncDeviceInfo，通过 updateDeviceFromSyncInfo 原子更新在线状态、固件版本等 5 个设备字段及 is_current 当前卡标识（DEVICE-04）。
+
+## Tasks Completed
+
+| Task | Name | Commit | Files |
+|------|------|--------|-------|
+| 1 | DeviceSimBindingStore 新增 UpdateIsCurrentByDeviceID 方法 | `ba1886c` | device_sim_binding_store.go |
+| 2 | Asset Service 注入 gatewayClient + 实现 updateDeviceFromSyncInfo + Refresh 接入 sync-info | `15dbf8d` | service.go, services.go |
+
+## Artifacts Delivered
+
+### Store 层
+
+- **UpdateIsCurrentByDeviceID**：事务两步原子更新。第一步将设备所有活跃绑定的 `is_current` 清为 false；第二步通过子查询定位 `current_iccid` 对应的 `iot_card_id`，将该绑定设为 `is_current = true`。`currentIccid` 为空时仅清空。
+
+### Service 层
+
+- **Service 结构体**：新增 `gatewayClient *gateway.Client` 字段（允许 nil）
+- **New() 构造函数**：新增 `gatewayClient *gateway.Client` 参数
+- **Refresh device 分支**：在设置冷却 Key 之后、`GetRealtimeStatus` 返回之前，增加 sync-info 调用逻辑（nil guard 保护，失败只记 Warn 日志）
+- **updateDeviceFromSyncInfo 私有函数**：
+  1. 解析 `last_online_time`（ISO 8601 → `*time.Time`，`time.RFC3339`）
+  2. GORM Updates 更新 5 个字段：`online_status`、`software_version`、`switch_mode`、`last_gateway_sync_at`、`last_online_time`（非空时）
+  3. 调用 `UpdateIsCurrentByDeviceID` 原子更新 `is_current`
+
+### Bootstrap 层
+
+- **services.go**：`asset.New()` 调用末尾追加 `deps.GatewayClient` 参数
+
+## Deviations from Plan
+
+None — 计划完全按预期执行。
+
+## Verification
+
+- ✅ `go build ./...` 零新增编译错误
+- ✅ `updateDeviceFromSyncInfo` 方法存在于 `internal/service/asset/service.go`
+- ✅ `Refresh` device 分支含 `gatewayClient.SyncDeviceInfo()` 调用（nil guard + Warn 日志）
+- ✅ `UpdateIsCurrentByDeviceID` 存在于 `internal/store/postgres/device_sim_binding_store.go`
+- ✅ `internal/bootstrap/services.go` asset.New() 传入了 `deps.GatewayClient`
+- ✅ sync-info 失败时只记录 Warn，不影响 Refresh 主流程
+
+## Self-Check: PASSED