---
inclusion: always
---

# 项目结构（Lite）

目标：在不注入大段目录树的前提下，让 Agent 快速理解“模块边界 + 高风险区”。

## 关键模块边界（高风险路径 = 变更默认需要审计）
- `cli/`：命令行入口与参数/运行模式（影响一键增量、调度参数等）
- `config/`：默认值、环境变量解析、AppConfig、调度任务配置（影响运行时假设）
- `api/`：外部接口客户端与端点路由（影响抓取/契约/回放）
- `database/`：连接、DDL/schema、seed、migrations（影响数据结构与回滚）
- `tasks/`：ETL 任务（ODS/DWD/DWS/指数/校验），业务规则主要落在这里
- `loaders/`：upsert 与维度/事实装载（影响落库与冲突处理）
- `scd/`：SCD2 处理（影响维度历史与生效区间）
- `orchestration/`：调度/注册/游标/运行记录（影响增量水位与可重复性）
- `models/`：解析与验证器（影响字段校验与转换）
- `utils/`：日志、JSON 存储、窗口切分等通用工具（影响全局行为）
- 根目录散文件：`.env*`、`pyproject.toml`、`requirements*`、`Makefile`、`README.md` 等（影响运行/依赖/发布）

## 架构要点（摘要）
- 任务模式：每个 ETL 任务继承 `BaseTask`（Extract → Transform → Load），并在 `orchestration/task_registry.py` 注册
- 加载器模式：每张目标表一个 Loader，维度/事实分目录；核心是 `upsert()` 与冲突处理策略
- 配置分层：DEFAULTS → `.env` → CLI 覆盖；通过 `AppConfig.get("dotted.path")` 访问
- 管线流程：`FULL` / `FETCH_ONLY` / `INGEST_ONLY` 由 CLI 或环境变量控制
- 调度器：负责游标（水位）与运行记录（增量正确性关键）

## 编码/命名约定（摘要）
- 文件编码：UTF-8
- SQL：纯 SQL（非 ORM）；迁移脚本放 `database/migrations/`，推荐“日期前缀”命名
- 任务：大写蛇形命名（例如 `DWD_LOAD_FROM_ODS`）
- 日志：统一经由 `utils/logging_utils.py`