初始提交：飞球 ETL 系统全量代码

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/endpoints/group_buy_packages.md
+++ b/docs/api-reference/endpoints/group_buy_packages.md
@@ -0,0 +1,731 @@
+# 团购套餐定义（QueryPackageCouponList）
+
+> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
+
+## 基本信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `PackageCoupon/QueryPackageCouponList` |
+| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/PackageCoupon/QueryPackageCouponList` |
+| 请求方法 | `POST` |
+| Content-Type | `application/json` |
+| 鉴权方式 | Bearer Token（`Authorization` 头） |
+| ODS 对应表 | `group_buy_packages` |
+| 分页方式 | `page` + `limit`（最大 100） |
+| 时间范围 | 不需要 |
+
+## 请求参数
+
+| 参数名 | 类型 | 示例值 | 说明 |
+|--------|------|--------|------|
+| `areaId` | array | `[]` | 区域 ID 列表（空=全部） |
+| `commonShowStatus` | int | `1` | 展示状态（1=展示中） |
+| `offlineCouponChannel` | int | `0` | 线下券渠道（0=全部） |
+| `systemGroupType` | int | `1` | 系统分组类型（1=默认） |
+| `page` | int | `1` | 页码（从 1 开始） |
+| `limit` | int | `100` | 每页条数（最大 100） |
+
+## 响应字段（共 35 个）
+
+| # | 字段名 | 类型 | 示例值 |
+|---|--------|------|--------|
+| 1 | `site_name` | string | '朗朗桌球' |
+| 2 | `effective_status` | int | 1 |
+| 3 | `id` | int | 2939215004469573 |
+| 4 | `site_id` | int | 2790685415443269 |
+| 5 | `tenant_id` | int | 2790683160709957 |
+| 6 | `package_name` | string | '早场特惠一小时' |
+| 7 | `table_area_id` | string | '0' |
+| 8 | `table_area_name` | string | 'A区' |
+| 9 | `selling_price` | float | 0.0 |
+| 10 | `duration` | int | 3600 |
+| 11 | `start_time` | string | '2025-10-27 00:00:00' |
+| 12 | `end_time` | string | '2026-10-28 00:00:00' |
+| 13 | `is_enabled` | int | 1 |
+| 14 | `is_delete` | int | 0 |
+| 15 | `type` | int | 2 |
+| 16 | `package_id` | int | 1814707240811572 |
+| 17 | `usable_count` | int | 9999999 |
+| 18 | `create_time` | string | '2025-10-27 18:24:09' |
+| 19 | `creator_name` | string | '店长:郑丽珊' |
+| 20 | `tenant_table_area_id` | string | '0' |
+| 21 | `table_area_id_list` | string | '' |
+| 22 | `tenant_table_area_id_list` | string | '2791960001957765' |
+| 23 | `start_clock` | string | '00:00:00' |
+| 24 | `end_clock` | string | '1.00:00:00' |
+| 25 | `add_start_clock` | string | '00:00:00' |
+| 26 | `add_end_clock` | string | '1.00:00:00' |
+| 27 | `date_info` | string | '' |
+| 28 | `date_type` | int | 1 |
+| 29 | `group_type` | int | 1 |
+| 30 | `usable_range` | string | '' |
+| 31 | `coupon_money` | float | 0.0 |
+| 32 | `area_tag_type` | int | 1 |
+| 33 | `system_group_type` | int | 1 |
+| 34 | `max_selectable_categories` | int | 0 |
+| 35 | `card_type_ids` | string | '0' |
+
+## 新增字段（相对本地 JSON 样本）
+
+以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
+
+| 字段名 | 类型 |
+|--------|------|
+| `is_first_limit` | int |
+| `sort` | int |
+| `tableAreaNameList` | array |
+| `tenantCouponSaleOrderItemId` | int |
+| `tenantTableAreaIdList` | array |
+
+## 详细字段分析
+
+> 以下内容迁移自旧版 `group_buy_packages-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
+
+一、文件整体内容与结构
+
+内容类型：
+
+该文件记录的是 “团购套餐定义列表”，即门店可用的各类团购套餐（早场一小时、斯诺克两小时、KTV 四小时等）的配置。
+
+每一条记录对应一种团购套餐的“规则定义”，包括：
+
+套餐名称；
+
+面值（coupon_money）；
+
+有效起止日期；
+
+每日可用时间段；
+
+限定台区；
+
+状态（上架/下架/是否过期）等
+
+二、记录级字段完整说明
+
+下面对 packageCouponList 中每条记录的 35 个字段逐一说明，按业务逻辑分组。
+
+1. 基本信息与主键类字段
+
+id
+
+类型：int
+
+含义：门店侧套餐 ID，本文件内部的主键。
+
+特点：17 条记录中均为不同的大整数 ID。
+
+关联（结构推断）：
+
+平台验券记录表中常见 group_package_id 字段，通常会指向这里的 id，即：平台券核销记录指向哪一个团购套餐配置。
+
+tenant_id
+
+类型：int
+
+含义：租户 ID（品牌/商户 ID）。
+
+特点：全表值相同，说明所有套餐定义属于同一商户（同一品牌）。
+
+site_id
+
+类型：int
+
+含义：门店 ID。
+
+特点：全表值相同，且与其他 JSON 文件中的 site_id 一致，对应“朗朗桌球”这家门店。
+
+site_name
+
+类型：string
+
+含义：门店名称。
+
+观测值：全部为 "朗朗桌球"。
+
+说明：这是对 site_id 的冗余，可直接展示门店名称。
+
+package_id
+
+类型：int
+
+含义：“上层套餐 ID” 或“总部/系统级套餐 ID”。
+
+特点：
+
+多个 id 不同的记录可能共享同一个 package_id，表示同一种业务套餐在不同门店或不同版本下的本地配置。
+
+在本门店数据里，package_id 和 id 不是一一对应的，有复用情况。
+
+package_name
+
+类型：string
+
+含义：团购套餐名称，用于前台展示和核销界面。
+
+示例：
+
+"早场特惠一小时"
+
+"B区桌球一小时"
+
+"午夜一小时"
+
+"中八、斯诺克包厢两小时"
+
+"助理教练竞技教学两小时"
+
+"KTV欢唱四小时"
+
+"麻将 、掼蛋包厢四小时"
+
+说明：可以从名称直观看出这是台费类、包厢类、助教教学类、KTV 类等不同套餐。
+
+creator_name
+
+类型：string
+
+含义：创建人信息，一般包含“角色：姓名”。
+
+示例："管理员：郑丽珊"
+
+说明：用于追溯是谁在后台创建了该团购套餐，方便权限追踪。
+
+create_time
+
+类型：string，格式 YYYY-MM-DD HH:MM:SS
+
+含义：该套餐在系统中创建的时间。
+
+特点：每条记录各不相同，覆盖了 2025-07 至 2025-10 的创建时间。
+
+2. 金额与价值字段
+
+selling_price
+
+类型：float
+
+观测值：所有记录均为 0.0。
+
+含义（结合字段命名）：
+
+语义上应该是“团购售卖价”（顾客在平台购买券时的成交价格）。
+
+本门店这份导出中全部为 0，说明：
+
+要么平台实际售卖价保存在别的表/平台侧，并未在本地落地；
+
+要么这个字段在当前版本中未被使用。
+
+结构结论：这是一个预留的价格字段，但当前数据源没有真实值。
+
+coupon_money
+
+类型：float
+
+含义：券面值或内部结算面值，表示该套餐在门店侧对应的金额额度。
+
+示例（对应套餐名称）：
+
+早场特惠一小时 → coupon_money = 40.0
+
+全天A区中八一小时 → 80.0
+
+KTV欢唱四小时 → 200.0
+
+麻将 、掼蛋包厢四小时 → 160.0
+
+使用方式（结构层面）：
+
+当平台验券或套餐流水使用该套餐时，会根据这个金额执行抵扣记账，即“本券在店内能抵扣多少金额”。
+
+usable_count
+
+类型：int
+
+观测值：所有记录均为 9999999。
+
+含义：可使用次数上限。
+
+数据特征说明：
+
+9999999 典型用法是当作“无限次”的哨兵值。
+
+即当前所有套餐在配置上不限制使用次数（只受时间、日期等条件限制）。
+
+3. 有效期与日期限制相关字段
+
+start_time
+
+类型：string，格式 YYYY-MM-DD HH:MM:SS
+
+含义：套餐开始生效的日期时间。
+
+示例："2025-07-20 00:00:00" 等。
+
+说明：一般是某天的 00:00:00，表示从该日开始可以使用此套餐。
+
+end_time
+
+类型：string，格式同上。
+
+含义：套餐失效的日期时间（到这个时间点后不可使用）。
+
+示例：形如 "2025-11-30 23:59:59"，部分记录使用 9999-12-31 23:59:59 风格的极大日期表示长期有效（本数据中如有这种值，可解读为“长期有效”）。
+
+date_type
+
+类型：int，枚举。
+
+观测值：全部为 1。
+
+含义（推测）：
+
+典型用法：区分“全部日期可用 / 工作日 / 周末 / 指定日期”等。
+
+当前数据全部为 1，可能表示“通用（每天都可以使用）”。
+
+结构上：这是一个日期限制类型枚举字段，但本门店所有套餐统一设置为同一类型。
+
+usable_range
+
+类型：string
+
+观测值：全部为空字符串 ""。
+
+含义（推测）：
+
+一般用于文字描述可用日期范围（例如“周一至周五”）。
+
+当前全部为空，说明没有填写文字说明，只依赖 date_type 或其他逻辑限制。
+
+date_info
+
+类型：string
+
+观测值：绝大多数为 ""，只有一条为 "0"。
+
+含义（推测）：
+
+预留字段，通常用来存储更细粒度的日期信息，如具体日期列表、节假日特殊规则（可能是 JSON 字符串或编码）。
+
+当前几乎空置，说明本门店在团购套餐上并未配置复杂日期规则。
+
+结构意义：这是将来可以支持“指定日期才能使用”的扩展字段。
+
+4. 每日时段限制相关字段
+
+这几个字段控制“每天什么时间段可以使用该套餐”。
+
+start_clock
+
+类型：string
+
+观测值示例：
+
+"10:00:00"
+
+"00:00:00"
+
+含义：每日可用起始时间点（第一段）。
+
+说明：配合 end_clock 使用，定义一个日内时段。
+
+end_clock
+
+类型：string
+
+观测值示例：
+
+"18:00:00"
+
+"23:59:00"
+
+"23:59:59"
+
+含义：每日可用的结束时间点（第一段）。
+
+结构说明：
+
+与 start_clock 一起构成 [start_clock, end_clock] 这段时间内可以核销使用该券。
+
+add_start_clock
+
+类型：string
+
+观测值：
+
+"00:00:00"（15条）
+
+"10:00:00"（2条）
+
+含义（推测）：附加可用时间段的起始时间（第二段）。
+
+例如有的套餐可以在两个不连续的时段使用：早场 + 夜场，则可用第一段 start_clock / end_clock 和第二段 add_start_clock / add_end_clock 组合。
+
+add_end_clock
+
+类型：string
+
+观测值：
+
+"1.00:00:00"（15条）
+
+"18:00:00"（1条）
+
+"23:59:00"（1条）
+
+特别注意：
+
+"1.00:00:00" 这种格式明显是 “天.时:分:秒” 的表示方式，即“第 1 天的 00:00:00”，也就是跨日截止（比 00:00:00+1天）。
+
+用来定义“跨午夜”的可用区间，比如从晚上 18:00 一直用到第二天 0 点。
+
+含义：附加时段结束时间，多数情况配合 "00:00:00" 或 "10:00:00" 使用。
+
+整体理解：
+
+start_clock / end_clock：第一时间段。
+
+add_start_clock / add_end_clock：第二时间段；当 add_end_clock 是 "1.00:00:00" 时，可以认为是从当天某时刻到次日凌晨。
+
+当前配置中，大部分套餐是“全天可用 + 夜场延伸”的模式，因此看到 00:00:00 → 1.00:00:00 这样的组合。
+
+5. 区域 / 台桌限制相关字段
+
+area_tag_type
+
+类型：int，枚举。
+
+观测值：全部为 1。
+
+含义（推测）：区域标记类型：
+
+1 很可能代表“按台区标签限制”，例如 A区、中八区、包厢、KTV 等。
+
+由于没有看到其它值，具体枚举含义需结合系统配置，但可以确认：这个字段是“区域约束的模式选择”。
+
+table_area_name
+
+类型：string
+
+观测值：（举例）
+
+"A区中八"、"B区中八"、"斯诺克"、"包厢"、"KTV" 等。
+
+含义：套餐适用的“门店台区名称”，用于显示和筛选。
+
+说明：这个字段是对区域 ID 维度的文字描述，便于直观理解。
+
+table_area_id
+
+类型：int
+
+观测值：全部为 0。
+
+含义（推测）：
+
+原始设计应为“单一台区 ID”，当套餐只限一个区域可以用这个字段存储。
+
+但当前版本已经使用“列表字段”进行多选，导致单值字段全部为 0（未启用）。
+
+tenant_table_area_id
+
+类型：int
+
+观测值：全部为 0。
+
+含义（推测）：
+
+与 table_area_id 类似，是租户层级的台区 ID，原本用于单区选择。
+
+由于引入多选逻辑后，实际使用转移到 tenant_table_area_id_list 字段，这里被弃用。
+
+tenant_table_area_id_list
+
+类型：在导出中为 int 类型（严格看是数字，但语义上是“多选集合”）。
+
+观测值：每条记录都是一个不同的大整数（例如 2791960001957765, 2791960521691013 等）。
+
+含义（推测）：
+
+实际代表“台区集合 ID”或“租户台区配置 ID”，用来限制套餐可用的台区范围。
+
+设计上是可以支持多个区域，因此字段名用了“list”，但在当前数据中，每个套餐只有一组区域组合，所以存的是单一 ID。
+
+结构逻辑：
+
+套餐定义 → tenant_table_area_id_list → 台区分组表（未在本次导出中看到，但可推断存在），该分组中包含实际的一个或多个 table_area_id。
+
+table_area_id_list
+
+类型：string
+
+观测值：全部为空字符串 ""。
+
+含义（推测）：
+
+用来存放具体台区 ID 列表（例如 "1,2,3"），实现更细粒度的台桌限制。
+
+当前门店的配置可能只用了“台区分组”而没有配置到具体单个台号，因此留空。
+
+总结区域字段结构：
+
+area_tag_type：选择约束方式（这里统一为 1，表示按台区标签）。
+
+table_area_name：文字名称，给人看的。
+
+tenant_table_area_id_list：真正起约束作用的 ID（指向台区分组）。
+
+table_area_id / tenant_table_area_id / table_area_id_list：历史单选/多选字段，当前配置中未实际使用（全部为 0 / 空串）。
+
+6. 适用卡种相关字段
+
+card_type_ids
+
+类型：int
+
+观测值：全部为 0。
+
+含义（推测）：
+
+原意是“适用会员卡类型 ID 列表”，例如某套餐只允许某几种会员卡使用，可以在此配置。
+
+当前统一为 0，说明未限定卡种，任何顾客/任何会员卡均可按平台规则使用该团购券。
+
+结构上：这是一个“未来可以细化到卡种”的扩展字段，本店目前未用。
+
+7. 状态 / 类型类字段
+
+is_enabled
+
+类型：int，枚举。
+
+观测值：全部为 1。
+
+含义：启用状态。
+
+从其他表的统一风格来看，1 一般表示“启用 / 上架”，2 表示“停用 / 下架”。
+
+当前数据全部为 1，说明导出时所有 17 个套餐处于“启用”状态（但是否“有效”，还要看 effective_status）。
+
+is_delete
+
+类型：int，枚举。
+
+观测值：全部为 0。
+
+含义：逻辑删除标志。
+
+0：正常；
+
+1：已删除（仅逻辑删除，数据仍保留）。
+
+当前没有任何套餐被标记为删除。
+
+effective_status
+
+类型：int，枚举。
+
+观测值：
+
+1：13 条
+
+3：4 条
+
+含义（结合命名和数据特征推断）：
+
+1：有效（在当前时间区间内、配置正常，可核销使用）。
+
+3：已过期或失效（虽然 is_enabled 仍为 1，但由于 end_time 已过期，或其他原因，被标记为不可用）。
+
+说明：is_enabled 更偏向“是否上架配置”；effective_status 是动态计算出的“当前是否处于可用状态”。
+
+group_type
+
+类型：int，枚举。
+
+观测值：全部为 1。
+
+含义（推测）：
+
+团购类型，例如：
+
+1：计时类/台费类套餐；
+
+其他值：可能用于区别商品类、代金券类等。
+
+本门店所有 17 个套餐的 group_type 均为 1，说明都归于同一大类。
+
+system_group_type
+
+类型：int，枚举。
+
+观测值：全部为 1。
+
+含义（推测）：
+
+系统内对团购类型更底层的划分，比如：
+
+1：券码类团购（需要凭码核销）；
+
+其它类型：如卡内套餐、内部套餐等。
+
+当前全部为 1，说明这些套餐都属于同一系统团购类型（标准券类）。
+
+type
+
+类型：int，枚举。
+
+观测值：
+
+1：13 条
+
+2：4 条
+
+含义（推测）：
+
+内部业务子类型，具体含义需要结合系统文档；仅从数据无法确定是“台费类 vs 包厢类”还是“平台套餐 vs 自定义套餐”。
+
+结构上：此字段用来进一步细分团购套餐类别，有两种子类型。
+
+8. 其他字段
+
+duration
+
+类型：int
+
+观测值（秒）：
+
+3600（1 小时）
+
+7200（2 小时）
+
+14400（4 小时）
+
+含义：套餐内包含的时长（秒）。
+
+与名称一致：
+
+“一小时”类套餐 → 3600
+
+“两小时”类 → 7200
+
+“四小时”类 → 14400
+
+结构用途：当券被核销时，可以用 duration 直接换算成应赠送/应抵扣的台费时间。
+
+usable_range
+
+已在日期部分说明（文字描述），这里只列入清单。
+
+三、与其他 JSON 文件的结构关联（字段层面）
+
+虽然你这次只问这一个文件，但按照结构分析的习惯，简单标一下这个“团购套餐定义表”和其它数据之间的关系：
+
+与门店/租户维度：
+
+tenant_id、site_id、site_name：
+
+与所有其他 JSON（台费流水、助教流水、门店销售记录、库存、会员等）的同名字段一致。
+
+用于在多门店部署场景下按门店过滤数据。
+
+site_name 冗余，但在所有记录中保持为“朗朗桌球”。
+
+与平台验券记录（平台验券记录.json）：
+
+验券记录中有 group_package_id 字段（我们之前已分析过），对应这里的 id：
+
+platform_coupon_use.group_package_id = 团购套餐.id
+
+这样，验券记录知道：某张券是按照哪一个“团购套餐配置”被核销的，从而可以根据这里的 duration、coupon_money、时段限制等字段判断是否符合规则。
+
+与团购套餐流水（团购套餐流水.json）：
+
+团购套餐流水记录单笔订单中某个券/套餐的使用情况。
+
+从字段命名风格看，流水记录会引用：
+
+套餐名称（冗余 ledger_name / package_name）；
+
+券码 coupon_code 与验券记录相连；
+
+通过验券记录的 group_package_id 再指向本表的 id。
+
+结构链路大致为：
+
+团购套餐定义（本文件） → 平台验券记录（券码与套餐ID） → 团购套餐流水（订单明细里的券使用记录）。
+
+与台桌/台区配置（台桌列表、台区配置相关 JSON）：
+
+tenant_table_area_id_list 与台区配置表中的“台区组合 ID”关联。
+
+table_area_name 与台区配置中 area_name 字段含义吻合（A区中八/B区中八/斯诺克/KTV/包厢等）。
+
+通过该关联，系统在核销时可以校验：
+
+当前使用的台桌所属区域是否在该套餐允许的区域范围内。
+
+与会员卡/储值卡体系：
+
+card_type_ids 字段设计上用来限制“哪些卡种可以用这个团购套餐”。
+
+当前值均为 0，表示不限卡种。但一旦 >0，则应该可以通过该字段与“卡类型定义表”关联（本次导出中没有单独的卡种定义 JSON，只有储值卡列表，此处只能从结构上推断）。
+
+四、结构层面的一些重要线索（非业务/盈利分析）
+
+从字段设计和实际值可以看出一些系统设计上的特点和潜在规则：
+
+“无限次”通过大数哨兵实现：
+
+usable_count = 9999999 明显是一个“无限使用次数”的标记，而不是一个有业务意义的真实上限。
+
+这类字段如果未来要限制使用次数，只需把这个值改成有限数即可。
+
+时间段支持跨日和双时段：
+
+start_clock / end_clock + add_start_clock / add_end_clock 的组合，以及 add_end_clock 中的 "1.00:00:00"，表明系统支持：
+
+单日内多段时间限制；
+
+跨午夜的可用时间段，比如“晚场到第二天凌晨”的场景。
+
+这种设计比简单的 HH:MM 模式更灵活，但也更复杂。
+
+区域限制采用“分组 ID + 名称”双层设计：
+
+单值字段 table_area_id、tenant_table_area_id 已基本弃用（全为0），实际使用的是 tenant_table_area_id_list 配合 table_area_name。
+
+这种设计允许一个套餐适用多个具体区域，而不仅仅是一个；只是本数据中每个套餐只有一个区域组合 ID，尚未用到真正的“多选”能力。
+
+状态字段拆成“启用/删除/有效”：
+
+is_enabled：是否上架（配置层面）。
+
+is_delete：是否逻辑删除（数据层面）。
+
+effective_status：是否在当前时间点视为有效（动态计算结果）。
+
+这种三层拆分，便于保留历史配置（is_delete）和允许“预设但未到期/已过期”的套餐（effective_status）。
+
+价格字段“selling_price”目前未落地：
+
+所有记录 selling_price = 0.0，但 coupon_money 有实际金额。
+
+这说明：在门店数据里，只关心“券在店内的抵扣价值”（coupon_money），而“平台对顾客的售卖价格”可能在外部系统（团购平台）或其他表中维护。
+
+从结构上看，这保留了未来把平台售价同步到本地的扩展空间。
+
+卡种限制预留但未使用：
+
+card_type_ids = 0 表明目前团购套餐未限制特定卡种。
+
+一旦业务需要特定会员卡才能享用某些团购，可以通过非零值（以及列表编码）实现，同样是结构级扩展。
+
+字段命名的一致性与冗余：
+
+site_id + site_name 的组合和其他 JSON 一致，说明整个系统在多模快数据里都采用相同的门店维度标识。
+
+多个字段采用“xxx_id + xxx_name”的模式（如台区、门店、套餐名称），有利于在不做联表查询的情况下直接展示内容。