# 团购套餐定义 — QueryPackageCouponList

> 模块：`PackageCoupon` · ODS 表：`group_buy_packages` · 维度表（快照）

---

## 一、接口概述

查询门店下所有团购套餐的配置定义。每条记录对应一种团购套餐的规则定义，包括套餐名称、面值、有效期、每日可用时段、限定台区、状态等。本表是团购业务的核心维度表，被平台券核销记录和团购核销记录通过套餐 ID 引用。

| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /PackageCoupon/QueryPackageCouponList` |
| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
| 鉴权 | `Authorization: Bearer <token>` |
| 分页 | `page` + `limit`（最大 100） |
| 时间范围 | 不需要（全量快照） |

---

## 二、请求

### 请求体（JSON）

```json
{
  "areaId": [],
  "commonShowStatus": 1,
  "offlineCouponChannel": 0,
  "systemGroupType": 1,
  "page": 1,
  "limit": 100
}
```

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `areaId` | array | 是 | 区域 ID 列表。空数组 = 全部 |
| `commonShowStatus` | int | 是 | 展示状态筛选。`1` = 展示中 |
| `offlineCouponChannel` | int | 是 | 线下券渠道筛选。`0` = 全部 |
| `systemGroupType` | int | 是 | 系统分组类型。`1` = 默认 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |

---

## 三、响应结构

```
{
  "code": 200,
  "data": {
    "list": [ { ... }, { ... } ],
    "total": 17
  }
}
```

`data.list` 中每个对象即为一条团购套餐定义记录，共 35 个字段，按 9 个逻辑分组说明如下。

---

## 四、响应字段详解（35 个字段）

### 4.1 基本信息与主键

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2939215004469573` | 门店侧套餐 ID（主键）。平台验券记录中的 `group_package_id` 指向此 ID |
| `package_id` | int | `1814707240811572` | 上层/系统级套餐 ID。多个 `id` 不同的记录可共享同一 `package_id`（同一套餐在不同门店/版本下的本地配置） |
| `package_name` | string | `"早场特惠一小时"` | 团购套餐名称，用于前台展示和核销界面。示例：`"B区桌球一小时"`、`"中八、斯诺克包厢两小时"`、`"KTV欢唱四小时"` |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
| `site_id` | int | `2790685415443269` | 门店 ID |
| `site_name` | string | `"朗朗桌球"` | 门店名称，冗余展示字段 |
| `creator_name` | string | `"店长:郑丽珊"` | 创建人信息（角色:姓名），用于权限追踪 |

### 4.2 金额与时长

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `selling_price` | float | `0.0` | 团购售卖价（元）。当前全部为 `0.0`，实际售价可能在平台侧维护 |
| `coupon_money` | float | `0.0` | 券面值/内部结算面值（元）。如：早场一小时 = `40.0`，KTV 四小时 = `200.0`。核销时按此金额执行抵扣记账 |
| `duration` | int | `3600` | 套餐包含时长（秒）。`3600` = 1 小时，`7200` = 2 小时，`14400` = 4 小时 |
| `usable_count` | int | `9999999` | 可使用次数上限。`9999999` 为"无限次"哨兵值 |

### 4.3 有效期与日期限制

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `start_time` | string | `"2025-10-27 00:00:00"` | 套餐生效开始日期 |
| `end_time` | string | `"2026-10-28 00:00:00"` | 套餐失效日期。极大日期（如 `9999-12-31`）表示长期有效 |
| `date_type` | int | `1` | 日期限制类型。`1` = 通用（每天可用）。其他值可能表示工作日/周末/指定日期 |
| `date_info` | string | `""` | 细粒度日期信息（如具体日期列表），预留字段，当前基本为空 |
| `usable_range` | string | `""` | 可用日期范围文字描述（如"周一至周五"），当前未使用 |

### 4.4 每日时段限制

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `start_clock` | string | `"00:00:00"` | 每日可用起始时间（第一时段） |
| `end_clock` | string | `"1.00:00:00"` | 每日可用结束时间（第一时段）。`1.00:00:00` 格式为"天.时:分:秒"，表示跨日截止 |
| `add_start_clock` | string | `"00:00:00"` | 附加可用时段起始时间（第二时段），支持不连续时段（如早场+夜场） |
| `add_end_clock` | string | `"1.00:00:00"` | 附加可用时段结束时间。`1.00:00:00` = 跨午夜到次日凌晨 |

### 4.5 区域/台桌限制

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `area_tag_type` | int | `1` | 区域约束模式。`1` = 按台区标签限制 |
| `table_area_name` | string | `"A区"` | 套餐适用台区名称。示例：`"A区中八"`、`"B区中八"`、`"斯诺克"`、`"包厢"`、`"KTV"` |
| `table_area_id` | string | `"0"` | 单一台区 ID（已弃用，全部为 `"0"`） |
| `tenant_table_area_id` | string | `"0"` | 租户级台区 ID（已弃用，全部为 `"0"`） |
| `tenant_table_area_id_list` | string | `"2791960001957765"` | 租户台区配置 ID，实际起约束作用。指向台区分组表 |
| `table_area_id_list` | string | `""` | 具体台区 ID 列表（如 `"1,2,3"`），当前未使用 |

