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

.kiro/steering/structure.md

@@ -0,0 +1,105 @@
+# 项目结构
+
+```
+FQ-ETL/                     # 工作区根目录（C:\ZQYY\FQ-ETL）
+├── cli/                    # CLI 入口（main.py）
+├── config/                 # 配置：默认值、环境变量解析、AppConfig、调度任务配置
+│   └── scheduled_tasks.json
+├── api/                    # API 客户端（HTTP、本地 JSON 回放、录制）
+│   └── endpoint_routing.py # 端点路由映射
+├── database/               # 数据库连接、操作、DDL Schema、种子脚本、迁移
+│   ├── migrations/         # 迁移脚本（纯 SQL，日期前缀命名）
+│   ├── schema_*.sql        # DDL 定义
+│   └── seed_*.sql          # 种子数据
+├── tasks/                  # ETL 任务实现（按数据层分目录）
+│   ├── base_task.py        # BaseTask 基类，提供 Extract/Transform/Load 模板
+│   ├── ods/                # ODS 层抓取任务（16 个业务实体 + ods_tasks 工厂）
+│   ├── dwd/                # DWD 层装载任务（base_dwd_task、维度/事实装载、质量检查）
+│   ├── dws/                # DWS 汇总与指数任务
+│   │   └── index/          # 指数计算任务（亲密度、新客转化、召回、关系、赢回）
+│   ├── utility/            # 工具类任务（Schema 初始化、手动入库、完整性检查、DWS 构建等）
+│   └── verification/       # ETL 后置校验任务（ODS/DWD/DWS/指数校验器）
+├── loaders/                # 数据加载器（ODS、维度、事实）
+│   ├── base_loader.py      # BaseLoader 基类，定义 upsert 接口
+│   ├── ods/                # 通用 ODS 加载器
+│   ├── dimensions/         # SCD2 维度加载器（会员、助教、商品、台桌、套餐）
+│   └── facts/              # 事实表加载器（订单、支付、退款、小票、充值等）
+├── scd/                    # SCD2（缓慢变化维度）处理器
+├── orchestration/          # 调度器、任务注册表、游标管理、运行记录
+│   ├── pipeline_runner.py  # 管线运行器
+│   ├── task_executor.py    # 任务执行器
+│   ├── task_registry.py    # 任务注册表
+│   ├── scheduler.py        # ETL 调度器
+│   ├── cursor_manager.py   # 游标（水位）管理
+│   └── run_tracker.py      # 运行记录追踪
+├── quality/                # 数据质量检查器（余额一致性、完整性）
+│   └── integrity_service.py # 完整性检查服务
+├── models/                 # 解析器与验证器
+├── utils/                  # 工具函数：日志、JSON 存储、报告、窗口切分
+├── gui/                    # PySide6 桌面 GUI
+│   ├── main_window.py
+│   ├── widgets/            # UI 面板与组件
+│   ├── workers/            # 后台工作线程
+│   ├── models/             # GUI 数据模型（任务、调度）
+│   ├── utils/              # GUI 专用工具（设置、CLI 构建器）
+│   └── resources/          # 样式表
+├── scripts/                # 运维/工具脚本
+│   ├── run_update.py       # 一键增量更新入口（ODS → DWD → DWS）
+│   ├── run_ods.bat         # ODS 批处理入口
+│   ├── audit/              # 仓库审计脚本（扫描器、分析器、报告生成）
+│   ├── check/              # 数据检查脚本（完整性、ODS 缺口、DWD 服务、内容哈希等）
+│   ├── db_admin/           # 数据库管理脚本（Excel 导入）
+│   ├── export/             # 数据导出脚本（指数、团购、亲密度、会员明细等）
+│   ├── rebuild/            # 数据重建脚本（全量 ODS→DWD 重建）
+│   └── repair/             # 数据修复脚本（回填、去重、hash 修复、维度修复、索引调优）
+├── tests/                  # 测试套件
+│   ├── unit/               # 单元测试（FakeDB/FakeAPI，无需真实数据库）
+│   └── integration/        # 集成测试（需要 TEST_DB_DSN 或真实数据库）
+├── docs/                   # 文档
+│   ├── audit/              # 仓库审计报告（自动生成）
+│   ├── bd_manual/          # 业务数据手册（DWD/DWS 表说明）
+│   │   ├── DWD/            # DWD 层表手册（main + Ex 扩展）
+│   │   └── dws/            # DWS 层表手册
+│   ├── dictionary/         # 数据字典
+│   ├── index/              # 指数算法文档
+│   ├── requirements/       # 需求文档
+│   ├── reports/            # 分析报告
+│   ├── data_exports/       # 数据导出文档与 CSV
+│   ├── templates/          # 模板文件（Excel 等）
+│   ├── api-reference/      # API 参考文档（标准化，替代 test-json-doc）
+│   │   ├── api_registry.json  # API 注册表（25 个端点定义）
+│   │   ├── endpoints/     # 每个 API 一个 .md 文档（25 个）
+│   │   └── samples/       # 最新响应样本（JSON）
+│   ├── test-json-doc/      # [已废弃] 旧版 API 测试 JSON 样本与分析
+│   └── 开发笔记/           # 开发备忘
+├── reports/                # 质检输出（JSON，已 gitignore）
+├── export/                 # JSON 落盘与日志（已 gitignore）
+├── logs/                   # 运行日志（已 gitignore）
+└── .Deleted/               # 已归档/废弃文件（隐藏目录，已 gitignore）
+```
+
+## 架构模式
+
+- **任务模式**：每个 ETL 任务继承 `BaseTask`（Extract → Transform → Load 模板方法），在 `orchestration/task_registry.py` 中注册。
+- **加载器模式**：每张目标表对应一个加载器，继承 `BaseLoader` 并实现 `upsert()` 方法。维度加载器在 `loaders/dimensions/`，事实加载器在 `loaders/facts/`。
+- **配置分层**：`DEFAULTS` 字典 → `.env` 覆盖 → CLI 参数覆盖。通过 `AppConfig.get("dotted.path")` 访问。
+- **管线流程**：`FULL`（抓取 + 入库）、`FETCH_ONLY`（仅抓取）、`INGEST_ONLY`（仅入库）。由 `--pipeline-flow` CLI 参数或 `PIPELINE_FLOW` 环境变量控制。
+- **调度器**：`ETLScheduler` 编排任务执行，管理游标（水位），在 `etl_admin` Schema 中记录运行状态。
+- **API 抽象**：`APIClient`（HTTP）、`LocalJsonClient`（离线回放）、`RecordingAPIClient`（抓取 + 落盘）共享相同接口，任务代码无需关心数据来源。
+
+## 编码约定
+- 文件编码：UTF-8，文件头加 `# -*- coding: utf-8 -*-`
+- 日志格式：通过 `utils/logging_utils.py` 统一
+- 任务代码：大写蛇形命名（如 `DWD_LOAD_FROM_ODS`、`DWS_ASSISTANT_DAILY`）
+- SQL 文件：纯 SQL，不使用 ORM；通过 `psycopg2` 执行
+- 数据库操作：批量 upsert + 冲突处理，显式 commit/rollback
+- 中文注释和文档字符串是正常且预期的
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-171500 — "继续"（Task 3 API 文档全面重构续接）
+- 直接原因: 新增 docs/api-reference/ 目录替代旧 test-json-doc，需在项目结构文档中反映
+- 变更摘要: docs/ 树中新增 api-reference/（含 api_registry.json、endpoints/、samples/）；test-json-doc 标记为 [已废弃]
+- 风险与验证: 纯文档结构描述变更，无运行时影响；验证方式：对比实际目录 `ls docs/api-reference/` 确认一致
+-->