217 lines
6.9 KiB
Markdown
217 lines
6.9 KiB
Markdown
# 基础设施：系统配置（tb_system_config）
|
||
|
||
> 被依赖：需求 02（H5流程配置）、需求 09（C端支付限制）
|
||
|
||
---
|
||
|
||
## 一、设计目标
|
||
|
||
将散落在代码里的"写死配置"提取到数据库，平台管理员可通过后台页面修改，无需重新部署。
|
||
|
||
---
|
||
|
||
## 二、数据库
|
||
|
||
```sql
|
||
-- 迁移文件：YYYYMMDD_create_tb_system_config.sql
|
||
CREATE TABLE tb_system_config (
|
||
id BIGSERIAL PRIMARY KEY,
|
||
config_key VARCHAR(100) NOT NULL, -- 唯一键，格式：module.group.name
|
||
config_value TEXT NOT NULL DEFAULT '', -- 值（string/number/json字符串）
|
||
value_type VARCHAR(20) NOT NULL DEFAULT 'string', -- string | int | bool | json
|
||
module VARCHAR(50) NOT NULL DEFAULT 'general', -- 所属模块（便于按模块查询）
|
||
description TEXT, -- 中文说明（前端展示用）
|
||
is_readonly BOOLEAN NOT NULL DEFAULT FALSE, -- 是否只读（代码内部，不允许后台改）
|
||
creator BIGINT NOT NULL DEFAULT 0,
|
||
updater BIGINT NOT NULL DEFAULT 0,
|
||
created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
|
||
CONSTRAINT uq_system_config_key UNIQUE (config_key)
|
||
);
|
||
|
||
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）');
|
||
```
|
||
|
||
---
|
||
|
||
## 三、Model
|
||
|
||
```go
|
||
// internal/model/system_config.go
|
||
|
||
// SystemConfig 系统全局配置模型
|
||
type SystemConfig struct {
|
||
ID uint `gorm:"column:id;primaryKey" json:"id"`
|
||
ConfigKey string `gorm:"column:config_key;uniqueIndex;not null" json:"config_key"`
|
||
ConfigValue string `gorm:"column:config_value;type:text;not null;default:''" json:"config_value"`
|
||
ValueType string `gorm:"column:value_type;type:varchar(20);not null;default:'string'" json:"value_type"`
|
||
Module string `gorm:"column:module;type:varchar(50);not null;default:'general';index" json:"module"`
|
||
Description string `gorm:"column:description;type:text" json:"description"`
|
||
IsReadonly bool `gorm:"column:is_readonly;not null;default:false" json:"is_readonly"`
|
||
Creator uint `gorm:"column:creator;not null;default:0" json:"creator"`
|
||
Updater uint `gorm:"column:updater;not null;default:0" json:"updater"`
|
||
CreatedAt time.Time `gorm:"column:created_at" json:"created_at"`
|
||
UpdatedAt time.Time `gorm:"column:updated_at" json:"updated_at"`
|
||
}
|
||
|
||
func (SystemConfig) TableName() string { return "tb_system_config" }
|
||
```
|
||
|
||
---
|
||
|
||
## 四、Store
|
||
|
||
```go
|
||
// internal/store/postgres/system_config_store.go
|
||
|
||
type SystemConfigStore struct {
|
||
db *gorm.DB
|
||
}
|
||
|
||
func (s *SystemConfigStore) GetByKey(ctx context.Context, key string) (*model.SystemConfig, error)
|
||
func (s *SystemConfigStore) GetByModule(ctx context.Context, module string) ([]model.SystemConfig, error)
|
||
func (s *SystemConfigStore) UpdateValue(ctx context.Context, key string, value string, updaterID uint) error
|
||
func (s *SystemConfigStore) BatchGet(ctx context.Context, keys []string) (map[string]*model.SystemConfig, error)
|
||
```
|
||
|
||
---
|
||
|
||
## 五、配置读取辅助包
|
||
|
||
业务代码不直接操作 Store，通过辅助函数读取，带 Redis 缓存（5分钟TTL）：
|
||
|
||
```go
|
||
// pkg/sysconfig/config.go
|
||
|
||
// GetString 读取字符串配置，返回默认值
|
||
func GetString(ctx context.Context, key string, defaultVal string) string
|
||
|
||
// GetStringSlice 读取 JSON 数组配置
|
||
func GetStringSlice(ctx context.Context, key string) ([]string, error)
|
||
|
||
// GetBool 读取布尔配置
|
||
func GetBool(ctx context.Context, key string, defaultVal bool) bool
|
||
|
||
// InvalidateCache 更新配置后清缓存（在 UpdateValue 后调用）
|
||
func InvalidateCache(ctx context.Context, key string)
|
||
```
|
||
|
||
Redis Key：`sys:config:{config_key}`，TTL 5分钟。
|
||
|
||
业务代码用法：
|
||
```go
|
||
// 读取卡的允许支付方式
|
||
allowedMethods, _ := sysconfig.GetStringSlice(ctx, "c2b.payment.card_allowed_methods")
|
||
// 返回 ["alipay","wallet"]
|
||
```
|
||
|
||
---
|
||
|
||
## 六、API 设计
|
||
|
||
### 6.1 获取配置列表
|
||
|
||
```
|
||
GET /admin/system/config?module=c2b.payment
|
||
```
|
||
|
||
响应：
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"data": {
|
||
"list": [
|
||
{
|
||
"config_key": "c2b.payment.card_allowed_methods",
|
||
"config_value": "[\"alipay\",\"wallet\"]",
|
||
"value_type": "json",
|
||
"description": "卡资产C端允许的支付方式",
|
||
"is_readonly": false,
|
||
"updated_at": "2026-07-11T10:00:00Z"
|
||
}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 6.2 更新配置
|
||
|
||
```
|
||
PUT /admin/system/config/{config_key}
|
||
```
|
||
|
||
请求体：
|
||
```json
|
||
{
|
||
"config_value": "[\"alipay\",\"wallet\",\"wechat\"]"
|
||
}
|
||
```
|
||
|
||
权限：仅平台超管可操作。
|
||
|
||
### DTO
|
||
|
||
```go
|
||
// internal/model/dto/system_config_dto.go
|
||
|
||
// SystemConfigListRequest 配置列表查询请求
|
||
type SystemConfigListRequest struct {
|
||
Module string `query:"module" description:"按模块过滤（可选）"`
|
||
}
|
||
|
||
// SystemConfigItem 配置项响应
|
||
type SystemConfigItem struct {
|
||
ConfigKey string `json:"config_key"`
|
||
ConfigValue string `json:"config_value"`
|
||
ValueType string `json:"value_type" description:"值类型 (string/int/bool/json)"`
|
||
Module string `json:"module"`
|
||
Description string `json:"description"`
|
||
IsReadonly bool `json:"is_readonly"`
|
||
UpdatedAt time.Time `json:"updated_at"`
|
||
}
|
||
|
||
// UpdateSystemConfigRequest 更新配置请求
|
||
type UpdateSystemConfigRequest struct {
|
||
ConfigValue string `json:"config_value" validate:"required" description:"新配置值"`
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 七、前端对接
|
||
|
||
### 页面：系统设置 > 系统配置
|
||
|
||
**初期可以做一个通用的 Key-Value 管理页面，按 module 分组展示。**
|
||
|
||
调用流程：
|
||
1. 进入页面 → `GET /admin/system/config`（不传 module = 返回全部）
|
||
2. 按 module 分组展示，`is_readonly=true` 的配置只读
|
||
3. 修改某项 → `PUT /admin/system/config/{config_key}`，body: `{config_value}`
|
||
4. 修改成功后提示"配置已更新，约5分钟后生效"（Redis 缓存 TTL）
|
||
|
||
**C端支付限制配置展示建议**（针对 `c2b.payment` 模块）：
|
||
|
||
不要让后台用户手动填 JSON，前端渲染成 CheckboxGroup：
|
||
|
||
```
|
||
卡资产允许支付方式：
|
||
☑ 支付宝 ☑ 钱包 ☐ 微信
|
||
|
||
设备允许支付方式：
|
||
☐ 支付宝 ☑ 钱包 ☑ 微信
|
||
```
|
||
|
||
前端把选中项序列化成 `["alipay","wallet"]` 提交。
|