root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

在准备环境前提交次全部更改。

Browse Source
This commit is contained in:
Neo
2026-02-19 08:35:13 +08:00
parent ded6dfb9d8
commit 4eac07da47
1387 changed files with 6107191 additions and 33002 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
.kiro/steering/product.md
View File

@@ -1,22 +1,32 @@
---
inclusion: always
---
# 产品概述
飞球 ETL 系统 (etl-billiards) — 面向台球门店业务的数据仓库 ETL 管线。
NeoZQYY Monorepo — 面向台球门店业务的全栈数据平台，包含 ETL Connector、后端 API、管理后台、微信小程序。
## 功能
## 子系统
- ETL Connector：从上游 SaaS API 抽取运营数据，经 ODS → DWD → DWS 三层处理
- FastAPI 后端：业务 API 服务
- 微信小程序：C 端用户界面
- 管理后台（`apps/admin-web/`）：任务管理、调度配置、数据查看、ETL 状态监控（已替代原 PySide6 桌面 GUI）
- 共享包：枚举、金额精度、时间工具
> 各子系统路径见 `structure-lite.md`
## ETL 功能
- 从上游 SaaS API 抽取运营数据（订单、支付、会员、助教、库存等）
- 原始数据落地 **ODS**（操作数据存储层），保留源 payload 便于回溯
- 清洗装载至 **DWD**（明细数据层），维度走 SCD2，事实按时间增量
- 汇总至 **DWS**（数据服务层）：助教业绩、财务日报、会员分析、工资计算、自定义指数算法（WBI/NCI/RS/OS/MS/ML）
- 提供 **PySide6 桌面 GUI**，支持任务管理、调度配置
- 原始数据落地 ODS，保留源 payload 便于回溯
- 清洗装载至 DWD，维度走 SCD2，事实按时间增量
- 汇总至 DWS：助教业绩、财务日报、会员分析、工资计算、自定义指数算法（WBI/NCI/RS/OS/MS/ML）
- 支持在线（API 抓取）和离线（JSON 回放）两种模式
## 业务上下文
- 单租户：一家台球门店（由 `STORE_ID` 标识）
- 核心实体：会员（客户）、助教（教练）、台桌、订单、支付、退款、团购套餐、库存
- 多门店隔离：通过 `site_id` + RLS 实现
- 核心实体：会员、助教、台桌、订单、支付、退款、团购套餐、库存
- 领域语言以中文为主；代码注释、文档、UI 文案均为中文
- 货币：人民币（CNY），金额以 numeric(2) 存储
## 主要入口
- CLI：`python -m cli.main`（主入口）
- GUI：`python -m gui.main`
- 批处理脚本：`run_etl.bat`、`run_gui.bat`（根目录）、`scripts/run_ods.bat`
详见 `tech.md` 常用命令节。

48
.kiro/steering/structure-lite.md
View File

