# .env 配置迁移指南

本文档说明如何将现有的 JSON 配置迁移到 .env 环境变量配置。

## 迁移原因

使用 .env 环境变量配置的优势：

1. **更好的安全性**: .env 文件不会被提交到版本控制（已添加到 .gitignore）
2. **更灵活的配置**: 可以在不同环境（开发、测试、生产）中使用不同的配置
3. **标准化**: 遵循 12-factor 应用配置最佳实践
4. **更简单**: 配置格式更简洁，易于维护

## 迁移步骤

### 方法 1: 从现有 JSON 配置迁移（推荐）

如果你已经有 `config/user_settings.json` 配置文件，可以使用迁移脚本自动转换：

```bash
python scripts/migrate_to_env.py migrate
```

该脚本会：
- 读取 `config/user_settings.json` 文件
- 创建 `.env` 文件
- 备份原 JSON 配置到 `config/user_settings.json.backup`

### 方法 2: 从模板创建新的配置

如果是首次配置，从模板创建：

```bash
python scripts/migrate_to_env.py from-example
```

该脚本会：
- 复制 `.env.example` 到 `.env`
- 提示你编辑 `.env` 文件填入实际配置

### 手动配置

1. 复制 `.env.example` 到 `.env`:

```bash
cp .env.example .env
```

2. 编辑 `.env` 文件，填入实际的配置值：

```bash
# ERP 系统配置
ERP_URL=https://your-erp-system.com/
ERP_USERNAME=your_username
ERP_PASSWORD=your_password

# 数据库配置
DB_TYPE=sqlserver  # 或 mysql
DB_SERVER=192.168.1.100
DB_NAME=YourDatabase
DB_USERNAME=your_db_username
DB_PASSWORD=your_db_password
```

## 配置验证

运行测试脚本验证配置是否正确加载：

```bash
python tests/test_env_config.py
```

## 环境变量参考

### ERP 系统配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `ERP_URL` | ERP 系统地址 | `https://68.11.34.30:8082/` |
| `ERP_USERNAME` | ERP 用户名 | `BLDpengqiangqiang` |
| `ERP_PASSWORD` | ERP 密码 | (必填) |
| `ERP_HEADLESS` | 无头模式 | `true` |
| `ERP_IGNORE_HTTPS_ERRORS` | 忽略 HTTPS 错误 | `true` |
| `ERP_AUTO_CLOSE_BROWSER` | 自动关闭浏览器 | `true` |

### 数据库配置（SQL Server）

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `DB_TYPE` | 数据库类型 | `sqlserver` |
| `DB_SERVER` | SQL Server 地址 | `192.168.110.114` |
| `DB_NAME` | 数据库名称 | `CompanyDB` |
| `DB_USERNAME` | 数据库用户名 | `peng` |
| `DB_PASSWORD` | 数据库密码 | (必填) |
| `DB_SQLSERVER_DRIVER` | ODBC 驱动 | `ODBC Driver 18 for SQL Server` |
| `DB_TRUST_SERVER_CERTIFICATE` | 信任服务器证书 | `yes` |

### 数据库配置（MySQL）

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `DB_TYPE` | 数据库类型 | `mysql` |
| `DB_MYSQL_HOST` | MySQL 主机地址 | `192.168.31.83` |
| `DB_MYSQL_PORT` | MySQL 端口 | `3306` |
| `DB_MYSQL_CHARSET` | 字符集 | `utf8mb4` |

### 路径配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `PATH_DATA_DIR` | 数据目录 | `D:/python/playwrite/data/` |
| `PATH_PRODUCTION_ID_FILE` | Production ID 文件名 | `ProductionID.txt` |
| `PATH_DEFAULT_OUTPUT` | 默认输出文件名 | `离散备料计划维护_合并.xlsx` |
| `PATH_VALIDATION_OUTPUT` | 校验输出文件名 | `物料状态校验结果.xlsx` |

