迭代计划准备

docs/7月迭代/需求09-C端支付限制配置化.md

@@ -1,5 +1,6 @@
 # 需求09：C端支付方式限制配置化
 
+> 状态：待评审
 > 依赖：[系统配置](./基础设施/系统配置.md)
 
 ---
@@ -25,6 +26,21 @@
 
 **钱包支付对所有资产类型均允许。**
 
+```mermaid
+flowchart TD
+    Pay[用户选择支付方式] --> Asset{资产类型}
+    Asset -->|IoT卡| Card[读取卡允许方式]
+    Asset -->|设备| Device[读取设备允许方式]
+    Asset -->|未知| RejectUnknown[拒绝：资产类型无效]
+    Card --> ConfigOK{配置可用?}
+    Device --> ConfigOK
+    ConfigOK -->|是| Match{支付方式在允许集合?}
+    ConfigOK -->|否| SafeDefault[使用代码内安全默认集合]
+    SafeDefault --> Match
+    Match -->|是| Continue[继续支付]
+    Match -->|否| Reject[拒绝并返回对应中文提示]
+```
+
 ---
 
 ## 实现方案
@@ -56,14 +72,16 @@ func (s *Service) validatePaymentMethod(ctx context.Context, assetType string, p
     case model.AssetTypeDevice: // "device"，定义在 internal/model/asset_identifier.go
         configKey = "c2b.payment.device_allowed_methods"
     default:
-        return nil // 未知资产类型不限制
+        return errors.New(errors.CodeInvalidParam, "资产类型无效")
     }
 
     allowedMethods, err := sysconfig.GetStringSlice(ctx, configKey)
     if err != nil || len(allowedMethods) == 0 {
-        // 配置读取失败，降级为允许（防止配置问题影响支付）
-        s.logger.Warn("读取支付方式配置失败，降级为允许", zap.String("config_key", configKey))
-        return nil
+        // 配置异常时回退到代码内安全默认值，禁止放开全部支付方式。
+        allowedMethods = defaultAllowedMethods(assetType)
+        s.logger.Error("读取支付方式配置失败，已使用安全默认值",
+            zap.String("config_key", configKey),
+            zap.Error(err))
     }
 
     for _, m := range allowedMethods {
@@ -77,6 +95,8 @@ func (s *Service) validatePaymentMethod(ctx context.Context, assetType string, p
 
 在 `client_wallet.go`（充值）和 `client_order/service.go`（订单支付）的对应位置恢复调用。
 
+系统配置更新时必须保证 `wallet` 始终存在于两个允许集合中；前端将钱包选项显示为勾选且不可取消，后端再次校验，避免配置破坏业务规则。
+
 ### 3. 错误信息
 
 用户端错误提示（友好文案）：
@@ -97,13 +117,17 @@ case model.AssetTypeDevice:
 
 ### C端支付页面
 
-前端在展示支付方式时，根据资产类型**过滤不可用的支付方式**（前端主动隐藏，后端兜底拦截）。
+前端不维护另一份固定规则。资产初始化/详情接口返回后端已经计算好的：
 
-前端需要从哪里知道"当前资产是卡还是设备"？登录/初始化时返回 `asset_type`，前端保存上下文。
+```go
+AllowedPaymentMethods []string `json:"allowed_payment_methods" description:"当前资产允许的支付方式"`
+```
+
+支付页只展示该集合中的方式，后端支付接口再次执行相同校验。配置变化后重新进入支付页或刷新资产信息即可获得新集合。
 
 ```
-资产类型 = "iot_card" → 展示支付方式：支付宝、余额
-资产类型 = "device"   → 展示支付方式：微信、余额
+allowed_payment_methods = ["alipay", "wallet"] → 展示支付宝、余额
+allowed_payment_methods = ["wechat", "wallet"] → 展示微信、余额
 ```
 
 ### 后台配置页面
@@ -115,6 +139,8 @@ case model.AssetTypeDevice:
 设备允许支付方式：  ☐ 支付宝   ☑ 余额   ☑ 微信
 ```
 
-修改后调用 `PUT /admin/system/config/c2b.payment.card_allowed_methods`。
+余额选项固定勾选且禁用，不允许管理员取消。
+
+修改后调用 `PUT /api/admin/system/config/c2b.payment.card_allowed_methods`。
 
 > 注意：**微信支付参数申请下来后**，直接在系统配置里把对应资产类型勾上微信即可生效，无需改代码。