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

在前后端开发联调前 的提交20260223

Browse Source
This commit is contained in:
Neo
2026-02-23 23:02:20 +08:00
parent 254ccb1e77
commit fafc95e64c
1142 changed files with 10366960 additions and 36957 deletions
Download Patch File Download Diff File Expand all files Collapse all files

48
.kiro/steering/export-paths-full.md Normal file
View File

@@ -0,0 +1,48 @@
---
inclusion: fileMatch
fileMatchPattern: "**/.env*,**/scripts/**,**/export/**,**/EXPORT-PATHS*"
name: export-paths-full
description: 输出路径完整规范（目录结构、环境变量映射、检查清单）。读到 .env / scripts / export 文件时自动加载。
---
# 输出路径完整规范
## 目录结构与环境变量
```
export/
├── ETL-Connectors/feiqiu/
│ ├── JSON/ — EXPORT_ROOT / FETCH_ROOT
│ ├── LOGS/ — LOG_ROOT
│ └── REPORTS/ — ETL_REPORT_ROOT
├── SYSTEM/
│ ├── LOGS/ — SYSTEM_LOG_ROOT
│ ├── REPORTS/
│ │ ├── dataflow_analysis/ — SYSTEM_ANALYZE_ROOT
│ │ ├── field_audit/ — FIELD_AUDIT_ROOT
│ │ └── full_dataflow_doc/ — FULL_DATAFLOW_DOC_ROOT
│ └── CACHE/
│ └── api_samples/ — API_SAMPLE_CACHE_ROOT
└── BACKEND/
└── LOGS/ — BACKEND_LOG_ROOT
```
## 路径读取方式详细
- `scripts/ops/` 脚本：通过 `_env_paths.get_output_path("变量名")` 读取（内部自动 `load_dotenv`）
- ETL 核心模块：通过 `env_parser.py` → `AppConfig` 的 `io.*` 配置节读取
- ETL 独立脚本：通过 `os.environ.get("ETL_REPORT_ROOT")` 读取，缺失时抛错
- 后端：通过 `os.environ.get("BACKEND_LOG_ROOT")` 读取
## 新增输出场景的检查清单
当任何操作需要写入文件时，按以下顺序确认：
1. 该输出是否已有对应的环境变量？→ 直接使用
2. 是否属于现有目录分类（ETL/SYSTEM/BACKEND）？→ 使用对应父目录变量 + 子路径
3. 都不匹配？→ 在 `export/` 下新建合理子目录，新增环境变量，更新 `.env` / `.env.template` / `EXPORT-PATHS.md`
## 共享工具
- `scripts/ops/_env_paths.py`：提供 `get_output_path(env_var)` 函数，自动 `load_dotenv` + 读取 + 建目录 + 缺失报错
## 参考文档
- 完整目录说明：`docs/deployment/EXPORT-PATHS.md`
- 环境变量定义：根 `.env` 的"统一输出路径配置"节

16
.kiro/steering/export-paths.md Normal file
View File

@@ -0,0 +1,16 @@
---
inclusion: always
---
# 输出路径规范（强制）
## 核心原则
所有文件输出必须写入 `export/` 统一目录结构，通过 `.env` 环境变量控制路径。禁止在 `export/` 体系外自行创建输出目录。
## 编码规则
1. 路径必须从 `.env` 读取，禁止硬编码任何目录结构（含绝对路径和相对路径）
2. 环境变量缺失时必须报错（`KeyError` / `RuntimeError`），禁止静默回退
3. 路径读取方式：`scripts/ops/` 用 `_env_paths.get_output_path()`；ETL 核心用 `AppConfig.io.*`；独立脚本用 `os.environ.get()` + 显式报错
4. 新增输出类型：先在根 `.env` + `.env.template` 新增变量，再在代码中引用，同步更新 `docs/deployment/EXPORT-PATHS.md`
> 完整目录结构、环境变量映射表、新增场景检查清单见 `export-paths-full.md`（fileMatch：读到 `.env*` / `scripts/` / `export/` 文件时自动加载，也可 `#export-paths-full` 手动加载）。

18
.kiro/steering/product-full.md Normal file
View File

