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、迁移脚本日期前缀、任务大写蛇形

治理

任何逻辑改动必须可追溯、可验证、可回滚。审计检测与提醒由 hooks 自动执行（agent-on-stop + prompt-on-submit），用户按需手动触发 /audit。

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