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

db/etl_feiqiu/README.md

@@ -0,0 +1,78 @@
+# 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
+├── 20260214_drop_ods_settlelist.sql
+├── 20260214_drop_dwd_settle_list.sql
+└── 20260214_drop_ods_option_name_able_site_transfer.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` 直接执行
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-14
+- Prompt: P20260214-030000 — 上下文传递续接，完成 settlelist 删除后的变更影响审查
+- 直接原因: Change Impact Review 要求将新增迁移脚本同步到 database/README.md
+- 变更摘要: 迁移脚本列表新增 20260214_drop_ods_settlelist.sql 条目
+- 风险与验证: 纯文档变更，无运行时影响；验证方式：`ls database/migrations/` 确认文件存在
+-->
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-14
+- Prompt: P20260214-040000 — "dwd_settlement_head_ex.settle_list 也没有必要保留了"
+- 直接原因: 新增迁移脚本需同步到 README 迁移列表
+- 变更摘要: 迁移脚本列表新增 20260214_drop_dwd_settle_list.sql
+- 风险与验证: 纯文档变更；验证：ls database/migrations/ 确认文件存在
+-->
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-14
+- Prompt: P20260214-070000 — ODS 清理（删除 option_name/able_site_transfer）变更影响审查
+- 直接原因: Change Impact Review 要求将新增迁移脚本同步到 database/README.md
+- 变更摘要: 迁移脚本列表新增 20260214_drop_ods_option_name_able_site_transfer.sql
+- 风险与验证: 纯文档变更；验证：ls database/migrations/ 确认文件存在
+-->