Merge branch 'main' into dev

etl_billiards/README.md

@@ -191,6 +191,37 @@ pytest --cov=. --cov-report=html
 - `tests/unit/test_parsers.py` – 解析器单元测试
 - `tests/integration/test_database.py` – 数据库集成测试
 
+<<<<<<< HEAD
+=======
+#### 3.3.1 测试模式（ONLINE / OFFLINE）
+
+- `TEST_MODE=ONLINE`（默认）时，测试会模拟实时 API，完整执行 E/T/L。
+- `TEST_MODE=OFFLINE` 时，测试改为从 `TEST_JSON_ARCHIVE_DIR` 指定的归档 JSON 中读取数据，仅做 Transform + Load，适合验证本地归档数据是否仍可回放。
+- `TEST_JSON_ARCHIVE_DIR`：离线 JSON 归档目录（示例：`tests/testdata_json` 或 CI 产出的快照）。
+- `TEST_JSON_TEMP_DIR`：测试生成的临时 JSON 输出目录，便于隔离每次运行的数据。
+- `TEST_DB_DSN`：可选，若设置则单元测试会连接到此 PostgreSQL DSN，实打实执行写库；留空时测试使用内存伪库，避免依赖数据库。
+
+示例命令：
+
+```bash
+# 在线模式覆盖所有任务
+TEST_MODE=ONLINE pytest tests/unit/test_etl_tasks_online.py
+
+# 离线模式使用归档 JSON 覆盖所有任务
+TEST_MODE=OFFLINE TEST_JSON_ARCHIVE_DIR=tests/testdata_json pytest tests/unit/test_etl_tasks_offline.py
+
+# 使用脚本按需组合参数（示例：在线 + 仅订单用例）
+python scripts/run_tests.py --suite online --mode ONLINE --keyword ORDERS
+
+# 使用脚本连接真实测试库并回放离线模式
+python scripts/run_tests.py --suite offline --mode OFFLINE --db-dsn postgresql://user:pwd@localhost:5432/testdb
+
+# 使用“指令仓库”中的预置命令
+python scripts/run_tests.py --preset offline_realdb
+python scripts/run_tests.py --list-presets   # 查看或自定义 scripts/test_presets.py
+```
+
+>>>>>>> main
 ---
 
 ## 4. 项目结构与文件说明
@@ -277,6 +308,11 @@ etl_billiards/
 │   │   ├── __init__.py
 │   │   ├── test_config.py
 │   │   └── test_parsers.py
+<<<<<<< HEAD
+=======
+│   ├── testdata_json/           # 清洗入库用的测试Json文件
+│   │   └── XX.json              
+>>>>>>> main
 │   └── integration/             # 集成测试
 │       ├── __init__.py
 │       └── test_database.py