# BD 手册：FDW 反向映射 — ETL 库读取业务库维客线索

> 创建日期：2026-02-26（原 `member_birthday_manual`），2026-03-19 重写为当前版本
> 替代文档：`docs/database/_archived/BD_Manual_fdw_reverse_member_birthday.md`
> 关联 SQL：`db/fdw/setup_fdw_reverse.sql`（生产）、`db/fdw/setup_fdw_reverse_test.sql`（测试）
> 关联表文档：`docs/database/BD_Manual_member_retention_clue.md`

---

## 1. 概述

在 `etl_feiqiu`（生产）/ `test_etl_feiqiu`（测试）数据库中，通过 `postgres_fdw` 创建指向 `zqyy_app` / `test_zqyy_app` 的外部表 `fdw_app.member_retention_clue`，使 ETL DWS 任务可只读访问助教为会员记录的维客线索数据。

方向：`etl_feiqiu → zqyy_app`（与正向 FDW `setup_fdw.sql` 的 `zqyy_app → etl_feiqiu` 方向相反）。

### 数据流向

```
zqyy_app.public.member_retention_clue  （业务库源表，后端 API 写入）
        │
        │  postgres_fdw（只读）
        ▼
etl_feiqiu.fdw_app.member_retention_clue  （ETL 库外部表，DWS 任务读取）
```

### 历史沿革

| 日期 | 事件 |
|------|------|
| 2026-02-22 | 初版：`fdw_app.member_birthday_manual`（映射助教手动补录生日表） |
| 2026-02-26 | 重构：`member_birthday_manual` → `member_retention_clue`（维客线索替代单一生日方案） |
| 2026-02-27 | 业务库侧新增 `source` 列（线索来源），FDW 外部表定义未同步更新 |
| 2026-03-08 | 业务库侧 `category` 枚举对齐：`客户基础信息` → `客户基础` |

---

## 2. 变更说明

### 2.1 新增对象

| 所在库 | 对象类型 | 名称 | 说明 |
|--------|---------|------|------|
| etl_feiqiu / test_etl_feiqiu | 扩展 | `postgres_fdw` | PostgreSQL 外部数据包装器（如已安装则跳过） |
| etl_feiqiu | 外部服务器 | `zqyy_app_server` | 指向 `zqyy_app` 业务库（host/port 按环境配置） |
| test_etl_feiqiu | 外部服务器 | `test_zqyy_app_server` | 指向 `test_zqyy_app` 测试业务库 |
| etl_feiqiu / test_etl_feiqiu | 用户映射 | `etl_user → app_reader` | ETL 连接角色映射到业务库只读角色 |
| etl_feiqiu / test_etl_feiqiu | Schema | `fdw_app` | 存放来自业务库的外部表 |
| etl_feiqiu / test_etl_feiqiu | 外部表 | `fdw_app.member_retention_clue` | 映射 `public.member_retention_clue` |

### 2.2 外部表列定义

| 列名 | 类型 | 说明 |
|------|------|------|
| id | BIGINT | 自增主键 |
| member_id | BIGINT | 会员 ID |
| category | VARCHAR(20) | 线索大类（6 值枚举：客户基础/消费习惯/玩法偏好/促销偏好/社交关系/重要反馈） |
| summary | VARCHAR(200) | 摘要 |
| detail | TEXT | 详情 |
| recorded_by_assistant_id | BIGINT | 记录助教 ID |
| recorded_by_name | VARCHAR(50) | 记录助教姓名 |
| recorded_at | TIMESTAMPTZ | 记录时间 |
| site_id | BIGINT | 门店 ID |

> **注意**：业务库侧 `member_retention_clue` 已于 2026-02-27 新增 `source VARCHAR(20)` 列（线索来源：`manual` / `ai_consumption` / `ai_note`），但当前 FDW 外部表定义（`db/fdw/setup_fdw_reverse*.sql`）尚未包含此列。如 ETL 任务需要读取 `source` 字段，需更新外部表定义并重新执行部署脚本。

### 2.3 角色与权限

| 角色 | 所在库 | 用途 |
|------|--------|------|
| `etl_user` | etl_feiqiu / test_etl_feiqiu | ETL 连接角色，通过 FDW 只读访问业务库数据 |
| `app_reader` | zqyy_app / test_zqyy_app | 业务库只读角色，供 FDW 用户映射使用 |

权限配置：

