---
inclusion: fileMatch
fileMatchPattern: "pyproject.toml,**/pyproject.toml,.kiro/steering/structure-lite.md,.kiro/agents/**"
name: structure-full
description: 完整目录树 + 架构模式 + 文件归属规则展开。读到项目配置或 steering/agent 定义时自动加载。
---

# NeoZQYY Monorepo 完整结构

```
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/            # 微信小程序
│   │   ├── miniprogram/        # 小程序源码
│   │   └── doc/                # 小程序文档
│   ├── 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/
│   │   ├── 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/           # 架构设计
│   ├── deployment/             # 部署文档（EXPORT-PATHS.md、LAUNCH-CHECKLIST.md）
│   ├── prd/                    # 产品需求
│   ├── contracts/              # 数据契约
│   └── ...
├── tests/                      # Monorepo 级属性测试（hypothesis）
├── scripts/                    # 项目级运维脚本
│   ├── audit/                  # 审计工具（gen_audit_dashboard.py）
│   ├── ops/                    # 日常运维（init_databases、clone_to_test_db 等）
│   ├── migrate/                # 一次性迁移脚本
│   └── server/                 # 服务器部署脚本
├── pyproject.toml              # uv workspace 根配置（4 成员）
├── .env.template
└── README.md
```

## 架构模式
- 任务模式：继承 `BaseTask`（Extract → Transform → Load），在 `orchestration/task_registry.py` 注册
- 加载器模式：每张目标表一个 Loader，`upsert()` + 冲突处理
- 配置分层：DEFAULTS → `.env` → CLI 覆盖
- Flow：通过 `--pipeline` 参数指定（如 `api_full`）
- 多门店隔离：`site_id` + RLS（`app` schema 视图层）
- 跨库访问：`zqyy_app` 通过 FDW 只读映射 `etl_feiqiu.app`

## 文件归属规则（展开说明）

### 模块内部（各 APP / Connector 自治）
每个子模块的 `docs/`、`tests/`、`scripts/` 属于模块专属，只放该模块自身的内容。
禁止将项目级内容放入模块内部目录，也禁止将模块专属内容放到根目录。

### 项目级（根目录统管）
- `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`
- 禁止将审计产物写入子模块内部

### 速查表

| 判断标准 | 放置位置 |
|----------|----------|
| 只有本模块开发者需要看的文档 | 模块内 `docs/` |
| 跨模块对照或全局视角的文档 | 根 `docs/` |
| 只验证本模块逻辑的测试 | 模块内 `tests/` |
| 守护 monorepo 结构/约定的测试 | 根 `tests/` |
| 只操作本模块数据的脚本 | 模块内 `scripts/` |
| 运维/全局工具脚本 | 根 `scripts/` |
| 审计记录（任何模块的变更） | 根 `docs/audit/` |
| 数据库文档（全局 schema 视角） | 根 `docs/database/` |