---
inclusion: always
---

# 技术栈与构建

## 语言与运行时
- Python 3.10+
- uv workspace 统一依赖管理（根 `pyproject.toml` 声明 3 个 workspace 成员）

## 核心依赖
- ETL：`psycopg2-binary`、`requests`、`python-dateutil`、`tzdata`、`python-dotenv`、`openpyxl`
- 后端：`fastapi`、`uvicorn[standard]`、`psycopg2-binary`、`python-dotenv`
- 管理后台：`React`、`Vite`、`Ant Design`（`apps/admin-web/`，独立 pnpm 管理）
- 共享包：`neozqyy-shared`（workspace 内部引用）
- 测试：`pytest`、`hypothesis`

## 数据库
- PostgreSQL（远程实例）
- 六层 Schema 架构：`meta`（调度元数据）、`ods`（原始数据）、`dwd`（明细数据）、`core`（跨门店标准化）、`dws`（汇总数据）、`app`（RLS 视图层）
- 业务数据库：`zqyy_app`（用户/RBAC/任务/审批），通过 FDW 只读映射 ETL 数据
- DDL 文件位于 `db/etl_feiqiu/schemas/`，迁移脚本位于 `db/etl_feiqiu/migrations/`
- 种子数据位于 `db/etl_feiqiu/seeds/`

## 测试
- ETL 单元测试：`cd apps/etl/connectors/feiqiu && pytest tests/unit`
- ETL 集成测试：`TEST_DB_DSN="..." pytest tests/integration`
- Monorepo 属性测试：`pytest tests/ -v`（根目录，hypothesis）
- 测试工具：`apps/etl/connectors/feiqiu/tests/unit/task_test_utils.py` 提供 FakeDB/FakeAPI

## 常用命令
```bash
# 安装依赖
uv sync

# ETL 开发
cd apps/etl/connectors/feiqiu
python -m cli.main --dry-run --tasks DWD_LOAD_FROM_ODS

# 后端开发
cd apps/backend
uvicorn app.main:app --reload

# ETL 单元测试
cd apps/etl/connectors/feiqiu && pytest tests/unit

# 属性测试
cd C:\NeoZQYY && pytest tests/ -v
```

## 配置体系
- 分层叠加：根 `.env` < 应用 `.env.local` < 环境变量 < CLI 参数
- ETL 配置类：`apps/etl/connectors/feiqiu/config/settings.py` → `AppConfig`
- 敏感值放在 `.env` / `.env.local` 中，禁止提交；`.env.template` 提供模板

## 脚本执行规范
- 需要执行多步操作、文件处理、数据库操作等脚本级任务时，优先编写 Python 脚本（`.py`）再通过 `python script.py` 执行
- 避免直接使用 PowerShell 编写复杂逻辑，防止转义符、编码、管道等语法陷阱
- 以下情况可以直接用 shell 命令：
  - 用户明确指定使用 PowerShell / CMD
  - 操作本身是单条简单命令（如 `pytest`、`uv sync`、`git status`）
- Python 脚本放置遵循"两层分治"原则：一次性运维脚本放 `scripts/ops/`，模块专属脚本放模块内 `scripts/`的合理目录下