# 平台券核销记录（GetOfflineCouponConsumePageList）

> 自动生成于 2026-02-13 | 数据来源：实时 API

## 基本信息

| 属性 | 值 |
|------|-----|
| 接口路径 | `Promotion/GetOfflineCouponConsumePageList` |
| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/Promotion/GetOfflineCouponConsumePageList` |
| 请求方法 | `POST` |
| Content-Type | `application/json` |
| 鉴权方式 | Bearer Token（`Authorization` 头） |
| ODS 对应表 | `platform_coupon_redemption_records` |
| 分页方式 | `page` + `limit`（最大 100） |
| 时间范围 | 需要（startTime / endTime） |

## 请求参数

| 参数名 | 类型 | 示例值 | 说明 |
|--------|------|--------|------|
| `couponChannel` | int | `0` | 优惠券渠道（0=全部） |
| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
| `siteId` | int | `2790685415443269` | 门店 ID |
| `couponUseStatus` | int | `0` | 优惠券使用状态（0=全部） |
| `page` | int | `1` | 页码（从 1 开始） |
| `limit` | int | `100` | 每页条数（最大 100） |

## 响应字段（共 26 个）

| # | 字段名 | 类型 | 示例值 |
|---|--------|------|--------|
| 1 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
| 2 | `id` | int | 3092405812332869 |
| 3 | `tenant_id` | int | 2790683160709957 |
| 4 | `site_id` | int | 2790685415443269 |
| 5 | `sale_price` | float | 20.26 |
| 6 | `coupon_code` | string | '0108919359400' |
| 7 | `coupon_channel` | int | 1 |
| 8 | `site_order_id` | int | 3092345641453701 |
| 9 | `coupon_free_time` | int | 0 |
| 10 | `use_status` | int | 1 |
| 11 | `create_time` | string | '2026-02-12 23:37:54' |
| 12 | `is_delete` | int | 0 |
| 13 | `coupon_name` | string | '【全天可用】中八桌球一小时（大厅A区）' |
| 14 | `coupon_cover` | string | '' |
| 15 | `coupon_remark` | string | '' |
| 16 | `channel_deal_id` | int | 1128411555 |
| 17 | `group_package_id` | int | 0 |
| 18 | `consume_time` | string | '2026-02-12 23:37:55' |
| 19 | `groupon_type` | int | 1 |
| 20 | `coupon_money` | float | 48.0 |
| 21 | `operator_id` | int | 2790687322443013 |
| 22 | `operator_name` | string | '收银员:郑丽珊' |
| 23 | `table_id` | int | 2793002808987781 |
| 24 | `certificate_id` | string | '5017032743553662850' |
| 25 | `verify_id` | string | '' |
| 26 | `deal_id` | int | 1345108507 |

## 详细字段分析

> 以下内容迁移自旧版 `platform_coupon_redemption_records-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。

2. 记录内容类型

每条记录对应 一次第三方团购券的核销事件，属于“平台券（如美团等）在门店被实际使用”的流水：

一张券被核销一次 → 产生一条记录；

包含与外部平台有关的信息（券码、平台 dealId、certificateId 等）；

包含与门店内部业务关联的信息（门店 ID、订单 ID、球台 ID、操作员等）。

二、字段逐项详解（含类型与枚举）

下面按逻辑分组逐一说明所有字段。

1. 门店 / 商户相关字段
1.1 tenant_id

类型：int

含义：商户/租户 ID（品牌级别）。

特点：本文件中为固定值（同一个品牌“朗朗桌球”）。

关联：

与其他所有 JSON 中的 tenant_id 一致，用于区分不同品牌/商户的数据域。

枚举：非枚举，是长整型主键。

1.2 site_id

类型：int

含义：门店 ID。

特点：本数据集中恒定为同一数值，对应同一家门店。

关联：

对应 siteProfile.id；

在其他 JSON（台费流水、门店销售记录、会员档案等）中也作为门店维度字段出现。

枚举：非枚举，长整型主键。

1.3 siteProfile

类型：object

含义：门店信息快照。

主要子字段（只列结构性有用的）：

id：站点 ID，与上面的 site_id 相同。

org_id：组织 ID（上级组织/集团内组织结构）。

shop_name：门店名称（例如“朗朗桌球”）。

business_tel：门店电话。

full_address / address：完整地址 / 显示地址。

longitude / latitude：经纬度。

tenant_site_region_id：地域编码。

auto_light：是否自动控灯（1/0 枚举）。

attendance_enabled：是否启用考勤（1/0 枚举）。

shop_status：门店状态（1=营业中；其他值可能代表停业、装修等）。

作用：为每条验券记录提供门店维度的冗余信息，方便报表直接展示，无需再联表查门店档案。

