285 lines
6.6 KiB
Markdown
285 lines
6.6 KiB
Markdown
# Config API 测试指南
|
|
|
|
## 问题解决
|
|
|
|
### 问题: API文档打不开
|
|
|
|
**原因**: `adminConfigRoutes.js` 中使用了错误的中间件函数名 `checkPermission`,应该使用 `requireAdmin`
|
|
|
|
**解决方案**: 已修复,将 `checkPermission` 替换为 `requireAdmin`
|
|
|
|
### 问题: config表不存在
|
|
|
|
**原因**: 数据库迁移中包含了config表定义,但可能没有正确执行
|
|
|
|
**解决方案**: 运行 `node create-config-table.js` 创建表并初始化默认配置
|
|
|
|
## API访问地址
|
|
|
|
### 1. Swagger UI (推荐)
|
|
```
|
|
http://localhost:3000/api-docs
|
|
```
|
|
在浏览器中打开,可以查看所有API文档并进行测试
|
|
|
|
### 2. OpenAPI JSON
|
|
```
|
|
http://localhost:3000/api-docs.json
|
|
```
|
|
获取完整的OpenAPI规范JSON
|
|
|
|
### 3. OpenAPI YAML
|
|
```
|
|
http://localhost:3000/api-docs.yaml
|
|
```
|
|
获取完整的OpenAPI规范YAML
|
|
|
|
## 测试Config API
|
|
|
|
### 方法1: 使用测试脚本
|
|
|
|
```bash
|
|
cd backend
|
|
node test-config-api.js
|
|
```
|
|
|
|
### 方法2: 使用curl命令
|
|
|
|
#### 测试公开配置API (无需认证)
|
|
|
|
```bash
|
|
# 获取所有公开配置
|
|
curl http://localhost:3000/api/v1/config
|
|
```
|
|
|
|
**响应示例:**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "Configuration retrieved successfully",
|
|
"data": {
|
|
"app_logo": "",
|
|
"about_us_image": "",
|
|
"app_name": "Overseas Appointment System",
|
|
"contact_phone": "",
|
|
"contact_email": ""
|
|
}
|
|
}
|
|
```
|
|
|
|
#### 测试管理后台配置API (需要认证)
|
|
|
|
**步骤1: 登录获取token**
|
|
|
|
```bash
|
|
curl -X POST http://localhost:3000/api/v1/admin/auth/login \
|
|
-H "Content-Type: application/json" \
|
|
-d "{\"username\":\"admin\",\"password\":\"admin123\"}"
|
|
```
|
|
|
|
**响应示例:**
|
|
```json
|
|
{
|
|
"code": 0,
|
|
"message": "Login successful",
|
|
"data": {
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
|
|
"admin": {
|
|
"id": "...",
|
|
"username": "admin",
|
|
"role": "super_admin"
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**步骤2: 使用token访问配置API**
|
|
|
|
```bash
|
|
# 设置token变量
|
|
TOKEN="your_token_here"
|
|
|
|
# 获取所有配置
|
|
curl http://localhost:3000/api/v1/admin/config \
|
|
-H "Authorization: Bearer $TOKEN"
|
|
|
|
# 获取单个配置
|
|
curl http://localhost:3000/api/v1/admin/config/app_name \
|
|
-H "Authorization: Bearer $TOKEN"
|
|
|
|
# 更新配置
|
|
curl -X PUT http://localhost:3000/api/v1/admin/config/app_name \
|
|
-H "Authorization: Bearer $TOKEN" \
|
|
-H "Content-Type: application/json" \
|
|
-d "{\"value\":\"My App\",\"type\":\"string\",\"category\":\"general\",\"description\":\"Application name\"}"
|
|
|
|
# 删除配置 (谨慎使用)
|
|
curl -X DELETE http://localhost:3000/api/v1/admin/config/custom_key \
|
|
-H "Authorization: Bearer $TOKEN"
|
|
```
|
|
|
|
### 方法3: 使用Swagger UI测试
|
|
|
|
1. 打开浏览器访问: http://localhost:3000/api-docs
|
|
2. 找到 "Config" 或 "Admin - Config" 标签
|
|
3. 点击要测试的接口
|
|
4. 点击 "Try it out" 按钮
|
|
5. 填写参数
|
|
6. 点击 "Execute" 执行请求
|
|
7. 查看响应结果
|
|
|
|
**对于需要认证的接口:**
|
|
1. 先测试登录接口获取token
|
|
2. 点击页面右上角的 "Authorize" 按钮
|
|
3. 输入 `Bearer your_token_here`
|
|
4. 点击 "Authorize"
|
|
5. 现在可以测试需要认证的接口了
|
|
|
|
## 管理后台测试
|
|
|
|
### 启动管理后台
|
|
|
|
```bash
|
|
cd admin
|
|
npm run dev
|
|
```
|
|
|
|
访问: http://localhost:5173 (或显示的端口)
|
|
|
|
### 登录管理后台
|
|
|
|
- 用户名: `admin`
|
|
- 密码: `admin123` (或你设置的密码)
|
|
|
|
### 访问系统配置页面
|
|
|
|
1. 登录后,点击左侧菜单的 "系统配置"
|
|
2. 可以看到三个标签页:
|
|
- 外观配置: 上传Logo和关于我们图片
|
|
- 基本信息: 设置应用名称
|
|
- 联系方式: 设置联系电话和邮箱
|
|
|
|
### 测试配置功能
|
|
|
|
1. **上传Logo**
|
|
- 点击Logo上传区域
|
|
- 选择图片文件 (PNG/JPG, 最大5MB)
|
|
- 等待上传完成
|
|
- 点击"保存外观配置"
|
|
|
|
2. **修改应用名称**
|
|
- 切换到"基本信息"标签
|
|
- 修改应用名称
|
|
- 点击"保存基本信息"
|
|
|
|
3. **设置联系方式**
|
|
- 切换到"联系方式"标签
|
|
- 输入联系电话和邮箱
|
|
- 点击"保存联系方式"
|
|
|
|
4. **验证配置生效**
|
|
- 刷新页面,检查配置是否保存
|
|
- 或者调用公开API查看配置
|
|
|
|
## 常见问题
|
|
|
|
### Q: API文档页面空白或加载失败
|
|
|
|
**A**: 检查以下几点:
|
|
1. 后端服务是否正常运行: `http://localhost:3000/health`
|
|
2. 查看后端日志是否有错误
|
|
3. 检查浏览器控制台是否有JavaScript错误
|
|
4. 尝试清除浏览器缓存
|
|
|
|
### Q: 配置保存后不生效
|
|
|
|
**A**:
|
|
1. 检查Redis是否正常运行
|
|
2. 清除Redis缓存: `redis-cli FLUSHDB`
|
|
3. 重启后端服务
|
|
|
|
### Q: 图片上传失败
|
|
|
|
**A**:
|
|
1. 检查 `backend/uploads` 目录是否存在且有写入权限
|
|
2. 检查文件大小是否超过5MB
|
|
3. 检查文件格式是否为PNG或JPG
|
|
4. 查看后端日志获取详细错误信息
|
|
|
|
### Q: 401 Unauthorized错误
|
|
|
|
**A**:
|
|
1. 确认已登录并获取token
|
|
2. 检查token是否过期
|
|
3. 确认请求头格式: `Authorization: Bearer <token>`
|
|
4. 检查用户是否有管理员权限
|
|
|
|
### Q: 403 Forbidden错误
|
|
|
|
**A**:
|
|
1. 确认用户角色是否为admin或super_admin
|
|
2. 检查RBAC权限配置
|
|
3. 查看后端日志获取详细权限信息
|
|
|
|
## 数据库操作
|
|
|
|
### 查看config表数据
|
|
|
|
使用数据库客户端或命令行:
|
|
|
|
```sql
|
|
USE overseas_appointment;
|
|
SELECT * FROM config;
|
|
```
|
|
|
|
### 手动插入配置
|
|
|
|
```sql
|
|
INSERT INTO config (id, `key`, value, type, category, description, created_at, updated_at)
|
|
VALUES (UUID(), 'custom_key', 'custom_value', 'string', 'general', 'Custom configuration', NOW(), NOW());
|
|
```
|
|
|
|
### 清空配置表 (谨慎!)
|
|
|
|
```sql
|
|
TRUNCATE TABLE config;
|
|
```
|
|
|
|
然后运行初始化脚本恢复默认配置:
|
|
```bash
|
|
node create-config-table.js
|
|
```
|
|
|
|
## 开发建议
|
|
|
|
### 添加新配置项
|
|
|
|
1. 在 `configService.js` 的 `initializeDefaults` 方法中添加默认值
|
|
2. 在管理后台页面添加对应的表单字段
|
|
3. 如需公开给小程序,在 `getPublicConfigs` 方法中添加配置键名
|
|
4. 更新API文档
|
|
|
|
### 配置缓存策略
|
|
|
|
- 默认缓存时间: 1小时
|
|
- 修改配置时自动清除缓存
|
|
- 可在 `configService.js` 中调整 `CACHE_TTL` 常量
|
|
|
|
### 安全建议
|
|
|
|
1. 不要在公开API中暴露敏感配置
|
|
2. 定期备份配置数据
|
|
3. 重要配置修改前先记录当前值
|
|
4. 使用环境变量存储真正的敏感信息(如密钥)
|
|
|
|
## 相关文件
|
|
|
|
- API文档: `backend/src/docs/admin-config.docs.js`, `backend/src/docs/config.docs.js`
|
|
- 路由: `backend/src/routes/adminConfigRoutes.js`, `backend/src/routes/configRoutes.js`
|
|
- 控制器: `backend/src/controllers/adminConfigController.js`, `backend/src/controllers/configController.js`
|
|
- 服务: `backend/src/services/configService.js`
|
|
- 模型: `backend/src/models/Config.js`
|
|
- 前端页面: `admin/src/views/config/index.vue`
|
|
- 测试脚本: `backend/test-config-api.js`, `backend/create-config-table.js`
|
|
- 完整文档: `CONFIG_MANAGEMENT.md`
|