217 lines
8.6 KiB
Markdown
217 lines
8.6 KiB
Markdown
# 团购套餐定义 — 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 个字段，按逻辑分组说明如下。
|
||
|
||
---
|
||
|
||
## 四、响应字段详解（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 | `"店长:郑丽珊"` | 创建人信息（角色:姓名），用于权限追踪 |
|
||
| `create_time` | string | `"2025-10-27 18:24:09"` | 套餐创建时间 |
|
||
|
||
### 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` = 已过期/失效 |
|
||
| `type` | int | `2` | 内部业务子类型。`1` 和 `2` 两种值，具体含义需结合系统配置 |
|
||
| `group_type` | int | `1` | 团购类型。`1` = 计时类/台费类套餐 |
|
||
| `system_group_type` | int | `1` | 系统团购类型。`1` = 券码类团购（需凭码核销） |
|
||
|
||
---
|
||
|
||
## 五、响应样例（单条记录）
|
||
|
||
```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/ 确认字段覆盖完整
|
||
-->
|