枚举字段集中出现在 siteProfile 内，但这些枚举在本文件分析的重点不在此，就不展开逐个枚举值。

2. 券本身的身份字段

这些字段用于标识“是哪一张券、来自哪个平台、是哪一种团购产品”。

2.1 coupon_code

类型：string

含义：券码，顾客出示的团购券密码/编号。

特点：

本文件 200 条记录中，coupon_code 全部互不相同，是天然的业务唯一键（自然主键）。

用途：

业务上用于核销时输入/扫码；

技术上可作为查询、去重、幂等控制的重要索引。

枚举：非枚举，业务唯一标识符。

2.2 certificate_id

类型：string

含义：平台侧的凭证 ID（通常由第三方团购平台生成的券实例 ID）。

特点：

大部分是 16~19 位的纯数字字符串。

有重复值（同一个 certificate_id 在本文件中可出现 2 条记录，说明该凭证在不同 context 下被处理过）。

用途：对接第三方接口时用于对账、查询核销结果。

枚举：非枚举，外部主键。

2.3 verify_id

类型：string

含义：平台核销记录 ID（某些平台会为每一次核销生成一个唯一 ID）。

特点：

绝大部分记录为空字符串 ""；

少量记录有非空值（共 19 个不同值），说明仅部分平台或部分版本会回传这个 ID。

用途：当存在时，可以精准反查平台侧核销记录。

枚举：非枚举，外部主键，允许为空。

2.4 coupon_name

类型：string

含义：团购券产品名称（即第三方平台上向顾客展示的名称）。

示例：

【全天可用】中八桌球一小时（A区）

【全天可用】中八桌球两小时（B区）

1小时中八台球|【11月特惠】（A区）

【双11特惠】中八桌球一小时（A区）
等共 9 种名称。

特点：

与 deal_id、sale_price、coupon_money 一起，可以唯一描述一个团购商品的“规格”。

枚举：值域有限，但从设计上看是普通字符串，不是严格意义的枚举字段（新增套餐时会增加新名字）。

2.5 coupon_channel

类型：int（枚举）

观测值：1、2

含义：券来源渠道（第三方平台渠道编号）。

1：平台渠道 1（例如：某团购主平台）。

2：平台渠道 2（例如：同集团的另一 App，或不同入口）。

备注：具体“1 对应哪家平台，需要查系统配置”，从字段名和数值分布只能确认“它是平台渠道枚举”。

2.6 groupon_type

类型：int（枚举）

观测值：全部为 1

含义：团购券类型。目前只出现一种类型，可能含义：

1 = 标准团购券；

其他值（未在本数据中出现）可能代表“次卡、套餐券、权益券”等类型。

说明：从结构设计看是枚举字段，只是当前导出时间段只有一种类型。

2.7 channel_deal_id

类型：int

含义：渠道侧 dealId / 产品 ID，一般是第三方平台给该团购商品定义的主键。

特点：

值域有限，有约 9 个不同取值；

与 coupon_name 一一对应（不同名称对应不同 channel_deal_id）。

用途：

对接平台接口时，反查“是哪一个团购商品”；

对账时，用于按平台产品维度统计核销量。

2.8 deal_id

类型：int

含义：另一个层次的团购产品 ID。

特点：

大部分记录为非 0 的整数（如 1345108507 等），也有部分记录 deal_id = 0。

与 coupon_name 的对应关系：

例如：

【全天可用】中八桌球一小时（A区） → deal_id = 1345108507

【全天可用】中八桌球两小时（A区） → 1346103574

1小时中八台球|【11月特惠】（A区） → 1364921087

部分“斯诺克两小时”“双11特惠”类券 → deal_id = 0（内部未配置或未同步）。

推断：

deal_id 更像是平台/系统内部统一的产品 ID；

channel_deal_id 则偏向“渠道侧产品 ID”（当 deal_id 为 0 时，仍有 channel_deal_id，说明渠道信息完整，而内部映射缺失）。

2.9 group_package_id

类型：int

观测值：本文件中 全部为 0。

设计含义（根据命名推断）：

用于关联内部“团购套餐”定义表的主键，对应“团购套餐.json”中某个套餐的 id。

现状：

当前导出数据里，平台券没有被映射到内部“团购套餐”，所以一直是 0；

字段从结构上看是预留的外键字段。

3. 金额 / 面值相关字段
3.1 sale_price

类型：float

含义：顾客在第三方平台上实际支付的价格（团购售价）。

观测值（有限集合）：

11.11、29.9、39.9、59.9、69.9、128.0

特点：

与 coupon_name、coupon_money 一起描述出商品的销售策略；

始终小于对应的 coupon_money（体现“折扣价/团购价”这一结构事实）。

3.2 coupon_money

类型：float

含义：券面值 / 套餐价值（系统层面的“可抵扣金额或对应套餐价值”）。

