迭代计划准备

docs/7月迭代/基础设施/系统配置.md

@@ -1,6 +1,7 @@
 # 基础设施：系统配置（tb_system_config）
 
-> 被依赖：需求 02（H5流程配置）、需求 09（C端支付限制）
+> 状态：待评审
+> 被依赖：需求 09（C端支付限制）
 
 ---
 
@@ -8,6 +9,25 @@
 
 将散落在代码里的"写死配置"提取到数据库，平台管理员可通过后台页面修改，无需重新部署。
 
+```mermaid
+sequenceDiagram
+    actor Admin as 平台超管
+    participant Web as 后台配置页
+    participant API as SystemConfig Application
+    participant DB as PostgreSQL
+    participant Redis as Redis
+    participant Biz as 业务读取方
+
+    Admin->>Web: 修改受控配置表单
+    Web->>API: PUT /api/admin/system/config/{config_key}
+    API->>API: 按配置 key 注册规则校验类型和值域
+    API->>DB: 更新值并写审计日志
+    API->>Redis: 删除对应缓存
+    API-->>Web: 返回最新配置和更新时间
+    Biz->>Redis: 下次读取缓存未命中
+    Biz->>DB: 读取最新配置并回填缓存
+```
+
 ---
 
 ## 二、数据库
@@ -35,14 +55,11 @@ COMMENT ON TABLE tb_system_config IS '系统全局配置表';
 INSERT INTO tb_system_config (config_key, config_value, value_type, module, description) VALUES
 -- C端支付限制（需求9）
 ('c2b.payment.card_allowed_methods',   '["alipay","wallet"]',   'json',   'c2b.payment', '卡资产C端允许的支付方式（alipay/wechat/wallet）'),
-('c2b.payment.device_allowed_methods', '["wechat","wallet"]',   'json',   'c2b.payment', '设备C端允许的支付方式'),
-
--- H5流程顺序（需求2，per-asset 覆盖，此处是全局默认）
--- 注意：per-asset 的 realname_policy 已在 iot_card.realname_policy 字段存储
--- 此处仅存"H5绑定手机后的默认流程"
-('h5.flow.default_realname_policy', 'after_order', 'string', 'h5.flow', 'H5新用户默认实名策略（none/before_order/after_order）');
+('c2b.payment.device_allowed_methods', '["wechat","wallet"]',   'json',   'c2b.payment', '设备C端允许的支付方式');
 ```
 
+需求02不写入全局默认实名策略。H5 始终读取卡或设备自身的 `realname_policy`；新建资产使用模型默认 `after_order`，避免全局 Key 与资产字段产生两套优先级。
+
 ---
 
 ## 三、Model
@@ -123,7 +140,7 @@ allowedMethods, _ := sysconfig.GetStringSlice(ctx, "c2b.payment.card_allowed_met
 ### 6.1 获取配置列表
 
 ```
-GET /admin/system/config?module=c2b.payment
+GET /api/admin/system/config?module=c2b.payment
 ```
 
 响应：
@@ -148,7 +165,7 @@ GET /admin/system/config?module=c2b.payment
 ### 6.2 更新配置
 
 ```
-PUT /admin/system/config/{config_key}
+PUT /api/admin/system/config/{config_key}
 ```
 
 请求体：
@@ -187,6 +204,8 @@ type UpdateSystemConfigRequest struct {
 }
 ```
 
+更新接口不能只校验 `value_type`。Application 需要按 `config_key` 注册允许值，例如支付方式只能来自 `alipay/wechat/wallet`，实名策略只能来自 `none/before_order/after_order`。未知 key 默认只读，禁止通过通用页面写入任意系统配置。
+
 ---
 
 ## 七、前端对接
@@ -196,10 +215,10 @@ type UpdateSystemConfigRequest struct {
 **初期可以做一个通用的 Key-Value 管理页面，按 module 分组展示。**
 
 调用流程：
-1. 进入页面 → `GET /admin/system/config`（不传 module = 返回全部）
+1. 进入页面 → `GET /api/admin/system/config`（不传 module = 返回全部）
 2. 按 module 分组展示，`is_readonly=true` 的配置只读
-3. 修改某项 → `PUT /admin/system/config/{config_key}`，body: `{config_value}`
-4. 修改成功后提示"配置已更新，约5分钟后生效"（Redis 缓存 TTL）
+3. 修改某项 → `PUT /api/admin/system/config/{config_key}`，body: `{config_value}`
+4. 更新成功后后端立即删除该 key 的缓存，前端提示“配置已更新”并刷新当前值
 
 **C端支付限制配置展示建议**（针对 `c2b.payment` 模块）：
 
@@ -214,3 +233,5 @@ type UpdateSystemConfigRequest struct {
 ```
 
 前端把选中项序列化成 `["alipay","wallet"]` 提交。
+
+通用 Key-Value 页面只作为管理壳层，已知业务配置必须使用受控组件（单选、复选或开关），不向运营人员暴露 JSON 文本框。