16 KiB
16 KiB
phase, plan, type, wave, depends_on, files_modified, autonomous, requirements, must_haves
| phase | plan | type | wave | depends_on | files_modified | autonomous | requirements | must_haves | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 03-device-system | 01 | execute | 1 |
|
true |
|
|
Purpose: Plan 2 的 Refresh 接入依赖本 Plan 的全部产出（模型字段 + Gateway 方法 + DTO 定义） Output: 2 个迁移对、Device/DeviceSimBinding 模型更新、Gateway SyncDeviceInfo 方法、DTO 扩展
<execution_context> @$HOME/.config/opencode/get-shit-done/workflows/execute-plan.md @$HOME/.config/opencode/get-shit-done/templates/summary.md </execution_context>
@.planning/PROJECT.md @.planning/ROADMAP.md @.planning/STATE.md @.planning/phases/03-device-system/03-CONTEXT.mdinternal/gateway/device.go（现有方法）：
func (c *Client) GetDeviceInfo(ctx context.Context, req *DeviceInfoReq) (*DeviceInfoResp, error)
func (c *Client) GetSlotInfo(ctx context.Context, req *DeviceInfoReq) (*SlotInfoResp, error)
// 其他方法略
internal/gateway/client.go（泛型请求方法）：
// 签名：
func doRequestWithResponse[T any](c *Client, ctx context.Context, path string, params interface{}) (*T, error)
// 用法（参考 GetDeviceInfo）：
return doRequestWithResponse[DeviceInfoResp](c, ctx, "/device/info", req)
internal/gateway/models.go 中已有的设备 DTO（参考风格）：
type DeviceInfoReq struct {
CardNo string `json:"cardNo,omitempty" description:"..."`
DeviceID string `json:"deviceId,omitempty" description:"..."`
}
type DeviceInfoResp struct {
IMEI string `json:"imei" description:"..."`
OnlineStatus int `json:"onlineStatus" description:"..."`
// ...
}
internal/model/device.go 现有字段（末尾追加新字段）：
type Device struct {
gorm.Model
BaseModel `gorm:"embedded"`
VirtualNo string `gorm:"column:virtual_no;..."`
IMEI string `gorm:"column:imei;type:varchar(20);..."`
SN string `gorm:"column:sn;type:varchar(100);..."`
// ... 其余字段 ...
Generation int `gorm:"column:generation;type:int;not null;default:1;..."`
// 在 Generation 之后追加 5 个新字段
}
internal/model/device_sim_binding.go 现有字段（末尾追加 is_current）：
type DeviceSimBinding struct {
gorm.Model
BaseModel `gorm:"embedded"`
DeviceID uint `gorm:"column:device_id;..."`
IotCardID uint `gorm:"column:iot_card_id;..."`
SlotPosition int `gorm:"column:slot_position;..."`
BindStatus int `gorm:"column:bind_status;..."`
BindTime *time.Time `gorm:"column:bind_time;..."`
UnbindTime *time.Time `gorm:"column:unbind_time;..."`
// 追加 IsCurrent
}
internal/model/dto/device_dto.go 中 DeviceResponse 和 DeviceCardBindingResponse：
type DeviceResponse struct {
// ... 现有字段 ...
UpdatedAt time.Time `json:"updated_at" description:"更新时间"`
// 在 UpdatedAt 之后追加 5 个新字段
}
type DeviceCardBindingResponse struct {
// ... 现有字段（末尾是 BindTime）...
BindTime *time.Time `json:"bind_time,omitempty" description:"绑定时间"`
// 追加 IsCurrent
}
internal/model/dto/asset_dto.go 中 BoundCardInfo：
type BoundCardInfo struct {
CardID uint `json:"card_id" description:"卡ID"`
ICCID string `json:"iccid" description:"ICCID"`
MSISDN string `json:"msisdn,omitempty" description:"手机号"`
NetworkStatus int `json:"network_status" description:"网络状态：0停机 1开机"`
RealNameStatus int `json:"real_name_status" description:"实名状态"`
SlotPosition int `json:"slot_position,omitempty" description:"插槽位置"`
// 追加 IsCurrent
}
Gateway sync-info 接口：
- URL：
POST /v1/iot/openApi/device/sync-info（业务路径参数传/device/sync-info） - cardNo：ICCID（>15位）/ IMEI（=15位）/ SN（=11位）
- 关键响应字段：current_iccid, software_version, switch_mode, online_status, last_online_time（ISO 8601 string）, last_update_time
最新迁移编号：000089_realname_expiry_base，新迁移从 000090 开始
创建 migrations/000090_device_fields_extension.up.sql：
-- 扩展 tb_device 设备表，新增 Gateway sync-info 同步的存储字段
-- 这些字段有"离线意义"（设备下线后仍需保留最后状态），非实时字段（rssi/battery 等）不入库
ALTER TABLE tb_device
ADD COLUMN online_status INT NOT NULL DEFAULT 0,
ADD COLUMN last_online_time TIMESTAMP NULL,
ADD COLUMN software_version VARCHAR(100) NOT NULL DEFAULT '',
ADD COLUMN switch_mode VARCHAR(10) NOT NULL DEFAULT '0',
ADD COLUMN last_gateway_sync_at TIMESTAMP NULL;
COMMENT ON COLUMN tb_device.online_status IS '在线状态：0未知，1在线，2离线';
COMMENT ON COLUMN tb_device.last_online_time IS '最后在线时间（来自 Gateway sync-info）';
COMMENT ON COLUMN tb_device.software_version IS '固件版本号';
COMMENT ON COLUMN tb_device.switch_mode IS '切卡模式：0=自动，1=手动';
COMMENT ON COLUMN tb_device.last_gateway_sync_at IS '最后一次 sync-info 同步时间';
创建 migrations/000090_device_fields_extension.down.sql：
ALTER TABLE tb_device
DROP COLUMN IF EXISTS online_status,
DROP COLUMN IF EXISTS last_online_time,
DROP COLUMN IF EXISTS software_version,
DROP COLUMN IF EXISTS switch_mode,
DROP COLUMN IF EXISTS last_gateway_sync_at;
迁移文件 000091（tb_device_sim_binding 新增 is_current）
创建 migrations/000091_device_sim_binding_is_current.up.sql：
-- 新增 is_current 字段，标识设备当前正在使用的卡（由 sync-info current_iccid 字段决定）
ALTER TABLE tb_device_sim_binding
ADD COLUMN is_current BOOLEAN NOT NULL DEFAULT FALSE;
COMMENT ON COLUMN tb_device_sim_binding.is_current IS '是否为当前使用的卡（同一设备同一时刻最多一条为 true）';
创建 migrations/000091_device_sim_binding_is_current.down.sql：
ALTER TABLE tb_device_sim_binding
DROP COLUMN IF EXISTS is_current;
执行迁移
执行 make migrate-up 并确认：
make migrate-version输出版本为 91，dirty=false- 使用 PostgreSQL MCP 验证 tb_device 新增 5 列、tb_device_sim_binding 新增 is_current
更新 internal/model/device.go
在 Generation 字段之后追加 5 个字段（保持与其他字段相同的标签格式）：
// 以下字段由 Gateway sync-info 接口同步，有离线存储意义
OnlineStatus int `gorm:"column:online_status;type:int;not null;default:0;comment:在线状态：0未知 1在线 2离线" json:"online_status"`
LastOnlineTime *time.Time `gorm:"column:last_online_time;comment:最后在线时间（来自 Gateway sync-info）" json:"last_online_time,omitempty"`
SoftwareVersion string `gorm:"column:software_version;type:varchar(100);not null;default:'';comment:固件版本号" json:"software_version"`
SwitchMode string `gorm:"column:switch_mode;type:varchar(10);not null;default:'0';comment:切卡模式：0=自动 1=手动" json:"switch_mode"`
LastGatewaySyncAt *time.Time `gorm:"column:last_gateway_sync_at;comment:最后一次 sync-info 同步时间" json:"last_gateway_sync_at,omitempty"`
更新 internal/model/device_sim_binding.go
在 UnbindTime 字段之后追加：
IsCurrent bool `gorm:"column:is_current;type:boolean;not null;default:false;comment:是否为当前使用的卡" json:"is_current"`
在文件末尾（// ============ 结束 ============ 之前或文件末）追加，放在「设备相关 DTO」分组下：
// SyncDeviceInfoReq sync-info 同步查询设备信息请求
// cardNo 规则：>15 位用 ICCID，=15 位用 IMEI，=11 位用 SN
type SyncDeviceInfoReq struct {
CardNo string `json:"card_no" description:"设备标识（ICCID/IMEI/SN）"`
}
// SyncDeviceInfoResp sync-info 同步查询设备信息响应（对应 Gateway data 字段）
// 注意：所有字段均可能为 null/零值，表示暂无数据
type SyncDeviceInfoResp struct {
DeviceID string `json:"device_id" description:"设备ID（IMEI/SN）"`
DeviceName string `json:"device_name" description:"设备名称"`
IMEI string `json:"imei" description:"IMEI号"`
CurrentIccid string `json:"current_iccid" description:"当前使用的ICCID"`
DeviceType string `json:"device_type" description:"设备类型：1=诺行，2=玺龙，3=迎势达"`
SoftwareVersion string `json:"software_version" description:"软件版本号"`
MacAddress string `json:"mac_address" description:"MAC地址"`
SSID string `json:"ssid" description:"WiFi热点名称"`
WifiEnabled bool `json:"wifi_enabled" description:"WiFi开关状态"`
SwitchMode string `json:"switch_mode" description:"切卡模式：0=自动，1=手动"`
RSSI string `json:"rssi" description:"接收信号强度"`
BatteryLevel *int `json:"battery_level" description:"电池电量百分比（无电池时为null）"`
OnlineStatus int `json:"online_status" description:"在线状态：1=在线，2=离线"`
LastUpdateTime string `json:"last_update_time" description:"设备信息最后更新时间（ISO 8601）"`
LastOnlineTime string `json:"last_online_time" description:"设备最后在线时间（ISO 8601）"`
RunTime string `json:"run_time" description:"本次开机运行时间（秒）"`
DailyUsage string `json:"daily_usage" description:"日使用流量（字节）"`
}
internal/gateway/device.go — 新增 SyncDeviceInfo 方法
在文件末尾追加：
// SyncDeviceInfo 同步查询设备信息（直接返回，无需回调）
// 与异步 /device/info 的区别：直接返回全量数据，无需 callbackUrl
// POST /device/sync-info
func (c *Client) SyncDeviceInfo(ctx context.Context, req *SyncDeviceInfoReq) (*SyncDeviceInfoResp, error) {
if req.CardNo == "" {
return nil, errors.New(errors.CodeInvalidParam, "cardNo 不能为空")
}
return doRequestWithResponse[SyncDeviceInfoResp](c, ctx, "/device/sync-info", req)
}
更新文件顶部包注释：「提供设备相关的 8 个 API 方法封装」（从 7 改为 8）
internal/model/dto/device_dto.go — DeviceResponse 和 DeviceCardBindingResponse 字段扩展
DeviceResponse — 在 UpdatedAt 字段之后追加（per D-0）：
// 设备实时同步字段（由 sync-info 接口写入）
OnlineStatus int `json:"online_status" description:"在线状态：0未知 1在线 2离线"`
LastOnlineTime *time.Time `json:"last_online_time,omitempty" description:"最后在线时间"`
SoftwareVersion string `json:"software_version" description:"固件版本号"`
SwitchMode string `json:"switch_mode" description:"切卡模式：0=自动，1=手动"`
LastGatewaySyncAt *time.Time `json:"last_gateway_sync_at,omitempty" description:"最后 sync-info 同步时间"`
DeviceCardBindingResponse — 在 BindTime 字段之后追加（per D-2）：
IsCurrent bool `json:"is_current" description:"是否为当前使用的卡"`
internal/model/dto/asset_dto.go — BoundCardInfo 字段扩展
在 SlotPosition 字段之后追加（per D-2，D-11 决策）：
IsCurrent bool `json:"is_current" description:"是否为当前使用的卡"`
验证
执行 go build ./...，确认无编译错误。
go build ./...
- SyncDeviceInfoReq / SyncDeviceInfoResp 在 internal/gateway/models.go 中定义
- SyncDeviceInfo() 方法在 internal/gateway/device.go 中实现
- DeviceResponse 含 5 个新字段，DeviceCardBindingResponse 含 is_current
- BoundCardInfo 含 is_current
- go build ./... 零新增错误
2. 编译通过
go build ./...
3. 字段验证（通过 PostgreSQL MCP）
dbhub_search_objects: object_type=column, table=tb_device
确认：online_status / last_online_time / software_version / switch_mode / last_gateway_sync_at
dbhub_search_objects: object_type=column, table=tb_device_sim_binding
确认：is_current
4. Gateway 方法搜索
grep -r "SyncDeviceInfo" internal/gateway/
</verification>
<success_criteria>
- [ ] `make migrate-version` 输出 version=91, dirty=false
- [ ] `go build ./...` 零新增编译错误
- [ ] `internal/gateway/device.go` 含 `SyncDeviceInfo()` 方法
- [ ] `internal/gateway/models.go` 含 `SyncDeviceInfoReq` / `SyncDeviceInfoResp`
- [ ] `DeviceResponse` 含 5 个新字段，`DeviceCardBindingResponse` 含 `is_current`
- [ ] `BoundCardInfo` 含 `is_current`
</success_criteria>
<output>
完成后创建 `.planning/phases/03-device-system/03-01-SUMMARY.md`
</output>