# 团购核销记录 — GetSiteTableUseDetails

> 模块：`Site` · ODS 表：`group_buy_redemption_records` · 事实表（增量）

---

## 一、接口概述

查询团购券在门店台费上的使用明细流水。每条记录描述一张团购券被核销到某张球台的台费上，包含券码、套餐配置、抵扣金额与时长、关联订单与球台、促销拆账等信息。本表是"团购套餐定义 + 台费流水 + 平台券核销"之间的桥接事实表，将某张券、某个套餐配置、某个订单、某张桌、某段时间、某个金额绑定在一起。

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

---

## 二、请求

### 请求体（JSON）

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

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `siteId` | int | 是 | 门店 ID |
| `offlineCouponChannel` | int | 是 | 线下券渠道筛选。`0` = 全部 |
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |
| `queryType` | int | 是 | 查询类型。`1` = 默认 |

---

## 三、响应结构

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

`data.list` 中每个对象即为一条团购核销流水记录，共 43 个字段，按 10 个逻辑分组说明如下。

---

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

### 4.1 台桌与门店维度

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_id` | int | `2793003705192517` | 球台 ID，对应台桌列表的 `id` |
| `tableName` | string | `"A17"` | 球台名称/台号。示例：`"A7"`、`"B1"`、`"斯1"`、`"麻1"` |
| `tableAreaName` | string | `"A区"` | 球台所属台区名称。枚举：`"A区"`、`"B区"`、`"斯诺克区"`、`"麻将房"` |
| `tenant_table_area_id` | int | `2791960001957765` | 租户级台区分组 ID，用于校验券的适用台区与实际台桌是否匹配 |
| `site_id` | int | `2790685415443269` | 门店 ID |
| `siteName` | string | `"朗朗桌球"` | 门店名称，冗余展示用 |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |

### 4.2 订单与关联 ID

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957924029615941` | 团购核销流水记录主键 ID |
| `order_trade_no` | int | `2957858167230149` | 订单交易号，与台费流水、助教流水、小票详情等共用的订单主键 |
| `order_settle_id` | int | `2957922914357125` | 结算单 ID（小票结账主键），对应小票详情的 `orderSettleId` |
| `order_pay_id` | int | `0` | 支付记录 ID。`0` = 未关联具体支付记录 |
| `order_coupon_id` | int | `2957858168229573` | 订单中券使用记录 ID，与平台验券记录主键对应 |
| `coupon_origin_id` | int | `2957858168229573` | 平台/上游系统券记录主键 ID（券来源 ID）。当前与 `order_coupon_id` 完全相等 |
| `promotion_activity_id` | int | `2957858166460101` | 团购/促销活动 ID，对应平台或内部促销活动主键 |
| `promotion_coupon_id` | int | `2798727423528005` | 团购套餐定义 ID，对应 `group_buy_packages` 表的 `id` |

### 4.3 金额字段（核心）

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_unit_price` | float | `29.9` | 台费标准单价（元/小时）。已知值：`29.9`、`39.9`、`59.9`、`69.9`、`11.11`、`128.0` |
| `ledger_count` | int | `3600` | 本次券实际核销的计费秒数。大部分等于 `promotion_seconds`，少数略有差异 |
| `ledger_amount` | float | `48.0` | 本次券实际冲抵台费的金额（元）。绝大部分与 `coupon_money` 相等 |
| `coupon_money` | float | `48.0` | 本次核销时券在门店侧的可抵扣金额（元）。已知值：`48.0`、`58.0`、`68.0`、`96.0`、`116.0`、`288.0` |
| `goodsOptionPrice` | float | `0.0` | 商品规格价格，用于商品类促销分摊。当前未使用 |

### 4.4 时长字段

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `promotion_seconds` | int | `3600` | 团购套餐标准时长（秒）。枚举：`3600`（1 小时）、`7200`（2 小时）、`14400`（4 小时）。与套餐定义的 `duration` 一致 |
| `table_charge_seconds` | int | `3600` | 本次结算中球台总计费秒数。当券完全覆盖时等于 `ledger_count`；有多种计费组合时可能更大 |

### 4.5 促销拆账字段

> 按不同业务子模块预留的促销金额分摊字段。当前门店团购券仅用于抵扣台费，以下字段全部为 `0.0`。

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_service_promotion_money` | float | `0.0` | 分摊到台费服务费的促销金额（元） |
| `assistant_promotion_money` | float | `0.0` | 分摊到助教服务的促销金额（元） |
| `assistant_service_promotion_money` | float | `0.0` | 分摊到助教服务费的促销金额（元） |
| `goods_promotion_money` | float | `0.0` | 分摊到商品的促销金额（元） |
| `reward_promotion_money` | float | `0.0` | 奖励金/积分抵扣的促销金额（元） |
| `recharge_promotion_money` | float | `0.0` | 充值类优惠的分摊金额（元） |

### 4.6 券标识与渠道

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `coupon_code` | string | `"0107892475999"` | 团购券券码，核销时扫描/录入。与平台验券记录的 `coupon_code` 一致，串联全链路 |
| `order_coupon_channel` | int | `1` | 券渠道类型。`1` = 渠道 A，`2` = 渠道 B（具体平台需查系统配置） |
| `offer_type` | int | `1` | 优惠类型。`1` = 套餐券（当前唯一值） |
| `ledger_name` | string | `"全天A区中八一小时"` | 团购项目记账名称，通常来源于套餐定义的 `package_name` |
| `ledger_group_name` | string | `""` | 团购项目记账分组名称，当前未使用 |