### 4.6 适用卡种

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `card_type_ids` | string | `"0"` | 适用会员卡类型 ID。`"0"` = 不限卡种 |
| `max_selectable_categories` | int | `0` | 最大可选分类数。`0` = 不限制 |

### 4.7 状态与类型

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `is_enabled` | int | `1` | 启用状态（配置层面）。`1` = 启用/上架，`2` = 停用/下架 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 正常，`1` = 已删除 |
| `effective_status` | int | `1` | 动态有效状态。`1` = 有效（可核销），`3` = 已过期/失效 |
| `is_first_limit` | integer | `1` | 是否限制首次使用（1=不限制），控制套餐是否仅限新客首次核销 |
| `type` | int | `2` | 内部业务子类型。`1` 和 `2` 两种值，具体含义需结合系统配置 |
| `group_type` | int | `1` | 团购类型。`1` = 计时类/台费类套餐 |
| `system_group_type` | int | `1` | 系统团购类型。`1` = 券码类团购（需凭码核销） |
| `sort` | integer | `100` | 排序权重，用于前端套餐列表展示排序 |

### 4.8 关联 ID 与台区列表

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tenantCouponSaleOrderItemId` | integer | `0` | 租户券销售订单项 ID，关联团购券的销售订单明细。`0` = 无关联 |
| `tableAreaNameList` | array | `["A区中八"]` | 适用台区名称列表，与 `tenantTableAreaIdList` 对应的文本展示 |
| `tenantTableAreaIdList` | array | `[2791960001957765]` | 适用租户台区 ID 列表，替代旧版单值字段 `tenant_table_area_id`，指向台区分组表 |

### 4.9 时间

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-10-27 18:24:09"` | 套餐创建时间 |

---

## 五、响应样例（单条记录）

```json
{
  "site_name": "朗朗桌球",
  "effective_status": 1,
  "id": 2939215004469573,
  "site_id": 2790685415443269,
  "tenant_id": 2790683160709957,
  "package_name": "早场特惠一小时",
  "table_area_id": "0",
  "table_area_name": "A区",
  "selling_price": 0.0,
  "duration": 3600,
  "start_time": "2025-10-27 00:00:00",
  "end_time": "2026-10-28 00:00:00",
  "is_enabled": 1,
  "is_delete": 0,
  "type": 2,
  "package_id": 1814707240811572,
  "usable_count": 9999999,
  "create_time": "2025-10-27 18:24:09",
  "creator_name": "店长:郑丽珊",
  "tenant_table_area_id": "0",
  "table_area_id_list": "",
  "tenant_table_area_id_list": "2791960001957765",
  "start_clock": "00:00:00",
  "end_clock": "1.00:00:00",
  "add_start_clock": "00:00:00",
  "add_end_clock": "1.00:00:00",
  "date_info": "",
  "date_type": 1,
  "group_type": 1,
  "usable_range": "",
  "coupon_money": 0.0,
  "area_tag_type": 1,
  "system_group_type": 1,
  "max_selectable_categories": 0,
  "card_type_ids": "0"
}
```

---

## 六、跨表关联

### 与平台券核销记录（`platform_coupon_redemption_records`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `group_package_id` | 套餐 ID → 平台券关联的内部套餐（当前全部为 0，预留） |

### 与团购核销记录（`group_buy_redemption_records`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `id` | `promotion_coupon_id` | 套餐 ID → 核销流水中使用的套餐定义 |
| `duration` | `promotion_seconds` | 套餐标准时长，两表一致 |

> 结构链路：团购套餐定义 → 平台验券记录（券码与套餐 ID） → 团购核销记录（订单明细中的券使用记录）。

### 与台桌/台区配置

- `tenant_table_area_id_list`：与台区配置表中的台区组合 ID 关联
- `table_area_name`：与台区配置中的 `area_name` 含义一致

### 与门店维度

所有业务表的 `tenant_id`、`site_id` 一致，共享门店维度。

<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
- 直接原因: 按标杆文档格式重写高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/group_buy_packages.md，按逻辑分组详解所有字段，含跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整

- 日期: 2026-02-14
- Prompt: P20260214-103000 — MD 占位符修正 + 临时文件清理
- 直接原因: v2 脚本自动插入的占位符描述需替换为正式中文业务说明；type 字段重复行需去除
- 变更摘要: is_first_limit、sort、tableAreaNameList、tenantCouponSaleOrderItemId、tenantTableAreaIdList 五个新字段占位符替换为正式说明；删除重复的 type 行
- 风险与验证: 纯文档文案修正，无运行时影响；验证：grep "新发现字段" 本文件应返回 0 结果

- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.7"状态与类型"组过于臃肿，混入排序、台区列表、关联 ID 等非状态字段
- 变更摘要: 4.7 精简为纯状态/类型字段 + sort；新增 4.8"关联 ID 与台区列表"组（3 字段）；create_time 从 4.1 移至 4.9"时间"组
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 35
-->