# 系统配置管理功能说明

## 功能概述

系统配置管理功能允许管理员通过管理后台动态配置系统参数,这些配置会实时生效并缓存以提高性能。

## 功能特性

### 1. 配置分类

系统配置按功能分为三大类:

- **外观配置 (appearance)**: 应用Logo、关于我们图片等视觉元素
- **基本信息 (general)**: 应用名称等基础信息
- **联系方式 (contact)**: 联系电话、联系邮箱等客服信息

### 2. 配置类型

支持多种数据类型:

- `string`: 字符串类型
- `number`: 数字类型
- `boolean`: 布尔类型
- `json`: JSON对象类型
- `image`: 图片URL类型

### 3. 缓存机制

- 配置数据会自动缓存到Redis,有效期1小时
- 更新配置时自动清除缓存
- 首次访问从数据库读取,后续访问从缓存读取

## API接口

### 公开接口 (供小程序使用)

#### 获取公开配置
```
GET /api/v1/config
```

**响应示例:**
```json
{
  "code": 0,
  "message": "Configuration retrieved successfully",
  "data": {
    "app_logo": "https://example.com/logo.png",
    "about_us_image": "https://example.com/about.jpg",
    "app_name": "Overseas Appointment System",
    "contact_phone": "+1234567890",
    "contact_email": "contact@example.com"
  }
}
```

### 管理后台接口

#### 1. 获取所有配置
```
GET /api/v1/admin/config
Authorization: Bearer <token>
```

**查询参数:**
- `category` (可选): 按分类筛选 (appearance/general/contact)

**响应示例:**
```json
{
  "code": 0,
  "message": "Configurations retrieved successfully",
  "data": [
    {
      "id": "uuid",
      "key": "app_logo",
      "value": "https://example.com/logo.png",
      "type": "image",
      "category": "appearance",
      "description": "Application logo image URL",
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z"
    }
  ]
}
```

#### 2. 获取单个配置
```
GET /api/v1/admin/config/:key
Authorization: Bearer <token>
```

#### 3. 更新配置
```
PUT /api/v1/admin/config/:key
Authorization: Bearer <token>
Content-Type: application/json

{
  "value": "new value",
  "type": "string",
  "category": "general",
  "description": "Configuration description"
}
```

#### 4. 删除配置
```
DELETE /api/v1/admin/config/:key
Authorization: Bearer <token>
```

## 管理后台使用

### 访问路径

登录管理后台后,点击侧边栏的"系统配置"菜单进入配置管理页面。

### 外观配置

1. **应用Logo**
   - 点击上传区域选择图片
   - 建议尺寸: 200x200px
   - 支持格式: PNG, JPG
   - 文件大小: 最大5MB
   - 可点击"清除Logo"按钮删除当前Logo

2. **关于我们图片**
   - 点击上传区域选择图片
   - 建议尺寸: 750x400px
   - 支持格式: PNG, JPG
   - 文件大小: 最大5MB
   - 可点击"清除图片"按钮删除当前图片

3. 点击"保存外观配置"按钮保存更改

### 基本信息

1. **应用名称**
   - 输入应用名称 (2-50个字符)
   - 此名称将显示在小程序标题栏和关于页面

2. 点击"保存基本信息"按钮保存更改

### 联系方式

1. **联系电话**
   - 输入客服联系电话
   - 格式示例: +86 13800138000

2. **联系邮箱**
   - 输入客服联系邮箱
   - 必须是有效的邮箱格式

3. 点击"保存联系方式"按钮保存更改

### 其他功能

- **刷新**: 点击右上角"刷新"按钮重新加载配置
- **重置**: 点击"重置"按钮恢复到上次保存的状态
- **表单验证**: 系统会自动验证输入格式,不符合要求会提示错误

## 数据库结构

### config表

| 字段 | 类型 | 说明 |
|------|------|------|
| id | UUID | 主键 |
| key | VARCHAR(100) | 配置键名 (唯一) |
| value | TEXT | 配置值 |
| type | ENUM | 值类型 (string/number/boolean/json/image) |
| category | VARCHAR(50) | 配置分类 |
| description | VARCHAR(500) | 配置描述 |
| created_at | TIMESTAMP | 创建时间 |
| updated_at | TIMESTAMP | 更新时间 |

### 索引

- `key`: 唯一索引
- `category`: 普通索引

## 默认配置

系统初始化时会自动创建以下默认配置:

```javascript
{
  app_logo: '',
  about_us_image: '',
  app_name: 'Overseas Appointment System',
  contact_phone: '',
  contact_email: ''
}
```

## 小程序前端集成

### 获取配置

在小程序中使用Config模块获取配置:

```javascript
import Config from '@/modules/Config'

// 获取所有公开配置
const configs = await Config.getPublicConfig()

// 使用配置
console.log(configs.app_name)
console.log(configs.app_logo)
console.log(configs.contact_phone)
```

### 配置缓存

Config模块会自动缓存配置到本地存储,减少网络请求:

- 首次访问从服务器获取
- 后续访问从本地缓存读取
- 可手动刷新配置

## 权限要求

- 查看配置: 需要管理员权限 (admin)
- 修改配置: 需要管理员权限 (admin)
- 删除配置: 需要管理员权限 (admin)
- 公开配置: 无需认证

## 注意事项

1. **图片上传**: 图片会上传到服务器的uploads目录,确保该目录有写入权限
2. **缓存更新**: 修改配置后,缓存会自动清除,小程序端需要重新获取
3. **配置验证**: 修改配置前会进行格式验证,确保数据有效性
4. **备份建议**: 重要配置修改前建议先备份当前值
5. **权限控制**: 只有管理员角色可以修改配置

## API文档

完整的API文档可以通过以下方式访问:

- Swagger UI: http://localhost:3000/api-docs
- OpenAPI JSON: http://localhost:3000/api-docs.json
- OpenAPI YAML: http://localhost:3000/api-docs.yaml

在Swagger UI中搜索"Config"或"系统配置"查看相关接口文档。

## 故障排查

### 配置不生效

1. 检查Redis是否正常运行
2. 清除Redis缓存: `redis-cli FLUSHDB`
3. 重启后端服务

### 图片上传失败

1. 检查uploads目录权限
2. 检查文件大小是否超过5MB
3. 检查文件格式是否为PNG或JPG

### 配置丢失

1. 检查数据库连接
2. 查看config表数据
3. 运行初始化脚本恢复默认配置

## 扩展配置

如需添加新的配置项:

1. 在`configService.js`的`initializeDefaults`方法中添加默认值
2. 在管理后台页面添加对应的表单字段
3. 更新API文档
4. 如需公开给小程序,在`getPublicConfigs`方法中添加配置键名

## 相关文件

### 后端

- 模型: `backend/src/models/Config.js`
- 服务: `backend/src/services/configService.js`
- 控制器: `backend/src/controllers/adminConfigController.js`
- 路由: `backend/src/routes/adminConfigRoutes.js`
- 文档: `backend/src/docs/admin-config.docs.js`

### 前端

- 页面: `admin/src/views/config/index.vue`
- 路由: `admin/src/router/index.js`

### 小程序

- 模块: `modules/Config.js`
- API: `modules/api/AppServer.js`