6.3 KiB
6.3 KiB
inclusion, fileMatchPattern, name, description
| inclusion | fileMatchPattern | name | description |
|---|---|---|---|
| fileMatch | pyproject.toml,**/pyproject.toml,.kiro/steering/project-overview.md,.kiro/agents/** | structure-full | 完整目录树 + 架构模式 + 文件归属规则展开。读到项目配置或 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（appschema 视图层） - 跨库访问：
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/ |