在前后端开发联调前 的提交20260223

.kiro/steering/export-paths-full.md

@@ -0,0 +1,48 @@
+---
+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` 的"统一输出路径配置"节