观测值：

48.0、58.0、68.0、96.0、116.0、288.0

特点：

固定组合关系，例如：

coupon_name = 【全天可用】中八桌球一小时（A区）
→ sale_price = 29.9，coupon_money = 48.0

coupon_name = 1小时中八台球|【11月特惠】（A区）
→ sale_price = 11.11，coupon_money = 48.0

这体现出系统层面区分“顾客支付价”和“券可抵扣价值”。

3.3 coupon_free_time

类型：int

单位：秒

观测值：本文件中全部为 0

含义（根据命名）：

券附带的“免费时长”字段（例如送多少分钟台费）；

若券中包含赠送时长，则理论上应是正数，当前数据中没有此情况。

现状：字段结构已预留，但当前导出时间段内均无赠送时长。

4. 使用状态与时间字段
4.1 use_status

类型：int（枚举）

观测分布：

值 1：198 条

值 2：2 条

含义（结合常见券系统习惯推断）：

1：已使用 / 已核销（正常消耗）；

2：已退款 / 已撤销 / 使用后反冲（极少数记录）。

结构说明：

这是判断券当前生命周期状态的核心字段；

与 is_delete 不同，is_delete 是逻辑删除标志，而 use_status 是业务状态。

4.2 create_time

类型：string

格式："YYYY-MM-DD HH:MM:SS"

含义：验券记录在本系统中创建的时间（记录入库时间）。

特点：

与 consume_time 通常只相差 1 秒左右。

可视为“系统记录时间”。

4.3 consume_time

类型：string

格式同上。

含义：券被核销/使用的业务时间。

特点：

在所有记录中都非空；

对于 use_status=2 的记录，consume_time 仍有值，说明先发生“使用”，后续才在其他流程中被退/撤。

结构上的结论：

create_time 更偏向“记录生成时间”，

consume_time 是“业务使用时间”，后者更意义上代表核销时间。

5. 订单 / 球台 / 操作员关联字段
5.1 site_order_id

类型：int

含义：门店内部的订单 ID（平台券核销时对应的店内订单）。

关联：

与台费流水、门店销售记录、助教流水等中出现的订单 ID 字段对应，用于把“平台券核销记录”挂到一笔本地订单上。

后续可以用 site_order_id 去对照：

该订单有哪些台费记录；

是否有商品销售记录；

是否用了其他优惠（储值卡、折扣等）。

索引意义：

可以作为查询入口之一（按订单维度查看该订单有没有用平台券）。

5.2 table_id

类型：int

含义：使用券的球台 ID。

关联：

与“台桌列表”中的 id 对应；

间接关联到 table_name、table_area 等静态信息（在本文件中不重载这些名称，统一在台桌档案中维护）。

结构意义：

用于统计每张台桌通过平台券带来的使用量；

与台费、助教流水一起，可从结构上看到“同一台桌由平台券带来的流量”。

5.3 operator_id

类型：int

含义：操作员 ID（执行验券操作的收银员/员工）。

特点：

本文件中几乎固定为同一个 ID，说明当前数据时间段只有一个收银员在验券。

关联：

可与员工档案或账号表中的 id 对应（其他 JSON 中也有同样的 operator_id 字段）。

索引意义：

按操作员维度过滤或统计验券记录（结构上可支持这种需求）。

5.4 operator_name

类型：string

含义：操作员姓名，例如 "收银员:郑丽珊"。

特点：

是 operator_id 的冗余展示字段；

即使员工账号发生变化，历史记录仍保留当时的文字信息。

6. 记录主键与删除标志
6.1 id

类型：int

含义：本条平台验券记录在本系统内的主键 ID。

特点：

长整型，看上去类似分布式 ID（如雪花算法），全库范围内唯一。

结构角色：

数据库层面的主键；

程序内部用于定位、更新这条记录。

6.2 is_delete

类型：int（枚举）

观测值：全部为 0。

含义：

0：未删除；

1：已逻辑删除。

与 use_status 的区分：

use_status 是业务行为状态（使用/撤销），即使 use_status=2 也不一定 is_delete=1；

is_delete 表示这条记录是否在系统层面被标记为无效（通常用于误操作回退等）。

三、字段之间的结构关系与索引设计

这里只谈字段设计层面的关系和潜在索引，不做任何金额/盈利层面的分析。

1. 本表内部的主键 / 候选键

id：系统主键（技术主键）。

coupon_code：

在当前 200 条数据中，coupon_code 完全唯一；

可视为业务自然主键；

很适合作为查询索引（按券码查验券记录）。

(coupon_channel, coupon_code) 组合键：

当系统需要支持多平台同时使用类似码段时，可以把二者视为联合业务主键；

从目前数据（channel 只有 1/2）来看，单 coupon_code 即可唯一，但结构上两者组合更稳健。