| 角色 | Schema | 权限 |
|------|--------|------|
| `etl_user` | `fdw_app` | `USAGE` + `SELECT ON ALL TABLES` + `ALTER DEFAULT PRIVILEGES`（自动授权未来新增外部表） |

---

## 3. 与正向 FDW 的对比

| 维度 | 正向 FDW（`setup_fdw.sql`） | 反向 FDW（`setup_fdw_reverse.sql`） |
|------|---------------------------|-------------------------------------|
| 执行位置 | `zqyy_app` 业务库 | `etl_feiqiu` ETL 库 |
| 数据方向 | 业务库读取 ETL 数据 | ETL 库读取业务库数据 |
| 目标 Schema | `fdw_etl`（35 张外部表） | `fdw_app`（1 张外部表） |
| 导入方式 | `IMPORT FOREIGN SCHEMA app`（批量） | `CREATE FOREIGN TABLE`（逐表定义） |
| 消费方 | 后端 API | ETL DWS 任务 |
| 文档 | `BD_Manual_fdw_etl_setup.md` | 本文档 |

---

## 4. 兼容性影响

| 组件 | 影响 |
|------|------|
| ETL DWS 任务 | 可通过 `fdw_app.member_retention_clue` 只读访问维客线索数据。当前无 DWS 任务直接消费此表（原 `member_birthday_manual` 的生日读取逻辑已移除，生日仅从 `dim_member.birthday` 读取） |
| 后端 API | 无影响。后端直接写入 `zqyy_app.public.member_retention_clue`，不经过 FDW |
| 小程序 | 无影响。小程序通过后端 API 间接访问 |
| 管理后台 | 无影响 |
| 正向 FDW（`fdw_etl`） | 无影响。两个方向的 FDW 配置完全独立 |
| 业务库 `member_retention_clue` 表 | 无影响。FDW 为只读映射，不修改源表 |

### 幂等性说明

`CREATE FOREIGN TABLE IF NOT EXISTS` 确保重复执行不会报错。如需更新列定义（如添加 `source` 列），需先 `DROP FOREIGN TABLE` 再重建，或使用 `ALTER FOREIGN TABLE ADD COLUMN`。

---

## 5. 回滚策略

### 5.1 完整回滚（按逆序执行）

```sql
-- 在 etl_feiqiu（生产）中执行：
ALTER DEFAULT PRIVILEGES IN SCHEMA fdw_app REVOKE SELECT ON TABLES FROM etl_user;
REVOKE SELECT ON ALL TABLES IN SCHEMA fdw_app FROM etl_user;
REVOKE USAGE ON SCHEMA fdw_app FROM etl_user;
DROP FOREIGN TABLE IF EXISTS fdw_app.member_retention_clue;
DROP SCHEMA IF EXISTS fdw_app CASCADE;
DROP USER MAPPING IF EXISTS FOR etl_user SERVER zqyy_app_server;
DROP SERVER IF EXISTS zqyy_app_server CASCADE;
-- 注意：如果其他外部表也使用 postgres_fdw，不要执行 DROP EXTENSION
```

```sql
-- 在 test_etl_feiqiu（测试）中执行：
ALTER DEFAULT PRIVILEGES IN SCHEMA fdw_app REVOKE SELECT ON TABLES FROM etl_user;
REVOKE SELECT ON ALL TABLES IN SCHEMA fdw_app FROM etl_user;
REVOKE USAGE ON SCHEMA fdw_app FROM etl_user;
DROP FOREIGN TABLE IF EXISTS fdw_app.member_retention_clue;
DROP SCHEMA IF EXISTS fdw_app CASCADE;
DROP USER MAPPING IF EXISTS FOR etl_user SERVER test_zqyy_app_server;
DROP SERVER IF EXISTS test_zqyy_app_server CASCADE;
```

### 5.2 仅删除外部表（保留 FDW 基础设施）

```sql
DROP FOREIGN TABLE IF EXISTS fdw_app.member_retention_clue;
```

回滚无数据丢失风险：外部表不存储数据，仅为远程表的映射定义。

---

## 6. 验证 SQL

以下 SQL 在 ETL 库（`etl_feiqiu` 或 `test_etl_feiqiu`）中执行：

