# Environment Configuration

**Source of Truth:** `.env.example`

<!-- AUTO-GENERATED -->
<!-- Generator: update-docs skill -->
<!-- Last Generated: 2026-09-02 -->

## Application Settings

| Variable | Required | Description | Default |
|----------|----------|-------------|---------|
| `APP_ENV` | Yes | Application environment | `production` |

### Valid Values for APP_ENV

| Value | Environment |
|-------|-------------|
| `development` | Local development with debug features |
| `production` | Production deployment with optimized settings |

## Database Configuration

### Development Environment

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `DB_DEV_HOST` | Yes | Development database server hostname | `localhost` |
| `DB_DEV_PORT` | Yes | SQL Server port | `1433` |
| `DB_DEV_DATABASE` | Yes | Development database name | `DocumentSystem_Dev` |
| `DB_DEV_USERNAME` | Yes | Database username | `sa` |
| `DB_DEV_PASSWORD` | Yes | Database password | `dev_password` |

### Production Environment

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `DB_PROD_HOST` | Yes | Production database server hostname | `prod-db-server` |
| `DB_PROD_PORT` | Yes | SQL Server port | `1433` |
| `DB_PROD_DATABASE` | Yes | Production database name | `DocumentSystem` |
| `DB_PROD_USERNAME` | Yes | Database username | `sa` |
| `DB_PROD_PASSWORD` | Yes | Database password | `prod_password` |

## RPA Database Configuration (EPRHaiyaProcessingTasks 所在库)

### Development Environment

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `RPA_DB_DEV_HOST` | Yes | RPA database hostname | `localhost` |
| `RPA_DB_DEV_PORT` | Yes | SQL Server port | `1433` |
| `RPA_DB_DEV_DATABASE` | Yes | RPA database name | `rpa_dev` |
| `RPA_DB_DEV_USERNAME` | Yes | Database username | `sa` |
| `RPA_DB_DEV_PASSWORD` | Yes | Database password | `dev_password` |

### Production Environment

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `RPA_DB_PROD_HOST` | Yes | RPA database hostname | `prod-db-server` |
| `RPA_DB_PROD_PORT` | Yes | SQL Server port | `1433` |
| `RPA_DB_PROD_DATABASE` | Yes | RPA database name | `rpa` |
| `RPA_DB_PROD_USERNAME` | Yes | Database username | `sa` |
| `RPA_DB_PROD_PASSWORD` | Yes | Database password | `prod_password` |

## External Services

