Initial commit of akmon project
This commit is contained in:
217
COMPANY_CONFIG_GUIDE.md
Normal file
217
COMPANY_CONFIG_GUIDE.md
Normal file
@@ -0,0 +1,217 @@
|
||||
# 公司信息全局配置系统使用指南
|
||||
|
||||
## 概述
|
||||
|
||||
`comindex.uvue` 页面现在支持从全局配置表 `ak_global_config` 中动态获取公司信息，支持多语言展示。
|
||||
|
||||
## 特性
|
||||
|
||||
### 1. 多语言支持
|
||||
支持以下语言：
|
||||
- 简体中文 (zh-CN)
|
||||
- 英文 (en)
|
||||
- 繁体中文 (zh-TW)
|
||||
- 日文 (ja)
|
||||
|
||||
### 2. 配置项目
|
||||
从全局配置表获取的信息包括：
|
||||
|
||||
#### 公司基础信息
|
||||
- `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_*` 到 `hot_search_5_*`: 热门搜索关键词
|
||||
|
||||
*注：带 * 的配置项支持多语言，后缀为 _zh, _en, _tw, _ja*
|
||||
|
||||
## 新设计说明 (推荐)
|
||||
|
||||
### 表结构优化
|
||||
新设计采用主表+翻译表模式，解决了原有设计的冗余问题：
|
||||
|
||||
#### 主配置表 (ak_global_config)
|
||||
```sql
|
||||
CREATE TABLE public.ak_global_config (
|
||||
id UUID PRIMARY KEY,
|
||||
config_key VARCHAR(100) UNIQUE, -- 如: company_name (不再有语言后缀)
|
||||
config_category VARCHAR(50), -- 配置分类: company, social, search等
|
||||
is_translatable BOOLEAN, -- 是否需要多语言翻译
|
||||
default_value TEXT, -- 默认值（用于不需翻译的配置）
|
||||
sort_order INTEGER, -- 排序
|
||||
is_active BOOLEAN
|
||||
);
|
||||
```
|
||||
|
||||
#### 翻译表 (ak_global_config_translations)
|
||||
```sql
|
||||
CREATE TABLE public.ak_global_config_translations (
|
||||
config_id UUID REFERENCES ak_global_config(id),
|
||||
language_code VARCHAR(10), -- zh, en, tw, ja
|
||||
translated_value TEXT, -- 翻译值
|
||||
UNIQUE(config_id, language_code)
|
||||
);
|
||||
```
|
||||
|
||||
### 新设计优势
|
||||
- ✅ **结构清晰**: 主表存元数据，翻译表存多语言值
|
||||
- ✅ **易于维护**: 新增语言只需在翻译表添加记录
|
||||
- ✅ **分类管理**: 通过 config_category 实现配置分组
|
||||
- ✅ **类型区分**: 通过 is_translatable 区分是否需要翻译
|
||||
- ✅ **默认回退**: 支持默认值回退机制
|
||||
|
||||
### 便捷查询
|
||||
新设计提供了视图和函数简化查询：
|
||||
|
||||
```sql
|
||||
-- 获取指定语言的所有配置
|
||||
SELECT * FROM get_config_by_language('zh');
|
||||
|
||||
-- 获取热门搜索关键词
|
||||
SELECT * FROM get_hot_searches('zh');
|
||||
|
||||
-- 查看多语言配置视图
|
||||
SELECT * FROM vw_global_config_multilingual WHERE language_code = 'zh';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 原有设计说明 (兼容)
|
||||
|
||||
*注：为保持兼容性，以下内容保留作为参考*
|
||||
|
||||
## 部署步骤
|
||||
|
||||
### 1. 执行数据库初始化
|
||||
```sql
|
||||
-- 运行初始化脚本
|
||||
\i init_company_global_config.sql
|
||||
```
|
||||
|
||||
### 2. 验证配置
|
||||
```sql
|
||||
-- 查看所有配置
|
||||
SELECT * FROM public.vw_active_global_config;
|
||||
|
||||
-- 查看特定语言的公司名称
|
||||
SELECT config_key, config_value
|
||||
FROM public.ak_global_config
|
||||
WHERE config_key LIKE 'company_name_%'
|
||||
AND is_active = true;
|
||||
```
|
||||
|
||||
### 3. 自定义配置
|
||||
更新配置值：
|
||||
```sql
|
||||
-- 更新公司名称
|
||||
UPDATE public.ak_global_config
|
||||
SET config_value = '您的公司名称'
|
||||
WHERE config_key = 'company_name_zh';
|
||||
|
||||
-- 更新社交媒体链接
|
||||
UPDATE public.ak_global_config
|
||||
SET config_value = 'https://your-wechat-link'
|
||||
WHERE config_key = 'social_wechat_url';
|
||||
```
|
||||
|
||||
## 页面功能
|
||||
|
||||
### 1. 自动加载
|
||||
页面初始化时自动从配置表加载公司信息。
|
||||
|
||||
### 2. 语言切换
|
||||
用户切换语言时，页面会自动更新为对应语言的公司信息。
|
||||
|
||||
### 3. 加载状态
|
||||
在公司LOGO旁边显示加载指示器，用户体验更友好。
|
||||
|
||||
### 4. 错误处理
|
||||
如果配置加载失败，使用默认值保证页面正常展示。
|
||||
|
||||
## 代码结构
|
||||
|
||||
### 主要函数
|
||||
- `loadCompanyConfig()`: 加载全局配置
|
||||
- `updateCompanyInfoByLanguage()`: 根据语言更新信息
|
||||
- `updateSocialMediaLinks()`: 更新社交媒体链接
|
||||
- `updateHotSearchKeywords()`: 更新热门搜索关键词
|
||||
|
||||
### 数据类型
|
||||
```typescript
|
||||
type CompanyConfig = {
|
||||
id?: string
|
||||
config_key: string
|
||||
config_value: string
|
||||
config_type: string
|
||||
description?: string
|
||||
language?: string
|
||||
is_active?: boolean
|
||||
created_at?: string
|
||||
updated_at?: string
|
||||
}
|
||||
```
|
||||
|
||||
## 最佳实践
|
||||
|
||||
### 1. 配置管理
|
||||
- 定期备份配置数据
|
||||
- 使用版本控制管理配置变更
|
||||
- 在更新配置前先测试
|
||||
|
||||
### 2. 多语言内容
|
||||
- 确保所有语言版本的内容长度适中
|
||||
- 注意文化差异，调整内容表达
|
||||
- 定期检查翻译质量
|
||||
|
||||
### 3. 性能优化
|
||||
- 配置数据会在页面初始化时一次性加载
|
||||
- 语言切换时只更新显示，无需重新请求
|
||||
- 使用Map结构快速查找配置项
|
||||
|
||||
## 扩展指南
|
||||
|
||||
### 添加新语言
|
||||
1. 在数据库中添加新的配置项（如 `company_name_fr` 法语）
|
||||
2. 更新 `loadCompanyConfig()` 函数的配置key列表
|
||||
3. 更新 `getLanguageSuffix()` 函数支持新语言
|
||||
4. 在 `availableLanguages` 中添加新语言选项
|
||||
|
||||
### 添加新配置项
|
||||
1. 在数据库中插入新的配置记录
|
||||
2. 更新配置获取列表
|
||||
3. 在对应的更新函数中处理新配置
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 常见问题
|
||||
1. **配置不生效**: 检查 `is_active` 字段是否为 true
|
||||
2. **多语言显示错误**: 确认配置key的命名规范
|
||||
3. **加载失败**: 检查数据库连接和表结构
|
||||
|
||||
### 调试方法
|
||||
```javascript
|
||||
// 在浏览器控制台查看配置数据
|
||||
console.log('配置映射:', companyConfigMap.value)
|
||||
console.log('当前语言:', currentLanguageCode.value)
|
||||
console.log('公司名称:', companyDisplayName.value)
|
||||
```
|
||||
|
||||
## 更新日志
|
||||
|
||||
### v1.0.0 (2025-01-07)
|
||||
- 初始版本
|
||||
- 支持4种语言的公司信息配置
|
||||
- 实现动态加载和语言切换
|
||||
- 添加加载状态和错误处理
|
||||
Reference in New Issue
Block a user