feat: batch update - gift card breakdown spec, backend APIs, miniprogram pages, ETL finance recharge, docs & migrations

2026-03-20 01:43:48 +08:00
parent 075caf067f
commit 79f9a0e1da
437 changed files with 118603 additions and 976 deletions
--- a/docs/database/BD_Manual_app_schema_rls_views.md
+++ b/docs/database/BD_Manual_app_schema_rls_views.md
@@ -1,9 +1,9 @@
 # BD_Manual：app Schema 与 RLS 视图层

 > 目标库：`test_etl_feiqiu`（通过 `PG_DSN` 连接）
-> 迁移脚本：`db/etl_feiqiu/migrations/2026-02-24__p1_create_app_schema_rls_views.sql`
+> 迁移脚本：`db/etl_feiqiu/migrations/2026-02-24__p1_create_app_schema_rls_views.sql`、`db/etl_feiqiu/migrations/2026-03-19_add_board_rls_views.sql`
 > DDL 位置：`docs/database/ddl/etl_feiqiu__app.sql`（执行后需重新生成）
-> 关联 SPEC：`miniapp-db-foundation`（P1 基础设施层）
+> 关联 SPEC：`miniapp-db-foundation`（P1 基础设施层）、`rns1-board-apis`（BOARD 看板）

 ---

@@ -15,7 +15,7 @@
 ### 新增角色
 - `app_reader`：只读角色（`LOGIN`），拥有 `app` Schema 的 `USAGE` + `SELECT` 权限

-### 新增视图（35 张）
+### 新增视图（38 张）

 **DWD 层（11 张，全部含 `site_id` 过滤）：**

@@ -33,7 +33,7 @@
 | `app.v_dim_staff` | `dwd.dim_staff` | 同上 |
 | `app.v_dim_staff_ex` | `dwd.dim_staff_ex` | 同上 |

-**DWS 层 — 含 `site_id` 过滤（20 张）：**
+**DWS 层 — 含 `site_id` 过滤（23 张）：**

 | 视图 | 源表 |
 |------|------|
@@ -57,6 +57,9 @@
 | `app.v_dws_platform_settlement` | `dws.dws_platform_settlement` |
 | `app.v_dws_assistant_recharge_commission` | `dws.dws_assistant_recharge_commission` |
 | `app.v_dws_order_summary` | `dws.dws_order_summary` |
+| `app.v_dws_assistant_project_tag` | `dws.dws_assistant_project_tag` |
+| `app.v_dws_member_project_tag` | `dws.dws_member_project_tag` |
+| `app.v_dws_member_spending_power_index` | `dws.dws_member_spending_power_index` |

 **DWS 层 — cfg_* 配置表（4 张，无 `site_id`，直接 `SELECT *`）：**

@@ -74,9 +77,10 @@
 | `app_reader` | `app` | `USAGE` + `SELECT ON ALL TABLES` + `ALTER DEFAULT PRIVILEGES` |

 ### P2 预留（注释形式，暂不创建）
- `dws.dws_member_spending_power_index` → `app.v_dws_member_spending_power_index`
 - `dws.dws_assistant_order_contribution` → `app.v_dws_assistant_order_contribution`

+> `v_dws_member_spending_power_index`、`v_dws_assistant_project_tag`、`v_dws_member_project_tag` 已于 2026-03-19 正式创建（迁移脚本 `2026-03-19_add_board_rls_views.sql`）。
+
 ---

 ## 2. 兼容性影响
@@ -113,7 +117,7 @@ DROP ROLE IF EXISTS app_reader;
 -- 1. 验证 app Schema 存在
 SELECT schema_name FROM information_schema.schemata WHERE schema_name = 'app';

-- 2. 验证视图数量（应为 35 张）
+-- 2. 验证视图数量（应为 38 张：原 35 + 2026-03-19 新增 3）
 SELECT count(*) FROM information_schema.views WHERE table_schema = 'app';

 -- 3. 验证 app_reader 角色存在且有 app Schema 权限
--- a/docs/database/BD_Manual_biz_tables.md
+++ b/docs/database/BD_Manual_biz_tables.md
@@ -16,7 +16,7 @@
 |---|------|------|--------|
 | 1 | `biz.coach_tasks` | 助教任务表：存储任务分配、状态、有效期、置顶、放弃原因等 | 15 |
 | 2 | `biz.coach_task_history` | 任务变更历史表：记录任务关闭/新建/置顶/放弃的追溯链 | 9 |
-| 3 | `biz.notes` | 统一备注表：通过 `type` 字段区分普通备注/回访备注/放弃原因，含星星评分 | 14 |
+| 3 | `biz.notes` | 统一备注表：通过 `type` 字段区分普通备注/回访备注/放弃原因，含星星评分 | 15 |
 | 4 | `biz.trigger_jobs` | 触发器配置表：存储 cron/interval/event 三种触发方式的配置与执行状态 | 9 |

 ### 表字段明细
