akmon/NEW_CONFIG_INTEGRATION_GUIDE.md

新配置系统集成指南

数据库结构

主表+翻译表设计

-- 主配置表
ak_global_config (
  id UUID PRIMARY KEY,
  config_key VARCHAR(100) UNIQUE,
  config_type VARCHAR(50),
  config_category VARCHAR(50),
  default_value TEXT,
  is_translatable BOOLEAN,
  is_active BOOLEAN,
  sort_order INTEGER
)

-- 翻译表
ak_global_config_translations (
  id UUID PRIMARY KEY,
  config_id UUID REFERENCES ak_global_config(id),
  language_code VARCHAR(10),
  translated_value TEXT NOT NULL,
  is_active BOOLEAN
)

-- 语言表（保留现有）
ak_languages (
  id UUID PRIMARY KEY,
  code VARCHAR(10) UNIQUE,
  name VARCHAR(100),
  native_name VARCHAR(100),
  is_active BOOLEAN
)

前端集成

1. 数据获取方式（优先级顺序）

方式1：使用优化函数（推荐）

const result = await supa.rpc('get_configs_by_language', { 
  p_language_code: 'zh' 
})

方式2：使用多语言视图

const result = await supa
  .from('vw_global_config_multilingual')
  .select('config_key, config_value, config_type, config_category')
  .eq('language_code', 'zh')
  .eq('is_active', true)

方式3：主表+翻译表联查

const result = await supa
  .from('ak_global_config')
  .select(`
    config_key,
    config_type,
    config_category,
    default_value,
    is_translatable,
    ak_global_config_translations!left(
      language_code,
      translated_value
    )
  `)
  .eq('is_active', true)

2. 语言代码映射

const getStandardLanguageCode = (langCode: string): string => {
  switch (langCode) {
    case 'en':
    case 'en-US':
      return 'en'
    case 'zh-TW':
      return 'tw' 
    case 'ja':
    case 'ja-JP':
      return 'ja'
    case 'zh-CN':
    case 'zh':
    default:
      return 'zh'
  }
}

3. 配置使用

公司基本信息

• company_name - 公司名称（多语言）
• company_slogan - 公司标语（多语言）
• company_address - 公司地址（多语言）
• company_phone - 联系电话（无多语言）
• company_email - 邮箱（无多语言）
• company_icp - ICP备案（无多语言）
• company_logo_url - LOGO链接（无多语言）

社交媒体链接

• social_wechat_url - 微信链接
• social_weibo_url - 微博链接
• social_qq_url - QQ链接
• social_linkedin_url - LinkedIn链接
• social_twitter_url - Twitter链接

热门搜索关键词

• hot_search_1 - 关键词1（多语言）
• hot_search_2 - 关键词2（多语言）
• hot_search_3 - 关键词3（多语言）
• hot_search_4 - 关键词4（多语言）
• hot_search_5 - 关键词5（多语言）

部署步骤

1. 数据库初始化

   -- 执行 improved_global_config_with_translation.sql
   

2. 清理旧表（可选）

   -- 执行 force_cleanup_new_tables.sql
   

3. 前端更新

   • 新的数据获取逻辑已集成到 comindex.uvue
   • 支持自动降级到不同查询方式
   • 包含完整的错误处理和默认配置

优势

数据库层面

• ✅ 结构清晰：主表+翻译表分离
• ✅ 性能优化：索引和视图支持
• ✅ 扩展性强：易于添加新语言和配置项
• ✅ 数据完整性：外键约束和触发器

前端层面

• ✅ 智能降级：多种查询方式自动切换
• ✅ 语言支持：完整的多语言代码映射
• ✅ 错误处理：完善的错误处理和默认配置
• ✅ 调试支持：开发环境调试面板

维护层面

• ✅ 易于管理：分类和排序支持
• ✅ 灵活配置：可翻译字段标识
• ✅ 版本控制：创建和更新时间记录
• ✅ 数据安全：RLS和权限控制

调试功能

开发环境调试面板

• 显示当前配置状态
• 测试多语言切换
• 验证数据库查询
• 配置值实时查看

控制台日志

• 详细的加载过程日志
• 错误信息和回退逻辑
• 配置更新状态追踪

注意事项

1. 语言代码一致性：确保前端和数据库使用相同的语言代码格式
2. 默认配置：始终提供默认配置作为最后的回退方案
3. 性能考虑：语言切换时重新加载配置，避免缓存问题
4. 错误处理：每个查询都有完整的错误处理机制