### 数据提取配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `EXTRACTION_BATCH_SIZE` | 批次大小 | `100` |
| `EXTRACTION_VERBOSE` | 详细日志 | `true` |
| `EXTRACTION_AUTO_CONVERT` | 自动转换 Excel | `true` |
| `EXTRACTION_MERGE_BATCHES` | 合并批次 | `true` |
| `EXTRACTION_ENABLE_DB_PERSISTENCE` | 保存到数据库 | `false` |

### 校验配置

| 变量名 | 说明 | 默认值 |
|--------|------|--------|
| `VALIDATION_DATA_SOURCE` | 数据源类型 | `database_full` |
| `VALIDATION_USE_DATABASE` | 使用数据库 | `true` |
| `VALIDATION_BATCH_SIZE` | 数据库批次大小 | `2000` |
| `VALIDATION_ENABLE_CRUD` | 启用 CRUD 操作 | `false` |
| `VALIDATION_DEFAULT_MANAGER` | 默认负责人 | (空) |
| `VALIDATION_MATCH_MODE` | 匹配模式 | `substring` |

## 切换数据库类型

要切换数据库类型，修改 `.env` 文件中的 `DB_TYPE` 变量：

### 切换到 MySQL

```bash
# 编辑 .env 文件
DB_TYPE=mysql
DB_NAME=BLD_DB
DB_USERNAME=remote_user
DB_PASSWORD=your_mysql_password
DB_MYSQL_HOST=192.168.31.83
DB_MYSQL_PORT=3306
```

### 切换到 SQL Server

```bash
# 编辑 .env 文件
DB_TYPE=sqlserver
DB_NAME=CompanyDB
DB_USERNAME=peng
DB_PASSWORD=your_sqlserver_password
DB_SERVER=192.168.110.114
```

## 在代码中使用配置

### 使用 ConfigLoader（推荐）

```python
from config.loader import ConfigLoader

# 加载配置（自动从环境变量）
config = ConfigLoader.load()

# 访问配置
erp_url = config.erp.url
db_type = config.database.db_type
```

### 直接从环境变量创建配置

```python
from config.schema import AppConfig

# 从环境变量创建配置
config = AppConfig.from_env()
```

### 使用 ConfigManager（GUI）

```python
from gui.config_manager import ConfigManager

# 创建配置管理器
config_manager = ConfigManager(use_env=True)

# 访问配置
erp_url = config_manager.get("erp.url")
```

## GUI 设置界面

GUI 设置界面已更新为读写 .env 文件。所有通过界面修改的配置会自动保存到 `.env` 文件。

## 回滚方案

如果迁移后出现问题，可以回滚：

1. 恢复 JSON 配置:
   ```bash
   cp config/user_settings.json.backup config/user_settings.json
   ```

2. 删除 .env 文件:
   ```bash
   rm .env
   ```

3. 修改代码使用 JSON 配置（需要修改 `ConfigManager` 初始化参数）:
   ```python
   config_manager = ConfigManager(use_env=False)
   ```

## 安全注意事项

1. **永远不要将 .env 文件提交到版本控制**
   - `.env` 已添加到 `.gitignore`
   - 只提交 `.env.example` 模板文件

2. **保护敏感信息**
   - 不要在代码中硬编码密码
   - 使用强密码
   - 定期更换密码

3. **文件权限**
   - 确保 .env 文件只有你本人可读
   - 在 Linux/Mac 上: `chmod 600 .env`

## 故障排除

### 配置未生效

1. 确认 `.env` 文件存在于项目根目录
2. 检查环境变量名称是否正确（区分大小写）
3. 重启应用程序以重新加载配置

### 迁移脚本错误

1. 检查 Python 版本（需要 Python 3.8+）
2. 确保已安装 `python-dotenv`: `pip install python-dotenv`
3. 查看错误信息并相应解决

### 数据库连接失败

1. 验证数据库配置是否正确
2. 检查数据库服务是否运行
3. 确认网络连接正常
4. 查看数据库驱动是否已安装

## 进一步阅读

- [12-factor App: Config](https://12factor.net/config)
- [python-dotenv 文档](https://github.com/theskumar/python-dotenv)