# 配置管理使用说明

## 📋 概述

本文档说明如何使用配置管理工具来确保系统配置一致性，避免常见的配置错误。

## 🛠️ 工具列表

### 1. 配置一致性检查清单
**文件**: `配置一致性检查清单.md`
**用途**: 详细记录所有需要保持一致的配置项
**使用场景**: 
- 新开发人员入职时的配置参考
- 系统部署前的配置核对
- 故障排查时的配置检查

### 2. 自动配置检查脚本
**文件**: `../../../check-config.sh`
**用途**: 自动检查系统配置状态
**使用方法**:
```bash
# 在项目根目录执行
./check-config.sh
```

**检查内容**:
- ✅ Docker服务状态
- ✅ 端口占用情况
- ✅ 服务健康状态
- ✅ 配置文件存在性
- ✅ 认证功能测试
- ✅ CORS配置验证

### 3. 通用基础提示词
**文件**: `子agent/00-通用基础/base_prompt.md`
**用途**: 为所有子agent提供统一的开发规范和调试方法
**核心内容**:
- 系统化问题定位策略
- 配置一致性检查方法
- 常见错误处理模式
- 开发最佳实践

## 🚀 快速开始

### 第一次使用
1. **阅读配置清单**:
   ```bash
   cat "配置一致性检查清单.md"
   ```

2. **运行配置检查**:
   ```bash
   cd ../../../
   ./check-config.sh
   ```

3. **根据结果修复问题**:
   - 如果有失败项，按照建议进行修复
   - 重新运行检查直到所有项都通过

### 日常开发使用

#### 开发前检查
```bash
# 快速检查系统状态
cd ../../../
./check-config.sh

# 如果有问题，启动必要服务
docker-compose up -d
```

#### 遇到问题时
1. **先运行配置检查**:
   ```bash
   cd ../../../
   ./check-config.sh
   ```

2. **对照配置清单**:
   - 检查数据库连接配置
   - 验证CORS域名设置
   - 确认API格式匹配

3. **查看通用提示词**:
   - 按照分层验证法定位问题
   - 使用错误分类处理方法

## 📊 配置检查结果解读

### 正常输出示例
```
🎉 所有检查都通过了！系统配置正常。
通过: 15
失败: 0
```

### 异常输出示例
```
⚠️ 发现 3 个问题，请检查配置。
通过: 12
失败: 3

💡 解决建议:
1. 确保Docker服务已启动: docker-compose up -d
2. 检查端口是否被占用或服务未启动
3. 参考 '配置一致性检查清单.md' 核对配置
```

## 🔧 常见问题解决

### 1. Docker服务未运行
**症状**: `❌ Docker 服务 mysql 未运行`
**解决**: 
```bash
cd ../../../
docker-compose up -d
```

### 2. 端口被占用
**症状**: `❌ 端口 8000 未占用`
**解决**: 检查对应服务是否启动，或端口是否被其他程序占用

### 3. 认证功能失败
**症状**: `❌ 检查登录API 失败`
**解决**: 
1. 检查后端服务是否正常运行
2. 验证数据库连接配置
3. 确认测试用户是否存在

### 4. CORS配置问题
**症状**: `❌ 检查CORS预检请求 失败`
**解决**: 
1. 检查后端CORS配置中是否包含前端端口
2. 确认前端运行在正确的端口上

## 📝 配置维护流程

### 添加新配置项
1. 在`配置一致性检查清单.md`中记录新配置
2. 如需要，在`../../../check-config.sh`中添加检查逻辑
3. 更新`子agent/00-通用基础/base_prompt.md`中的相关说明

### 修改现有配置
1. 同时更新所有相关组件的配置
2. 运行配置检查脚本验证
3. 更新配置清单文档

### 部署新环境
1. 复制配置文件模板
2. 根据环境修改配置值
3. 运行配置检查确保一致性
4. 测试核心功能正常工作

## 🎯 最佳实践

### 开发团队协作
1. **统一工具**: 所有团队成员都使用相同的配置检查工具
2. **定期检查**: 每天开始工作前运行一次配置检查
3. **问题共享**: 遇到新的配置问题时，及时更新文档和工具

### 配置管理原则
1. **版本控制**: 所有配置文件都纳入版本控制
2. **环境隔离**: 不同环境使用不同的配置文件
3. **敏感信息**: 密码等敏感信息使用环境变量管理
4. **文档同步**: 配置变更时同步更新文档

### 故障处理流程
1. **快速定位**: 使用配置检查脚本快速发现问题
2. **系统排查**: 按照分层验证法逐层检查
3. **根本解决**: 不仅修复症状，还要解决根本原因
4. **经验沉淀**: 将解决方案更新到文档和工具中

---

**记住**: 配置一致性是分布式系统稳定运行的基础，投入时间维护配置管理工具能够大大提高开发效率和系统可靠性！