248 lines
10 KiB
Markdown
248 lines
10 KiB
Markdown
# 台费流水 — 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` 中每个对象即为一条台费流水记录，共 39 个字段，按逻辑分组说明如下。
|
||
|
||
---
|
||
|
||
## 四、响应字段详解（39 个字段）
|
||
|
||
### 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` | 附加费用合计（元）。预留字段，当前未启用 |
|
||
|
||
### 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 状态与标记
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `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.9 门店信息快照
|
||
|
||
| 字段 | 类型 | 示例 | 说明 |
|
||
|------|------|------|------|
|
||
| `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/ 确认字段覆盖完整
|
||
-->
|