@@ -4,30 +4,30 @@ inclusion: always
# 项目结构（Lite）
目标：在不注入大段目录树的前提下，让 Agent 快速理解“模块边界 + 高风险区”。
> 详细目录树、架构模式、文件归属规则展开说明见 `structure.md`（读到 pyproject.toml 或 agent 定义时自动加载，也可 `#structure-full` 手动加载）。
## 关键模块边界（高风险路径 = 变更默认需要审计）
- `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` 等（影响运行/依赖/发布）
## 顶层目录
- `apps/etl/connectors/feiqiu/` — 飞球 Connector
- `apps/backend/` — FastAPI 后端
- `apps/miniprogram/` — 微信小程序
- `apps/admin-web/` — 管理后台（React + Vite + Ant Design）
- `packages/shared/` — 跨项目共享包
- `db/` — DDL / 迁移 / 种子（`etl_feiqiu/`、`zqyy_app/`、`fdw/`）
- `docs/` — 项目级文档 + `audit/`（统一审计落地点）
- `tests/` — Monorepo 级属性测试
- `scripts/` — 项目级运维脚本
## 架构要点（摘要）
- 任务模式：每个 ETL 任务继承 `BaseTask`（Extract → Transform → Load），并在 `orchestration/task_registry.py` 注册
- 加载器模式：每张目标表一个 Loader，维度/事实分目录；核心是 `upsert()` 与冲突处理策略
- 配置分层：DEFAULTS → `.env` → CLI 覆盖；通过 `AppConfig.get("dotted.path")` 访问
- 管线流程：`FULL` / `FETCH_ONLY` / `INGEST_ONLY` 由 CLI 或环境变量控制
- 调度器：负责游标（水位）与运行记录（增量正确性关键）
## 高风险路径（变更需审计）
- `apps/etl/connectors/feiqiu/` 下：`api/`、`cli/`、`config/`、`database/`、`loaders/`、`models/`、`orchestration/`、`scd/`、`tasks/`、`utils/`、`quality/`
- `apps/backend/app/`、`apps/admin-web/src/`、`apps/miniprogram/miniapp/`、`apps/miniprogram/miniprogram/`
- `packages/shared/`、`db/`、根目录散文件（`.env*`、`pyproject.toml`）
## 编码/命名约定（摘要）
- 文件编码：UTF-8
- SQL：纯 SQL（非 ORM）；迁移脚本放 `database/migrations/`，推荐“日期前缀”命名
- 任务：大写蛇形命名（例如 `DWD_LOAD_FROM_ODS`）
- 日志：统一经由 `utils/logging_utils.py`
## 文件归属规则（强制）
- 模块专属的 docs/tests/scripts → 放模块内部
- 项目级/跨模块的 docs/tests/scripts → 放根目录
- 审计产物统一写 `docs/audit/`，禁止写入子模块内部
- 一览表刷新：`python scripts/audit/gen_audit_dashboard.py`
## 编码/命名约定
- UTF-8、纯 SQL（非 ORM）、迁移脚本 `db/etl_feiqiu/migrations/`（日期前缀）
- 任务大写蛇形（`DWD_LOAD_FROM_ODS`）、日志经 `utils/logging_utils.py`

210
.kiro/steering/structure.md
View File

