# 助教服务流水 — GetOrderAssistantDetails

> 模块：`AssistantPerformance` · ODS 表：`assistant_service_records` · 事实表（增量）

---

## 一、接口概述

查询门店在指定时间范围内的助教服务流水记录。每条记录对应一次助教服务明细（一位助教在一张桌上的一段服务），是助教业绩核算、薪资计算的核心数据源。

助教流水是事实表，通过 `order_trade_no` / `order_settle_id` 与结账记录、台费流水、小票详情等表关联，构成同一笔订单下的不同消费子项目。

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

---

## 二、请求

### 请求体（JSON）

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

### 参数说明

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `siteId` | int | 是 | 门店 ID |
| `startTime` | string | 是 | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS` |
| `endTime` | string | 是 | 查询结束时间 |
| `IsConfirm` | int | 是 | 确认状态筛选。`0` = 全部，`1` = 待确认，`2` = 已确认 |
| `page` | int | 是 | 页码，从 1 开始 |
| `limit` | int | 是 | 每页条数，最大 100 |

---

## 三、响应结构

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

`data.list` 中每个对象即为一条助教服务流水记录，共 64 个字段（含嵌套 `siteProfile` 对象），按逻辑分组说明如下。

---

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

### 4.1 订单与关联 ID

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `id` | int | `2957913441292165` | 助教流水记录主键 ID（流水唯一标识） |
| `order_trade_no` | int | `2957784612605829` | 订单交易号。与台费流水、商品销售、团购流水等表的同名字段一致，用于串联同一笔订单下的各类消费明细 |
| `order_settle_id` | int | `2957913171693253` | 订单结算 ID（结账单号）。与结账记录的 `id`、小票详情的 `orderSettleId` 对应 |
| `order_assistant_id` | int | `2957788717240005` | 订单中助教项目明细的内部 ID。同一订单有多条助教项目时（换助教、多时段），此字段唯一标识每条明细 |
| `order_assistant_type` | int | `1` | 助教服务类型枚举：`1` = 常规服务（基础课），`2` = 附加类服务（附加课）。与 `skillName` 对应 |
| `order_pay_id` | int | `0` | 关联支付记录的主键 ID。`0` = 无直接支付关联（通过结账记录间接关联） |
| `tenant_id` | int | `2790683160709957` | 租户/品牌 ID，全表固定 |
| `site_id` | int | `2790685415443269` | 门店 ID |
| `site_assistant_id` | int | `2946266869435205` | 门店维度的助教 ID。与助教账号表的 `id` 对应，是助教档案的外键 |
| `user_id` | int | `2946266868976453` | 助教的系统用户账号 ID。与助教账号表的 `user_id` 一致，区别于岗位级的 `site_assistant_id` |
| `person_org_id` | int | `2946266869336901` | 助教所属人事组织/部门 ID。与助教账号表的 `person_org_id` 一致 |
| `assistant_team_id` | int | `2792011585884037` | 助教所属团队 ID。与助教账号表的 `team_id` 对应，用于排班/团队统计 |
| `tenant_member_id` | int | `0` | 商户维度会员 ID。`0` = 非会员；非零时与会员档案的 `id` 一致 |
| `system_member_id` | int | `0` | 系统级会员 ID（全集团统一）。与会员档案的 `system_member_id` 对应，用于跨门店/跨卡种串联 |
| `skill_id` | int | `2790683529513797` | 助教服务课程/技能 ID，对应课程配置表主键 |

### 4.2 助教维度

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `assistantNo` | string | `"27"` | 助教编号/工号。与助教账号表的 `assistant_no` 对应 |
| `assistantName` | string | `"何海婷"` | 助教真实姓名。与助教账号表的 `real_name` 一致 |
| `nickname` | string | `"泡芙"` | 助教对外昵称（非顾客昵称）。在小票/商品名中常以"编号-昵称"组合出现（如 `ledger_name = "27-泡芙"`） |
| `assistant_level` | int | `10` | 助教等级枚举：`8` = 助教管理，`10` = 初级，`20` = 中级，`30` = 高级。与助教账号表的 `level` 对应 |
| `levelName` | string | `"初级"` | 助教等级名称，与 `assistant_level` 一一对应，展示用冗余字段 |
| `skillName` | string | `"基础课"` | 当前服务对应的课程/技能名称。`order_assistant_type=1` 时多为"基础课"，`=2` 时为"附加课" |
| `ledger_name` | string | `"27-泡芙"` | 台账显示名称，"编号-昵称"组合，用于报表和前端展示 |
| `ledger_group_name` | string | `""` | 助教项目所属计费分组/套餐分组名称，当前未使用 |

### 4.3 桌台与门店维度

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `tableName` | string | `"S1"` | 助教服务所在球台名称。与台桌列表的 `table_name` / `table_no` 对应 |
| `site_table_id` | int | `2793020259897413` | 球台 ID。对应台桌列表的 `id` |
| `siteProfile` | object | `{id, shop_name, ...}` | 门店信息快照（嵌套对象），包含 `id`、`shop_name`、`address`、`longitude`/`latitude` 等。与其他接口的 `siteProfile` 结构一致。**注意：此处 siteProfile 包含真实门店数据**（区别于结账记录中的空壳） |

### 4.4 时间与时长

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `create_time` | string | `"2025-11-09 23:25:11"` | 流水记录创建时间，接近结算/下单时间 |
| `start_use_time` | string | `"2025-11-09 21:18:18"` | 助教实际开始服务时间。正常情况下与 `ledger_start_time` 相同 |
| `last_use_time` | string | `"2025-11-09 23:24:50"` | 最后一次使用时间。正常结束时与 `ledger_end_time` 相同 |
| `ledger_start_time` | string | `"2025-11-09 21:18:18"` | 台账计费起始时间 |
| `ledger_end_time` | string | `"2025-11-09 23:24:50"` | 台账计费结束时间。`real_use_seconds=0` 时开始=结束，表示仅预约未实际服务 |
| `income_seconds` | int | `7560` | 计费秒数（应计收入对应时间）。值通常为 60 的倍数，配合 `ledger_unit_price` 计算应计金额 |
| `real_use_seconds` | int | `7592` | 实际使用时长（秒）。与 `ledger_count` 基本一致（±1 秒差）。`0` = 已预约但未消耗 |
| `ledger_count` | int | `7592` | 台账计时总秒数，即本条服务真正消耗的总时长 |
| `add_clock` | int | `0` | 加钟秒数（临时追加时长）。值为 60 的倍数，如 `600` = 10 分钟 |
| `returns_clock` | int | `0` | 退钟秒数（取消加钟或提前结束退回的时间）。当前未出现退钟场景 |

### 4.5 金额与折扣

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_unit_price` | float | `98.0` | 助教服务标准单价（每小时/每节课），如 98.0、108.0、190.0 |
| `ledger_amount` | float | `206.67` | 按标准单价计算的应收金额（近似 = `ledger_unit_price × income_seconds / 3600`），未扣除优惠 |
| `projected_income` | float | `168.0` | 实际结算计入门店的金额（已考虑折扣、卡权益、券等）。通常 `projected_income < ledger_amount` |
| `coupon_deduct_money` | float | `0.0` | 优惠券/代金券/团购券直接抵扣到本条助教服务的金额。与平台验券记录/团购流水联动 |
| `manual_discount_amount` | float | `0.0` | 收银员手动减免金额（人工改价） |
| `member_discount_amount` | float | `0.0` | 会员卡折扣产生的优惠金额。实际折扣可能已体现在 `projected_income` 与 `ledger_amount` 的差额中 |
| `service_money` | float | `0.0` | 平台预留的成本/分成字段，当前未启用 |

