# 平台券核销记录 — GetOfflineCouponConsumePageList

> 模块：`Promotion` · ODS 表：`platform_coupon_redemption_records` · 事实表（增量）

---

## 一、接口概述

查询第三方团购平台（如美团等）券在门店被核销使用的流水记录。每条记录对应一次平台券的核销事件，包含券码、平台产品信息、售价与面值、核销状态、关联订单与球台、操作员等。本表是"外部平台 → 券 → 门店订单 → 台桌"完整链路的关键节点。

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

---

## 二、请求

### 请求体（JSON）

```json
{
  "couponChannel": 0,
  "startTime": "2026-02-01 08:00:00",
  "endTime": "2026-02-13 08:00:00",
  "siteId": 2790685415443269,
  "couponUseStatus": 0,
  "page": 1,
  "limit": 100
}
```

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `couponChannel` | int | 是 | 优惠券渠道筛选。`0` = 全部 |
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `siteId` | int | 是 | 门店 ID |
| `couponUseStatus` | int | 是 | 使用状态筛选。`0` = 全部 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |

---

## 三、响应结构

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

`data.list` 中每个对象即为一条平台券核销记录，共 26 个字段，按逻辑分组说明如下。

---

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

### 4.1 主键与门店/租户

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `3092405812332869` | 平台验券记录主键 ID（分布式 ID） |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
| `site_id` | int | `2790685415443269` | 门店 ID |

### 4.2 门店信息快照

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteProfile` | object | `{...}` | 门店信息快照对象，包含 `id`（站点 ID）、`org_id`（组织 ID）、`shop_name`（门店名称）、`business_tel`（门店电话）、`full_address`（完整地址）、`longitude`/`latitude`（经纬度）、`auto_light`（自动控灯，`1`=是）、`attendance_enabled`（考勤，`1`=启用）、`shop_status`（`1`=营业中）等子字段 |

### 4.3 券身份与平台信息

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `coupon_code` | string | `"0108919359400"` | 券码，顾客出示的团购券编号。业务唯一键，可作为查询/去重索引 |
| `coupon_name` | string | `"【全天可用】中八桌球一小时（大厅A区）"` | 团购券产品名称（第三方平台展示名称） |
| `coupon_channel` | int | `1` | 券来源渠道。`1` = 平台渠道 1，`2` = 平台渠道 2（具体平台需查系统配置） |
| `groupon_type` | int | `1` | 团购券类型。`1` = 标准团购券 |
| `channel_deal_id` | int | `1128411555` | 渠道侧产品 ID（第三方平台给团购商品定义的主键），与 `coupon_name` 一一对应 |
| `deal_id` | int | `1345108507` | 系统内部团购产品 ID。`0` = 内部未配置/未同步。与 `channel_deal_id` 形成"渠道侧 ↔ 系统侧"双层映射 |
| `group_package_id` | int | `0` | 内部团购套餐定义 ID，对应 `group_buy_packages` 表的 `id`。当前全部为 `0`（平台券尚未映射到内部套餐） |
| `certificate_id` | string | `"5017032743553662850"` | 平台侧凭证 ID（第三方平台生成的券实例 ID），用于对账。可能有重复值 |
| `verify_id` | string | `""` | 平台核销记录 ID。大部分为空，仅部分平台/版本回传 |
| `coupon_cover` | string | `""` | 券封面图 URL，当前未使用 |
| `coupon_remark` | string | `""` | 券备注信息，当前未使用 |

### 4.4 金额与时长

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `sale_price` | float | `20.26` | 顾客在第三方平台实际支付的价格（元）。已知值：`11.11`、`29.9`、`39.9`、`59.9`、`69.9`、`128.0`。始终小于 `coupon_money` |
| `coupon_money` | float | `48.0` | 券面值/可抵扣金额（元）。已知值：`48.0`、`58.0`、`68.0`、`96.0`、`116.0`、`288.0` |
| `coupon_free_time` | int | `0` | 券附带的免费时长（秒）。当前全部为 `0`（未启用赠送时长） |

### 4.5 使用状态与时间

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `use_status` | int | `1` | 券使用状态。`1` = 已使用/已核销，`2` = 已退款/已撤销 |
| `create_time` | string | `"2026-02-12 23:37:54"` | 验券记录创建时间（系统记录时间） |
| `consume_time` | string | `"2026-02-12 23:37:55"` | 券被核销的业务时间。与 `create_time` 通常相差 1 秒左右 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 未删除，`1` = 已逻辑删除。与 `use_status` 独立：`use_status=2` 不一定 `is_delete=1` |

### 4.6 订单、球台与操作员

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `site_order_id` | int | `3092345641453701` | 门店内部订单 ID，将平台券核销挂到本地订单上 |
| `table_id` | int | `2793002808987781` | 使用券的球台 ID，对应台桌列表的 `id` |
| `operator_id` | int | `2790687322443013` | 执行验券操作的收银员/员工 ID |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名（带职位前缀） |

---

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

```json
{
  "siteProfile": {
    "id": 2790685415443269,
    "org_id": 2790684179467077,
    "shop_name": "朗朗桌球",
    "business_tel": "13316068642",
    "full_address": "广东省广州市天河区丽阳街12号",
    "shop_status": 1
  },
  "id": 3092405812332869,
  "tenant_id": 2790683160709957,
  "site_id": 2790685415443269,
  "sale_price": 20.26,
  "coupon_code": "0108919359400",
  "coupon_channel": 1,
  "site_order_id": 3092345641453701,
  "coupon_free_time": 0,
  "use_status": 1,
  "create_time": "2026-02-12 23:37:54",
  "is_delete": 0,
  "coupon_name": "【全天可用】中八桌球一小时（大厅A区）",
  "coupon_cover": "",
  "coupon_remark": "",
  "channel_deal_id": 1128411555,
  "group_package_id": 0,
  "consume_time": "2026-02-12 23:37:55",
  "groupon_type": 1,
  "coupon_money": 48.0,
  "operator_id": 2790687322443013,
  "operator_name": "收银员:郑丽珊",
  "table_id": 2793002808987781,
  "certificate_id": "5017032743553662850",
  "verify_id": "",
  "deal_id": 1345108507
}
```

---

## 六、跨表关联

### 与团购套餐定义（`group_buy_packages`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `group_package_id` | `id` | 内部团购套餐 ID（当前全部为 0，预留外键） |

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

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `coupon_code` | `coupon_code` | 券码，串联"平台 → 核销 → 台费流水"全链路 |

### 与订单/结账相关表

通过 `site_order_id` 将平台券核销记录挂到门店订单上，可进一步关联台费流水、商品销售记录、小票详情等。

### 与台桌列表

`table_id` 对应台桌列表的 `id`，标明券在哪张台桌上消费。

### 与外部平台

- `coupon_code`：顾客和平台双方可见的券码
- `certificate_id`：平台内部凭证 ID
- `verify_id`：平台核销 ID（部分平台回传）
- `channel_deal_id` / `deal_id`：平台和系统对团购产品的双重映射

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