---
inclusion: fileMatch
fileMatchPattern: "**/.env*,**/scripts/**,**/export/**,**/EXPORT-PATHS*"
name: export-paths-full
description: 输出路径完整规范（目录结构、环境变量映射、检查清单）。读到 .env / scripts / export 文件时自动加载。
---

# 输出路径完整规范

## 目录结构与环境变量

```
export/
├── ETL-Connectors/feiqiu/
│   ├── JSON/          — EXPORT_ROOT / FETCH_ROOT
│   ├── LOGS/          — LOG_ROOT
│   └── REPORTS/       — ETL_REPORT_ROOT
├── SYSTEM/
│   ├── LOGS/          — SYSTEM_LOG_ROOT
│   ├── REPORTS/
│   │   ├── dataflow_analysis/  — SYSTEM_ANALYZE_ROOT
│   │   ├── field_audit/        — FIELD_AUDIT_ROOT
│   │   └── full_dataflow_doc/  — FULL_DATAFLOW_DOC_ROOT
│   └── CACHE/
│       └── api_samples/        — API_SAMPLE_CACHE_ROOT
└── BACKEND/
    └── LOGS/          — BACKEND_LOG_ROOT
```

## 路径读取方式详细
- `scripts/ops/` 脚本：通过 `_env_paths.get_output_path("变量名")` 读取（内部自动 `load_dotenv`）
- ETL 核心模块：通过 `env_parser.py` → `AppConfig` 的 `io.*` 配置节读取
- ETL 独立脚本：通过 `os.environ.get("ETL_REPORT_ROOT")` 读取，缺失时抛错
- 后端：通过 `os.environ.get("BACKEND_LOG_ROOT")` 读取

## 新增输出场景的检查清单

当任何操作需要写入文件时，按以下顺序确认：
1. 该输出是否已有对应的环境变量？→ 直接使用
2. 是否属于现有目录分类（ETL/SYSTEM/BACKEND）？→ 使用对应父目录变量 + 子路径
3. 都不匹配？→ 在 `export/` 下新建合理子目录，新增环境变量，更新 `.env` / `.env.template` / `EXPORT-PATHS.md`

## 共享工具
- `scripts/ops/_env_paths.py`：提供 `get_output_path(env_var)` 函数，自动 `load_dotenv` + 读取 + 建目录 + 缺失报错

## 参考文档
- 完整目录说明：`docs/deployment/EXPORT-PATHS.md`
- 环境变量定义：根 `.env` 的"统一输出路径配置"节