# 技术设计文档

## 上下文
当前系统支持从 `config.yaml` 和环境变量读取配置，环境变量可以覆盖 `config.yaml` 中的值。这种双重配置来源增加了系统的复杂性和维护成本。为了简化配置管理，需要移除环境变量支持，统一使用 `config.yaml` 作为唯一配置来源。

## 目标 / 非目标

### 目标
- 简化配置管理，统一配置来源为 `config.yaml`
- 减少代码复杂度，移除环境变量处理逻辑
- 提高配置的可追溯性和可维护性
- 确保所有配置都通过文件管理，便于版本控制

### 非目标
- 不支持配置热重载（需要重启应用）
- 不支持多环境配置文件（如 dev.yaml, prod.yaml）
- 不支持配置加密（敏感信息如 API key 以明文存储在 config.yaml 中）

## 决策

### 1. 配置来源：仅使用 config.yaml
**决策**：移除所有环境变量支持，仅从 `config.yaml` 文件读取配置

**原因**：
- 简化配置管理逻辑
- 统一配置来源，减少混淆
- 配置文件便于版本控制和审查
- 降低配置管理的认知负担

**考虑的替代方案**：
- 保留环境变量但仅用于敏感信息（如 API key）：增加了复杂性，不符合简化目标
- 支持多环境配置文件：超出当前需求范围，可以后续添加

### 2. 错误处理策略
**决策**：在配置缺失时抛出明确的异常，而不是使用默认值或静默失败

**原因**：
- 快速发现配置问题
- 避免运行时错误
- 提供清晰的错误消息指导用户修复

**考虑的替代方案**：
- 使用默认值：可能导致配置错误被忽略，不符合明确失败的原则

### 3. 代码清理范围
**决策**：删除所有环境变量相关代码，包括：
- `app/config.py` 中的 `_apply_env_overrides()` 方法
- 所有 `os.getenv()` 调用
- 启动脚本中的环境变量检查
- 文档中的环境变量说明

**原因**：
- 彻底移除功能，避免遗留代码
- 减少维护负担
- 防止未来误用

## 风险 / 权衡

### 风险
1. **迁移成本**：使用环境变量的用户需要迁移配置
   - **缓解措施**：提供清晰的迁移指南和错误消息

2. **安全性**：API key 等敏感信息存储在配置文件中
   - **缓解措施**：在文档中说明安全最佳实践（不要提交到版本控制）

3. **灵活性降低**：无法通过环境变量快速切换配置
   - **缓解措施**：对于需要多环境配置的场景，可以后续添加多配置文件支持

### 权衡
- **简化 vs 灵活性**：选择简化，牺牲了环境变量的灵活性
- **统一 vs 多样性**：选择统一配置来源，提高可维护性

## 迁移计划

### 步骤
1. 更新代码，移除环境变量支持
2. 更新文档，说明配置迁移方法
3. 更新错误消息，提供配置指导
4. 验证所有配置项都能正确读取

### 回滚
如果需要回滚，可以恢复之前的代码，但建议用户迁移到 `config.yaml` 配置方式。

## 开放问题
无