Neo-ZQYY/.kiro/steering/tech.md

inclusion

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

常用命令

# 安装依赖
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/的合理目录下