Neo
70324d8542
- .kiro/specs/ → docs/specs/（41 个历史需求 spec 迁移，移除 .config.kiro） - CLAUDE.md 三层拆分：根文件精简 + apps/backend/CLAUDE.md + .claude/commands/ - 新增 /spec-close、/pre-change 两个工作流命令 - DDL 基线刷新（从测试库重新导出 11 个文件，dws 35→38 表，biz 18→21 表） - BD_Manual → BD_manual 命名统一（48 个文件） - 修复 3 处文档与数据库不一致（auth.users.status 默认值、scheduled_tasks 字段、RLS 视图数） - 新增 BD_manual_public_rbac_tables.md（public schema 8 张 RBAC/工作流表） - 合并 biz.trigger_jobs 文档（10→12 字段，归档独立文档） - docs/database/README.md 索引更新 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
109 lines
6.4 KiB
Markdown
109 lines
6.4 KiB
Markdown
# 实现计划：小程序数据库基础设施层（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）均使用占位符，按环境替换
|