Neo
b25308c3f4
## 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 排除规则
89 lines
7.2 KiB
Markdown
89 lines
7.2 KiB
Markdown
# 需求文档：小程序数据库基础设施层（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`），缺失时立即报错终止
|