# 台费流水 — GetSiteTableOrderDetails

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

---

## 一、接口概述

查询门店下台桌使用的计费流水。每条记录对应一段台桌使用时长的结算快照，包含计费时长、单价、原始应收金额以及各类优惠/调账的金额拆分。是台费维度的核心事实表，通过订单号与助教流水、小票详情、支付记录等表关联。

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

---

## 二、请求

### 请求体（JSON）

```json
{
  "startTime": "2025-11-01 08:00:00",
  "endTime": "2025-11-10 08:00:00",
  "siteId": 2790685415443269,
  "isSaleManUser": 0,
  "page": 1,
  "limit": 100
}
```

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `siteId` | int | 是 | 门店 ID |
| `isSaleManUser` | int | 是 | 是否销售员用户筛选。`0` = 全部 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |

---

## 三、响应结构

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

`data.siteTableUseDetailsList` 中每个对象即为一条台费流水记录，共 42 个字段，按逻辑分组说明如下。

---

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

### 4.1 主键与订单关联

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957924029058885` | 台费流水记录主键 |
| `order_trade_no` | int | `2957858167230149` | 订单交易号，整笔订单的主编号。与助教流水、小票详情等表的同名字段一致 |
| `order_settle_id` | int | `2957922914357125` | 结算单号/结账 ID，对应一次结账操作。与小票详情的 `orderSettleId` 对应 |
| `order_pay_id` | int | `0` | 订单支付记录 ID，对应支付记录表的 `id` 或 `relate_id`。`0` 表示未直接关联 |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID，所有记录相同 |
| `site_id` | int | `2790685415443269` | 门店 ID |

### 4.2 台桌维度

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `site_table_id` | int | `2793003705192517` | 台桌 ID，对应台桌配置表主键 |
| `ledger_name` | string | `"A17"` | 台号名称，冗余展示字段。与 `site_table_id` 一一对应 |
| `site_table_area_id` | int | `2791963794329671` | 门店内台桌区域 ID |
| `tenant_table_area_id` | int | `2791960001957765` | 租户维度台桌区域 ID，支持多门店共享区域配置 |
| `site_table_area_name` | string | `"A区"` | 台桌区域名称。已知值：`"A区"`、`"B区"`、`"C区"`、`"斯诺克区"`、`"麻将房"`、`"K包"`、`"VIP包厢"`、`"666"`、`"TV台"`、`"M8"` |

### 4.3 会员维度

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `member_id` | int | `0` | 会员 ID。`0` = 散客/非会员。非 0 时对应会员档案表的 `id` |

### 4.4 时间字段

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-09 23:35:57"` | 台费流水创建时间，通常接近结账时间 |
| `start_use_time` | string | `"2025-11-09 22:28:57"` | 实际开台时间。当前数据中与 `ledger_start_time` 完全相同 |
| `ledger_start_time` | string | `"2025-11-09 22:28:57"` | 计费起始时间 |
| `ledger_end_time` | string | `"2025-11-09 23:28:57"` | 计费结束时间 |
| `last_use_time` | string | `"2025-11-09 23:28:57"` | 最后使用/操作时间。与 `ledger_end_time` 多数相差 1 秒（系统截断） |

### 4.5 时长（秒）

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_count` | int | `3600` | 计费秒数（应收时长）。与 `real_table_use_seconds` 基本一致，少数差 1 秒 |
| `real_table_use_seconds` | int | `3600` | 实际使用总秒数。当两者均为 0 且 `is_single_order = 0` 时，为占位/关联记录 |
| `add_clock_seconds` | int | `0` | 加钟秒数。`0` = 无加钟。非 0 时通常为 60 的倍数（如 2400 = 40 分钟） |

### 4.6 金额与优惠拆分

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_unit_price` | float | `48.0` | 每小时计费单价（元/人民币）。常见值：48.0、58.0、68.0、88.0、98.0、116.0 |
| `ledger_amount` | float | `48.0` | 原始应收台费金额（元）。近似关系：`ledger_amount ≈ ledger_unit_price × ledger_count / 3600` |
| `real_table_charge_money` | float | `0.0` | 实际向顾客收取的台费金额（元）。`0` 表示完全由券/调账承担 |
| `coupon_promotion_amount` | float | `48.0` | 优惠券/活动/团购承担的优惠金额（元）。当此值等于 `ledger_amount` 且 `real_table_charge_money = 0` 时，表示台费由促销全额承担 |
| `member_discount_amount` | float | `0.0` | 会员权益/折扣承担的优惠金额（元） |
| `adjust_amount` | float | `0.0` | 调账/减免金额（元）。对应台费优惠记录表（`table_fee_discount_records`）中的 `ledger_amount` |
| `used_card_amount` | float | `0.0` | 储值卡/次卡抵扣金额（元）。当前门店未启用 |
| `service_money` | float | `0.0` | 服务费/成本/分成金额（元）。当前门店未启用 |
| `mgmt_fee` | float | `0.0` | 管理费（元）。预留字段，当前未启用 |
| `fee_total` | float | `0.0` | 附加费用合计（元）。预留字段，当前未启用 |
| `real_service_money` | number | `0.0` | 实际服务金额（元），扣除各类优惠后的台费实收金额 |

