Initial commit of akmon project

2026-01-20 08:04:15 +08:00
commit 77a2bab985
1309 changed files with 343305 additions and 0 deletions
--- a/NEW_CONFIG_SYSTEM_GUIDE.md
+++ b/NEW_CONFIG_SYSTEM_GUIDE.md
@@ -0,0 +1,295 @@
+# 新配置系统部署和使用指南
+
+## 概述
+本指南说明如何部署和使用新的 `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 函数而非复杂视图查询
+   - 按需加载配置分类
+
+## 总结
+
+新的配置系统提供了：
+- ✅ 更科学的数据结构设计
+- ✅ 更灵活的多语言支持
+- ✅ 更好的扩展性和维护性
+- ✅ 向后兼容的迁移方案
+- ✅ 完善的调试和监控工具
+
+通过本指南，您可以成功部署和使用新的全局配置系统。