init: 项目初始提交 - NeoZQYY Monorepo 完整代码

.kiro/steering/structure-lite.md

@@ -0,0 +1,33 @@
+---
+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`