# 数据库模型文档

## SiteConfigModel

SiteConfigModel 是一个网站配置管理模型，提供了灵活的键值对配置存储和管理功能，支持单个配置项和批量配置操作。

### 主要特性

- ✅ 键值对配置存储
- ✅ 单个和批量配置操作
- ✅ 自动时间戳管理
- ✅ 配置项唯一性保证
- ✅ 灵活的配置值类型支持

### 数据库字段

| 字段名 | 类型 | 说明 |
|--------|------|------|
| id | integer | 主键，自增 |
| key | string(100) | 配置项键名（必填，唯一，最大长度100） |
| value | text | 配置项值（必填） |
| created_at | timestamp | 创建时间 |
| updated_at | timestamp | 更新时间 |

### 基本用法

```javascript
import { SiteConfigModel } from '../models/SiteConfigModel.js'

// 设置单个配置项
await SiteConfigModel.set("site_name", "我的网站")
await SiteConfigModel.set("site_description", "一个优秀的网站")
await SiteConfigModel.set("maintenance_mode", "false")

// 获取单个配置项
const siteName = await SiteConfigModel.get("site_name")
// 返回: "我的网站"

// 批量获取配置项
const configs = await SiteConfigModel.getMany([
    "site_name", 
    "site_description", 
    "maintenance_mode"
])
// 返回: { site_name: "我的网站", site_description: "一个优秀的网站", maintenance_mode: "false" }

// 获取所有配置
const allConfigs = await SiteConfigModel.getAll()
// 返回所有配置项的键值对对象
```

### 核心方法

#### 单个配置操作
- `get(key)` - 获取指定key的配置值
- `set(key, value)` - 设置配置项（有则更新，无则插入）

#### 批量配置操作
- `getMany(keys)` - 批量获取多个key的配置值
- `getAll()` - 获取所有配置项

### 配置管理策略

#### 自动更新机制
```javascript
// set方法会自动处理配置项的创建和更新
static async set(key, value) {
    const exists = await db("site_config").where({ key }).first()
    if (exists) {
        // 如果配置项存在，则更新
        await db("site_config").where({ key }).update({ 
            value, 
            updated_at: db.fn.now() 
        })
    } else {
        // 如果配置项不存在，则创建
        await db("site_config").insert({ key, value })
    }
}
```

#### 批量获取优化
```javascript
// 批量获取时使用 whereIn 优化查询性能
static async getMany(keys) {
    const rows = await db("site_config").whereIn("key", keys)
    const result = {}
    rows.forEach(row => {
        result[row.key] = row.value
    })
    return result
}
```

### 配置值类型支持

支持多种配置值类型：

#### 字符串配置
```javascript
await SiteConfigModel.set("site_name", "我的网站")
await SiteConfigModel.set("contact_email", "admin@example.com")
```

#### 布尔值配置
```javascript
await SiteConfigModel.set("maintenance_mode", "false")
await SiteConfigModel.set("debug_mode", "true")
```

#### 数字配置
```javascript
await SiteConfigModel.set("max_upload_size", "10485760") // 10MB
await SiteConfigModel.set("session_timeout", "3600") // 1小时
```

#### JSON配置
```javascript
await SiteConfigModel.set("social_links", JSON.stringify({
    twitter: "https://twitter.com/example",
    facebook: "https://facebook.com/example"
}))
```

### 使用场景

#### 网站基本信息配置
```javascript
// 设置网站基本信息
await SiteConfigModel.set("site_name", "我的博客")
await SiteConfigModel.set("site_description", "分享技术和生活")
await SiteConfigModel.set("site_keywords", "技术,博客,编程")
await SiteConfigModel.set("site_author", "张三")
```

#### 功能开关配置
```javascript
// 功能开关
await SiteConfigModel.set("enable_comments", "true")
await SiteConfigModel.set("enable_registration", "false")
await SiteConfigModel.set("enable_analytics", "true")
```

#### 系统配置
```javascript
// 系统配置
await SiteConfigModel.set("max_login_attempts", "5")
await SiteConfigModel.set("password_min_length", "8")
await SiteConfigModel.set("session_timeout", "3600")
```

#### 第三方服务配置
```javascript
// 第三方服务配置
await SiteConfigModel.set("google_analytics_id", "GA-XXXXXXXXX")
await SiteConfigModel.set("recaptcha_site_key", "6LcXXXXXXXX")
await SiteConfigModel.set("smtp_host", "smtp.gmail.com")
```

### 配置获取和缓存

#### 基础获取
```javascript
// 获取网站名称
const siteName = await SiteConfigModel.get("site_name") || "默认网站名称"

// 获取维护模式状态
const isMaintenance = await SiteConfigModel.get("maintenance_mode") === "true"
```

#### 批量获取优化
```javascript
// 一次性获取多个配置项，减少数据库查询
const configs = await SiteConfigModel.getMany([
    "site_name",
    "site_description", 
    "maintenance_mode"
])

// 使用配置
if (configs.maintenance_mode === "true") {
    console.log("网站维护中")
} else {
    console.log(`欢迎访问 ${configs.site_name}`)
}
```

### 错误处理

所有方法都包含适当的错误处理：
```javascript
try {
    const siteName = await SiteConfigModel.get("site_name")
    if (!siteName) {
        console.log("网站名称未配置，使用默认值")
        return "默认网站名称"
    }
    return siteName
} catch (error) {
    console.error("获取配置失败:", error.message)
    return "默认网站名称"
}
```

### 性能优化

- `key` 字段已添加唯一索引，提高查询性能
- 支持批量操作，减少数据库查询次数
- 建议在应用层实现配置缓存机制

### 迁移和种子

项目包含完整的数据库迁移和种子文件：
- `20250621013128_site_config.mjs` - 创建site_config表
- `20250621013324_site_config_seed.mjs` - 示例配置数据

### 运行迁移和种子

```bash
# 运行迁移
npx knex migrate:latest

# 运行种子
npx knex seed:run
```

### 扩展建议

可以考虑添加以下功能：
- 配置项分类管理
- 配置项验证规则
- 配置变更历史记录
- 配置导入/导出功能
- 配置项权限控制
- 配置项版本管理
- 配置项依赖关系
- 配置项加密存储

### 最佳实践

1. **配置项命名**: 使用清晰的命名规范，如 `feature_name` 或 `service_config`
2. **配置值类型**: 统一配置值的类型，如布尔值统一使用字符串 "true"/"false"
3. **配置分组**: 使用前缀对配置项进行分组，如 `email_`, `social_`, `system_`
4. **默认值处理**: 在应用层为配置项提供合理的默认值
5. **配置验证**: 在设置配置项时验证值的有效性
6. **配置缓存**: 实现配置缓存机制，减少数据库查询