# NeoZQYY Monorepo

台球门店运营助手一体化平台，整合 ETL 数据 Connector、微信小程序后端、小程序前端与管理后台。

## 项目结构

| 目录 | 说明 | 文档 |
|------|------|------|
| `apps/etl/connectors/feiqiu/` | 飞球 Connector（API → ODS → DWD → DWS） | [docs/](apps/etl/connectors/feiqiu/docs/) |
| `apps/backend/` | FastAPI 后端（13 个路由 · JWT 双认证 · WebSocket） | [README](apps/backend/README.md) · [API 参考](apps/backend/docs/API-REFERENCE.md) |
| `apps/miniprogram/` | 微信小程序（Donut + TDesign + TypeScript） | [README](apps/miniprogram/README.md) |
| `apps/admin-web/` | 管理后台（React + Vite + Ant Design） | [README](apps/admin-web/README.md) |
| `apps/mcp-server/` | MCP Server（AI 工具集成，PostgreSQL 只读查询） | [README](apps/mcp-server/README.md) |
| `packages/shared/` | 共享包（枚举、金额精度、时间工具） | [README](packages/shared/README.md) |
| `db/etl_feiqiu/` | ETL 数据库（6 层 Schema：meta/ods/dwd/core/dws/app） | [README](db/etl_feiqiu/README.md) |
| `db/zqyy_app/` | 业务数据库（auth 认证 + 任务队列 + 调度） | [README](db/zqyy_app/README.md) |
| `docs/` | 项目文档中心（架构、数据库、部署、审计） | [README](docs/README.md) |
| `scripts/` | 运维/工具脚本 | — |
| `tests/` | Monorepo 级属性测试 | — |

## 快速开始

```bash
# 安装全部依赖（需要 uv）
uv sync

# 运行 ETL
cd apps/etl/connectors/feiqiu
python -m cli.main --pg-dsn "$PG_DSN" --store-id "$STORE_ID" --api-token "$API_TOKEN"

# 启动后端 API
cd apps/backend
uvicorn app.main:app --reload

# 运行 ETL 单元测试
cd apps/etl/connectors/feiqiu
pytest tests/unit
```

## 配置

配置采用分层叠加：根 .env -> 应用 .env.local -> 环境变量 -> CLI 参数。

参见 .env.template 了解可用配置项。

## 技术栈

- Python 3.10+, uv workspace（4 个成员：etl、backend、mcp-server、shared）
- PostgreSQL 四库：`etl_feiqiu` / `test_etl_feiqiu`（ETL）、`zqyy_app` / `test_zqyy_app`（业务）
- FastAPI + Uvicorn（后端 API）
- React 19 + Vite 6 + Ant Design 5（管理后台，独立 pnpm）
- 微信小程序原生 + Donut + TDesign + TypeScript（C 端）
- JWT 双认证（管理后台用户名密码 + 小程序微信登录）
- 多门店隔离（`site_id` + RLS）