ZQYY.FQ-ETL/docs/api-reference/endpoints/group_buy_packages.md

团购套餐定义（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”的模式（如台区、门店、套餐名称），有利于在不做联表查询的情况下直接展示内容。