初始提交：飞球 ETL 系统全量代码

.kiro/steering/tech.md

@@ -0,0 +1,60 @@
+# 技术栈与构建
+
+## 语言与运行时
+- Python 3.10+（测试缓存中观察到 3.13）
+- 未提交虚拟环境；用户自行管理
+
+## 核心依赖（requirements.txt）
+- `psycopg2-binary>=2.9.0` — PostgreSQL 驱动
+- `requests>=2.28.0` — 上游 API 的 HTTP 客户端
+- `python-dateutil>=2.8.0` / `tzdata>=2023.0` — 日期解析与时区处理
+- `python-dotenv` — `.env` 文件加载
+- `openpyxl>=3.1.0` — Excel 导入导出（DWS 数据）
+- `PySide6>=6.5.0` — Qt 桌面 GUI 框架
+- `flask>=2.3` — 可选 Web API
+- `pyinstaller>=6.0.0` — 可选，仅打包 EXE 时需要
+
+## 数据库
+- PostgreSQL（连接远程实例）
+- Schema：`billiards`（OLTP/ODS）、`billiards_dwd`、`billiards_dws`、`etl_admin`
+- DDL 文件位于 `database/schema_*.sql`，种子脚本位于 `database/seed_*.sql`
+- 迁移脚本位于 `database/migrations/`（纯 SQL，日期前缀命名）
+
+## 测试
+- 框架：`pytest`（未固定在 requirements 中，需单独安装）
+- 配置：`pytest.ini` 设置 `pythonpath = .`
+- 结构：`tests/unit/`（基于 mock，无需数据库）、`tests/integration/`（需要 `TEST_DB_DSN`）
+- 测试工具：`tests/unit/task_test_utils.py` 提供 FakeDB/FakeAPI 辅助类
+
+## 常用命令
+```bash
+# 安装依赖
+pip install -r requirements.txt
+
+# 在线全流程 ETL（抓取 + 入库）
+python -m cli.main --pg-dsn "$PG_DSN" --store-id "$STORE_ID" --api-token "$API_TOKEN"
+
+# 运行指定任务
+python -m cli.main --tasks INIT_ODS_SCHEMA,MANUAL_INGEST --pipeline-flow INGEST_ONLY
+
+# 试运行（不写库）
+python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
+
+# 单元测试
+pytest tests/unit
+
+# 集成测试（需要数据库）
+TEST_DB_DSN="postgresql://..." pytest tests/integration
+
+# 启动 GUI
+python -m gui.main
+```
+
+## 配置体系
+- 分层叠加：`config/defaults.py` < `.env` / 环境变量 < CLI 参数
+- 配置类：`config.settings.AppConfig`，支持点号路径访问（`config.get("db.dsn")`）
+- 敏感值（DSN、API Token）放在 `.env` 中，禁止提交
+
+## 打包
+- 已移除 EXE 打包支持（`build_exe.py`、`setup.py` 已归档至 `.Deleted/`）
+- 直接通过 `python -m cli.main` 或 `python -m gui.main` 运行