Neo-ZQYY/.kiro/steering/project-overview.md

inclusion

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

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

治理

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

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