@@ -0,0 +1,18 @@
---
inclusion: fileMatch
fileMatchPattern: "**/tasks/**,**/models/**,**/loaders/**,**/scd/**,**/quality/**,**/business-rules/**"
name: product-full
description: 产品详细说明（ETL 功能、指数算法、在线/离线模式）。读到 ETL 任务/模型/业务规则文件时自动加载。
---
# 产品详细说明
## ETL 功能
- 从上游 SaaS API 抽取运营数据（订单、支付、会员、助教、库存等）
- 原始数据落地 ODS，保留源 payload 便于回溯
- 清洗装载至 DWD，维度走 SCD2，事实按时间增量
- 汇总至 DWS：助教业绩、财务日报、会员分析、工资计算、自定义指数算法（WBI/NCI/RS/OS/MS/ML/SPI）
- 支持在线（API 抓取）和离线（JSON 回放）两种模式
## 主要入口
详见 `tech.md` 常用命令节。

30
.kiro/steering/product.md
View File

@@ -4,29 +4,19 @@ inclusion: always
# 产品概述
NeoZQYY Monorepo — 面向台球门店业务的全栈数据平台，包含 ETL Connector、后端 API、管理后台、微信小程序。
NeoZQYY Monorepo — 面向台球门店业务的全栈数据平台。
## 子系统
- 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）
- 支持在线（API 抓取）和离线（JSON 回放）两种模式
- ETL Connector（`apps/etl/connectors/feiqiu/`）：上游 SaaS API → ODS → DWD → DWS 三层处理
- FastAPI 后端（`apps/backend/`）：业务 API 服务
- 微信小程序（`apps/miniprogram/`）：C 端用户界面
- 管理后台（`apps/admin-web/`）：任务管理、调度配置、数据查看、ETL 监控
- MCP Server（`apps/mcp-server/`）：AI 工具集成服务
- 共享包（`packages/shared/`）：枚举、金额精度、时间工具
## 业务上下文
- 多门店隔离：通过 `site_id` + RLS 实现
- 多门店隔离：`site_id` + RLS
- 核心实体：会员、助教、台桌、订单、支付、退款、团购套餐、库存
- 领域语言以中文为主；代码注释、文档、UI 文案均为中文
- 货币：人民币（CNY），金额以 numeric(2) 存储
- 领域语言中文；货币 CNY，金额 numeric(2)
## 主要入口
详见 `tech.md` 常用命令节。
> ETL 功能细节、指数算法等见 `product-full.md`（fileMatch：读到 ETL 任务/模型/业务规则文件时自动加载，也可 `#product-full` 手动加载）。

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

@@ -11,15 +11,16 @@ inclusion: always
- `apps/backend/` — FastAPI 后端
- `apps/miniprogram/` — 微信小程序
- `apps/admin-web/` — 管理后台（React + Vite + Ant Design）
- `apps/mcp-server/` — MCP Server（AI 工具集成）
- `packages/shared/` — 跨项目共享包
- `db/` — DDL / 迁移 / 种子（`etl_feiqiu/`、`zqyy_app/`、`fdw/`）
- `docs/` — 项目级文档 + `audit/`（统一审计落地点）
- `tests/` — Monorepo 级属性测试
- `scripts/` — 项目级运维脚本
- `scripts/` — 项目级运维脚本（`ops/`、`audit/`、`migrate/`、`server/`）
## 高风险路径（变更需审计）
- `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/`
- `apps/backend/app/`、`apps/admin-web/src/`、`apps/miniprogram/miniprogram/`
- `packages/shared/`、`db/`、根目录散文件（`.env*`、`pyproject.toml`）
## 文件归属规则（强制）

28
.kiro/steering/structure.md
View File