### 4.7 状态与标志

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_status` | int | `1` | 流水状态。`1` = 正常有效 |
| `is_single_order` | int | `1` | 是否独立订单行。`1` = 独立条目结算，`0` = 嵌在组合结算中 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 正常，`1` = 已删除 |

### 4.8 操作员与销售员

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `2790687322443013` | 执行核销/结算操作的员工 ID |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名（带职位前缀） |
| `salesman_user_id` | int | `0` | 营业员用户 ID。当前未启用 |
| `salesman_name` | string | `""` | 营业员姓名。当前未启用 |
| `salesman_role_id` | int | `0` | 营业员角色 ID。当前未启用 |
| `sales_man_org_id` | int | `0` | 营业员所属组织 ID。当前未启用 |

### 4.9 结算分摊金额

> 订单结算时按业务子模块拆分的实际分摊金额。与 4.5 "促销拆账字段"不同：4.5 是促销优惠的分摊，本组是实际收入的分摊。

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `table_share_money` | number | `39.9` | 台费分摊金额（元），核销券抵扣台费后的实际台费收入分摊 |
| `table_service_share_money` | number | `0.0` | 台费服务费分摊金额（元） |
| `assistant_share_money` | number | `0.0` | 助教分摊金额（元） |
| `assistant_service_share_money` | number | `0.0` | 助教服务费分摊金额（元） |
| `goods_share_money` | number | `0.0` | 商品分摊金额（元） |
| `good_service_share_money` | number | `0.0` | 商品服务费分摊金额（元） |
| `recharge_share_money` | number | `0.0` | 充值分摊金额（元） |
| `member_discount_money` | number | `0.0` | 会员折扣金额（元），会员卡权益产生的优惠抵扣 |
| `coupon_sale_id` | integer | `0` | 券销售记录 ID，关联团购券的销售订单。`0` = 无关联 |

### 4.10 时间

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-09 23:35:57"` | 流水创建时间（券核销时间，接近结账时间） |

---

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

```json
{
  "tableName": "A17",
  "tableAreaName": "A区",
  "siteName": "朗朗桌球",
  "goodsOptionPrice": 0.0,
  "id": 2957924029615941,
  "order_trade_no": 2957858167230149,
  "table_id": 2793003705192517,
  "site_id": 2790685415443269,
  "tenant_id": 2790683160709957,
  "operator_id": 2790687322443013,
  "operator_name": "收银员:郑丽珊",
  "order_settle_id": 2957922914357125,
  "ledger_name": "全天A区中八一小时",
  "ledger_group_name": "",
  "ledger_unit_price": 29.9,
  "ledger_count": 3600,
  "ledger_amount": 48.0,
  "order_pay_id": 0,
  "create_time": "2025-11-09 23:35:57",
  "is_delete": 0,
  "promotion_activity_id": 2957858166460101,
  "promotion_coupon_id": 2798727423528005,
  "is_single_order": 1,
  "order_coupon_id": 2957858168229573,
  "order_coupon_channel": 1,
  "ledger_status": 1,
  "promotion_seconds": 3600,
  "coupon_origin_id": 2957858168229573,
  "table_charge_seconds": 3600,
  "offer_type": 1,
  "coupon_money": 48.0,
  "tenant_table_area_id": 2791960001957765,
  "assistant_promotion_money": 0.0,
  "assistant_service_promotion_money": 0.0,
  "table_service_promotion_money": 0.0,
  "goods_promotion_money": 0.0,
  "reward_promotion_money": 0.0,
  "recharge_promotion_money": 0.0,
  "salesman_user_id": 0,
  "salesman_name": "",
  "salesman_role_id": 0,
  "sales_man_org_id": 0,
  "coupon_code": "0107892475999"
}
```

---

## 六、跨表关联

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

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `promotion_coupon_id` | `id` | 套餐定义 ID → 使用的是哪种团购套餐 |

> 通过此关联可获取套餐名称、标准时长、适用台区、每日可用时段等配置。`promotion_seconds` 与套餐定义的 `duration` 在结构上一致。

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

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `coupon_code` | `coupon_code` | 券码，串联平台 → 核销 → 台费流水全链路 |
| `coupon_origin_id` / `order_coupon_id` | `id` | 平台券记录主键 |

### 与订单/小票相关表

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_trade_no` | `order_trade_no` | 订单号 → 同一笔结账中的台费、助教、商品等明细 |
| `order_settle_id` | `orderSettleId` | 结算单 ID → 小票详情 |
| `order_pay_id` | 支付记录 `id` | 支付流水 ID（非 0 时） |

### 与台桌维度/台区配置

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `table_id` | 台桌列表 `id` | 具体球台 |
| `tenant_table_area_id` | 套餐定义 `tenant_table_area_id_list` | 实际使用台区 ↔ 套餐允许台区，用于校验 |

### 与门店维度

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

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

- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行；补全 2 个缺失字段（coupon_channel, coupon_remark）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过

- 日期: 2026-02-14
- Prompt: P20260214-130000 — 25 个 API 文档归档至 summary/ + 字段分组修正
- 直接原因: 4.9"时间"组混入 9 个非时间字段（分摊金额、券 ID、会员折扣），严重影响文档可读性
- 变更摘要: 新增 4.9"结算分摊金额"组（9 字段）和 4.10"时间"组；原 4.9 中 create_time 保留在时间组，其余字段按语义重新归类
- 风险与验证: 纯文档分组调整，无运行时影响；验证：统计各组字段数总和 = 43
-->
