初始提交：飞球 ETL 系统全量代码

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/assistant_service_records.md
+++ b/docs/api-reference/assistant_service_records.md
@@ -0,0 +1,294 @@
+# 助教服务流水 — 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/ 确认字段覆盖完整
+-->