@@ -31,12 +31,14 @@ NeoZQYY/
│ │ ├── tests/ # 后端测试
│ │ └── pyproject.toml
│ ├── miniprogram/ # 微信小程序
│ │ ├── miniapp/ # 小程序源码（主包）
│ │ ├── miniprogram/ # 小程序源码（分包）
│ │ ├── miniprogram/ # 小程序源码
│ │ └── doc/ # 小程序文档
│ └── admin-web/ # 管理后台
│ ├── src/ # 前端源码（api/components/pages/store/types）
│ └── src/__tests__/ # 前端测试
│ ├── admin-web/ # 管理后台
│ │ ├── src/ # 前端源码（api/components/pages/store/types）
│ │ └── src/__tests__/ # 前端测试
│ └── mcp-server/ # MCP Server（AI 工具集成）
│ ├── server.py
│ └── pyproject.toml
├── packages/shared/ # 跨项目共享包（enums, money, datetime_utils）
├── db/
│ ├── etl_feiqiu/
@@ -53,6 +55,7 @@ NeoZQYY/
│ │ └── audit_dashboard.md # 审计一览表（自动生成）
│ ├── database/ # 全局数据库文档
│ ├── architecture/ # 架构设计
│ ├── deployment/ # 部署文档（EXPORT-PATHS.md、LAUNCH-CHECKLIST.md）
│ ├── prd/ # 产品需求
│ ├── contracts/ # 数据契约
│ └── ...
@@ -60,8 +63,9 @@ NeoZQYY/
├── scripts/ # 项目级运维脚本
│ ├── audit/ # 审计工具（gen_audit_dashboard.py）
│ ├── ops/ # 日常运维（init_databases、clone_to_test_db 等）
│ └── migrate/ # 一次性迁移脚本
├── pyproject.toml # uv workspace 根配置
│ ├── migrate/ # 一次性迁移脚本
│ └── server/ # 服务器部署脚本
├── pyproject.toml # uv workspace 根配置（4 成员）
├── .env.template
└── README.md
```
@@ -70,18 +74,14 @@ NeoZQYY/
- 任务模式：继承 `BaseTask`（Extract → Transform → Load），在 `orchestration/task_registry.py` 注册
- 加载器模式：每张目标表一个 Loader，`upsert()` + 冲突处理
- 配置分层：DEFAULTS → `.env` → CLI 覆盖
- Flow：通过 `--pipeline` 参数指定（如 `api_full`），旧 `--pipeline-flow` 已弃用
- Flow：通过 `--pipeline` 参数指定（如 `api_full`）
- 多门店隔离：`site_id` + RLS（`app` schema 视图层）
- 跨库访问：`zqyy_app` 通过 FDW 只读映射 `etl_feiqiu.app`
## 文件归属规则（展开说明）
### 模块内部（各 APP / Connector 自治）
每个子模块的以下目录属于模块专属，只放该模块自身的内容：
- `docs/` — 模块专属文档（API 参考、业务规则、任务说明、运维指南等）
- `tests/` — 模块专属测试（单元测试、集成测试）
- `scripts/` — 模块专属脚本（数据检查、修复、导出等）
每个子模块的 `docs/`、`tests/`、`scripts/` 属于模块专属，只放该模块自身的内容。
禁止将项目级内容放入模块内部目录，也禁止将模块专属内容放到根目录。
### 项目级（根目录统管）
@@ -96,7 +96,7 @@ NeoZQYY/
- 审计一览表：`docs/audit/audit_dashboard.md`（自动生成，勿手动编辑）
- Prompt 日志：`docs/audit/prompt_logs/`
- 一览表生成脚本：`scripts/audit/gen_audit_dashboard.py`
- 禁止将审计产物写入子模块内部（如 `apps/etl/connectors/feiqiu/docs/audit/`）
- 禁止将审计产物写入子模块内部
### 速查表

27
.kiro/steering/tech-full.md Normal file
View File

@@ -0,0 +1,27 @@
---
inclusion: fileMatch
fileMatchPattern: "**/pyproject.toml,**/config/**,**/migrations/**,**/.env*,**/seeds/**"
name: tech-full
description: 技术栈详细信息（依赖清单、DDL 基线、测试工具、种子数据）。读到配置/迁移/依赖文件时自动加载。
---
# 技术栈详细信息
## 核心依赖
- ETL：`psycopg2-binary`、`requests`、`python-dateutil`、`tzdata`、`python-dotenv`、`openpyxl`
- 后端：`fastapi`、`uvicorn[standard]`、`psycopg2-binary`、`python-dotenv`
- 管理后台：`React`、`Vite`、`Ant Design`（独立 pnpm 管理）
- 共享包：`neozqyy-shared`（workspace 内部引用）
- 测试：`pytest`、`hypothesis`
## 数据库详细
- 业务库 `zqyy_app`（用户/RBAC/任务/审批），通过 FDW 只读映射 ETL 数据
- DDL 基线：`docs/database/ddl/`（从测试库自动导出，按 schema 分文件），重新生成：`python scripts/ops/gen_consolidated_ddl.py`
- 旧 DDL / 迁移脚本已归档至 `db/_archived/ddl_baseline_2026-02-22/`
- 种子数据：`db/etl_feiqiu/seeds/`、`db/zqyy_app/seeds/`
## 测试
- 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

57
.kiro/steering/tech.md
View File

@@ -5,58 +5,29 @@ inclusion: always
# 技术栈与构建
## 语言与运行时
- Python 3.10+
- uv workspace 统一依赖管理（根 `pyproject.toml` 声明 3 个 workspace 成员）
## 核心依赖
- 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`
- Python 3.10+，uv workspace（根 `pyproject.toml` 声明 4 个成员：etl/connectors/feiqiu、backend、mcp-server、shared）
- 管理后台：React + Vite + Ant Design（`apps/admin-web/`，独立 pnpm）
## 数据库
- 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/`
## 测试
- 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
- PostgreSQL 远程实例，四库：`etl_feiqiu` / `test_etl_feiqiu`（ETL）、`zqyy_app` / `test_zqyy_app`（业务）
- ETL 六层 Schema：meta / ods / dwd / core / dws / app
- DSN：`PG_DSN`（ETL）、`APP_DB_DSN`（业务），根 `.env` 定义
## 常用命令
```bash
# 安装依赖
uv sync
# ETL 开发
cd apps/etl/connectors/feiqiu
python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
# 后端开发
cd apps/backend
uvicorn app.main:app --reload
# ETL 单元测试
cd apps/etl/connectors/feiqiu && pytest tests/unit
# 属性测试
cd C:\NeoZQYY && pytest tests/ -v
uv sync # 安装依赖
cd apps/etl/connectors/feiqiu && python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS
cd apps/backend && uvicorn app.main:app --reload
cd apps/etl/connectors/feiqiu && pytest tests/unit # ETL 单元测试
cd C:\NeoZQYY && pytest tests/ -v # 属性测试
```
## 配置体系
- 分层叠加：根 `.env` < 应用 `.env.local` < 环境变量 < CLI 参数
- ETL 配置类：`apps/etl/connectors/feiqiu/config/settings.py` → `AppConfig`
- 敏感值放在 `.env` / `.env.local` 中，禁止提交；`.env.template` 提供模板
## 脚本执行规范
- 需要执行多步操作、文件处理、数据库操作等脚本级任务时，优先编写 Python 脚本（`.py`）再通过 `python script.py` 执行
- 避免直接使用 PowerShell 编写复杂逻辑，防止转义符、编码、管道等语法陷阱
- 以下情况可以直接用 shell 命令：
- 用户明确指定使用 PowerShell / CMD
- 操作本身是单条简单命令（如 `pytest`、`uv sync`、`git status`）
- Python 脚本放置遵循"两层分治"原则：一次性运维脚本放 `scripts/ops/`，模块专属脚本放模块内 `scripts/`的合理目录下
- 复杂操作优先写 Python 脚本再执行，避免 PowerShell 复杂逻辑
- 一次性运维脚本放 `scripts/ops/`，模块专属脚本放模块内 `scripts/`
> 核心依赖清单、DDL 基线、种子数据等详细信息见 `tech-full.md`（fileMatch：读到 pyproject.toml / 配置 / 迁移文件时自动加载，也可 `#tech-full` 手动加载）。

