# 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
```

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

```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 | ✅ | 充值金额（分），范围 100~10000000（1 元~10 万元） |
| `payment_method` | string | ✅ | 支付方式：`wechat` / `alipay`（支付宝保留但本次不改造） |

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

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

```json
{
  "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** 系统返回错误

```json
{
  "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` 作为关联上下文