certificate_id：

有重复值，不能单独作为唯一键；

配合 coupon_channel 可作为对接外部平台的联合索引。

2. 与其他表的结构关联键

从字段命名和含义看，可与其他 JSON 建立如下结构关联（这里不依赖具体数值匹配，只看设计）：

与订单 / 结账相关表：

键：site_order_id

作用：把平台验券记录挂到本门店的一条订单上。

推断：

订单主表（结账记录）中会有与 site_order_id 对应的主键；

小票详情可通过结算 ID（例如 order_settle_id）和 site_order_id 间接建立关系。

与球台（台桌列表）表：

键：table_id ↔ 台桌表中的 id

作用：标明券在使用时是在哪张台桌上消费的；

联动：可用于后续把平台券使用时间段与台费流水对齐（仅结构层面）。

与团购套餐定义（团购套餐.json）：

键：group_package_id ↔ 团购套餐表中的 id

现状：

目前全部为 0，说明这批平台券尚未映射到内部团购套餐；

结构设计：

一旦做了“平台券 ↔ 自有团购套餐”的映射，这个字段就是关键外键。

与员工 / 账号表：

键：operator_id ↔ 员工/账号表中的 id

作用：按员工维度审计平台券核销情况；

配合 operator_name 做展示。

与外部平台：

键：

coupon_code：对顾客和平台双方都看得见的券码。

certificate_id：平台内部凭证 ID。

verify_id：平台核销 ID（存在时）。

channel_deal_id / deal_id：平台和系统对团购产品的双重映射。

作用：在系统与第三方平台之间做对账、同步状态的基础字段。

3. 索引设计上的自然倾向（从字段看）

纯看字段设计，在数据库里比较合理的索引组合是：

主键：id

唯一索引（候选）：coupon_code

一般索引：

coupon_channel（按平台分流查询）；

use_status（查询未使用或已撤销的券）；

consume_time（时间区间查询，比如一天内所有核销）；

site_order_id（按订单维度查是否用了平台券）；

table_id（按球台查平台券使用情况）；

operator_id（按收银员查）。

这些都属于结构层面可以直接读出的信息，无关任何金额统计。

四、结构层面的额外线索与观察

最后总结一些从结构和字段组合上能看出的“额外信息”，仍然只停留在结构与属性层面：

券产品定义的冗余与稳健性

对同一种团购产品，系统同时存了：

coupon_name

sale_price

coupon_money

deal_id

channel_deal_id

任意一个 ID 字段缺失时（如部分记录 deal_id=0），仍然可以通过其他字段（coupon_name + sale_price + coupon_money + channel_deal_id）唯一识别该产品。

这种多字段冗余，结构上提升了抗“配置缺失”的能力。

多层 ID 设计（内部 ↔ 渠道 ↔ 平台）

对同一个概念（“团购商品”）同时存在：

渠道侧：channel_deal_id；

平台/系统侧：deal_id；

内部套餐侧：group_package_id（虽暂为 0）。

对同一张券同时存在：

顾客看到的 coupon_code；

平台内部的 certificate_id、verify_id；

系统内部的 id。

结构上体现出：系统刻意把“外部 ID”和“内部 ID”分层保存，而不是只保留其中一个。

时间字段区分“记录生成”与“业务发生”

create_time 与 consume_time 同时存在，多数记录仅相差 1 秒；

结构上明确：系统把“核销动作被记录的时间”和“券被认为实际使用的时间”分开存储，为后续审计、对账预留了空间（例如出现延迟写入或补录时）。

使用状态与逻辑删除的双维度

use_status 负责描述“业务意义上的状态”（已用/已撤销等）；

is_delete 负责描述“这条记录在系统里是否被逻辑删除”；

从结构设计看，可以同时存在 use_status=2 且 is_delete=0 的记录，说明“业务状态异常但仍然需要保留记录”。

与订单、台桌结合后可形成的“结构视图”

仅从字段关系看，一次平台券核销在全系统里的“链路”大致是：

平台券产品（deal_id / channel_deal_id）
→ 券实例（coupon_code / certificate_id）
→ 平台验券记录（本文件 id）
→ 门店订单（site_order_id）
→ 具体台桌（table_id，对应台桌列表）
→ 台费流水 / 其他订单明细（通过同一订单号在其他 JSON 里衔接）

即使不看任何金额，从 ID 设计也能看出：系统是希望把“外部平台 → 券 → 订单 → 台桌”串成一条完整链路的。

字段值域的稳定性

多个字段采用了典型“0/1/2”小枚举：

coupon_channel：1/2 两个平台；

use_status：1/2 两种状态；

groupon_type：目前只有 1；

is_delete：0/1；

说明系统在这部分采用的是固定枚举编码，而不是随意字符串，这一点利于后续联表和性能优化。
