junhong_cmp_fiber/openspec/changes/archive/2026-04-17-asset-realname-policy/tasks.md at 4aab0bcbf26d1901ace771e1e5dd7998d5d0228d

Files

huang 4aab0bcbf2

构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 4m39s

Details

2026-04-18 09:10:29 +08:00

1. 基础设施（常量 + 迁移 + Model）

1.1 在 pkg/constants/ 中定义 RealnamePolicy 枚举常量（none / before_order / after_order）及新增错误码 CodeRealnameNotAvailable（pkg/errors/codes.go）
1.2 创建数据库迁移文件，为 tb_iot_card 新增 realname_policy VARCHAR(20) NOT NULL DEFAULT 'none'
1.3 创建数据库迁移文件，为 tb_device 新增 realname_policy VARCHAR(20) NOT NULL DEFAULT 'none'
1.4 创建数据库迁移文件，为 tb_iot_card_import_task 新增 realname_policy VARCHAR(20) NOT NULL DEFAULT 'none'
1.5 创建数据库迁移文件，为 tb_device_import_task 新增 realname_policy VARCHAR(20) NOT NULL DEFAULT 'none'
1.6 在 internal/model/iot_card.go 的 IotCard 结构体新增 RealnamePolicy 字段（含 gorm 标签和中文注释）
1.7 在 internal/model/device.go 的 Device 结构体新增 RealnamePolicy 字段（含 gorm 标签和中文注释）
1.8 在 internal/model/iot_card_import_task.go 的 IotCardImportTask 结构体新增 RealnamePolicy 字段
1.9 在 internal/model/device_import_task.go 的 DeviceImportTask 结构体新增 RealnamePolicy 字段
1.10 执行迁移并验证四张表字段已正确添加

2.1 在合适的公共 Service 或工具包中实现 GetEffectiveRealnamePolicy(card *model.IotCard, device *model.Device) string：设备卡取 device.RealnamePolicy，单卡取 card.RealnamePolicy
2.2 实现检查 after_order 生效条件的方法：查询该资产当前 generation 内是否存在有效充值（status=2）或已支付订单（payment_status=2），返回 bool

3.1 在 ImportIotCardRequest DTO 中新增 realname_policy 字段（含 validate、description 标签）
3.2 更新 iot_card_import Service 的 CreateImportTask 方法：将请求中的 realname_policy 保存到 IotCardImportTask.realname_policy
3.3 更新 IoT 卡导入 Worker 处理逻辑：创建 IotCard 记录时从任务的 realname_policy 写入卡的 realname_policy
3.4 在 ImportTaskResponse（IoT 卡）中新增 realname_policy 字段（含 description 标签）

4.1 在 ImportDeviceRequest DTO 中新增 realname_policy 字段（含 validate、description 标签）
4.2 更新 device_import Service 的 CreateImportTask 方法：将请求中的 realname_policy 保存到 DeviceImportTask.realname_policy
4.3 更新设备导入 Worker 处理逻辑：创建 Device 记录时从任务的 realname_policy 写入设备的 realname_policy
4.4 在 DeviceImportTaskResponse 中新增 realname_policy 字段（含 description 标签）

5.1 在 StandaloneIotCardResponse（iot_card_dto.go）中新增 realname_policy 字段，更新 Store/Service 中的 DTO 填充逻辑
5.2 在 DeviceResponse（device_dto.go）中新增 realname_policy 字段，更新填充逻辑
5.3 在 AssetResolveResponse（asset_dto.go）中新增 realname_policy 字段，更新 asset Service 的 Resolve 方法填充逻辑
5.4 在 AssetRealtimeStatusResponse（asset_dto.go）中新增 realname_policy 字段，更新填充逻辑
5.5 在 DeviceCardBindingResponse（device_dto.go）中新增 realname_policy 字段，更新填充逻辑
5.6 在 BoundCardInfo（asset_dto.go，后台管理端公共子结构）中新增 realname_policy 字段，更新填充逻辑

6.1 在 AssetInfoResponse（client_asset_dto.go）中新增 realname_policy 字段，更新 client_asset Service 的填充逻辑
6.2 在 C 端 BoundCardInfo（client_asset_dto.go 内嵌子结构）中新增 realname_policy 字段，更新填充逻辑
6.3 在 DeviceCardItem（client_realname_device_dto.go）中新增 realname_policy 字段，更新 GetDeviceCards 接口填充逻辑

7.1 在 client_wallet Service 的充值预检方法（C3 对应逻辑）中，在归属校验后插入实名策略检查：before_order + 未实名 → 返回 CodeNeedRealname
7.2 在 client_wallet Service 的充值下单方法（C4 对应逻辑）中，在归属校验后、OpenID 查询前插入实名策略检查：before_order + 未实名 → 返回 CodeNeedRealname

9.1 在 client_realname Service 的 GetRealnameLink 方法中，目标卡定位后，real_name_status=1 检查前，插入策略检查：after_order + 无有效充值/订单 → 返回 CodeRealnameNotAvailable
9.2 验证 before_order 和 none 模式下实名链接接口行为不受影响

10.1 在 iot_card Store 中新增 UpdateRealnamePolicy(ctx, cardID uint, policy string) error 方法
10.2 在 device Store 中新增 UpdateRealnamePolicy(ctx, deviceID uint, policy string) error 方法
10.3 在 iot_card Service 中新增 UpdateRealnamePolicy(ctx, cardID uint, policy string) error 方法（含幂等检查）
10.4 在 device Service 中新增 UpdateRealnamePolicy(ctx, deviceID uint, policy string) error 方法（含幂等检查）
10.5 在 asset_dto.go 中新增 UpdateAssetRealnameModRequest 和 UpdateAssetRealnameModResponse DTO
10.6 在 asset Handler（internal/handler/admin/asset.go）中新增 UpdateRealnameMode 方法，遵循 UpdatePollingStatus 模式
10.7 在路由注册文件中注册新接口 PATCH /api/admin/assets/:identifier/realname-mode
10.8 更新文档生成器 cmd/api/docs.go 和 cmd/gendocs/main.go，添加新 Handler