init: 项目初始提交 - NeoZQYY Monorepo 完整代码

2026-02-15 14:58:14 +08:00
commit ded6dfb9d8
769 changed files with 182616 additions and 0 deletions
--- a/.kiro/steering/db-docs.md
+++ b/.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/database
+
+2) 文档最低要求：
+   - 变更说明：新增/修改/删除的表、字段、约束、索引
+   - 兼容性：对 ETL、后端 API、小程序字段映射的影响
+   - 回滚策略：如何撤销（DDL 回滚 / 数据回填）
+   - 验证步骤：最少包含 3 条校验 SQL
--- a/.kiro/steering/governance.md
+++ b/.kiro/steering/governance.md
@@ -0,0 +1,27 @@
+---
+inclusion: always
+---
+
+# Governance（Lite）
+
+## 目的
+在“上下文压缩很致命”的前提下，保留最小硬约束：**任何逻辑改动必须可追溯、可验证、可回滚**。
+
+## 何时必须审计（Audit Required）
+满足任一即视为“高风险”，必须运行 `/audit`：
+- 改动文件命中：`api/`、`cli/`、`config/`、`database/`、`loaders/`、`models/`、`orchestration/`、`scd/`、`tasks/`、`utils/` 或根目录散文件
+- 出现 DB schema / migration / `*.sql` / `*.prisma` 结构性变更
+- 业务口径/资金精度与舍入/数据清洗聚合映射/API 契约/鉴权权限/调度游标逻辑发生变化
+
+## 执行方式（自动判定 + 半自动执行）
+- 系统会在你提交 prompt 时自动判定“是否待审计”，并在与 Kiro 交互结束时提醒（15 分钟限频）
+- 用户将手动触发 `/audit`（Manual: Run /audit hook），由 **audit-writer 子代理**执行重型写入
+- 主对话只接收“极短回执”（done + files_written + next_step），避免审计细节淹没上下文
+
+## 审计产物（由 /audit 生成）
+- `docs/audit/changes/<YYYY-MM-DD>__<slug>.md`
+- 每个被改文件内：`AI_CHANGELOG`
+- 每处逻辑变更附近：`CHANGE` 注释
+- DB schema 变更：同步 `docs/database/`
+
+（详细模板/清单/流程见 skills：`steering-readme-maintainer`、`change-annotation-audit`、`bd-manual-db-docs`）
--- a/.kiro/steering/language-zh.md
+++ b/.kiro/steering/language-zh.md
@@ -0,0 +1,18 @@
+---
+inclusion: always
+---
+# 语言与编码规范（强制）
+
+## 输出语言
+- 默认：所有“说明性文字”一律使用简体中文（对话回复、文档内容、代码注释、README/ADR/变更说明等）。
+- 允许保留英文的部分：
+  - 代码标识符（类名/函数名/变量名/接口名/库名/命令名）不翻译
+  - 第三方工具的原始 CLI 输出/报错原文不篡改（可在原文后补充中文解释）
+
+## 文档与注释
+- 新增/修改的文档必须与代码变更同步更新
+- 注释只写“为什么/边界/假设”，避免复述代码
+
+## 编码与字符集
+- 仓库内所有文本文件统一 UTF-8，无 BOM。
+- 禁止出现 GBK/Big5 混用；若发现历史文件，先转码再重构
--- a/.kiro/steering/product.md
+++ b/.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`
--- a/.kiro/steering/steering-readme-maintainer.md
+++ b/.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/audit/changes/<date>__<slug>.md
+- 是否需要在每个修改文件写入 AI_CHANGELOG
+- 是否需要在逻辑变更处加 CHANGE 标记注释
--- a/.kiro/steering/structure-lite.md
+++ b/.kiro/steering/structure-lite.md
@@ -0,0 +1,33 @@
+---
+inclusion: always
+---
+
+# 项目结构（Lite）
+
+目标：在不注入大段目录树的前提下，让 Agent 快速理解“模块边界 + 高风险区”。
+
+## 关键模块边界（高风险路径 = 变更默认需要审计）
+- `cli/`：命令行入口与参数/运行模式（影响一键增量、调度参数等）
+- `config/`：默认值、环境变量解析、AppConfig、调度任务配置（影响运行时假设）
+- `api/`：外部接口客户端与端点路由（影响抓取/契约/回放）
+- `database/`：连接、DDL/schema、seed、migrations（影响数据结构与回滚）
+- `tasks/`：ETL 任务（ODS/DWD/DWS/指数/校验），业务规则主要落在这里
+- `loaders/`：upsert 与维度/事实装载（影响落库与冲突处理）
+- `scd/`：SCD2 处理（影响维度历史与生效区间）
+- `orchestration/`：调度/注册/游标/运行记录（影响增量水位与可重复性）
+- `models/`：解析与验证器（影响字段校验与转换）
+- `utils/`：日志、JSON 存储、窗口切分等通用工具（影响全局行为）
+- 根目录散文件：`.env*`、`pyproject.toml`、`requirements*`、`Makefile`、`README.md` 等（影响运行/依赖/发布）
+
+## 架构要点（摘要）
+- 任务模式：每个 ETL 任务继承 `BaseTask`（Extract → Transform → Load），并在 `orchestration/task_registry.py` 注册
+- 加载器模式：每张目标表一个 Loader，维度/事实分目录；核心是 `upsert()` 与冲突处理策略
+- 配置分层：DEFAULTS → `.env` → CLI 覆盖；通过 `AppConfig.get("dotted.path")` 访问
+- 管线流程：`FULL` / `FETCH_ONLY` / `INGEST_ONLY` 由 CLI 或环境变量控制
+- 调度器：负责游标（水位）与运行记录（增量正确性关键）
+
+## 编码/命名约定（摘要）
+- 文件编码：UTF-8
+- SQL：纯 SQL（非 ORM）；迁移脚本放 `database/migrations/`，推荐“日期前缀”命名
+- 任务：大写蛇形命名（例如 `DWD_LOAD_FROM_ODS`）
+- 日志：统一经由 `utils/logging_utils.py`
--- a/.kiro/steering/structure.md
+++ b/.kiro/steering/structure.md
@@ -0,0 +1,124 @@
+---
+inclusion: auto
+name: structure-full
+description: Full directory tree + architecture patterns. Load only for large refactors, module moves, or changes spanning multiple subsystems.
+---
+
+# 项目结构
+
+```
+NeoZQYY/                     # Monorepo 工作区根目录（C:\NeoZQYY）
+├── 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/                   # 文档
+│   ├── CHANGELOG.md        # 项目级版本变更历史
+│   ├── audit/              # 审计产物
+│   │   ├── changes/        # AI 逐次变更审计记录
+│   │   ├── repo/           # 仓库审计报告（自动生成）
+│   │   ├── prompt_logs/    # Prompt 日志（每次 prompt 一个独立文件，按时间戳命名）
+│   │   └── audit_dashboard.md # 审计一览表（/audit 自动刷新）
+│   ├── architecture/       # 架构设计文档（系统概览、数据流向）
+│   ├── business-rules/     # 业务规则文档（指数算法、DWS 口径、SCD2 规则）
+│   ├── operations/         # 运维文档（环境搭建、调度配置、故障排查）
+│   ├── database/           # 数据库文档统一目录（ODS/DWD/DWS/ETL_Admin 表手册 + 概览索引）
+│   │   ├── overview/       # 层级概览 / 速查索引
+│   │   ├── ODS/            # ODS 层表手册（main/mappings/changes）
+│   │   ├── DWD/            # DWD 层表手册（main + Ex 扩展）
+│   │   ├── DWS/            # DWS 层表手册
+│   │   └── ETL_Admin/      # ETL 管理层表手册
+│   ├── etl_tasks/          # ETL 任务文档
+│   ├── requirements/       # 需求文档（功能需求、口径补充、指数 PRD）
+│   ├── reports/            # 分析报告
+│   ├── api-reference/      # API 参考文档（标准化）
+│   │   ├── api_registry.json  # API 注册表（25 个端点定义）
+│   │   ├── summary/       # 每个 API 一个精简版 .md（25 个）
+│   │   ├── endpoints/     # 每个 API 一个详细版 .md 文档（24 个）
+│   │   └── samples/       # 最新响应样本（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/` 确认一致
+
+- 日期: 2026-02-14
+- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
+- 直接原因: 新增 summary/ 子目录存放精简版 API 文档，需在项目结构中反映
+- 变更摘要: api-reference/ 树中新增 summary/（25 个精简版 .md）；endpoints/ 说明从"25 个"更正为"24 个"
+- 风险与验证: 纯文档结构描述变更，无运行时影响
+-->
--- a/.kiro/steering/tech.md
+++ b/.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_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 辅助类
+
+## 常用命令
+```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 --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` 运行