# 台费优惠记录 — GetTaiFeeAdjustList

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

---

## 一、接口概述

查询门店下台费打折/调账的流水记录。每条记录不是台桌使用记录，而是在台费基础上追加的一条"金额调整记录"，用于记录某个订单、某张台在台费上的手工打折/减免金额。与台费流水表形成"主表 + 子操作表"的关系，通过 `adjust_amount ↔ ledger_amount` 闭合金额链路。

| 属性 | 值 |
|------|-----|
| 完整路径 | `POST /Site/GetTaiFeeAdjustList` |
| 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,
  "page": 1,
  "limit": 100
}
```

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `startTime` | string | 是 | 查询起始时间 |
| `endTime` | string | 是 | 查询结束时间 |
| `siteId` | int | 是 | 门店 ID |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |

---

## 三、响应结构

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

`data.taiFeeAdjustInfos` 中每个对象即为一条台费优惠记录，共 20 个字段，按逻辑分组说明如下。

---

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

### 4.1 主键与订单关联

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957913441881989` | 台费打折/调整流水主键 ID |
| `order_trade_no` | int | `2957784612605829` | 订单交易号。与台费流水、助教流水、小票详情的同名字段一致。少数订单有多条调整记录 |
| `order_settle_id` | int | `2957913171693253` | 结算单/小票 ID。与小票详情的 `orderSettleId` 对应 |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID |
| `site_id` | int | `2790685415443269` | 门店 ID |

### 4.2 台桌维度

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `site_table_id` | int | `2793020259897413` | 台桌 ID，对应台桌配置表主键 |
| `tenant_table_area_id` | int | `2791961347968901` | 租户维度台桌区域 ID |
| `tableProfile` | object | `{...}` | 台桌配置信息快照，子字段见下表 |

#### tableProfile 子字段

| 字段路径 | 类型 | 示例 | 说明 |
|----------|------|------|------|
| `tableProfile.id` | int | `2793020259897413` | 台桌 ID，与 `site_table_id` 一致 |
| `tableProfile.tenant_id` | int | `2790683160709957` | 租户 ID |
| `tableProfile.tenant_name` | string | `""` | 租户名称（当前为空） |
| `tableProfile.siteName` | string | `""` | 门店名称（当前为空，冗余字段） |
| `tableProfile.table_name` | string | `"S1"` | 台号名称 |
| `tableProfile.site_table_area_id` | int | `2791963836207173` | 门店级台桌区域 ID |
| `tableProfile.site_table_area_name` | string | `"斯诺克区"` | 区域名称 |
| `tableProfile.area_type_id` | int | `0` | 区域类型 ID |
| `tableProfile.table_price` | float | `0.0` | 基础单价（元），当前为 0.0 |
| `tableProfile.ewelink_client_id` | string | `""` | 易微联智能硬件设备 ID |
| `tableProfile.charge_free` | int | `0` | 免单标识。`0` = 正常计费 |

### 4.3 金额与数量

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_amount` | float | `148.15` | 台费调账/减免金额（元/人民币）。**注意**：在本表中 `ledger_amount` 表示"被调整掉的金额"，对应台费流水中同一订单的 `adjust_amount`。与台费流水中的 `ledger_amount`（原始应收）含义不同 |
| `ledger_count` | int | `1` | 调整次数，当前固定为 `1`（一次调账事件）。与台费流水中的 `ledger_count`（计费秒数）含义完全不同 |
| `ledger_name` | string | `""` | 调账项目名称/打折原因描述。当前门店未使用，全部为空字符串。预留字段 |

### 4.4 申请与操作信息

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `adjust_type` | int | `1` | 调整类型枚举。`1` = 台费打折/减免。其他值（如台费转移、误操作恢复）当前未出现 |
| `applicant_id` | int | `2790687322443013` | 打折/调账申请人 ID |
| `applicant_name` | string | `"收银员:郑丽珊"` | 申请人姓名（带角色描述），冗余展示字段 |
| `operator_id` | int | `2790687322443013` | 实际执行调账操作的操作员 ID。当前数据中与 `applicant_id` 相同 |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员姓名 |
| `create_time` | string | `"2025-11-09 23:25:11"` | 调整记录创建时间，即打折操作执行的时间戳 |

### 4.5 状态与标记

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_status` | int | `1` | 调整记录状态。`1` = 生效（当前有效的调账记录）；`0` = 已失效/被覆盖（历史记录、已撤销或被后续调账覆盖）。同一 `order_trade_no` 下可能有多条记录，仅 `ledger_status = 1` 的为当前有效 |
| `is_delete` | int | `0` | 逻辑删除标记。`0` = 未删除，`1` = 已逻辑删除 |

### 4.6 门店信息快照

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `siteProfile` | object | `{...}` | 门店信息快照（冗余），结构与其他接口一致，不再逐字段展开 |

---

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

```json
{
  "tableProfile": {
    "id": 2793020259897413,
    "tenant_id": 2790683160709957,
    "tenant_name": "",
    "siteName": "",
    "table_name": "S1",
    "site_table_area_id": 2791963836207173,
    "area_type_id": 0,
    "table_price": 0.0,
    "ewelink_client_id": "",
    "site_table_area_name": "斯诺克区",
    "charge_free": 0
  },
  "siteProfile": { "id": 2790685415443269, "shop_name": "朗朗桌球", "..." : "..." },
  "id": 2957913441881989,
  "adjust_type": 1,
  "applicant_id": 2790687322443013,
  "applicant_name": "收银员:郑丽珊",
  "create_time": "2025-11-09 23:25:11",
  "is_delete": 0,
  "ledger_amount": 148.15,
  "ledger_count": 1,
  "ledger_name": "",
  "ledger_status": 1,
  "operator_id": 2790687322443013,
  "operator_name": "收银员:郑丽珊",
  "order_settle_id": 2957913171693253,
  "order_trade_no": 2957784612605829,
  "site_id": 2790685415443269,
  "site_table_id": 2793020259897413,
  "tenant_id": 2790683160709957,
  "tenant_table_area_id": 2791961347968901
}
```

---

## 六、跨表关联

### 与台费流水（`table_fee_transactions`）

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

> 台费流水给出时长 + 原始台费 + 各种金额拆分（含 `adjust_amount`）；台费优惠记录给出是谁、何时、以哪种类型发起了调账，调了多少金额。两表通过 `order_trade_no` 做一对一/一对多关系。

### 与台桌配置 / 区域配置

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `site_table_id` | 台桌配置表 `id` | 台桌主键 |
| `tableProfile.table_name` | 台桌配置表 `table_name` | 台号名称 |
| `tableProfile.site_table_area_id` | 门店台桌区域维表 | 门店级区域 |
| `tenant_table_area_id` | 租户台桌区域维表 | 租户级区域 |

### 与员工/账号体系

`applicant_id` / `operator_id` 与账号体系中的用户 ID 对应（与助教账号 `user_id` 属于同一 ID 空间）。可按员工维度统计台费打折频次和金额。

### 与门店维度

`site_id` 与所有业务表的 `site_id` 一致。`siteProfile` 为冗余快照。

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