### 4.6 评价相关

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `skill_grade` | int | `0` | 顾客对技能表现的评分。`0` = 未评价 |
| `service_grade` | int | `0` | 顾客对服务态度的评分。`0` = 未评价 |
| `composite_grade` | float | `0.0` | 综合评分（技能+服务加权平均） |
| `sum_grade` | float | `0.0` | 累计评分总和，用于计算平均分 |
| `get_grade_times` | int | `0` | 被评价次数 |
| `grade_status` | int | `1` | 评价状态：`1` = 未评价/正常 |
| `composite_grade_time` | string | `"0001-01-01 00:00:00"` | 最近评价时间。`0001-01-01` = 无效占位（未评价） |

### 4.7 状态与标志位

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `ledger_status` | int | `1` | 流水记录状态：`1` = 正常有效。其他值可能对应"未结算""已作废" |
| `is_confirm` | int | `2` | 确认状态：`1` = 待确认，`2` = 已确认/已完成 |
| `is_single_order` | int | `1` | 是否单独订单结算：`1` = 单独结算，`0` = 与其他项目打包在综合订单中 |
| `is_not_responding` | int | `0` | 是否爽约/未响应：`0` = 正常，`1` = 有爽约 |
| `is_trash` | int | `0` | 是否已废除：`0` = 正常，`1` = 已废除（对应助教撤销记录表） |
| `is_delete` | int | `0` | 逻辑删除标志：`0` = 未删除，`1` = 已删除。与 `is_trash` 不同：`is_trash` 是业务废除，`is_delete` 是系统级删除 |