@@ -1,124 +1,112 @@
---
inclusion: auto
inclusion: fileMatch
fileMatchPattern: "pyproject.toml,**/pyproject.toml,.kiro/steering/structure-lite.md,.kiro/agents/**"
name: structure-full
description: Full directory tree + architecture patterns. Load only for large refactors, module moves, or changes spanning multiple subsystems.
description: 完整目录树 + 架构模式 + 文件归属规则展开。读到项目配置或 steering/agent 定义时自动加载。
---
# 项目结构
# NeoZQYY Monorepo 完整结构
```
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）
NeoZQYY/
├── apps/
│ ├── etl/connectors/feiqiu/ # 飞球 Connector（数据源连接器）
│ │ ├── api/ # API 客户端（HTTP、本地 JSON 回放、录制）
│ │ ├── cli/ # CLI 入口
│ │ ├── config/ # 配置（默认值、环境变量、AppConfig、调度任务）
│ │ ├── database/ # 数据库连接与操作（Python 模块）
│ │ ├── tasks/ # ETL 任务（ods/dwd/dws/index/utility/verification）
│ │ ├── loaders/ # 数据加载器（ods/dimensions/facts）
│ │ ├── scd/ # SCD2 处理器
│ │ ├── orchestration/ # 调度器、任务注册、游标、运行记录
│ │ ├── quality/ # 数据质量检查
│ │ ├── models/ # 解析器与验证器
│ │ ├── utils/ # 工具函数（日志、JSON 存储、窗口切分）
│ │ ├── docs/ # ETL 专属文档（api-reference、business-rules、etl_tasks 等）
│ │ ├── tests/ # ETL 测试（unit/integration）
│ │ ├── scripts/ # ETL 专属脚本（check/repair/rebuild/export/audit）
│ │ └── pyproject.toml
│ ├── backend/ # FastAPI 后端
│ │ ├── app/ # main.py, config.py, database.py, routers/, middleware/, schemas/
│ │ ├── tests/ # 后端测试
│ │ └── pyproject.toml
│ ├── miniprogram/ # 微信小程序
│ │ ├── miniapp/ # 小程序源码（主包）
│ │ ├── miniprogram/ # 小程序源码（分包）
│ │ └── doc/ # 小程序文档
│ └── admin-web/ # 管理后台
│ ├── src/ # 前端源码（api/components/pages/store/types）
│ └── src/__tests__/ # 前端测试
├── packages/shared/ # 跨项目共享包（enums, money, datetime_utils）
├── db/
│ ├── etl_feiqiu/
│ │ ├── schemas/ # 六层 Schema DDL（meta/ods/dwd/core/dws/app）
│ │ ├── migrations/ # 迁移脚本（日期前缀）
│ │ ├── seeds/ # 种子数据
│ │ └── scripts/ # 测试数据库脚本
│ ├── zqyy_app/schemas/ # 业务数据库 DDL
│ └── fdw/ # FDW 跨库映射
├── docs/ # 项目级文档
│ ├── audit/ # 统一审计落地点
│ │ ├── changes/ # 变更审计记录
│ │ ├── prompt_logs/ # Prompt 日志
│ │ └── audit_dashboard.md # 审计一览表（自动生成）
│ ├── database/ # 全局数据库文档
│ ├── architecture/ # 架构设计
│ ├── prd/ # 产品需求
│ ├── contracts/ # 数据契约
│ └── ...
├── tests/ # Monorepo 级属性测试（hypothesis）
├── scripts/ # 项目级运维脚本
│ ├── audit/ # 审计工具（gen_audit_dashboard.py）
│ ├── ops/ # 日常运维（init_databases、clone_to_test_db 等）
│ └── migrate/ # 一次性迁移脚本
├── pyproject.toml # uv workspace 根配置
├── .env.template
└── README.md
```
## 架构模式
- 任务模式：继承 `BaseTask`（Extract → Transform → Load），在 `orchestration/task_registry.py` 注册
- 加载器模式：每张目标表一个 Loader，`upsert()` + 冲突处理
- 配置分层：DEFAULTS → `.env` → CLI 覆盖
- Flow：通过 `--pipeline` 参数指定（如 `api_full`），旧 `--pipeline-flow` 已弃用
- 多门店隔离：`site_id` + RLS（`app` schema 视图层）
- 跨库访问：`zqyy_app` 通过 FDW 只读映射 `etl_feiqiu.app`
- **任务模式**：每个 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
- 中文注释和文档字符串是正常且预期的
### 模块内部（各 APP / Connector 自治）
每个子模块的以下目录属于模块专属，只放该模块自身的内容：
- `docs/` — 模块专属文档（API 参考、业务规则、任务说明、运维指南等）
- `tests/` — 模块专属测试（单元测试、集成测试）
- `scripts/` — 模块专属脚本（数据检查、修复、导出等）
<!--
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 个"
- 风险与验证: 纯文档结构描述变更，无运行时影响
-->
### 项目级（根目录统管）
- `docs/` — 跨模块文档：架构设计、PRD、权限矩阵、数据契约、运维手册、路线图
- `docs/audit/` — 统一审计落地点（所有模块的变更记录、Prompt 日志、审计一览表）
- `docs/database/` — 全局数据库文档（跨模块共享的 DB 视角）
- `tests/` — Monorepo 级属性测试（守护项目结构/约定/跨模块一致性）
- `scripts/` — 项目级运维脚本（数据库初始化、迁移、审计工具等）
### 审计产物路径（硬约束）
- 变更审计记录：`docs/audit/changes/<YYYY-MM-DD>__<slug>.md`
- 审计一览表：`docs/audit/audit_dashboard.md`（自动生成，勿手动编辑）
- Prompt 日志：`docs/audit/prompt_logs/`
- 一览表生成脚本：`scripts/audit/gen_audit_dashboard.py`
- 禁止将审计产物写入子模块内部（如 `apps/etl/connectors/feiqiu/docs/audit/`）
### 速查表
| 判断标准 | 放置位置 |
|----------|----------|
| 只有本模块开发者需要看的文档 | 模块内 `docs/` |
| 跨模块对照或全局视角的文档 | 根 `docs/` |
| 只验证本模块逻辑的测试 | 模块内 `tests/` |
| 守护 monorepo 结构/约定的测试 | 根 `tests/` |
| 只操作本模块数据的脚本 | 模块内 `scripts/` |
| 运维/全局工具脚本 | 根 `scripts/` |
| 审计记录（任何模块的变更） | 根 `docs/audit/` |
| 数据库文档（全局 schema 视角） | 根 `docs/database/` |

80
.kiro/steering/tech.md
View File

