Neo-ZQYY/docs/database/BD_Manual_fdw_etl_setup.md

BD_Manual：FDW 跨库映射配置（fdw_etl）

目标库：test_zqyy_app（通过 APP_DB_DSN 连接） 迁移脚本：db/zqyy_app/migrations/2026-02-24__p1_setup_fdw_etl.sql 关联 SPEC：miniapp-db-foundation（P1 基础设施层）

---

1. 变更说明

新增扩展

扩展	用途
postgres_fdw	PostgreSQL 外部数据包装器，支持跨库查询

新增外部服务器

服务器名	目标库	说明
etl_feiqiu_server	ETL 库（通过 PG_DSN 连接）	通用名称，通过 host/dbname/port 参数区分环境

新增用户映射

本地角色	远程角色	服务器
app_user	app_reader	etl_feiqiu_server

新增 Schema

Schema	用途
fdw_etl	存放从 ETL 库 app Schema 导入的外部表（只读）

导入的外部表

通过 IMPORT FOREIGN SCHEMA app 批量导入，外部表与 ETL 库 app Schema 中的 RLS 视图一一对应（共 38 张，2026-03-19 新增 3 张 BOARD 看板视图）：

• 11 张 DWD 视图：v_dim_member、v_dim_assistant、v_dim_member_card_account、v_dim_table、v_dwd_settlement_head、v_dwd_table_fee_log、v_dwd_assistant_service_log、v_dwd_recharge_order、v_dwd_store_goods_sale、v_dim_staff、v_dim_staff_ex
• 27 张 DWS 视图（含 4 张 cfg_* 配置表）：v_dws_member_consumption_summary、v_dws_member_visit_detail 等

权限配置

角色	Schema	权限
app_user	fdw_etl	USAGE + SELECT ON ALL TABLES + ALTER DEFAULT PRIVILEGES

---

1.1 RNS1.2 接口引用说明（2026-03-19 补充）

RNS1.2（客户与助教接口）通过 fdw_queries.py 直连 ETL 库查询以下 app.v_* RLS 视图（不使用 fdw_etl.* 外部表，原因：postgres_fdw 不传递自定义 GUC 参数到远端连接）：

视图	引用接口	用途
app.v_dim_member	CUST-1, CUST-2, COACH-1	会员信息（nickname, mobile），DQ-6 合规
app.v_dim_member_card_account	CUST-1, COACH-1	会员卡余额，DQ-7 合规
app.v_dim_assistant	CUST-1, COACH-1	助教基本信息
app.v_dwd_assistant_service_log	CUST-1, CUST-2, COACH-1	服务记录明细（is_delete=0 废单排除，ledger_amount items_sum 口径）
app.v_dws_assistant_salary_calc	COACH-1	助教绩效/档位/收入
app.v_dws_member_assistant_relation_index	CUST-1, COACH-1	会员-助教关系指数

本次无 FDW 配置变更。所有视图已存在于 ETL 库 app schema 中。审计详情见 docs/audit/changes/2026-03-19__rns12-db-audit.md。

---

2. 兼容性影响

组件	影响
ETL 任务	无影响。本脚本仅在业务库创建外部表映射，不修改 ETL 库
后端 API	⚠️ 已不再使用 FDW 外部表。后端自 2026-03-18 起通过 get_etl_readonly_connection(site_id) 直连 ETL 库查询 app.v_* RLS 视图（原因：postgres_fdw 不传递自定义 GUC 参数，RLS 门店隔离失效）。FDW 外部表仅作为备用保留，不再被后端代码引用
小程序	无直接影响。小程序通过后端 API 间接访问
管理后台	无直接影响
auth/biz Schema	无影响。FDW 配置独立于业务 Schema
public Schema	无影响
现有 db/fdw/setup_fdw_test.sql	功能重叠。本迁移脚本使用通用服务器名 etl_feiqiu_server（不含环境前缀），与旧脚本的 test_etl_feiqiu_server 共存但独立

幂等性说明

IMPORT FOREIGN SCHEMA 不支持 IF NOT EXISTS，重复执行会因外部表已存在而报错。本脚本采用 DROP SCHEMA IF EXISTS fdw_etl CASCADE + 重建的方式确保幂等性。副作用是每次执行会重建所有外部表，但由于外部表不存储数据，无数据丢失风险。

---

3. 回滚策略

迁移脚本末尾已包含注释形式的回滚语句，按逆序执行：

ALTER DEFAULT PRIVILEGES IN SCHEMA fdw_etl REVOKE SELECT ON TABLES FROM app_user;
REVOKE SELECT ON ALL TABLES IN SCHEMA fdw_etl FROM app_user;
REVOKE USAGE ON SCHEMA fdw_etl FROM app_user;
DROP SCHEMA IF EXISTS fdw_etl CASCADE;
DROP USER MAPPING IF EXISTS FOR app_user SERVER etl_feiqiu_server;
DROP SERVER IF EXISTS etl_feiqiu_server CASCADE;
DROP EXTENSION IF EXISTS postgres_fdw;

注意：

• DROP SERVER CASCADE 会级联删除依赖的用户映射和外部表
• 如果其他 Schema 也使用 postgres_fdw 扩展，不要执行最后一行 DROP EXTENSION
• 回滚不影响 ETL 库侧的 app Schema 和 RLS 视图

---

4. 验证 SQL

-- 1. 验证 postgres_fdw 扩展已安装
SELECT extname, extversion
FROM pg_extension
WHERE extname = 'postgres_fdw';

-- 2. 验证外部服务器已创建
SELECT srvname, srvowner::regrole, srvoptions
FROM pg_foreign_server
WHERE srvname = 'etl_feiqiu_server';

-- 3. 验证用户映射已创建
SELECT um.umid, r.rolname AS local_role, s.srvname, um.umoptions
FROM pg_user_mappings um
JOIN pg_foreign_server s ON s.srvname = um.srvname
JOIN pg_roles r ON r.rolname = um.usename
WHERE s.srvname = 'etl_feiqiu_server';

-- 4. 验证 fdw_etl Schema 存在且包含外部表
SELECT foreign_table_schema, foreign_table_name, foreign_server_name
FROM information_schema.foreign_tables
WHERE foreign_table_schema = 'fdw_etl'
ORDER BY foreign_table_name;

-- 5. 验证 app_user 对 fdw_etl 有 USAGE 权限
SELECT has_schema_privilege('app_user', 'fdw_etl', 'USAGE') AS fdw_etl_usage;

-- 6. 验证 ALTER DEFAULT PRIVILEGES 已设置
SELECT n.nspname AS schema_name,
       d.defaclacl AS default_acl
FROM pg_default_acl d
JOIN pg_namespace n ON n.oid = d.defaclnamespace
WHERE n.nspname = 'fdw_etl';