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

docs/database/etl_feiqiu_schema_migration.md

@@ -0,0 +1,72 @@
+# etl_feiqiu 六层 Schema 迁移文档
+
+## 变更说明
+
+将现有 4 个 schema 重组为 6 层 schema 架构：
+
+| 原 Schema | 新 Schema | 文件 | 说明 |
+|-----------|-----------|------|------|
+| etl_admin | meta | meta.sql | 调度、游标、运行记录（3 表） |
+| billiards_ods | ods | ods.sql | ODS 原始数据（23 表） |
+| billiards_dwd | dwd | dwd.sql | DWD 明细，保留 main+EX 拆分（40 表） |
+| （新增） | core | core.sql | 统一维度/事实最小字段集（7 表） |
+| billiards_dws | dws | dws.sql | DWS 汇总（29 表） |
+| （新增） | app | app.sql | 视图+RLS（7 视图，6 策略） |
+
+### 新增表（core schema）
+- core.dim_site — 门店维度核心字段
+- core.dim_member — 会员维度核心字段
+- core.dim_assistant — 助教维度核心字段
+- core.dim_table — 台桌维度核心字段
+- core.dim_goods_category — 商品分类维度核心字段
+- core.fact_settlement — 结算事实核心字段
+- core.fact_payment — 支付事实核心字段
+
+### 新增视图（app schema）
+- pp.v_site — 门店视图
+- pp.v_member — 会员视图
+- pp.v_assistant — 助教视图
+- pp.v_assistant_daily — 助教日明细视图
+- pp.v_finance_daily — 财务日报视图
+- pp.v_member_consumption — 会员消费汇总视图
+- pp.v_order_summary — 订单汇总视图
+
+### RLS 策略
+- 所有 core 表启用 ROW LEVEL SECURITY
+- 策略基于 current_setting('app.current_site_id')::bigint 过滤
+- 角色 pp_reader 仅有 SELECT 权限
+
+## 兼容性
+
+- **ETL 管线**：需更新 ETL 代码中的 schema 引用（etl_admin -> meta, billiards_ods -> ods 等）
+- **后端 API**：通过 app schema 视图访问，无需直接引用底层表
+- **小程序**：通过 FDW 映射 app schema，不受影响
+
+## 回滚策略
+
+1. 删除新 schema：DROP SCHEMA IF EXISTS meta, ods, dwd, core, dws, app CASCADE;
+2. 重建原 schema：执行原始 schema_etl_admin.sql、schema_ODS_doc.sql、schema_dwd_doc.sql、schema_dws.sql
+3. 原始 DDL 文件保留在 db/etl_feiqiu/schemas/schema_*.sql 作为参考
+
+## 验证 SQL
+
+`sql
+-- 1. 验证六个 schema 均已创建
+SELECT schema_name FROM information_schema.schemata
+WHERE schema_name IN ('meta', 'ods', 'dwd', 'core', 'dws', 'app')
+ORDER BY schema_name;
+
+-- 2. 验证各 schema 表数量
+SELECT table_schema, COUNT(*) AS table_count
+FROM information_schema.tables
+WHERE table_schema IN ('meta', 'ods', 'dwd', 'core', 'dws', 'app')
+GROUP BY table_schema ORDER BY table_schema;
+
+-- 3. 验证 RLS 策略已启用
+SELECT schemaname, tablename, rowsecurity
+FROM pg_tables
+WHERE schemaname = 'core' AND rowsecurity = true;
+
+-- 4. 验证 app_reader 角色存在
+SELECT rolname FROM pg_roles WHERE rolname = 'app_reader';
+`