@@ -1,60 +1,62 @@
---
inclusion: always
---
# 技术栈与构建
## 语言与运行时
- Python 3.10+（测试缓存中观察到 3.13）
- 未提交虚拟环境；用户自行管理
- Python 3.10+
- uv workspace 统一依赖管理（根 `pyproject.toml` 声明 3 个 workspace 成员）
## 核心依赖（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 时需要
## 核心依赖
- ETL：`psycopg2-binary`、`requests`、`python-dateutil`、`tzdata`、`python-dotenv`、`openpyxl`
- 后端：`fastapi`、`uvicorn[standard]`、`psycopg2-binary`、`python-dotenv`
- 管理后台：`React`、`Vite`、`Ant Design`（`apps/admin-web/`，独立 pnpm 管理）
- 共享包：`neozqyy-shared`（workspace 内部引用）
- 测试：`pytest`、`hypothesis`
## 数据库
- PostgreSQL（连接远程实例）
- Schema：`billiards_ods`（ODS 原始数据）、`billiards_dwd`（明细数据）、`billiards_dws`（汇总数据）、`etl_admin`（调度/运行记录）
- DDL 文件位于 `database/schema_*.sql`，种子脚本位于 `database/seed_*.sql`
- 迁移脚本位于 `database/migrations/`（纯 SQL，日期前缀命名）
- PostgreSQL（远程实例）
- 六层 Schema 架构：`meta`（调度元数据）、`ods`（原始数据）、`dwd`（明细数据）、`core`（跨门店标准化）、`dws`（汇总数据）、`app`（RLS 视图层）
- 业务数据库：`zqyy_app`（用户/RBAC/任务/审批），通过 FDW 只读映射 ETL 数据
- DDL 文件位于 `db/etl_feiqiu/schemas/`，迁移脚本位于 `db/etl_feiqiu/migrations/`
- 种子数据位于 `db/etl_feiqiu/seeds/`
## 测试
- 框架：`pytest`（未固定在 requirements 中，需单独安装）
- 配置：`pytest.ini` 设置 `pythonpath = .`
- 结构：`tests/unit/`（基于 mock，无需数据库）、`tests/integration/`（需要 `TEST_DB_DSN`）
- 测试工具：`tests/unit/task_test_utils.py` 提供 FakeDB/FakeAPI 辅助类
- ETL 单元测试：`cd apps/etl/connectors/feiqiu && pytest tests/unit`
- ETL 集成测试：`TEST_DB_DSN="..." pytest tests/integration`
- Monorepo 属性测试：`pytest tests/ -v`（根目录，hypothesis）
- 测试工具：`apps/etl/connectors/feiqiu/tests/unit/task_test_utils.py` 提供 FakeDB/FakeAPI
## 常用命令
```bash
# 安装依赖
pip install -r requirements.txt
uv sync
# 在线全流程 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
# 试运行（不写库）
# ETL 开发
cd apps/etl/connectors/feiqiu
python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
# 单元测试
pytest tests/unit
# 后端开发
cd apps/backend
uvicorn app.main:app --reload
# 集成测试（需要数据库）
TEST_DB_DSN="postgresql://..." pytest tests/integration
# ETL 单元测试
cd apps/etl/connectors/feiqiu && pytest tests/unit
# 启动 GUI
python -m gui.main
# 属性测试
cd C:\NeoZQYY && pytest tests/ -v
```
## 配置体系
- 分层叠加：`config/defaults.py` < `.env` / 环境变量 < CLI 参数
- 配置类：`config.settings.AppConfig`，支持点号路径访问（`config.get("db.dsn")`）
- 敏感值（DSN、API Token）放在 `.env` 中，禁止提交
- 分层叠加：根 `.env` < 应用 `.env.local` < 环境变量 < CLI 参数
- ETL 配置类：`apps/etl/connectors/feiqiu/config/settings.py` → `AppConfig`
- 敏感值放在 `.env` / `.env.local` 中，禁止提交；`.env.template` 提供模板
## 打包
- 已移除 EXE 打包支持（`build_exe.py`、`setup.py` 已归档至 `.Deleted/`）
- 直接通过 `python -m cli.main` 或 `python -m gui.main` 运行
## 脚本执行规范
- 需要执行多步操作、文件处理、数据库操作等脚本级任务时，优先编写 Python 脚本（`.py`）再通过 `python script.py` 执行
- 避免直接使用 PowerShell 编写复杂逻辑，防止转义符、编码、管道等语法陷阱
- 以下情况可以直接用 shell 命令：
- 用户明确指定使用 PowerShell / CMD
- 操作本身是单条简单命令（如 `pytest`、`uv sync`、`git status`）
- Python 脚本放置遵循"两层分治"原则：一次性运维脚本放 `scripts/ops/`，模块专属脚本放模块内 `scripts/`的合理目录下