root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dev
Neo-ZQYY/.kiro/specs/01-miniapp-db-foundation/requirements.md
Neo b25308c3f4 feat: P1-P3 全栈集成 — 数据库基础 + DWS 扩展 + 小程序鉴权 + 工程化体系 
## P1 数据库基础
- zqyy_app: 创建 auth/biz schema、FDW 连接 etl_feiqiu
- etl_feiqiu: 创建 app schema RLS 视图、商品库存预警表
- 清理 assistant_abolish 残留数据

## P2 ETL/DWS 扩展
- 新增 DWS 助教订单贡献度表 (dws.assistant_order_contribution)
- 新增 assistant_order_contribution_task 任务及 RLS 视图
- member_consumption 增加充值字段、assistant_daily 增加处罚字段
- 更新 ODS/DWD/DWS 任务文档及业务规则文档
- 更新 consistency_checker、flow_runner、task_registry 等核心模块

## P3 小程序鉴权系统
- 新增 xcx_auth 路由/schema（微信登录 + JWT）
- 新增 wechat/role/matching/application 服务层
- zqyy_app 鉴权表迁移 + 角色权限种子数据
- auth/dependencies.py 支持小程序 JWT 鉴权

## 文档与审计
- 新增 DOCUMENTATION-MAP 文档导航
- 新增 7 份 BD_Manual 数据库变更文档
- 更新 DDL 基线快照（etl_feiqiu 6 schema + zqyy_app auth）
- 新增全栈集成审计记录、部署检查清单更新
- 新增 BACKLOG 路线图、FDW→Core 迁移计划

## Kiro 工程化
- 新增 5 个 Spec（P1/P2/P3/全栈集成/核心业务）
- 新增审计自动化脚本（agent_on_stop/build_audit_context/compliance_prescan）
- 新增 6 个 Hook（合规检查/会话日志/提交审计等）
- 新增 doc-map steering 文件

## 运维与测试
- 新增 ops 脚本：迁移验证/API 健康检查/ETL 监控/集成报告
- 新增属性测试：test_dws_contribution / test_auth_system
- 清理过期 export 报告文件
- 更新 .gitignore 排除规则
2026-02-26 08:03:53 +08:00

7.2 KiB
Raw Permalink Blame History

需求文档：小程序数据库基础设施层（miniapp-db-foundation）

简介

P1 基础设施层是整个小程序系统的第一个 SPEC，无前置依赖，是所有后续 SPEC 的硬依赖。本 SPEC 负责在业务库 test_zqyy_app 中建立清晰的 Schema 划分（auth + biz），在 ETL 库 test_etl_feiqiu 中为数据依赖矩阵列出的所有 DWD/DWS 表创建 RLS 视图（按 site_id 隔离），并通过 postgres_fdw 将 RLS 视图映射为业务库的外部表，使后端无需直连 ETL 库即可读取汇总/维度数据。

术语表

  • Schema_Manager：负责在 PostgreSQL 数据库中创建和管理 Schema、权限配置的迁移脚本系统
  • RLS_View_Layer：在 test_etl_feiqiu.app Schema 中创建的一组视图，通过 current_setting('app.current_site_id') 按 site_id 过滤数据，实现行级安全隔离
  • FDW_Bridge：通过 postgres_fdw 扩展在 test_zqyy_app.fdw_etl Schema 中创建的外部表集合，只读映射 ETL 库 app Schema 的 RLS 视图
  • Migration_Script：存放在 db/zqyy_app/migrations/ 或 db/etl_feiqiu/migrations/ 中的纯 SQL 迁移脚本，以日期前缀命名
  • Validation_Script：用于验证数据库对象是否正确创建、权限是否配置正确、数据是否可查询的 Python 脚本
  • site_id：门店标识符，类型为 BIGINT，用于多门店数据隔离
  • app_reader：ETL 库侧的只读角色，供 FDW 用户映射使用
  • app_user：业务库侧的应用连接角色，通过 FDW 读取 ETL 数据

需求

需求 1：业务库 Schema 划分与权限配置

用户故事： 作为后端开发者，我需要 test_zqyy_app 中有清晰的 Schema 划分（auth + biz），以便按功能组织业务表。

验收标准

  1. WHEN Migration_Script 执行完成, THE Schema_Manager SHALL 在 test_zqyy_app 中创建 auth Schema
  2. WHEN Migration_Script 执行完成, THE Schema_Manager SHALL 在 test_zqyy_app 中创建 biz Schema
  3. WHEN auth Schema 创建完成, THE Schema_Manager SHALL 授予 app_user 角色对 auth Schema 的 USAGE 权限和对其中所有表的 SELECT、INSERT、UPDATE、DELETE 权限
  4. WHEN biz Schema 创建完成, THE Schema_Manager SHALL 授予 app_user 角色对 biz Schema 的 USAGE 权限和对其中所有表的 SELECT、INSERT、UPDATE、DELETE 权限
  5. WHEN 新表在 auth 或 biz Schema 中创建, THE Schema_Manager SHALL 通过 ALTER DEFAULT PRIVILEGES 自动授予 app_user 角色相应权限
  6. THE Migration_Script SHALL 保留 public Schema 中现有的系统管理表（admin_users、roles、permissions 等）不受影响

需求 2：ETL 库 RLS 视图层创建

用户故事： 作为系统管理员，我需要 RLS 视图按 site_id 隔离数据，以便多门店数据安全。

