junhong_cmp_fiber/openspec/specs/asset-recharge-adaptation/spec.md

asset-recharge-adaptation Specification

Purpose

定义资产充值（IoT 卡/设备钱包充值）的完整规范：支付配置关联、充值记录表结构变更、回调验签流程及钱包常量从 Card 前缀统一重命名为 Asset 前缀。

Requirements

Requirement: 资产充值关联支付配置

系统 SHALL 在创建资产充值订单时记录当前生效的支付配置 ID，用于回调处理时加载正确的配置验签。

Scenario: 创建充值订单时记录支付配置 ID

• WHEN 个人客户创建资产充值订单（IoT 卡钱包或设备钱包充值）

POST /api/h5/wallets/recharge
Authorization: Bearer {token}
Content-Type: application/json

请求体（现有接口，字段不变）

{
  "resource_type": "iot_card",
  "resource_id": 101,
  "amount": 10000,
  "payment_method": "wechat"
}

字段	类型	必填	说明
resource_type	string	✅	资源类型：iot_card / device
resource_id	uint	✅	资源 ID（卡 ID 或设备 ID）
amount	int64	✅	充值金额（分），范围 10010000000（1 元10 万元）
payment_method	string	✅	支付方式：wechat / alipay（支付宝保留但本次不改造）

• THEN 系统查询当前生效的微信参数配置
• THEN 将 payment_config_id 写入充值记录

成功响应 200 OK（新增 payment_config_id 字段）

{
  "code": 0,
  "data": {
    "id": 1,
    "recharge_no": "CRCH20260316100000654321",
    "user_id": 100,
    "wallet_id": 50,
    "amount": 10000,
    "payment_method": "wechat",
    "payment_config_id": 1,
    "status": 1,
    "status_text": "待支付",
    "created_at": "2026-03-16T10:00:00+08:00",
    "updated_at": "2026-03-16T10:00:00+08:00"
  },
  "msg": "success",
  "timestamp": "2026-03-16T10:00:00+08:00"
}

Scenario: 无生效配置时拒绝第三方充值

• WHEN 个人客户创建充值订单（wechat/alipay），但当前无生效的微信参数配置
• THEN 系统返回错误

{
  "code": 1175,
  "data": null,
  "msg": "暂无可用的第三方支付渠道",
  "timestamp": "2026-03-16T10:00:00+08:00"
}

---

Requirement: 资产充值表结构变更

系统 MUST 在 tb_asset_recharge_record 新增以下字段，用于关联支付配置。

字段	类型	必填	说明
payment_config_id	bigint	❌	创建充值订单时使用的微信参数配置 ID（支付宝支付时为 NULL）

Scenario: 新建充值记录含 payment_config_id 字段

• WHEN 个人客户创建微信充值订单
• THEN 系统 MUST 将当前生效的微信参数配置 ID 写入 payment_config_id 字段

---

Requirement: 资产充值回调按配置验签

系统 MUST 在处理资产充值支付回调时，通过 payment_config_id 加载对应配置并使用该配置验签。

Scenario: 收到充值回调按配置验签

• WHEN 收到支付回调（微信或富友），订单号前缀为 CRCH
• THEN 系统 MUST 查询 tb_asset_recharge_record，通过 payment_config_id 加载对应配置
• THEN 系统 MUST 使用该配置的凭证验签
• THEN 验签通过后调用 rechargeService.HandlePaymentCallback()

---

Requirement: 常量重命名（Card → Asset）

系统 MUST 将 pkg/constants/wallet.go 中以下常量从 Card 前缀重命名为 Asset 前缀，旧常量保留为废弃别名。

旧名称	新名称
CardWalletResourceTypeIotCard	AssetWalletResourceTypeIotCard
CardWalletResourceTypeDevice	AssetWalletResourceTypeDevice
CardWalletStatusNormal	AssetWalletStatusNormal
CardWalletStatusFrozen	AssetWalletStatusFrozen
CardWalletStatusClosed	AssetWalletStatusClosed
CardTransactionTypeRecharge	AssetTransactionTypeRecharge
CardTransactionTypeDeduct	AssetTransactionTypeDeduct
CardTransactionTypeRefund	AssetTransactionTypeRefund
CardRechargeOrderPrefix	AssetRechargeOrderPrefix
CardRechargeMinAmount	AssetRechargeMinAmount
CardRechargeMaxAmount	AssetRechargeMaxAmount

Scenario: 新代码使用 Asset 前缀常量

• WHEN 业务代码引用钱包资源类型或充值相关常量
• THEN 系统 MUST 使用 Asset* 前缀常量，Card* 常量标注 Deprecated

Requirement: 资产充值记录扩展字段（操作人与代际）

系统 MUST 在 tb_asset_recharge_record 新增以下字段：

字段	类型	必填	说明
operator_type	varchar(20)	✅	操作人类型，枚举 admin_user / personal_customer，默认 admin_user
generation	int	✅	资产代际，默认 1
linked_package_ids	jsonb	❌	关联套餐 ID 列表，默认 '[]'
linked_order_type	varchar(20)	❌	关联订单类型
linked_carrier_type	varchar(20)	❌	关联载体类型（如 iot_card/device）
linked_carrier_id	bigint	❌	关联载体 ID

Scenario: 新建充值记录默认字段值

• WHEN 系统创建新的资产充值记录且未显式传入新增字段
• THEN operator_type MUST 默认为 admin_user
• THEN generation MUST 默认为 1
• THEN linked_package_ids MUST 默认为空数组 []

Scenario: 写入关联上下文信息

• WHEN 充值记录由订单或套餐联动产生
• THEN 系统 MUST 可写入 linked_order_type、linked_carrier_type、linked_carrier_id 作为关联上下文