### 4.8 员工 / 销售人员

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `operator_id` | int | `2790687322443013` | 操作员 ID（录入/结算该服务的员工） |
| `operator_name` | string | `"收银员:郑丽珊"` | 操作员名称，含角色前缀 |
| `salesman_name` | string | `""` | 营业员/销售员姓名（提成归属），当前未配置 |
| `salesman_user_id` | int | `0` | 营业员用户 ID |
| `salesman_org_id` | int | `0` | 营业员所属组织/部门 ID |

### 4.9 作废 / 废除相关

| 字段 | 类型 | 示例 | 说明 |
|------|------|------|------|
| `trash_applicant_id` | int | `0` | 废除申请人员工 ID。`0` = 未发生废除 |
| `trash_applicant_name` | string | `""` | 废除申请人姓名 |
| `trash_reason` | string | `""` | 废除原因文本，如"顾客取消""录入错误"等 |

> 当 `is_trash = 1` 时，废除详情同时记录在助教撤销记录表（`assistant_cancellation_records`）中。

---

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

```json
{
  "assistantNo": "27",
  "nickname": "泡芙",
  "levelName": "初级",
  "assistantName": "何海婷",
  "tableName": "S1",
  "siteProfile": {
    "id": 2790685415443269,
    "org_id": 2790684179467077,
    "shop_name": "朗朗桌球",
    "avatar": "https://oss.ficoo.vip/admin/hXcE4E_1752495052016.jpg",
    "business_tel": "13316068642",
    "full_address": "广东省广州市天河区丽阳街12号",
    "address": "广东省广州市天河区天园街道朗朗桌球",
    "longitude": 113.360321,
    "latitude": 23.133629,
    "tenant_site_region_id": 156440100,
    "tenant_id": 2790683160709957,
    "auto_light": 1,
    "site_type": 1,
    "site_label": "A",
    "attendance_enabled": 1,
    "shop_status": 1
  },
  "skillName": "基础课",
  "id": 2957913441292165,
  "order_trade_no": 2957784612605829,
  "site_id": 2790685415443269,
  "tenant_id": 2790683160709957,
  "operator_id": 2790687322443013,
  "operator_name": "收银员:郑丽珊",
  "order_settle_id": 2957913171693253,
  "ledger_name": "27-泡芙",
  "ledger_unit_price": 98.0,
  "ledger_count": 7592,
  "ledger_amount": 206.67,
  "create_time": "2025-11-09 23:25:11",
  "assistant_level": 10,
  "ledger_start_time": "2025-11-09 21:18:18",
  "ledger_end_time": "2025-11-09 23:24:50",
  "site_assistant_id": 2946266869435205,
  "order_assistant_type": 1,
  "site_table_id": 2793020259897413,
  "projected_income": 168.0,
  "income_seconds": 7560,
  "real_use_seconds": 7592,
  "is_confirm": 2,
  "grade_status": 1
}
```

> 样例已精简，完整字段见 `samples/assistant_service_records.json`。

---

## 六、跨表关联

### 与助教账号（`assistant_accounts_master`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `site_assistant_id` | `id` | 助教主键（核心外键） |
| `user_id` | `user_id` | 系统用户 ID |
| `assistant_team_id` | `team_id` | 团队 ID |
| `person_org_id` | `person_org_id` | 人事组织 ID |
| `assistant_level` | `level` | 助教等级 |

> 助教流水是事实表，助教账号是对应的维表。

### 与结账记录（`settlement_records`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `order_settle_id` | `id` | 结账单号 |
| `order_trade_no` | `settleRelateId` | 交易号 |

> 结账记录中的 `assistantPdMoney` = 本表对应订单下 `ledger_amount` 的汇总。

### 与会员档案（`member_profiles`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `tenant_member_id` | `id` | 商户维度会员 ID |
| `system_member_id` | `system_member_id` | 系统级会员 ID |

### 与台桌（`site_tables_master`）

| 本表字段 | 关联表字段 | 说明 |
|----------|-----------|------|
| `site_table_id` | `id` | 球台 ID |

### 与助教撤销记录（`assistant_cancellation_records`）

当 `is_trash = 1` 时，废除详情在撤销记录表中。`trash_reason`、`trash_applicant_id/name` 是废除信息在本表中的快照。

### 新增字段说明（相对旧版 JSON 样本）

| 字段 | 说明 |
|------|------|
| `assistantTeamName` | 助教团队名称（展示用） |
| `real_service_money` | 实际服务金额 |

<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-180000 — 上下文传递续接，继续 Phase 2 API 文档重构
- 直接原因: 按标杆文档格式重写 assistant_service_records 高质量 API 参考文档
- 变更摘要: 新建 docs/api-reference/assistant_service_records.md，64 个字段按 9 个逻辑分组详解，含时长计算说明、跨表关联
- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
-->