```sql
-- 1. 确认 postgres_fdw 扩展已安装
SELECT extname, extversion
  FROM pg_extension
 WHERE extname = 'postgres_fdw';
-- 预期：1 行

-- 2. 确认外部服务器存在
-- 生产：
SELECT srvname, srvoptions FROM pg_foreign_server WHERE srvname = 'zqyy_app_server';
-- 测试：
SELECT srvname, srvoptions FROM pg_foreign_server WHERE srvname = 'test_zqyy_app_server';
-- 预期：1 行，srvoptions 包含正确的 host/dbname/port

-- 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 IN ('zqyy_app_server', 'test_zqyy_app_server')
   AND r.rolname = 'etl_user';
-- 预期：1 行

-- 4. 确认 fdw_app schema 存在
SELECT schema_name
  FROM information_schema.schemata
 WHERE schema_name = 'fdw_app';
-- 预期：1 行

-- 5. 确认外部表列结构完整（当前 9 列）
SELECT column_name, data_type
  FROM information_schema.columns
 WHERE table_schema = 'fdw_app'
   AND table_name = 'member_retention_clue'
 ORDER BY ordinal_position;
-- 预期：9 行（id, member_id, category, summary, detail,
--              recorded_by_assistant_id, recorded_by_name, recorded_at, site_id）

-- 6. 确认外部表在 information_schema.foreign_tables 中注册
SELECT foreign_table_schema, foreign_table_name, foreign_server_name
  FROM information_schema.foreign_tables
 WHERE foreign_table_schema = 'fdw_app'
   AND foreign_table_name = 'member_retention_clue';
-- 预期：1 行

-- 7. 确认 etl_user 对 fdw_app 有 USAGE 权限
SELECT has_schema_privilege('etl_user', 'fdw_app', 'USAGE') AS has_usage;
-- 预期：true

-- 8. 确认外部表可读取（需业务库侧表已存在且网络连通）
SELECT COUNT(*) FROM fdw_app.member_retention_clue;
-- 预期：返回行数（可能为 0）

-- 9. 确认 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_app';
-- 预期：1 行，default_acl 包含 etl_user 的 SELECT 权限
```

---

## 7. 已知差异与待办

| 项目 | 状态 | 说明 |
|------|------|------|
| `source` 列缺失 | ⚠️ 待同步 | 业务库侧已有 `source VARCHAR(20) NOT NULL DEFAULT 'manual'`（2026-02-27），FDW 外部表定义未包含。当前无 ETL 任务需要此字段，但未来如需读取线索来源需先更新外部表 |
| DWS 任务消费 | 📋 待规划 | 原 `member_birthday_manual` 的 DWS 消费逻辑已移除。维客线索的 DWS 聚合任务尚未规划 |

### source 列同步方法（备用）

如需同步 `source` 列，在 ETL 库中执行：

```sql
-- 方法 1：ALTER 追加列（推荐，无需重建）
ALTER FOREIGN TABLE fdw_app.member_retention_clue
  ADD COLUMN source VARCHAR(20);

-- 方法 2：DROP + 重建（完整重置）
DROP FOREIGN TABLE IF EXISTS fdw_app.member_retention_clue;
CREATE FOREIGN TABLE fdw_app.member_retention_clue (
    id                       BIGINT,
    member_id                BIGINT,
    category                 VARCHAR(20),
    summary                  VARCHAR(200),
    detail                   TEXT,
    recorded_by_assistant_id BIGINT,
    recorded_by_name         VARCHAR(50),
    recorded_at              TIMESTAMPTZ,
    site_id                  BIGINT,
    source                   VARCHAR(20)
) SERVER zqyy_app_server
  OPTIONS (schema_name 'public', table_name 'member_retention_clue');
```

同步后需更新 `db/fdw/setup_fdw_reverse.sql` 和 `db/fdw/setup_fdw_reverse_test.sql` 中的外部表定义。

---

## 8. 关联文件

| 文件 | 说明 |
|------|------|
| `db/fdw/setup_fdw_reverse.sql` | 生产环境部署脚本（在 `etl_feiqiu` 中执行） |
| `db/fdw/setup_fdw_reverse_test.sql` | 测试环境部署脚本（在 `test_etl_feiqiu` 中执行） |
| `docs/database/BD_Manual_member_retention_clue.md` | 业务库侧 `member_retention_clue` 表结构文档 |
| `docs/database/BD_Manual_fdw_etl_setup.md` | 正向 FDW 配置文档（方向相反） |
| `docs/database/BD_Manual_app_schema_rls_views.md` | ETL 库 `app` Schema RLS 视图层文档 |
| `db/zqyy_app/migrations/2026-02-26__refactor_birthday_to_retention_clue.sql` | 业务库侧建表迁移脚本 |