### 4.7 操作员与营业员

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `2790687322443013` | 操作员 ID（开台/结账员工） |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名，冗余展示字段 |
| `salesman_name` | string | `""` | 营业员/提成归属人姓名。当前门店未启用 |
| `salesman_user_id` | int | `0` | 营业员用户 ID。当前未启用 |
| `salesman_org_id` | int | `0` | 营业员所属机构 ID。当前未启用 |

### 4.8 订单类型与活动优惠

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `order_consumption_type` | integer | `1` | 订单消费类型枚举（如 1=普通消费），区分不同消费场景 |
| `activity_discount_amount` | number | `0.0` | 活动折扣金额（元），由门店活动/促销规则产生的台费优惠金额 |

### 4.9 状态与标记

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_status` | int | `1` | 台费状态。`1` = 正常已结算。其他值（如 `0` 未结算、`2` 作废）当前未出现 |
| `is_single_order` | int | `1` | 是否独立计费单元。`1` = 独立结算的台费；`0` = 非独立条目（合并结账/占位/转台的中间记录，此时 `ledger_count` 和 `real_table_use_seconds` 为 0） |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 未删除，`1` = 已逻辑删除 |

### 4.10 门店信息快照

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteProfile` | object | `{...}` | 门店信息快照（冗余），包含门店名称、地址、经纬度等 26 个子字段。结构与其他接口一致，不再逐字段展开 |

---

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

```json
{
  "siteProfile": { "id": 2790685415443269, "shop_name": "朗朗桌球", "..." : "..." },
  "id": 2957924029058885,
  "order_trade_no": 2957858167230149,
  "site_id": 2790685415443269,
  "tenant_id": 2790683160709957,
  "member_id": 0,
  "operator_id": 2790687322443013,
  "operator_name": "收银员:郑丽珊",
  "order_settle_id": 2957922914357125,
  "ledger_unit_price": 48.0,
  "ledger_name": "A17",
  "ledger_count": 3600,
  "ledger_amount": 48.0,
  "order_pay_id": 0,
  "create_time": "2025-11-09 23:35:57",
  "is_delete": 0,
  "site_table_id": 2793003705192517,
  "site_table_area_id": 2791963794329671,
  "tenant_table_area_id": 2791960001957765,
  "is_single_order": 1,
  "ledger_start_time": "2025-11-09 22:28:57",
  "ledger_end_time": "2025-11-09 23:28:57",
  "ledger_status": 1,
  "site_table_area_name": "A区",
  "real_table_charge_money": 0.0,
  "used_card_amount": 0.0,
  "adjust_amount": 0.0,
  "real_table_use_seconds": 3600,
  "coupon_promotion_amount": 48.0,
  "service_money": 0.0,
  "member_discount_amount": 0.0,
  "last_use_time": "2025-11-09 23:28:57",
  "salesman_name": "",
  "salesman_user_id": 0,
  "salesman_org_id": 0,
  "mgmt_fee": 0.0,
  "fee_total": 0.0,
  "start_use_time": "2025-11-09 22:28:57",
  "add_clock_seconds": 0
}
```

---

## 六、跨表关联

### 与助教流水（`assistant_service_records`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_trade_no` | `order_trade_no` | 同一订单下的台费与助教明细 |
| `order_settle_id` | `order_settle_id` | 同一结账事件 |
| `site_id` / `tenant_id` | `site_id` / `tenant_id` | 门店与租户维度一致 |

### 与台费优惠记录（`table_fee_discount_records`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_trade_no` | `order_trade_no` | 同一订单 |
| `order_settle_id` | `order_settle_id` | 同一结算单 |
| `adjust_amount` | `ledger_amount`（生效记录） | 台费流水的调账金额 = 台费优惠记录中有效记录的减免金额 |

### 与小票详情（`settlement_records`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_settle_id` | `settleList.id` / `orderSettleId` | 结算单 ID |
| `order_trade_no` | 订单号 | 订单维度关联 |

> 小票是顾客看到的整笔账单，台费流水是其中"台费项目"的明细拆解。

### 与会员档案

`member_id` 对应会员档案表的 `id`（`tenant_member_id`），可反查会员手机号、姓名、卡状态等。

### 与支付记录（`payment_transactions`）

`order_pay_id` 对应支付记录的 `id` 或 `relate_id`，可追踪付款方式（现金/微信/支付宝等）。

### 与台桌配置

`site_table_id` 对应台桌列表主键；`site_table_area_id` / `tenant_table_area_id` 分别对应门店级和租户级区域配置表。

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

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