docs: 新增 OpenSpec 提案 add-payment-config-management

包含 proposal.md、design.md、tasks.md 及各模块 spec 文件（微信配置管理、富友支付、代理充值、订单支付、资产充值适配、微信支付留桩） Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-opencode) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-03-16 23:30:39 +08:00
parent 429edf0d19
commit 63ca12393b
10 changed files with 2797 additions and 0 deletions
--- a/openspec/changes/add-payment-config-management/specs/asset-recharge-adaptation/spec.md
+++ b/openspec/changes/add-payment-config-management/specs/asset-recharge-adaptation/spec.md
@@ -0,0 +1,116 @@
+## MODIFIED 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: 资产充值表结构变更
+
+`tb_asset_recharge_record` 新增字段：
+
+| 字段 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `payment_config_id` | bigint | ❌ | 创建充值订单时使用的微信参数配置 ID（支付宝支付时为 NULL） |
+
+---
+
+### Requirement: 资产充值回调按配置验签
+
+- **WHEN** 收到支付回调（微信或富友），订单号前缀为 `CRCH`
+- **THEN** 系统查询 `tb_asset_recharge_record`，通过 `payment_config_id` 加载对应配置
+- **THEN** 使用该配置的凭证验签
+- **THEN** 验签通过后调用 `rechargeService.HandlePaymentCallback()`
+
+> **注意**：当前代码中 `callback/payment.go` 使用废弃的 `RechargeOrderPrefix = "RCH"` 进行前缀匹配，需修复为 `AssetRechargeOrderPrefix = "CRCH"`。
+
+---
+
+### Requirement: 常量重命名（Card → Asset）
+
+`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` |
+
+旧 `Card*` 常量保留为废弃别名，添加 `Deprecated` 注释。段落标题 `卡钱包常量` → `资产钱包常量`。