Neo-ZQYY/.kiro/steering/tech.md

技术栈与构建

语言与运行时

• 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_ods（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 辅助类

常用命令

# 安装依赖
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 --data-source offline

# 试运行（不写库）
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 运行