@@ -55,7 +55,7 @@
 | `detail` | JSONB | 可空 | 附加详情（如放弃原因等） |
 | `created_at` | TIMESTAMPTZ | DEFAULT NOW() | 记录时间 |

-#### biz.notes（14 字段）
+#### biz.notes（15 字段）

 | 字段 | 类型 | 约束 | 说明 |
 |------|------|------|------|
@@ -73,6 +73,7 @@
 | `ai_analysis` | TEXT | 可空 | AI 分析结果（P5 实现） |
 | `created_at` | TIMESTAMPTZ | DEFAULT NOW() | 创建时间 |
 | `updated_at` | TIMESTAMPTZ | DEFAULT NOW() | 更新时间 |
+| `score` | SMALLINT | CHECK (1-5)，可空 | 备注星星评分，助教创建备注时可选填写，不参与 AI 分析（RNS1.1 新增） |

 #### biz.trigger_jobs（9 字段）

@@ -99,6 +100,7 @@
 | `notes` | `idx_notes_target` | INDEX | `(site_id, target_type, target_id)`，按目标查询备注加速 |
 | `notes` | CHECK `rating_service_willingness` | CHECK | `BETWEEN 1 AND 5` |
 | `notes` | CHECK `rating_revisit_likelihood` | CHECK | `BETWEEN 1 AND 5` |
+| `notes` | CHECK `score` | CHECK | `score IS NULL OR (score >= 1 AND score <= 5)`（RNS1.1 新增） |
 | `notes` | FK `task_id` | FK | → `biz.coach_tasks(id)` |
 | `trigger_jobs` | UNIQUE `job_name` | UNIQUE | 触发器名称唯一 |

@@ -128,6 +130,44 @@

 ---

+## 2.1 RNS1.3 看板接口引用说明（2026-03-20 补充）
+
+RNS1.3（三看板接口）BOARD-1 助教看板的任务维度查询引用了 `biz.coach_tasks`（无 schema 变更，仅新增读取路径）：
+
+| 表 | 引用接口 | 用途 |
+|----|---------|------|
+| `biz.coach_tasks` | BOARD-1 `_query_coach_tasks()` | 按 `site_id` + `assistant_id` + 日期范围查询任务完成数，按 `task_type` 分类统计 `recall`（召回类：`high_priority_recall` / `priority_recall`）和 `callback`（回访类：`follow_up_visit` / `relationship_building`），筛选条件 `status = 'completed'` + `completed_at BETWEEN start_date AND end_date` |
+
+查询模式：
+```sql
+SELECT assistant_id, task_type, COUNT(*) AS cnt
+FROM biz.coach_tasks
+WHERE site_id = :site_id
+  AND assistant_id = ANY(:assistant_ids)
+  AND status = 'completed'
+  AND completed_at BETWEEN :start_date AND :end_date
+GROUP BY assistant_id, task_type
+```
+
+> 该查询走 `idx_coach_tasks_assistant_status` 索引（`site_id, assistant_id, status`），无需新增索引。
+
+---
+
+## 2.2 RNS1.2 接口引用说明（2026-03-18 补充）
+
+RNS1.2（客户与助教接口）新增 3 个端点，引用了以下 biz/public 表（无 schema 变更，仅新增读取路径）：
+
+| 表 | 引用接口 | 用途 |
+|----|---------|------|
+| `biz.coach_tasks` | CUST-1 `coachTasks` 模块、COACH-1 `visibleTasks`/`hiddenTasks`/`abandonedTasks`/`tasksCompleted` | 查询客户关联的助教任务（按 `member_id`）；查询助教任务分组（按 `assistant_id`、`status` 分组）；统计当月完成任务数 |
+| `biz.notes` | CUST-1 `notes` 模块、COACH-1 `notes`/任务备注 | 查询客户备注（`target_type='member'`，最多 20 条）；查询助教相关备注（最多 20 条）；查询任务关联备注（`task_id` 关联） |
+| `biz.ai_cache` | CUST-1 `aiInsight` 模块 | 查询 AI 分析缓存（`cache_type='app4_analysis'`，`target_id=customerId`），解析 `cache_value` JSON 生成洞察摘要和策略建议 |
+| `public.member_retention_clue` | CUST-1 `retentionClues` 模块 | 查询维客线索（按 `created_at` 倒序），格式与 TASK-2 一致 |
+
+> 以上均为只读查询，不涉及表结构变更。`biz.ai_cache` 表由 P5（AI 集成）创建，`public.member_retention_clue` 表由独立迁移创建。
+
+---
+
 ## 3. 回滚策略

 按逆序 `DROP TABLE IF EXISTS CASCADE`（迁移脚本末尾已包含注释形式的回滚语句）：
