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

## 概述

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

## 任务

- [x] 1. ETL 库：创建 app Schema 与 RLS 视图
  - [x] 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_

  - [x] 1.2 编写属性测试：RLS 视图定义包含 site_id 过滤
    - **Property 3: RLS 视图定义包含 site_id 过滤**
    - 遍历 `app` Schema 所有视图，查询 `pg_views.definition`，验证含 `site_id` 列的源表对应视图包含 `current_setting` 过滤条件
    - **Validates: Requirements 2.4**

  - [x] 1.3 编写属性测试：未设置 site_id 时 RLS 视图拒绝访问
    - **Property 5: 未设置 site_id 时 RLS 视图拒绝访问**
    - 遍历所有含 `site_id` 过滤的 RLS 视图，在新会话（未设置 `app.current_site_id`）中执行 `SELECT`，验证抛出错误
    - **Validates: Requirements 2.6**

- [x] 2. 业务库：创建 auth/biz Schema 与权限
  - [x] 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_

  - [x] 2.2 编写属性测试：默认权限自动授予
    - **Property 1: 默认权限自动授予**
    - 使用 hypothesis 生成随机合法表名，在 `auth`/`biz` 中创建临时表，验证 `app_user` 自动获得 SELECT/INSERT/UPDATE/DELETE 权限，测试后清理
    - **Validates: Requirements 1.5**

- [x] 3. 业务库：配置 FDW 跨库映射
  - [x] 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_

  - [x] 3.2 编写属性测试：FDW 外部表完整性与数据一致性
    - **Property 6: FDW 外部表完整性与数据一致性**
    - 遍历 ETL 库 `app` Schema 所有视图，验证 `fdw_etl` 中存在对应外部表且可查询；在相同 `site_id` 下对比数据一致性
    - **Validates: Requirements 3.4, 3.5, 3.6**

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

- [x] 5. 编写端到端验证脚本
  - [x] 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_

  - [x] 5.2 编写属性测试：RLS 过滤正确性
    - **Property 4: RLS 过滤正确性**
    - 使用 hypothesis 生成随机 `site_id`，设置 `app.current_site_id` 后查询含 `site_id` 的 RLS 视图，验证返回结果中所有行的 `site_id` 等于设置值
    - **Validates: Requirements 2.5**

  - [x] 5.3 编写属性测试：环境变量缺失报错
    - **Property 9: 环境变量缺失时验证脚本报错**
    - 使用 hypothesis 生成 `PG_DSN`/`APP_DB_DSN` 的缺失组合，验证脚本抛出 `RuntimeError`
    - **Validates: Requirements 5.8**

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

  - [x] 5.5 编写属性测试：迁移脚本幂等性
    - **Property 8: 迁移脚本幂等性**
    - 对每个迁移脚本连续执行两次，验证第二次执行无错误
    - **Validates: Requirements 4.5**

- [x] 6. Final checkpoint — 全量验证
  - 运行验证脚本 `python scripts/ops/validate_p1_db_foundation.py`，确认所有检查项通过
  - 运行属性测试 `cd C:\NeoZQYY && pytest tests/ -v -k p1`，确认所有属性测试通过
  - 如有问题请告知用户

## 说明

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