huang
b9733c4913
All checks were successful
构建并部署到测试环境（无 SSH） / build-and-deploy (push) Successful in 7m12s
1. 修正 retail_price 架构：
- 删除 batch-pricing 接口的 pricing_target 字段和 retail_price 分支
（上级只能改下级成本价，不能改零售价）
- 新增 PATCH /api/admin/packages/:id/retail-price 接口
（代理自己改自己的零售价，校验 retail_price >= cost_price）
2. 清理旧微信 YAML 配置（已全部迁移到数据库 tb_wechat_config）：
- 删除 config.yaml 中 wechat.official_account 配置节
- 删除 NewOfficialAccountApp() 旧工厂函数
- 清理 personal_customer service 中的死代码（旧登录/绑定微信方法）
- 清理 docker-compose.prod.yml 中旧微信环境变量和证书挂载注释
3. 归档四个已完成提案到 openspec/changes/archive/
4. 新增前端接口变更说明文档（docs/前端接口变更说明.md）
5. 修正归档提案和 specs 中关于 pricing_target 的错误描述
151 lines
5.5 KiB
Markdown
151 lines
5.5 KiB
Markdown
# 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` 作为关联上下文
|
||
|