微信小程序页面迁移校验之前 P5任务处理之前

docs/database/BD_Manual_group_buy_package_details.md

@@ -0,0 +1,92 @@
+# BD_Manual：ods.group_buy_package_details 团购套餐详情表
+
+> 日期：2026-03-05
+> 涉及库：`etl_feiqiu` / `test_etl_feiqiu`
+> DDL 路径：`db/etl_feiqiu/ods/group_buy_package_details.sql`
+> 直接原因：整合团购详情接口（QueryPackageCouponInfo），新建 ODS 详情表存储每个团购套餐的详情数据
+> Prompt 摘要：etl-coupon-detail spec — 需求 3 验收标准 1-4
+
+---
+
+## 1. 变更说明
+
+### 变更内容
+
+新建 `ods.group_buy_package_details` 表，用于存储 `QueryPackageCouponInfo` 详情接口的原始数据。
+
+| Schema | 表 | 操作 | 说明 |
+|--------|-----|------|------|
+| ods | group_buy_package_details | 新建 | 团购套餐详情，主键 `coupon_id`，含 12 个结构化字段 + 6 个 JSONB 数组字段 + 3 个 ETL 元数据字段 |
+
+### 数据获取方式
+
+通过 `ODS_GROUP_PACKAGE` 任务的 `detail_endpoint` 二级详情拉取子流程：
+- 主流程拉取团购列表 → `ods.group_buy_packages`
+- 子流程遍历每个 `id`，串行调用 `QueryPackageCouponInfo` → 本表
+- 全量快照模式，UPSERT on `coupon_id`
+
+### 关键字段
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `coupon_id` | BIGINT PK | 团购套餐 ID（= group_buy_packages.id） |
+| `table_area_ids` | JSONB | 可用台区 ID 列表 |
+| `table_area_names` | JSONB | 可用台区名称列表 |
+| `assistant_services` | JSONB | 助教服务关联数组 |
+| `groupon_site_infos` | JSONB | 关联门店信息数组 |
+| `package_services` | JSONB | 套餐服务数组（待调研） |
+| `coupon_details_list` | JSONB | 券明细数组（待调研） |
+| `content_hash` | TEXT | 内容哈希，用于变更检测 |
+| `payload` | JSONB | 完整原始 JSON 响应 |
+
+---
+
+## 2. 兼容性影响
+
+| 组件 | 影响 | 说明 |
+|------|------|------|
+| ETL ODS 层 | 新增表 | `ODS_GROUP_PACKAGE` 任务通过 `detail_endpoint` 配置自动写入 |
+| ETL DWD 层 | 需配合修改 | `dwd_load_task.py` 需 LEFT JOIN 本表将 4 个 JSONB 字段合并到 `dim_groupbuy_package_ex` |
+| 后端 API | 无影响 | 当前无接口直接查询本表 |
+| 小程序 | 无影响 | 不直接使用 ODS 层表 |
+
+---
+
+## 3. 回滚策略
+
+```sql
+DROP TABLE IF EXISTS ods.group_buy_package_details;
+```
+
+回滚后需同步移除 `ODS_GROUP_PACKAGE` 任务中的 `detail_endpoint` 相关配置。
+
+---
+
+## 4. 验证 SQL
+
+```sql
+-- 1. 确认表存在且主键正确
+SELECT column_name, data_type, is_nullable
+  FROM information_schema.columns
+ WHERE table_schema = 'ods'
+   AND table_name = 'group_buy_package_details'
+ ORDER BY ordinal_position;
+-- 预期：22 列，coupon_id 为 BIGINT NOT NULL
+
+-- 2. 确认主键约束
+SELECT constraint_name, constraint_type
+  FROM information_schema.table_constraints
+ WHERE table_schema = 'ods'
+   AND table_name = 'group_buy_package_details'
+   AND constraint_type = 'PRIMARY KEY';
+-- 预期：1 行，pk_group_buy_package_details
+
+-- 3. 确认 JSONB 列存在
+SELECT column_name, data_type
+  FROM information_schema.columns
+ WHERE table_schema = 'ods'
+   AND table_name = 'group_buy_package_details'
+   AND data_type = 'jsonb'
+ ORDER BY ordinal_position;
+-- 预期：8 行（table_area_ids, table_area_names, assistant_services, groupon_site_infos, package_services, coupon_details_list, payload）
+```