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

.kiro/steering/db-docs.md

@@ -0,0 +1,22 @@
+---
+inclusion: fileMatch
+fileMatchPattern:
+  - "**/migrations/**/*.*"
+  - "**/*.sql"
+  - "**/*schema*.*"
+  - "**/*ddl*.*"
+  - "**/*.prisma"
+---
+
+# Database Schema Documentation Rules
+
+当你修改任何可能影响 PostgreSQL schema/表结构的内容时（迁移脚本/DDL/表定义/ORM 模型）：
+
+1) 必须同步更新 BD 手册目录：
+   docs/bd_manual
+
+2) 文档最低要求：
+   - 变更说明：新增/修改/删除的表、字段、约束、索引
+   - 兼容性：对 ETL、后端 API、小程序字段映射的影响
+   - 回滚策略：如何撤销（DDL 回滚 / 数据回填）
+   - 验证步骤：最少包含 3 条校验 SQL

.kiro/steering/governance.md

@@ -0,0 +1,59 @@
+---
+inclusion: always
+---
+
+# Governance / Engineering Rigour
+
+## Hard Rules（必须遵守）
+
+### 1) Logic Change → Change Impact Review + Doc Updates
+任何**逻辑改动**必须做 Change Impact Review，并评估/必要时更新：
+- .kiro/steering/product.md
+- .kiro/steering/structure.md
+- .kiro/steering/tech.md
+- README.md
+
+**逻辑改动**包括（不限于）：
+- 业务规则/计算口径/资金处理（精度、舍入、阈值等）
+- 数据处理与 ETL 逻辑（含 SQL 逻辑、清洗/聚合/映射）
+- API 行为（返回结构、错误码、鉴权/权限）
+- 小程序交互逻辑（校验、关键流程状态机）
+
+**通常不视为逻辑改动**（仍需判断是否影响结构文档/运行方式）：
+- 纯格式化、拼写/文案微调、仅注释调整、无行为变化的重命名
+
+### 2) DB Schema / Table Structure Change → Must Update BD Manual
+任何数据库 schema / 表结构变化（DDL/迁移/字段类型/默认值/非空/约束/索引/外键等），必须同步到：
+- `docs/bd_manual` 下对应 schema 目录与表结构文档
+
+文档必须包含：变更原因、影响范围、回滚策略、数据迁移注意事项、验证 SQL。
+
+---
+
+## Audit & Annotation Requirements（审计与标注）
+
+### A) Per-change Audit Artifact（一次 Prompt 一份记录）
+每次修改（以一次用户 Prompt 驱动为单位）必须创建/追加：
+- `docs/ai_audit/changes/<YYYY-MM-DD>__<slug>.md`
+
+内容至少包含：
+- 日期（Asia/Taipei，YYYY-MM-DD）
+- 原始原因：用户 Prompt（原文或 ≤5 行摘录，需可追溯完整 Prompt）
+- 直接原因：为什么必须改 + 修改方案简介
+- Changed：涉及模块/接口/表（或关键文件）
+- Risk/Verify：风险点、回归范围、验证步骤
+- 如涉及 DB 结构：回滚要点 + 验证 SQL
+
+### B) Per-file AI_CHANGELOG（每个被修改文件必须可追溯）
+每个被修改的代码/文档文件必须追加/更新 **AI_CHANGELOG** 条目，至少包含：
+- 日期（Asia/Taipei，YYYY-MM-DD）
+- Prompt（原文或引用 Prompt-ID + 摘录）
+- 直接原因（必要性 + 方案简介）
+- 变更摘要（改了什么）
+- 风险与验证（至少 1 条验证方式）
+
+### C) Inline CHANGE Markers（逻辑变更处必须可读）
+对“逻辑变更”的代码块，在变更附近增加 **CHANGE 标记注释**，包含：
+- intent（变更意图）
+- assumptions（前置假设）
+- edge cases / money semantics（边界条件与资金口径：精度/舍入等）

.kiro/steering/language-zh.md

@@ -0,0 +1,18 @@
+---
+inclusion: always
+---
+# 语言与编码规范（强制）
+
+## 输出语言
+- 默认：所有“说明性文字”一律使用简体中文（对话回复、文档内容、代码注释、README/ADR/变更说明等）。
+- 允许保留英文的部分：
+  - 代码标识符（类名/函数名/变量名/接口名/库名/命令名）不翻译
+  - 第三方工具的原始 CLI 输出/报错原文不篡改（可在原文后补充中文解释）
+
+## 文档与注释
+- 新增/修改的文档必须与代码变更同步更新
+- 注释只写“为什么/边界/假设”，避免复述代码
+
+## 编码与字符集
+- 仓库内所有文本文件统一 UTF-8（建议无 BOM）
+- 禁止出现 GBK/Big5 混用；若发现历史文件，先转码再重构

.kiro/steering/product.md

@@ -0,0 +1,22 @@
+# 产品概述
+
+飞球 ETL 系统 (etl-billiards) — 面向台球门店业务的数据仓库 ETL 管线。
+
+## 功能
+- 从上游 SaaS API 抽取运营数据（订单、支付、会员、助教、库存等）
+- 原始数据落地 **ODS**（操作数据存储层），保留源 payload 便于回溯
+- 清洗装载至 **DWD**（明细数据层），维度走 SCD2，事实按时间增量
+- 汇总至 **DWS**（数据服务层）：助教业绩、财务日报、会员分析、工资计算、自定义指数算法（WBI/NCI/RS/OS/MS/ML）
+- 提供 **PySide6 桌面 GUI**，支持任务管理、调度配置
+- 支持在线（API 抓取）和离线（JSON 回放）两种模式
+
+## 业务上下文
+- 单租户：一家台球门店（由 `STORE_ID` 标识）
+- 核心实体：会员（客户）、助教（教练）、台桌、订单、支付、退款、团购套餐、库存
+- 领域语言以中文为主；代码注释、文档、UI 文案均为中文
+- 货币：人民币（CNY），金额以 numeric(2) 存储
+
+## 主要入口
+- CLI：`python -m cli.main`（主入口）
+- GUI：`python -m gui.main`
+- 批处理脚本：`run_etl.bat`、`run_gui.bat`（根目录）、`scripts/run_ods.bat`

.kiro/steering/steering-readme-maintainer.md

@@ -0,0 +1,17 @@
+---
+inclusion: manual
+---
+
+# 变更影响审查与文档同步（手动参考）
+
+说明：本文件用于“按需加载”的快速参考（可作为 /slash command），详细流程请优先使用 skill：
+- steering-readme-maintainer
+
+## 何时使用
+- 发生业务/资金口径/ETL/接口/鉴权/小程序交互等“逻辑改动”时
+
+## 快速清单
+- 是否需要更新 product.md / tech.md / structure.md / README.md / (各子目录下README.md)
+- 是否需要补齐审计记录 docs/ai_audit/changes/<date>__<slug>.md
+- 是否需要在每个修改文件写入 AI_CHANGELOG
+- 是否需要在逻辑变更处加 CHANGE 标记注释

.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/` 确认一致
+-->

.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` 运行