297 lines
6.6 KiB
Markdown
297 lines
6.6 KiB
Markdown
# 系统配置管理功能说明
|
|
|
|
## 功能概述
|
|
|
|
系统配置管理功能允许管理员通过管理后台动态配置系统参数,这些配置会实时生效并缓存以提高性能。
|
|
|
|
## 功能特性
|
|
|
|
### 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`
|