csxj2026/junhong_cmp_fiber

Fork 0

Files

break 2e130b98f5 临时备份一次

2026-07-13 12:01:18 +09:00

7.4 KiB

Raw Blame History

需求02：H5 流程顺序配置化

背景

H5 用户进入后：绑定手机号 → 充值 → 实名（当前顺序写死）

需求：允许按资产个体配置充值和实名的顺序，支持后台单条或批量改。

流程图

图一：H5 登录后资产视角判断与策略读取

flowchart TD
    A[用户扫码 / 输入虚拟号] --> B[解析 identifier]
    B --> C{资产类型}

    C -->|card| D{该卡是否绑定设备?}
    D -->|否 独立卡| E[卡视角\n读 IotCard.realname_policy]
    D -->|是| F[设备视角\n读 Device.realname_policy\n卡自身策略忽略]

    C -->|device| F

    E --> G{realname_policy}
    F --> G

    G -->|none| H[无需实名\n直接进充值页]
    G -->|before_order| I[先进实名页\n实名完成后才能充值]
    G -->|after_order| J[先进充值页\n充值完成后提示实名]

图二：H5 充值/购买前的策略拦截逻辑

flowchart TD
    A[用户发起充值/购买] --> B[读取 resolved.Asset.RealnamePolicy]
    B --> C{策略是 before_order?}
    C -->|否| D[放行，正常创建订单]
    C -->|是| E{当前资产 RealNameStatus == 1?}
    E -->|已实名| D
    E -->|未实名| F[返回 CodeNeedRealname\nH5 跳转实名页]

图三：GetEffectiveRealnamePolicy 取值逻辑

flowchart TD
    A[GetEffectiveRealnamePolicy\ncard, device] --> B{device != nil?}
    B -->|是| C[返回 device.RealnamePolicy]
    B -->|否| D{card != nil?}
    D -->|是| E[返回 card.RealnamePolicy]
    D -->|否| F[返回 none]

资产类型与策略归属

系统有两类资产：独立卡 和设备。

资产类型	realname_policy 归属	H5 视角
独立卡（无设备绑定）	卡自身的 `realname_policy`	卡视角
设备	设备自身的 `realname_policy`	设备视角
设备下的卡	设备的 `realname_policy`（卡自身策略无效）	设备视角

关键规则：设备下的卡无法以卡视角独立登录 H5，登录后自动进入设备视角，因此实名流程策略由设备决定，卡自身的 realname_policy 字段对 H5 流程无影响（但字段保留，仅作记录）。

该逻辑已在 internal/service/asset/service.go:GetEffectiveRealnamePolicy() 实现：设备不为 nil 时取设备策略，否则取卡策略。

当前字段状态

两个模型都已有 realname_policy 字段，无需迁移：

// internal/model/iot_card.go
RealnamePolicy string `gorm:"column:realname_policy;type:varchar(20);default:'after_order';not null;
    comment:实名认证策略(none=无需实名,before_order=先实名后充值/购买,after_order=先充值/购买后实名)"`

// internal/model/device.go
RealnamePolicy string `gorm:"column:realname_policy;type:varchar(20);default:'after_order';not null;
    comment:实名认证策略(none=无需实名,before_order=先实名后充值/购买,after_order=先充值/购买后实名)"`

值含义：

none — 无需实名
before_order — 先实名后充值
after_order — 先充值后实名（当前默认）

后端实现

1. 单条修改接口（已有，无需新建）

PATCH /api/admin/assets/:identifier/realname-mode

该接口已在 internal/handler/admin/asset.go:UpdateRealnamePolicy() 实现，通过 identifier 自动解析资产类型，卡和设备都走这里，不需要再建卡专属或设备专属路由。

请求体（已有 DTO）：

type UpdateAssetRealnamePolicyRequest struct {
    RealnamePolicy string `json:"realname_policy" validate:"required,oneof=none before_order after_order"
        description:"实名策略 (none:无需实名, before_order:先实名后充值, after_order:先充值后实名)"`
}

2. 新增批量修改接口（需新建）

卡和设备分开批量接口，因为两者在后台是不同的列表页。

2a. 批量修改卡实名策略

POST /admin/iot-cards/batch-update-realname-policy

请求体：

type BatchUpdateIotCardRealnamePolicy struct {
    IotCardIDs     []uint `json:"iot_card_ids" validate:"required,min=1" description:"卡ID列表"`
    RealnamePolicy string `json:"realname_policy" validate:"required,oneof=none before_order after_order"
        description:"实名策略 (none:无需实名, before_order:先实名后充值, after_order:先充值后实名)"`
}

Service：UPDATE tb_iot_cards SET realname_policy = ? WHERE id IN (...)，逐条写审计日志。

2b. 批量修改设备实名策略

POST /admin/devices/batch-update-realname-policy

请求体：

type BatchUpdateDeviceRealnamePolicy struct {
    DeviceIDs      []uint `json:"device_ids" validate:"required,min=1" description:"设备ID列表"`
    RealnamePolicy string `json:"realname_policy" validate:"required,oneof=none before_order after_order"
        description:"实名策略 (none:无需实名, before_order:先实名后充值, after_order:先充值后实名)"`
}

Service：UPDATE tb_devices SET realname_policy = ? WHERE id IN (...)，逐条写审计日志。

3. 全局默认值（兜底）

新建卡/设备时默认 after_order，通过 GORM default 标签保证，不需要读 tb_system_config。

前端对接

卡列表页

"操作"列或批量操作下拉增加"设置实名策略"：

单条：弹框选策略 → PATCH /api/admin/assets/{iccid}/realname-mode
批量：勾选多条 → 批量操作 → "设置实名策略" → POST /admin/iot-cards/batch-update-realname-policy

注意：设备下的卡即使在卡列表中修改了策略，对 H5 流程也无效（H5 取设备策略）。建议在卡列表展示"所属设备"列，提示运营该卡已属于某设备，实名策略需到设备处修改。

设备列表页