在准备环境前提交次全部更改。
This commit is contained in:
@@ -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/` |
|
||||
|
||||
Reference in New Issue
Block a user