| Variable | Required | Description |
|----------|----------|-------------|
| `WECHAT_WORK_WEBHOOK` | No | 企业微信机器人 Webhook（未设置时用代码内默认值） |
| `TENCENT_SECRET_ID` | No | 腾讯云凭证（身份证 OCR） |
| `TENCENT_SECRET_KEY` | No | 腾讯云凭证（身份证 OCR） |
| `TENCENT_COS_SECRET_ID` | No | 腾讯云 COS 凭证（可选） |
| `TENCENT_COS_SECRET_KEY` | No | 腾讯云 COS 凭证（可选） |
| `API_FLOW_COS_BUCKET` | No | ES EPR API 异步流程生成结果上传桶（默认 `usaeu-1259285998` SaaS 共享桶；与 source 桶 `vat-1259285998` 区分） |
| `API_FLOW_OSS_PREFIX` | No | ES EPR API 异步流程生成结果 COS 相对路径前缀（年份文件夹 `generatefile/2026/` 之前的部分；测试 `common-test/generatefile/`、正式 `common-prod/generatefile/`）；实际 key = `{前缀}{当前年}/es_epr_haiya/{业务流水号}/{文件名}`（业务流水号 = bizParam.BusinessSerialNumber，兜底 BusinessId） |
| `HAIYA_SIGNATURE_REQUIREMENT_URL` | No | 海牙认证签字盖章要求静态 PDF 的完整 OSS URL（`scripts/upload_haiya_requirement.php` 上传后填入；URL 路径含双段 `vat_factory/es/vat_factory/es/` 属 CosUploader 自动前缀，勿改；更新该文件后需重启生产 queue_processor） |
| `BAIDU_OCR_API_KEY` | No | 百度 OCR（信用报告/营业执照） |
| `BAIDU_OCR_SECRET_KEY` | No | 百度 OCR（信用报告/营业执照） |
| `BAIDU_PADDLEOCR_VL_API_KEY` | No | 百度官方 PaddleOCR-VL（查册文件 OCR 主接口，异步；凭证同 BAIDU_OCR_*） |
| `BAIDU_PADDLEOCR_VL_API_URL` | No | 千帆 PaddleOCR-VL 备选接口（同步），默认 `https://qianfan.baidubce.com/v2/ocr/paddleocr` |
| `BAIDU_PADDLEOCR_VL_MODEL` | No | 千帆模型名，默认 `paddleocr-vl-0.9b` |
| `BAIDU_PADDLEOCR_VL_TIMEOUT` | No | 千帆超时秒数，默认 `180` |
| `BAIDU_PADDLEOCR_VL_LANG` | No | 千帆语言，默认 `chinese_cht`（繁体查册文件） |
| `VOLCANO_API_KEY` | No | 火山翻译 |
| `DEEPL_API_KEY` | No | DeepL 翻译 |
| `DEEPL_IS_PRO` | No | DeepL 是否 Pro 账号，默认 `false` |
| `ALICLOUD_HK_OCR_APP_KEY` | No | 阿里云云市场香港 CR/BR OCR（`multiBlicenseHk`） |
| `ALICLOUD_HK_OCR_APP_SECRET` | No | 阿里云云市场香港 CR/BR OCR（`multiBlicenseHk`） |
| `EPR_API_TOKEN` | Yes | 公共API Bearer Token（`public/es_hague_api.php` / `public/es_030_api.php` 异步受理接口；2026-08-15 起端点内认证已注释关闭（本地调试，与 es_haiya 一致），恢复认证后必需、未配置时接口报 500） |
| `EPR_API_MAX_BODY_BYTES` | No | 公共API 请求体大小上限（字节），默认 `2097152`（2MB） |
| `SOURCE_OSS_BASE_URL` | No | 公共API 文件字段 `fileUrl` 相对路径拼接域名（上游 SaaS 系统 OSS），默认 `https://usaeu-1259285998.cos.ap-guangzhou.myqcloud.com` |
| `ALLOWED_DOWNLOAD_HOSTS` | No | 公共API 文件下载域名白名单（SSRF 防护，逗号分隔），默认 `usaeu-1259285998.cos.ap-guangzhou.myqcloud.com,file.usaeu.com,testfile.usaeu.com` |
| `EPR_API_TEST_LOCAL_FILES` | No | 本地测试：`true` 时 queue_processor 生成 API 海牙任务前用消费机器 `api_test_file/` 本地文件替代网络下载（受理时不覆盖，generator_data 保留原始 fileUrl；生产勿开，默认 `false`） |
| `ES_HAGUE_RESULT_CALLBACK_URL` | No | 异步结果回调地址：公共API 受理的 301 任务最终失败（达重试上限）时 POST 错误信息（统一信封含 bizParam）；默认 `https://test-cloud.usaeu.com/prod-api/delivery/rpa/callback`（.env 不配置此键即生效），显式留空则禁用 |
| `ES_HAGUE_CALLBACK_TIMEOUT` | No | 回调 HTTP 超时秒数，默认 `10` |

## Configuration Notes

1. **Security:** Never commit `.env` files with real credentials to version control
2. **Database:** The system uses SQL Server (port 1433) for document data storage
3. **Multi-environment:** Separate database configurations for dev and prod allow safe local testing
4. **RPA 库:** 任务表 `EPRHaiyaProcessingTasks` 位于 RPA 数据库（`RPA_DB_*`），文档数据在业务库（`DB_*`）

## Setup

```bash
# Copy example file
cp .env.example .env

# Edit with your credentials
nano .env
```

## Related Documentation

- [QUICK_REFERENCE.md](QUICK_REFERENCE.md) - Queue processor commands
- [QUEUE_PROCESSOR_README.md](QUEUE_PROCESSOR_README.md) - Complete processor guide