验收标准

  1. WHEN Migration_Script 执行完成, THE Schema_Manager SHALL 在 test_etl_feiqiu 中创建 app Schema（如不存在）
  2. WHEN app Schema 创建完成, THE RLS_View_Layer SHALL 为数据依赖矩阵中列出的每张 DWD 表创建对应的 RLS 视图（共 11 张：dim_member、dim_assistant、dim_member_card_account、dim_table、dwd_settlement_head、dwd_table_fee_log、dwd_assistant_service_log、dwd_recharge_order、dwd_store_goods_sale、dim_staff、dim_staff_ex）
  3. WHEN app Schema 创建完成, THE RLS_View_Layer SHALL 为数据依赖矩阵中列出的每张 DWS 表创建对应的 RLS 视图（共 24 张，包含 dws_* 和 cfg_* 表）
  4. THE RLS_View_Layer 中每个视图 SHALL 包含 WHERE site_id = current_setting('app.current_site_id')::bigint 过滤条件
  5. WHEN 设置 app.current_site_id 为某门店 ID 后查询 RLS 视图, THE RLS_View_Layer SHALL 仅返回该门店的数据
  6. WHEN 未设置 app.current_site_id 时查询 RLS 视图, THE RLS_View_Layer SHALL 抛出错误而非返回全部数据
  7. THE Schema_Manager SHALL 授予 app_reader 角色对 app Schema 的 USAGE 权限和对其中所有视图的 SELECT 权限
  8. THE RLS_View_Layer SHALL 为 P2 待建表（dws_member_spending_power_index、dws_assistant_order_contribution）在迁移脚本中以注释形式预留位置

需求 3：FDW 外部表映射

用户故事： 作为后端开发者，我需要通过 FDW 从 test_zqyy_app 读取 ETL 库的 DWS/DWD 数据，以便小程序页面展示 ETL 计算结果。

验收标准

  1. WHEN Migration_Script 执行完成, THE FDW_Bridge SHALL 在 test_zqyy_app 中安装 postgres_fdw 扩展
  2. WHEN postgres_fdw 扩展安装完成, THE FDW_Bridge SHALL 创建指向 test_etl_feiqiu 的外部服务器 test_etl_feiqiu_server
  3. WHEN 外部服务器创建完成, THE FDW_Bridge SHALL 创建 app_user 到 app_reader 的用户映射
  4. WHEN 用户映射创建完成, THE FDW_Bridge SHALL 在 fdw_etl Schema 中通过 IMPORT FOREIGN SCHEMA app 导入所有外部表
  5. WHEN 外部表导入完成, THE FDW_Bridge SHALL 对 fdw_etl Schema 中的每张外部表执行 SELECT 查询验证可读性
  6. WHEN 外部表查询成功, THE FDW_Bridge 返回的数据 SHALL 与 ETL 库 app Schema 中对应 RLS 视图的数据一致
  7. THE FDW_Bridge SHALL 授予 app_user 角色对 fdw_etl Schema 的 USAGE 权限和对其中所有外部表的 SELECT 权限

需求 4：迁移脚本管理

用户故事： 作为后端开发者，我需要所有数据库变更都有对应的迁移脚本，以便变更可追溯、可重放、可回滚。

验收标准

  1. THE Migration_Script SHALL 将 ETL 库变更（RLS 视图创建、app Schema 权限）存放在 db/etl_feiqiu/migrations/ 目录中
  2. THE Migration_Script SHALL 将业务库变更（Schema 创建、FDW 配置）存放在 db/zqyy_app/migrations/ 目录中
  3. THE Migration_Script SHALL 使用日期前缀命名（格式：YYYY-MM-DD__<描述>.sql）
  4. THE Migration_Script SHALL 在每个脚本中包含回滚语句（以注释形式）
  5. THE Migration_Script SHALL 使用 IF NOT EXISTS / OR REPLACE 等幂等语法，确保重复执行不会报错
  6. THE Migration_Script SHALL 使用 UTF-8 编码，纯 SQL（非 ORM）

需求 5：端到端验证

用户故事： 作为后端开发者，我需要一个自动化验证脚本，确认所有数据库对象正确创建且数据可访问。

验收标准

  1. WHEN Validation_Script 执行时, THE Validation_Script SHALL 检查 test_zqyy_app 中 auth 和 biz Schema 是否存在
  2. WHEN Validation_Script 执行时, THE Validation_Script SHALL 检查 test_etl_feiqiu.app Schema 中所有 RLS 视图是否存在
  3. WHEN Validation_Script 执行时, THE Validation_Script SHALL 检查 test_zqyy_app.fdw_etl 中所有外部表是否存在
  4. WHEN Validation_Script 执行时, THE Validation_Script SHALL 对每张外部表执行 SELECT count(*) 验证可查询性
  5. WHEN Validation_Script 执行时, THE Validation_Script SHALL 设置 app.current_site_id 后验证 RLS 视图正确过滤数据
  6. WHEN Validation_Script 执行时, THE Validation_Script SHALL 验证 app_user 和 app_reader 角色的权限配置正确
  7. WHEN 验证发现异常, THE Validation_Script SHALL 输出具体的失败项和错误信息
  8. THE Validation_Script SHALL 从 .env 加载数据库连接参数（PG_DSN、APP_DB_DSN），缺失时立即报错终止
Reference in New Issue View Git Blame Copy Permalink