296 lines
7.2 KiB
Markdown
296 lines
7.2 KiB
Markdown
# 新配置系统部署和使用指南
|
||
|
||
## 概述
|
||
本指南说明如何部署和使用新的 `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 函数而非复杂视图查询
|
||
- 按需加载配置分类
|
||
|
||
## 总结
|
||
|
||
新的配置系统提供了：
|
||
- ✅ 更科学的数据结构设计
|
||
- ✅ 更灵活的多语言支持
|
||
- ✅ 更好的扩展性和维护性
|
||
- ✅ 向后兼容的迁移方案
|
||
- ✅ 完善的调试和监控工具
|
||
|
||
通过本指南，您可以成功部署和使用新的全局配置系统。
|