25
.kiro/steering/testing-env.md Normal file
View File

@@ -0,0 +1,25 @@
---
inclusion: always
---
# 测试与验证环境规范（强制）
## 核心原则
AI 执行测试、验证、调试、一次性脚本时，必须使用与正式运行一致的参数环境。禁止因"只是测试"而省略配置、跳过 `.env` 加载、或使用不完整的参数集。
## 具体要求
1. **环境变量必须完整加载**：测试脚本必须通过 `load_dotenv` 或等效方式加载根 `.env`（及模块 `.env`），不得假设"测试不需要路径配置"
2. **禁止空值回退到意外默认**：如果某个必需参数（如 `FETCH_ROOT`、`EXPORT_ROOT`、`PG_DSN`）未加载到，应立即报错终止，而非静默使用空字符串或其他配置项的值
3. **cwd 必须与正式运行一致**：ETL CLI 测试的 `cwd` 应为 `apps/etl/connectors/feiqiu/`；后端测试的 `cwd` 应为 `apps/backend/`
4. **不得为测试单独构造简化配置**：除非用户明确要求隔离测试环境，否则一律使用 `AppConfig.load()` 正常流程加载配置
5. **数据库连接使用测试库**：测试涉及数据库时，优先使用 `test_etl_feiqiu` / `test_zqyy_app`（通过 `TEST_DB_DSN` 环境变量），而非正式库
## 例外情况
以下场景允许偏离：
- 用户明确指定使用特定参数或简化环境
- 纯单元测试使用 FakeDB/FakeAPI（`tests/unit/task_test_utils.py`），不涉及真实路径或连接
- `--dry-run` 模式下的 CLI 验证（但路径配置仍需完整）
## 背景
此规则源于实际事故：测试时 `FETCH_ROOT` 未正确加载，`or` 链回退到空字符串，导致时区值 `Asia/Shanghai` 被误用为文件路径，在项目目录下创建了垃圾目录 `Asia/Shanghai/ODS_JSON_ARCHIVE/`。