初始提交：飞球 ETL 系统全量代码

database/README.md

@@ -0,0 +1,48 @@
+# database/ — 数据库层
+
+## 文件说明
+
+| 文件 | 用途 |
+|------|------|
+| `connection.py` | 数据库连接管理（带超时的 psycopg2 封装） |
+| `operations.py` | 批量操作（upsert、execute、query） |
+| `base.py` | 数据库操作基础类 |
+
+## DDL Schema 文件
+
+| 文件 | Schema | 说明 |
+|------|--------|------|
+| `schema_ODS_doc.sql` | `billiards_ods` | ODS 层表结构（含字段注释） |
+| `schema_dwd_doc.sql` | `billiards_dwd` | DWD 层表结构（维度 + 事实，含 SCD2 列） |
+| `schema_dws.sql` | `billiards_dws` | DWS 层表结构（汇总表 + 配置表） |
+| `schema_etl_admin.sql` | `etl_admin` | ETL 元数据（任务注册、游标、运行记录） |
+| `schema_verify_perf_indexes.sql` | 各 Schema | 校验性能索引（仅索引 + ANALYZE） |
+
+## 种子脚本
+
+| 文件 | 用途 |
+|------|------|
+| `seed_ods_tasks.sql` | 注册 ODS 任务到 `etl_admin.etl_task` |
+| `seed_scheduler_tasks.sql` | 初始化调度任务配置 |
+| `seed_dws_config.sql` | DWS 配置数据（绩效档位、等级定价、技能映射等） |
+| `seed_index_parameters.sql` | 指数算法参数（WBI/NCI/RS/OS/MS/ML） |
+
+## 迁移脚本
+
+位于 `migrations/` 子目录，纯 SQL，按日期前缀命名：
+
+```
+migrations/
+└── 20260208_relation_index_manual_ml.sql
+```
+
+新增迁移时，文件名格式：`YYYYMMDD_描述.sql`
+
+## Schema 约定
+
+- 所有 DDL 使用 `CREATE TABLE IF NOT EXISTS`，支持幂等执行
+- 表名小写蛇形，带 Schema 前缀（如 `billiards_dwd.dim_member`）
+- 维度表包含 SCD2 列：`scd2_start_time`、`scd2_end_time`、`scd2_is_current`、`scd2_version`
+- ODS 表包含元数据列：`content_hash`、`payload`、`fetched_at`、`source_file`
+- 金额字段统一 `NUMERIC(12,2)`，ID 字段统一 `BIGINT`
+- 不使用 ORM，所有 SQL 通过 `psycopg2` 直接执行