akmon/NEW_CONFIG_SYSTEM_GUIDE.md

新配置系统部署和使用指南

概述

本指南说明如何部署和使用新的 ak_global_config + ak_global_config_translations 配置系统，替代原有的 key 后缀方式。

部署步骤

1. 数据库部署

创建新表结构

# 执行新配置表结构脚本
psql -h your-host -U your-user -d your-db -f improved_global_config_with_translation.sql

数据迁移（如需要）

# 如果有现有数据需要迁移
psql -h your-host -U your-user -d your-db -f migrate_global_config_data.sql

2. 验证数据库函数

执行以下 SQL 验证函数是否正确创建：

-- 1. 验证批量配置获取函数
SELECT * FROM get_configs_by_language('zh') LIMIT 5;

-- 2. 验证单值配置获取函数
SELECT get_config_value('company_name', 'zh');

-- 3. 验证热门搜索函数
SELECT * FROM get_hot_searches('zh');

-- 4. 验证多语言视图
SELECT * FROM vw_global_config_multilingual 
WHERE language_code = 'zh' AND config_category = 'company';

3. 前端代码部署

前端代码已更新为支持以下回退机制：

1. 主要方法: get_configs_by_language(p_language_code) - 推荐使用
2. 备用方法1: get_config_by_language(lang_code) - 向后兼容
3. 备用方法2: 直接查询 vw_global_config_multilingual 视图
4. 兜底方案: 使用硬编码的默认配置

可用的数据库函数

1. 批量配置获取（推荐）

-- 函数签名
get_configs_by_language(p_language_code VARCHAR(10) DEFAULT 'zh')

-- 返回字段
config_key, config_value, config_type, config_category, sort_order

-- 使用示例
SELECT * FROM get_configs_by_language('zh');
SELECT * FROM get_configs_by_language('en');

2. 单值配置获取

-- 函数签名
get_config_value(p_config_key VARCHAR(100), p_language_code VARCHAR(10) DEFAULT 'zh')

-- 使用示例
SELECT get_config_value('company_name', 'zh');
SELECT get_config_value('company_phone', 'en'); -- 无多语言差异的配置

3. 热门搜索关键词

-- 函数签名
get_hot_searches(lang_code VARCHAR(10) DEFAULT 'zh')

-- 返回字段
search_term, sort_order

-- 使用示例
SELECT * FROM get_hot_searches('zh');

4. 多语言配置视图

-- 视图名称
vw_global_config_multilingual

-- 主要字段
config_key, config_value, config_type, config_category, language_code, is_active

-- 使用示例
SELECT * FROM vw_global_config_multilingual 
WHERE language_code = 'zh' AND config_category = 'company';

前端使用示例

JavaScript/TypeScript

// 使用 Supabase 客户端
const loadConfig = async (languageCode = 'zh') => {
  try {
    // 方法1: 使用 RPC 函数（推荐）
    const { data, error } = await supabase
      .rpc('get_configs_by_language', { 
        p_language_code: languageCode 
      });
    
    if (data && !error) {
      return data;
    }
    
    // 方法2: 使用视图查询（备用）
    const { data: fallbackData, error: fallbackError } = await supabase
      .from('vw_global_config_multilingual')
      .select('config_key, config_value, config_type, config_category')
      .eq('language_code', languageCode)
      .eq('is_active', true);
    
    return fallbackData || [];
  } catch (error) {
    console.error('配置加载失败:', error);
    return [];
  }
};

// 获取单个配置值
const getConfigValue = async (key, language = 'zh') => {
  try {
    const { data, error } = await supabase
      .rpc('get_config_value', {
        p_config_key: key,
        p_language_code: language
      });
    
    return data || null;
  } catch (error) {
    console.error('配置获取失败:', error);
    return null;
  }
};

// 使用示例
const companyName = await getConfigValue('company_name', 'zh');
const configs = await loadConfig('en');

配置管理

添加新配置项

-- 1. 添加主配置记录
INSERT INTO ak_global_config (
    config_key, 
    config_category, 
    is_translatable, 
    sort_order,
    default_value
) VALUES (
    'new_config_key',
    'category_name',
    true, -- 或 false，表示是否需要翻译
    100,
    'default_value'
);

-- 2. 如果需要翻译，添加翻译记录
INSERT INTO ak_global_config_translations (config_id, language_code, translated_value)
SELECT 
    c.id,
    'zh',
    '中文值'
FROM ak_global_config c
WHERE c.config_key = 'new_config_key';

-- 重复上述步骤为其他语言添加翻译

更新配置值

-- 更新不需要翻译的配置
UPDATE ak_global_config 
SET default_value = 'new_value'
WHERE config_key = 'config_key';

-- 更新需要翻译的配置
UPDATE ak_global_config_translations 
SET translated_value = 'new_translated_value'
WHERE config_id = (
    SELECT id FROM ak_global_config WHERE config_key = 'config_key'
) AND language_code = 'zh';

添加新语言

-- 1. 添加语言记录
INSERT INTO ak_languages (code, name, native_name, sort_order)
VALUES ('fr', 'French', 'Français', 5);

-- 2. 为可翻译的配置添加法语翻译
INSERT INTO ak_global_config_translations (config_id, language_code, translated_value)
SELECT 
    c.id,
    'fr',
    'French translation here'
FROM ak_global_config c
WHERE c.is_translatable = true;

调试和故障排除

前端调试

页面包含了调试面板（仅在开发环境显示），可以：

1. 查看当前配置状态
2. 测试各种数据库函数
3. 手动重新加载配置

数据库调试

-- 检查配置数量
SELECT 
    config_category,
    COUNT(*) as config_count
FROM ak_global_config 
WHERE is_active = true
GROUP BY config_category;

-- 检查翻译完整性
SELECT 
    c.config_key,
    c.is_translatable,
    COUNT(t.language_code) as translation_count
FROM ak_global_config c
LEFT JOIN ak_global_config_translations t ON c.id = t.config_id
WHERE c.is_active = true
GROUP BY c.config_key, c.is_translatable
ORDER BY c.config_key;

-- 检查缺失的翻译
SELECT 
    c.config_key,
    l.code as missing_language
FROM ak_global_config c
CROSS JOIN ak_languages l
LEFT JOIN ak_global_config_translations t 
    ON c.id = t.config_id AND l.code = t.language_code
WHERE c.is_translatable = true 
    AND c.is_active = true 
    AND l.is_active = true
    AND t.id IS NULL;

常见问题

1. 函数不存在错误

   • 确认是否执行了 improved_global_config_with_translation.sql
   • 检查函数是否在正确的 schema 中创建

2. 配置加载失败

   • 检查表是否存在数据
   • 验证 is_active 字段设置正确
   • 检查语言代码是否匹配

3. 翻译缺失

   • 使用调试 SQL 检查翻译完整性
   • 确认 is_translatable 字段设置正确

性能优化

1. 索引优化

   • 确保相关索引已创建（脚本中已包含）
   • 监控查询性能

2. 缓存策略

   • 前端可以缓存配置数据
   • 考虑使用 Redis 等缓存解决方案

3. 查询优化

   • 优先使用 RPC 函数而非复杂视图查询
   • 按需加载配置分类

总结

新的配置系统提供了：

• ✅ 更科学的数据结构设计
• ✅ 更灵活的多语言支持
• ✅ 更好的扩展性和维护性
• ✅ 向后兼容的迁移方案
• ✅ 完善的调试和监控工具

通过本指南，您可以成功部署和使用新的全局配置系统。