--- a/docs/database/BD_Manual_fdw_etl_setup.md
+++ b/docs/database/BD_Manual_fdw_etl_setup.md
@@ -34,9 +34,9 @@

 ### 导入的外部表

-通过 `IMPORT FOREIGN SCHEMA app` 批量导入，外部表与 ETL 库 `app` Schema 中的 RLS 视图一一对应（共 35 张）：
+通过 `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`
- 24 张 DWS 视图：`v_dws_member_consumption_summary`、`v_dws_member_visit_detail` 等
+- 27 张 DWS 视图（含 4 张 cfg_* 配置表）：`v_dws_member_consumption_summary`、`v_dws_member_visit_detail` 等

 ### 权限配置

@@ -46,6 +46,23 @@

 ---

+## 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. 兼容性影响

 | 组件 | 影响 |
--- a/docs/database/BD_Manual_fdw_reverse_retention_clue.md
+++ b/docs/database/BD_Manual_fdw_reverse_retention_clue.md
@@ -0,0 +1,261 @@
+# 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` | 业务库侧建表迁移脚本 |
--- a/docs/database/ddl/etl_feiqiu__app.sql
+++ b/docs/database/ddl/etl_feiqiu__app.sql
@@ -1187,3 +1187,34 @@ SELECT site_id,
   FROM core.dim_site s;
 ;

+
+-- 2026-03-19 新增：BOARD 看板所需的 3 个 RLS 视图
+-- 迁移脚本：db/etl_feiqiu/migrations/2026-03-19_add_board_rls_views.sql
+
+CREATE OR REPLACE VIEW app.v_dws_assistant_project_tag AS
+SELECT id, site_id, tenant_id, assistant_id, time_window,
+       category_code, category_name, short_name,
+       duration_seconds, total_seconds, percentage, is_tagged,
+       computed_at, created_at, updated_at
+FROM dws.dws_assistant_project_tag
+WHERE site_id = current_setting('app.current_site_id')::bigint;
+
+CREATE OR REPLACE VIEW app.v_dws_member_project_tag AS
+SELECT id, site_id, tenant_id, member_id, time_window,
+       category_code, category_name, short_name,
+       duration_seconds, total_seconds, percentage, is_tagged,
+       computed_at, created_at, updated_at
+FROM dws.dws_member_project_tag
+WHERE site_id = current_setting('app.current_site_id')::bigint;
+
+CREATE OR REPLACE VIEW app.v_dws_member_spending_power_index AS
+SELECT spi_id, site_id, member_id,
+       spend_30, spend_90, recharge_90,
+       orders_30, orders_90, visit_days_30, visit_days_90,
+       avg_ticket_90, active_weeks_90, daily_spend_ewma_90,
+       score_level_raw, score_speed_raw, score_stability_raw,
+       score_level_display, score_speed_display, score_stability_display,
+       raw_score, display_score,
+       calc_time, created_at, updated_at
+FROM dws.dws_member_spending_power_index
+WHERE site_id = current_setting('app.current_site_id')::bigint;
--- a/docs/database/ddl/etl_feiqiu__dws.sql
+++ b/docs/database/ddl/etl_feiqiu__dws.sql
@@ -481,6 +481,12 @@ CREATE TABLE dws.dws_finance_recharge_summary (
    total_card_balance numeric(14,2) DEFAULT 0 NOT NULL,
    cash_card_balance numeric(14,2) DEFAULT 0 NOT NULL,
    gift_card_balance numeric(14,2) DEFAULT 0 NOT NULL,
+    gift_liquor_balance numeric(14,2) DEFAULT 0 NOT NULL,
+    gift_table_fee_balance numeric(14,2) DEFAULT 0 NOT NULL,
+    gift_voucher_balance numeric(14,2) DEFAULT 0 NOT NULL,
+    gift_liquor_recharge numeric(14,2) DEFAULT 0 NOT NULL,
+    gift_table_fee_recharge numeric(14,2) DEFAULT 0 NOT NULL,
+    gift_voucher_recharge numeric(14,2) DEFAULT 0 NOT NULL,
    created_at timestamp with time zone DEFAULT now() NOT NULL,
    updated_at timestamp with time zone DEFAULT now() NOT NULL
 );
--- a/docs/database/ddl/zqyy_app__biz.sql
+++ b/docs/database/ddl/zqyy_app__biz.sql
@@ -92,7 +92,8 @@ CREATE TABLE biz.notes (
    ai_score smallint,
    ai_analysis text,
    created_at timestamp with time zone DEFAULT now(),
-    updated_at timestamp with time zone DEFAULT now()
+    updated_at timestamp with time zone DEFAULT now(),
+    score smallint
 );

 CREATE TABLE biz.trigger_jobs (