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

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

## 部署步骤

### 1. 数据库部署

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

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

### 2. 验证数据库函数

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

```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. 批量配置获取（推荐）
```sql
-- 函数签名
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. 单值配置获取
```sql
-- 函数签名
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. 热门搜索关键词
```sql
-- 函数签名
get_hot_searches(lang_code VARCHAR(10) DEFAULT 'zh')

-- 返回字段
search_term, sort_order

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

### 4. 多语言配置视图
```sql
-- 视图名称
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
```javascript
// 使用 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');
```

## 配置管理

### 添加新配置项
```sql
-- 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';

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

### 更新配置值
```sql
-- 更新不需要翻译的配置
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';
```

### 添加新语言
```sql
-- 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. 手动重新加载配置

### 数据库调试
```sql
-- 检查配置数量
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 函数而非复杂视图查询
   - 按需加载配置分类

## 总结

新的配置系统提供了：
- ✅ 更科学的数据结构设计
- ✅ 更灵活的多语言支持
- ✅ 更好的扩展性和维护性
- ✅ 向后兼容的迁移方案
- ✅ 完善的调试和监控工具

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