# 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`