Neo-ZQYY/docs/specs/01-miniapp-db-foundation/tasks.md

实现计划：小程序数据库基础设施层（miniapp-db-foundation）

概述

按照"ETL 库先行 → 业务库跟进 → FDW 桥接 → 验证收尾"的顺序，将设计拆分为可增量执行的编码任务。每个迁移脚本使用幂等语法，所有连接参数通过环境变量驱动。

任务

• 1. ETL 库：创建 app Schema 与 RLS 视图

  • 1.1 编写迁移脚本 db/etl_feiqiu/migrations/YYYY-MM-DD__p1_create_app_schema_rls_views.sql

    • 创建 app Schema（CREATE SCHEMA IF NOT EXISTS app）
    • 创建 app_reader 角色（条件创建，DO $$ ... IF NOT EXISTS ... END $$）
    • 为 11 张 DWD 表创建 RLS 视图（CREATE OR REPLACE VIEW app.v_<表名> AS SELECT * FROM dwd.<表名> WHERE site_id = current_setting('app.current_site_id')::bigint）
    • 为 24 张 DWS 表创建 RLS 视图（同上模式；cfg_* 配置表若无 site_id 列则直接 SELECT * 不加过滤）
    • 在脚本末尾以注释形式预留 P2 待建表位置（dws_member_spending_power_index、dws_assistant_order_contribution）
    • 授予 app_reader 对 app Schema 的 USAGE + SELECT 权限 + ALTER DEFAULT PRIVILEGES
    • 包含回滚语句（注释形式）
    • Requirements: 2.1, 2.2, 2.3, 2.4, 2.7, 2.8, 4.1, 4.3, 4.4, 4.5, 4.6

  • 1.2 编写属性测试：RLS 视图定义包含 site_id 过滤

    • Property 3: RLS 视图定义包含 site_id 过滤
    • 遍历 app Schema 所有视图，查询 pg_views.definition，验证含 site_id 列的源表对应视图包含 current_setting 过滤条件
    • Validates: Requirements 2.4

  • 1.3 编写属性测试：未设置 site_id 时 RLS 视图拒绝访问

    • Property 5: 未设置 site_id 时 RLS 视图拒绝访问
    • 遍历所有含 site_id 过滤的 RLS 视图，在新会话（未设置 app.current_site_id）中执行 SELECT，验证抛出错误
    • Validates: Requirements 2.6

• 2. 业务库：创建 auth/biz Schema 与权限

  • 2.1 编写迁移脚本 db/zqyy_app/migrations/YYYY-MM-DD__p1_create_auth_biz_schemas.sql

    • 创建 auth Schema（CREATE SCHEMA IF NOT EXISTS auth）
    • 创建 biz Schema（CREATE SCHEMA IF NOT EXISTS biz）
    • 授予 app_user 对 auth/biz 的 USAGE + CRUD 权限
    • 设置 ALTER DEFAULT PRIVILEGES 自动授权未来新表
    • 包含回滚语句（注释形式）
    • Requirements: 1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 4.2, 4.3, 4.4, 4.5, 4.6

  • 2.2 编写属性测试：默认权限自动授予

    • Property 1: 默认权限自动授予
    • 使用 hypothesis 生成随机合法表名，在 auth/biz 中创建临时表，验证 app_user 自动获得 SELECT/INSERT/UPDATE/DELETE 权限，测试后清理
    • Validates: Requirements 1.5

• 3. 业务库：配置 FDW 跨库映射

  • 3.1 编写迁移脚本 db/zqyy_app/migrations/YYYY-MM-DD__p1_setup_fdw_etl.sql

    • 安装 postgres_fdw 扩展
    • 创建外部服务器 etl_feiqiu_server（host/dbname/port 使用占位符 '***'，按环境替换）
    • 创建 app_user → app_reader 用户映射
    • 创建 fdw_etl Schema
    • 执行 IMPORT FOREIGN SCHEMA app FROM SERVER etl_feiqiu_server INTO fdw_etl
    • 授予 app_user 对 fdw_etl 的 USAGE + SELECT 权限 + ALTER DEFAULT PRIVILEGES
    • 包含回滚语句（注释形式）
    • Requirements: 3.1, 3.2, 3.3, 3.4, 3.7, 4.2, 4.3, 4.4, 4.5, 4.6

  • 3.2 编写属性测试：FDW 外部表完整性与数据一致性

    • Property 6: FDW 外部表完整性与数据一致性
    • 遍历 ETL 库 app Schema 所有视图，验证 fdw_etl 中存在对应外部表且可查询；在相同 site_id 下对比数据一致性
    • Validates: Requirements 3.4, 3.5, 3.6

• 4. Checkpoint — 迁移脚本验证

  • 确保三个迁移脚本均可在测试环境中成功执行（按顺序：ETL 库 → 业务库 Schema → 业务库 FDW）
  • 验证重复执行不报错（幂等性）
  • 如有问题请告知用户

• 5. 编写端到端验证脚本

  • 5.1 创建 scripts/ops/validate_p1_db_foundation.py

    • 通过 load_dotenv() 加载根 .env，读取 PG_DSN 和 APP_DB_DSN，缺失时 RuntimeError 终止
    • 检查业务库中 auth、biz Schema 存在性
    • 检查 ETL 库中 app Schema 及所有 RLS 视图存在性（对照设计文档中的 35 张视图清单）
    • 检查业务库中 fdw_etl Schema 及所有外部表存在性
    • 对每张外部表执行 SELECT count(*) 验证可查询性
    • 设置 app.current_site_id 后验证 RLS 视图过滤正确性
    • 验证 app_user 和 app_reader 角色权限配置
    • 输出结构化验证结果（通过/失败/跳过），失败项附带错误信息
    • Requirements: 5.1, 5.2, 5.3, 5.4, 5.5, 5.6, 5.7, 5.8

  • 5.2 编写属性测试：RLS 过滤正确性

    • Property 4: RLS 过滤正确性
    • 使用 hypothesis 生成随机 site_id，设置 app.current_site_id 后查询含 site_id 的 RLS 视图，验证返回结果中所有行的 site_id 等于设置值
    • Validates: Requirements 2.5

  • 5.3 编写属性测试：环境变量缺失报错

    • Property 9: 环境变量缺失时验证脚本报错
    • 使用 hypothesis 生成 PG_DSN/APP_DB_DSN 的缺失组合，验证脚本抛出 RuntimeError
    • Validates: Requirements 5.8

  • 5.4 编写属性测试：迁移脚本结构合规性

    • Property 7: 迁移脚本结构合规性
    • 遍历本次新增的迁移脚本文件，验证文件名匹配 YYYY-MM-DD__*.sql 模式，且内容包含回滚语句注释
    • Validates: Requirements 4.3, 4.4

  • 5.5 编写属性测试：迁移脚本幂等性

    • Property 8: 迁移脚本幂等性
    • 对每个迁移脚本连续执行两次，验证第二次执行无错误
    • Validates: Requirements 4.5

• 6. Final checkpoint — 全量验证

  • 运行验证脚本 python scripts/ops/validate_p1_db_foundation.py，确认所有检查项通过
  • 运行属性测试 cd C:\Project\NeoZQYY && pytest tests/ -v -k p1，确认所有属性测试通过
  • 如有问题请告知用户

说明

• 标记 * 的子任务为可选，可跳过以加速 MVP
• 每个任务引用具体的需求编号，确保可追溯
• Checkpoint 确保增量验证
• 属性测试使用 Python hypothesis 框架，测试文件放在根目录 tests/ 下
• 迁移脚本中的数据库连接参数（host/dbname/port/password）均使用占位符，按环境替换