113 lines
6.3 KiB
Markdown
113 lines
6.3 KiB
Markdown
---
|
||
inclusion: fileMatch
|
||
fileMatchPattern: "pyproject.toml,**/pyproject.toml,.kiro/steering/project-overview.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/` |
|