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

docs/api-reference/endpoints/assistant_service_records.md

@@ -0,0 +1,852 @@
+# 助教服务流水（GetOrderAssistantDetails）
+
+> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
+
+## 基本信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `AssistantPerformance/GetOrderAssistantDetails` |
+| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/AssistantPerformance/GetOrderAssistantDetails` |
+| 请求方法 | `POST` |
+| Content-Type | `application/json` |
+| 鉴权方式 | Bearer Token（`Authorization` 头） |
+| ODS 对应表 | `assistant_service_records` |
+| 分页方式 | `page` + `limit`（最大 100） |
+| 时间范围 | 需要（startTime / endTime） |
+
+## 请求参数
+
+| 参数名 | 类型 | 示例值 | 说明 |
+|--------|------|--------|------|
+| `siteId` | int | `2790685415443269` | 门店 ID |
+| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
+| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
+| `IsConfirm` | int | `0` | 是否已确认（0=全部） |
+| `page` | int | `1` | 页码（从 1 开始） |
+| `limit` | int | `100` | 每页条数（最大 100） |
+
+## 响应字段（共 64 个）
+
+| # | 字段名 | 类型 | 示例值 |
+|---|--------|------|--------|
+| 1 | `assistantNo` | string | '27' |
+| 2 | `nickname` | string | '泡芙' |
+| 3 | `levelName` | string | '初级' |
+| 4 | `assistantName` | string | '何海婷' |
+| 5 | `tableName` | string | 'S1' |
+| 6 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
+| 7 | `skillName` | string | '基础课' |
+| 8 | `id` | int | 2957913441292165 |
+| 9 | `order_trade_no` | int | 2957784612605829 |
+| 10 | `site_id` | int | 2790685415443269 |
+| 11 | `tenant_id` | int | 2790683160709957 |
+| 12 | `operator_id` | int | 2790687322443013 |
+| 13 | `operator_name` | string | '收银员:郑丽珊' |
+| 14 | `order_settle_id` | int | 2957913171693253 |
+| 15 | `ledger_name` | string | '27-泡芙' |
+| 16 | `ledger_group_name` | string | '' |
+| 17 | `ledger_unit_price` | float | 98.0 |
+| 18 | `ledger_count` | int | 7592 |
+| 19 | `ledger_amount` | float | 206.67 |
+| 20 | `order_pay_id` | int | 0 |
+| 21 | `create_time` | string | '2025-11-09 23:25:11' |
+| 22 | `is_delete` | int | 0 |
+| 23 | `assistant_team_id` | int | 2792011585884037 |
+| 24 | `assistant_level` | int | 10 |
+| 25 | `ledger_start_time` | string | '2025-11-09 21:18:18' |
+| 26 | `ledger_end_time` | string | '2025-11-09 23:24:50' |
+| 27 | `is_single_order` | int | 1 |
+| 28 | `order_assistant_id` | int | 2957788717240005 |
+| 29 | `site_assistant_id` | int | 2946266869435205 |
+| 30 | `order_assistant_type` | int | 1 |
+| 31 | `ledger_status` | int | 1 |
+| 32 | `site_table_id` | int | 2793020259897413 |
+| 33 | `projected_income` | float | 168.0 |
+| 34 | `is_not_responding` | int | 0 |
+| 35 | `income_seconds` | int | 7560 |
+| 36 | `user_id` | int | 2946266868976453 |
+| 37 | `trash_applicant_id` | int | 0 |
+| 38 | `trash_applicant_name` | string | '' |
+| 39 | `is_trash` | int | 0 |
+| 40 | `trash_reason` | string | '' |
+| 41 | `real_use_seconds` | int | 7592 |
+| 42 | `add_clock` | int | 0 |
+| 43 | `returns_clock` | int | 0 |
+| 44 | `is_confirm` | int | 2 |
+| 45 | `member_discount_amount` | float | 0.0 |
+| 46 | `manual_discount_amount` | float | 0.0 |
+| 47 | `service_money` | float | 0.0 |
+| 48 | `person_org_id` | int | 2946266869336901 |
+| 49 | `last_use_time` | string | '2025-11-09 23:24:50' |
+| 50 | `salesman_name` | string | '' |
+| 51 | `salesman_user_id` | int | 0 |
+| 52 | `salesman_org_id` | int | 0 |
+| 53 | `coupon_deduct_money` | float | 0.0 |
+| 54 | `skill_id` | int | 2790683529513797 |
+| 55 | `start_use_time` | string | '2025-11-09 21:18:18' |
+| 56 | `tenant_member_id` | int | 0 |
+| 57 | `system_member_id` | int | 0 |
+| 58 | `skill_grade` | int | 0 |
+| 59 | `service_grade` | int | 0 |
+| 60 | `composite_grade` | float | 0.0 |
+| 61 | `sum_grade` | float | 0.0 |
+| 62 | `get_grade_times` | int | 0 |
+| 63 | `grade_status` | int | 1 |
+| 64 | `composite_grade_time` | string | '0001-01-01 00:00:00' |
+
+## 新增字段（相对本地 JSON 样本）
+
+以下字段在最新 API 响应中出现，但本地 JSON 样本中不存在：
+
+| 字段名 | 类型 |
+|--------|------|
+| `assistantTeamName` | string |
+| `real_service_money` | float |
+
+## 详细字段分析
+
+> 以下内容迁移自旧版 `assistant_service_records-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
+
+二、记录级字段完整清单与说明
+
+下面按逻辑分组来讲字段。数据类型和枚举值，是根据导出数据实际值推断出来的。
+
+1. 订单与关联 ID 类字段
+
+这些字段主要用来跟其他表做关联（订单、支付、会员、助教档案等）：
+
+id
+
+类型：int
+
+含义：本条助教流水记录的主键 ID（流水唯一标识）。
+
+作用：在系统内部唯一定位这一条助教服务记录。
+
+order_trade_no
+
+类型：int
+
+含义：订单交易号，整个订单层面的编号。
+
+关联：
+
+与台费流水、门店销售记录、团购套餐流水等表中的同名字段是一致的，用于把 同一笔订单下的各类消费明细（台费/商品/助教/套餐）串起来。
+
+order_settle_id
+
+类型：int
+
+含义：订单结算 ID，相当于“结账单号”的内部主键。
+
+关联：
+
+与小票详情中的 orderSettleId 对应。
+
+正常情况下也应对应结账记录表中的结算主键（本次导出结账记录为空，但字段设计明显就是用来关联的）。
+
+order_assistant_id
+
+类型：int
+
+含义：订单中“助教项目明细”的内部 ID。
+
+作用：如果订单里有多条助教项目（比如换助教、多个时间段），此字段唯一标识这一条助教明细。
+
+order_assistant_type
+
+类型：int，枚举。
+
+观测值：1 和 2。
+
+含义（推测）：
+
+1：常规助教服务（主课/基础课）。
+
+2：附加类助教服务（如“附加课”），和字段 skillName 的值相对应（本数据里，skillName 有 “基础课”和“附加课” 两类）。
+
+实际含义以系统内部配置为准，但可以确定是 助教服务类型枚举。
+
+order_pay_id
+
+类型：int
+
+含义：关联到“支付记录”的主键 ID。
+
+作用：可以和支付记录中的 id / relate_id 等字段对应，找到这条助教服务对应的支付流水。
+
+tenant_id
+
+类型：int
+
+含义：租户/品牌 ID；你这份数据中是固定值（同一个商户）。
+
+关联：全库所有表都有，作为“商户维度”的过滤键。
+
+site_id
+
+类型：int
+
+含义：门店 ID，本数据中指“朗朗桌球”这一家门店。
+
+关联：
+
+与其他所有 JSON 中的 site_id 一致，用于判断记录属于哪家门店。
+
+与内嵌的 siteProfile.id 一致。
+
+site_assistant_id
+
+类型：int
+
+含义：门店维度的助教 ID。
+
+关联：
+
+在 助教账号1/2.json 中，字段 id 就是这个 site_assistant_id。
+
+即：助教流水.site_assistant_id = 助教账号.id → 这是助教档案的外键。
+
+user_id
+
+类型：int
+
+含义：助教对应的“用户账号 ID”（系统级用户）。
+
+关联：
+
+在助教账号表中有同名字段 user_id，与这里完全一致。
+
+一般是登录账号的主键，区别于 site_assistant_id（岗位/角色 ID）。
+
+person_org_id
+
+类型：int
+
+含义：助教所属“人事组织/部门 ID”。
+
+关联：
+
+在助教账号表中同样存在 person_org_id 字段，值完全一致。
+
+用来做人员组织维度的归属，如“朗朗桌球-助教部”。
+
+assistant_team_id
+
+类型：int
+
+含义：助教所属团队 ID。
+
+特点：当前数据中所有记录都是同一个 team_id。
+
+关联：
+
+在助教账号表中有 team_id 字段，对应相同值。
+
+此字段常用于排班/团队统计。
+
+tenant_member_id
+
+类型：int
+
+含义：商户维度会员 ID（门店/品牌内的会员主键）。
+
+观测值：有不少为 0，表示非会员；非零时与会员档案中的 id 一致。
+
+关联：
+
+**会员档案（tenantMemberInfos）**中的 id = 此处的 tenant_member_id。
+
+用来联表查出对应会员的基本资料。
+
+system_member_id
+
+类型：int
+
+含义：系统级会员 ID（全集团统一 ID）。
+
+观测：大部分非 0 记录，对应会员档案中的 system_member_id。
+
+关联：
+
+会员档案中的 system_member_id 字段。
+
+说明：system_member_id 把一个会员在不同门店/不同卡种的账号串起来；tenant_member_id 则是本商户的那一条记录。
+
+skill_id
+
+类型：int
+
+含义：助教服务“课程/技能”ID。
+
+观测：当前数据中只有一个技能 ID（同一类“基础课/附加课”）。
+
+关联：应对应某个“课程/技能配置表”的主键（你这次导出里没见那个表）。
+
+2. 助教维度字段
+
+这些字段描述“是哪位助教、什么级别、属于哪个组”等：
+
+assistantNo
+
+类型：string
+
+含义：助教编号，例如 "27"。
+
+关联：在助教账号表里也有 assistant_no 字段，对应工号/编号。
+
+assistantName
+
+类型：string
+
+含义：助教姓名，如“何海婷”“胡敏”等。
+
+备注：和助教账号档案里的 real_name 一致。
+
+nickname
+
+类型：string
+
+含义：助教对外昵称，如“佳怡”“周周”“球球”等。
+
+说明：从数据看，这个 nickname 是“助教昵称”，不是顾客昵称（容易混淆）。
+
+关联：在很多小票、商品名里，会把 “编号-昵称” 组合使用（如 ledger_name = "2-佳怡"）。
+
+assistant_level
+
+类型：int，枚举。
+
+观测值与 levelName 对应关系（从数据中直接推出来）：
+
+8 → levelName = "助教管理"（管理角色）
+
+10 → "初级"
+
+20 → "中级"
+
+30 → "高级"
+
+说明：这是助教级别的数值编码，对应助教账号表中的 level 字段。
+
+levelName
+
+类型：string
+
+含义：助教等级名称，与 assistant_level 一一对应（初级/中级/高级/助教管理）。
+
+备注：属于展示用的冗余字段。
+
+assistant_team_id
+
+已在上一节说明（团队 ID）。
+
+skillName
+
+类型：string
+
+观测值："基础课" 或 "附加课"。
+
+含义：当前这条助教服务所对应的“课程/技能名称”。
+
+当 order_assistant_type = 1 时，多为“基础课”。
+
+当 order_assistant_type = 2 时，为“附加课”。
+
+skill_grade
+
+类型：int
+
+观测：全为 0。
+
+含义（推测）：顾客对“技能表现”的评分（整数或打分等级）。
+
+当前数据中还未产生评分记录，所以都是默认值 0。
+
+service_grade
+
+类型：int
+
+观测：全为 0。
+
+含义（推测）：顾客对“服务态度”的评分。
+
+composite_grade
+
+类型：float
+
+观测：全为 0.0。
+
+含义：综合评分（例如技能+服务加权后的平均分），当前数据没有实际评分。
+
+sum_grade
+
+类型：float
+
+观测：全为 0.0。
+
+含义：累计评分总和（可能用于计算平均分），当前为 0。
+
+get_grade_times
+
+类型：int
+
+观测：全为 0。
+
+含义：该条记录对应的评价次数（或该助教被评价次数快照）。
+
+grade_status
+
+类型：int，枚举。
+
+观测：全为 1。
+
+含义（推测）：评价状态，比如：
+
+1 = 未评价/正常；
+
+其他值可能表示“已评价”“屏蔽”等，当前数据没有别的值，具体含义需要系统配置表。
+
+composite_grade_time
+
+类型：string（时间）
+
+观测：全为 "0001-01-01 00:00:00"。
+
+含义（推测）：最近一次评价时间/综合评分更新时间。现在都是默认“无效时间”。
+
+3. 桌台 / 门店维度字段
+
+tableName
+
+类型：string
+
+含义：助教服务所在的球台名称（如 "A17"、"S1"）。
+
+关联：
+
+与台桌列表中的 table_name / table_no 对应（通过 site_table_id）。
+
+site_table_id
+
+类型：int
+
+含义：球台 ID。
+
+关联：
+
+对应台桌列表中的 id 字段，表示具体是哪一张桌。
+
+siteProfile
+
+类型：object
+
+含义：门店信息快照，包括 id、shop_name、address 等，和其他 JSON 里的 siteProfile 一致。
+
+作用：冗余门店信息，方便查看（而不是每次都联表看门店档案）。
+
+4. 时间 / 时长相关字段
+4.1 时间点（字符串时间）
+
+create_time
+
+类型：string，格式 YYYY-MM-DD HH:MM:SS
+
+含义：这条助教流水记录创建时间（一般接近结算/下单时间）。
+
+start_use_time
+
+类型：string
+
+含义：助教实际开始服务时间。
+
+特点：正常情况下与 ledger_start_time 相同。
+
+last_use_time
+
+类型：string
+
+含义：最后一次使用（实际服务）时间。
+
+特点：正常结束时与 ledger_end_time 相同；如果服务还未真正开始或立即结束，开始/结束时间可能相同。
+
+ledger_start_time
+
+类型：string
+
+含义：台账层面记录的开始时间。
+
+说明：与 start_use_time 在当前数据中完全一致，可以视为“计费起始时间”。
+
+ledger_end_time
+
+类型：string
+
+含义：台账层面的结束时间。
+
+说明：与 last_use_time 一致，可以视为“计费结束时间”。对于 real_use_seconds = 0 的记录，开始和结束时间相同，说明只是预约/录入，并未实际服务。
+
+4.2 时长（秒）
+
+这几个字段单位都是“秒”。
+
+income_seconds
+
+类型：int
+
+含义：计费秒数 / 应计收入对应的时间。
+
+特点：
+
+值基本是 60 的倍数（2700、3600、7200、10800 等），即按分钟整点计费的秒数。
+
+用这个字段配合 ledger_unit_price 计算应计金额（原价或折扣价）。
+
+real_use_seconds
+
+类型：int
+
+含义：实际使用时长（秒）。
+
+特点：
+
+大多数情况下，real_use_seconds ≈ ledger_count（有少量 ±1 秒差）。
+
+对于还没真正消费的记录，该值为 0，表示“已预约/已排钟但还没消耗”。
+
+ledger_count
+
+类型：int
+
+含义：台账记录的计时总秒数。
+
+特点：
+
+正常结束的记录中，与 real_use_seconds 基本一致。
+
+可以理解为“本条助教服务真正消耗的总时长（秒）”。
+
+add_clock
+
+类型：int（秒）
+
+观测值：多为 0，有少量为 240, 300, 420, 600, 900, 2400, 2700, 3600, 32400 等。
+
+含义（推测）：加钟秒数，即在原有预约/服务基础上临时追加的时长。
+
+说明：值均为 60 的倍数（分钟级加钟），如 600 秒=10 分钟。
+
+returns_clock
+
+类型：int（秒）
+
+观测：全部为 0。
+
+含义（推测）：退钟秒数（取消加钟或提前结束退回的时间）。
+
+当前数据里没有退钟场景，所以全为 0，但字段设计已经预留。
+
+5. 金额与折扣相关字段
+
+ledger_unit_price
+
+类型：float
+
+含义：助教服务 标准单价（通常是标价：每小时、每节课的单价）。
+
+特点：如 98.0、108.0、190.0 等。
+
+ledger_amount
+
+类型：float
+
+含义：按标准单价计算出来的应收金额（近似 = ledger_unit_price × income_seconds / 3600）。
+
+说明：从数据看，这个金额对应“按原价计费”的金额，未扣除各种优惠。
+
+projected_income
+
+类型：float
+
+含义：实际结算计入门店的金额（已经考虑折扣、卡权益、券等后的结果）。
+
+从数据：projected_income 明显低于 ledger_amount，说明中间有折扣，但折扣的明细并不全由下面几个字段体现（很多是卡权益内生折扣）。
+
+coupon_deduct_money
+
+类型：float
+
+观测值：大多数为 0.0，有少量记录为 195.73、431.1 等。
+
+含义：由“优惠券/代金券/团购券”等 直接抵扣到这条助教服务上的金额。
+
+说明：
+
+当 >0 时，表明这一条助教服务使用了券抵扣了这么多金额。
+
+与平台验券记录 / 团购套餐流水中的券相关字段联动。
+
+manual_discount_amount
+
+类型：float
+
+观测：全部为 0.0。
+
+含义：收银员手动给予的减免金额（人工改价）。
+
+当前导出时间段内暂未出现手动打折的情况。
+
+member_discount_amount
+
+类型：float
+
+观测：全部为 0.0。
+
+含义：由会员卡折扣产生的优惠金额。
+
+说明：尽管字段里是 0，但实际折扣可能已经体现在 projected_income 与 ledger_amount 的差额中，这里只是未单独拆出。
+
+service_money
+
+类型：float
+
+观测：全部为 0.0。
+
+含义（推测）：用于记录与助教结算的金额（平台预留的“成本/分成”字段）。
+
+当前数据中未启用这个机制，所以全为 0。
+
+6. 状态 / 标志字段
+
+ledger_status
+
+类型：int，枚举。
+
+观测：全部为 1。
+
+含义（推测）：助教流水记录状态：
+
+1：正常有效。
+
+其他值（例如 0、2）可能对应“未结算”“已作废”等，当前数据未出现。
+
+is_confirm
+
+类型：int，枚举。
+
+观测：全部为 2。
+
+含义（推测）：确认状态，例如：
+
+1：待确认；
+
+2：已确认 / 已完成。
+
+从全部为 2 推断：导出时选的是已经确认的流水。
+
+is_single_order
+
+类型：int，枚举。
+
+观测：全部为 1。
+
+含义（推测）：是否单独订单：
+
+1：本助教服务作为单独订单结算（或单独拆项）。
+
+0：与其他项目（台费、商品）一起打包在综合订单里。
+
+当前门店显然采用“助教单独结算”的模式，故全为 1。
+
+is_not_responding
+
+类型：int，枚举。
+
+观测：全为 0。
+
+含义（推测）：是否存在“爽约/未响应”情况：
+
+0：正常；
+
+1：有爽约等异常情况。
+
+当前时间段没有记录被标记为爽约。
+
+is_trash
+
+类型：int，枚举。
+
+观测：全为 0。
+
+含义：是否已废除/作废：
+
+0：正常有效；
+
+1：已废除（对应“助教废除.json”里的记录）。
+
+一旦为 1，一般会配合 trash_reason 等字段，并在“助教废除”表中有对应记录。
+
+is_delete
+
+类型：int，枚举。
+
+观测：全为 0。
+
+含义：逻辑删除标志。
+
+0：未删除；
+
+1：已删除（逻辑删除，历史保留）。
+
+和 is_trash 不同：is_trash 表示业务上的“废除”，is_delete 表示系统级删除。
+
+7. 会员/顾客维度（在本表中的影子）
+
+system_member_id / tenant_member_id
+
+已在“关联 ID 类字段”里说明：
+
+system_member_id 对应会员在整个系统的唯一 ID；
+
+tenant_member_id 对应当前租户中的会员 ID（会员档案的主键 id）。
+
+注意：这份助教流水里没有直接出现“顾客姓名”字段，只通过这两个 ID 与会员档案、储值卡等表关联。
+
+8. 员工 / 销售人员相关字段
+
+salesman_name
+
+类型：string
+
+含义：关联的“营业员/销售员姓名”，用于提成归属。
+
+观测：本数据中多数为空字符串，说明助教流水没有配置单独的营业员。
+
+salesman_user_id
+
+类型：int
+
+含义：营业员用户 ID。
+
+观测：多为 0，代表未指定。
+
+salesman_org_id
+
+类型：int
+
+含义：营业员所属组织/部门 ID。
+
+观测：多为 0。
+
+operator_id
+
+类型：int
+
+含义：操作员 ID（录入/结算这条助教服务的员工）。
+
+关联：可与员工/账号表对应（本次导出未单独给员工表，但其他 JSON 里多处出现该 ID）。
+
+operator_name
+
+类型：string
+
+含义：操作员姓名，与 operator_id 一起使用，便于直接阅读。
+
+user_id
+
+已在“关联 ID 类字段”说明：助教的系统用户 ID，与助教账号表中的 user_id 一致。
+
+person_org_id
+
+同样在上文说明：助教所属人事组织 ID。
+
+9. 作废 / 废除相关字段
+
+这几个字段在当前数据中值都为 0 或空串，但从命名可以看出专门用于记录“助教废除”的信息，与 助教废除.json 表配合使用。
+
+trash_applicant_id
+
+类型：int
+
+含义：提出废除申请的员工 ID（通常是操作员/管理员）。
+
+当前数据全为 0，因此短期内没有发生废除操作。
+
+trash_applicant_name
+
+类型：string
+
+含义：废除申请人姓名。
+
+trash_reason
+
+类型：string
+
+含义：废除原因（文本说明），例如“顾客取消”“录入错误”等。
+
+当前数据为空字符串，说明当前导出时间段没有被废除的助教流水记录。
+
+10. 其他字段
+
+ledger_group_name
+
+类型：string
+
+观测：全部为空字符串。
+
+含义（推测）：助教项目所属的“计费分组/套餐分组名称”，例如某种助教套餐或业务组名称。
+
+目前未被实际使用。
+
+三、助教流水与其它 JSON 的关键关系（从字段角度再强调一下）
+
+虽然你这次提问重点是字段本身，但从字段设计可以看出它在整个系统里的“位置”，这里简要点一下（不做数值分析）：
+
+与助教账号（助教账号1/2.json）
+
+site_assistant_id ↔ 助教账号表的 id
+
+user_id ↔ 助教账号表的 user_id
+
+assistant_team_id ↔ 助教账号表的 team_id
+
+person_org_id ↔ 助教账号表的 person_org_id
+
+assistant_level ↔ 助教账号表的 level
+
+说明：助教流水是“事实表”，助教账号是“维表”。
+
+与会员档案（会员档案.json）
+
+system_member_id ↔ 会员档案中的 system_member_id
+
+tenant_member_id ↔ 会员档案中的 id
+
+说明：通过这两个字段可以追溯到哪个会员预约/购买了这次助教服务。
+
+与台桌（台桌列表.json）
+
+site_table_id ↔ 台桌表中的 id
+
+tableName ↔ 台桌表中的 table_name/table_no
+
+说明：标记助教服务在哪张桌上进行。
+
+与订单/小票（小票详情.json / 结账记录.json）
+
+order_trade_no、order_settle_id 与其它消费明细（台费、商品、套餐流水）共享，构成一次订单下的不同子项目。
+
+小票详情中的 orderSettleId 与这里的 order_settle_id 对应。
+
+与支付/退款（支付记录.json / 退款记录.json）
+
+order_pay_id 对应支付记录中的 ID 或 relate_id。
+
+支付记录通过 relate_type 区分是订单支付还是其他业务（如充值）；这里的助教流水对应的是订单类支付。
+
+与助教废除（助教废除.json）
+
+当 is_trash = 1 时，对应的废除详情（原因、废除时间等）会记录在“助教废除.json”里。
+
+字段 trash_reason、trash_applicant_id/name 就是废除信息在当前流水记录中的快照。