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

.kiro/steering/testing-env.md

@@ -0,0 +1,25 @@
+---
+inclusion: always
+---
+
+# 测试与验证环境规范（强制）
+
+## 核心原则
+AI 执行测试、验证、调试、一次性脚本时，必须使用与正式运行一致的参数环境。禁止因"只是测试"而省略配置、跳过 `.env` 加载、或使用不完整的参数集。
+
+## 具体要求
+
+1. **环境变量必须完整加载**：测试脚本必须通过 `load_dotenv` 或等效方式加载根 `.env`（及模块 `.env`），不得假设"测试不需要路径配置"
+2. **禁止空值回退到意外默认**：如果某个必需参数（如 `FETCH_ROOT`、`EXPORT_ROOT`、`PG_DSN`）未加载到，应立即报错终止，而非静默使用空字符串或其他配置项的值
+3. **cwd 必须与正式运行一致**：ETL CLI 测试的 `cwd` 应为 `apps/etl/connectors/feiqiu/`；后端测试的 `cwd` 应为 `apps/backend/`
+4. **不得为测试单独构造简化配置**：除非用户明确要求隔离测试环境，否则一律使用 `AppConfig.load()` 正常流程加载配置
+5. **数据库连接使用测试库**：测试涉及数据库时，优先使用 `test_etl_feiqiu` / `test_zqyy_app`（通过 `TEST_DB_DSN` 环境变量），而非正式库
+
+## 例外情况
+以下场景允许偏离：
+- 用户明确指定使用特定参数或简化环境
+- 纯单元测试使用 FakeDB/FakeAPI（`tests/unit/task_test_utils.py`），不涉及真实路径或连接
+- `--dry-run` 模式下的 CLI 验证（但路径配置仍需完整）
+
+## 背景
+此规则源于实际事故：测试时 `FETCH_ROOT` 未正确加载，`or` 链回退到空字符串，导致时区值 `Asia/Shanghai` 被误用为文件路径，在项目目录下创建了垃圾目录 `Asia/Shanghai/ODS_JSON_ARCHIVE/`。