---
inclusion: always
---
# 项目概览

NeoZQYY Monorepo — 面向台球门店业务的全栈数据平台。多门店隔离（`site_id` + RLS），领域语言中文，货币 CNY，金额 numeric(2)。

## 子系统与目录
| 目录 | 说明 |
|------|------|
| `apps/etl/connectors/feiqiu/` | 飞球 Connector：上游 SaaS API → ODS → DWD → DWS |
| `apps/backend/` | FastAPI 后端 |
| `apps/miniprogram/` | 微信小程序（C 端） |
| `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 级属性测试（hypothesis） |
| `scripts/` | 项目级运维脚本（`ops/`、`audit/`、`migrate/`、`server/`） |

## 高风险路径（变更需审计）
- ETL：`api/`、`cli/`、`config/`、`database/`、`loaders/`、`models/`、`orchestration/`、`scd/`、`tasks/`、`utils/`、`quality/`
- `apps/backend/app/`、`apps/admin-web/src/`、`apps/miniprogram/miniprogram/`
- `packages/shared/`、`db/`、根目录散文件（`.env*`、`pyproject.toml`）

## 文件归属规则
- 模块专属 docs/tests/scripts → 模块内部
- 项目级/跨模块 → 根目录对应文件夹
- 审计产物统一写 `docs/audit/`，禁止写入子模块
- 编码：UTF-8、纯 SQL、迁移脚本日期前缀、任务大写蛇形

## 废弃对象黑名单（高频误引）

| 对象 | 类型 | 删除日期 | 替代方案 |
|------|------|----------|----------|
| `dwd.dwd_assistant_trash_event` / `_ex` | DWD 表 | 2026-02-22 | `dwd_assistant_service_log_ex.is_trash` |
| `ods.assistant_cancellation_records` | ODS 表 | 2026-02-22 | 不再需要独立链路 |
| `ODS_ASSISTANT_ABOLISH` / `ASSISTANT_ABOLISH` | ETL/调度任务 | 2026-02-22 | 无 |
| `BILLIARD_VIP` | cfg_area_category 分类代码 | 2026-03-07 | V1-V4 归入 `BILLIARD`，V5 归入 `SNOOKER` |
| `dws_member_recall_index` / `v_dws_member_recall_index` | DWS 表 + RLS 视图 | 2026-03-20 | `dws_member_winback_index`（WBI）+ `dws_member_newconv_index`（NCI） |

所有 `_archived/` 目录存放已废弃内容，除非用户明确要求，禁止读取或参考。

## 治理
任何逻辑改动必须可追溯、可验证、可回滚。审计检测与提醒由 hooks 自动执行。

> 详细目录树见 `structure.md`（fileMatch 自动加载）；ETL 功能细节见 `product-full.md`（fileMatch 自动加载）。