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

2026-02-13 08:05:34 +08:00
commit 3c51f5485d
441 changed files with 117631 additions and 0 deletions
--- a/docs/api-reference/endpoints/assistant_cancellation_records.md
+++ b/docs/api-reference/endpoints/assistant_cancellation_records.md
@@ -0,0 +1,444 @@
+# 助教撤销记录（GetAbolitionAssistant）
+
+> 自动生成于 2026-02-13 | 数据来源：本地 JSON 样本
+
+## 基本信息
+
+| 属性 | 值 |
+|------|-----|
+| 接口路径 | `AssistantPerformance/GetAbolitionAssistant` |
+| 完整 URL | `https://pc.ficoo.vip/apiprod/admin/v1/AssistantPerformance/GetAbolitionAssistant` |
+| 请求方法 | `POST` |
+| Content-Type | `application/json` |
+| 鉴权方式 | Bearer Token（`Authorization` 头） |
+| ODS 对应表 | `assistant_cancellation_records` |
+| 分页方式 | `page` + `limit`（最大 100） |
+| 时间范围 | 需要（startTime / endTime） |
+
+## 请求参数
+
+| 参数名 | 类型 | 示例值 | 说明 |
+|--------|------|--------|------|
+| `startTime` | string | `"2026-02-01 08:00:00"` | 查询起始时间 |
+| `endTime` | string | `"2026-02-13 08:00:00"` | 查询结束时间 |
+| `siteId` | int | `2790685415443269` | 门店 ID |
+| `page` | int | `1` | 页码（从 1 开始） |
+| `limit` | int | `100` | 每页条数（最大 100） |
+
+## 响应字段（共 13 个）
+
+| # | 字段名 | 类型 | 示例值 |
+|---|--------|------|--------|
+| 1 | `siteProfile` | object | {'id': 2790685415443269, 'org_id': 2790684179467077, 'sho... |
+| 2 | `createTime` | string | '2025-11-09 19:23:29' |
+| 3 | `id` | int | 2957675849518789 |
+| 4 | `siteId` | int | 2790685415443269 |
+| 5 | `tableAreaId` | int | 2791963816579205 |
+| 6 | `tableId` | int | 2793016660660357 |
+| 7 | `tableArea` | string | 'C区' |
+| 8 | `tableName` | string | 'C1' |
+| 9 | `assistantOn` | string | '27' |
+| 10 | `assistantName` | string | '泡芙' |
+| 11 | `pdChargeMinutes` | int | 214 |
+| 12 | `assistantAbolishAmount` | float | 5.83 |
+| 13 | `trashReason` | string | '' |
+
+## 详细字段分析
+
+> 以下内容迁移自旧版 `assistant_cancellation_records-Analysis.md`，包含字段的业务含义、枚举值、跨表关联等详细说明。
+
+1. 门店相关字段
+1.1 siteProfile
+
+类型：对象（Object）
+
+含义：门店信息快照。
+
+结构：包含以下子字段（26 个左右）：
+
+id：门店 ID（与其他 JSON 中的 site_id 一致）。
+
+org_id：组织 ID（总部/品牌组织）。
+
+shop_name：店名，如“朗朗桌球”。
+
+avatar：门店头像图片 URL。
+
+business_tel：门店电话。
+
+full_address：详细地址。
+
+address：简化地址描述。
+
+longitude / latitude：经纬度。
+
+tenant_site_region_id：区域行政编码。
+
+tenant_id：租户 ID（品牌商户 ID）。
+
+auto_light：是否自动控灯（0/1 枚举）。
+
+attendance_distance：考勤打卡范围。
+
+wifi_name / wifi_password：WiFi 账号和密码。
+
+customer_service_qrcode / customer_service_wechat：客服二维码、微信号。
+
+fixed_pay_qrCode：固定收款码。
+
+prod_env：环境标记（测试/生产等）。
+
+light_status / light_type / light_token：灯控相关配置。
+
+site_type：门店类型枚举。
+
+site_label：门店标签（如“A”）。
+
+attendance_enabled：是否启用考勤（0/1）。
+
+shop_status：门店状态（1=营业等）。
+
+特点：
+
+与其他 JSON 中的 siteProfile 完全同构，是冗余的门店信息快照。
+
+真正的主键是 siteProfile.id，且与同记录的 siteId 一致。
+
+1.2 siteId
+
+类型：整数（long）
+
+观测：所有记录均为同一值 2790685415443269。
+
+含义：门店 ID，即该废除记录所在门店。
+
+关联：
+
+与 siteProfile.id 一致。
+
+与其他 JSON 中所有 site_id 字段相同（同一门店的数据）。
+
+2. 台桌维度字段
+
+这几个字段描述废除发生在哪张桌、哪个区域。
+
+2.1 tableId
+
+类型：整数（long）
+
+含义：球台/桌子的 ID。
+
+关联：
+
+对应 “台桌列表.json” 中的 id 字段。
+
+用于定位具体哪一张台桌上发生了助教废除。
+
+2.2 tableName
+
+类型：字符串（string）
+
+示例值：
+
+"C1", "C2", "B9", "VIP1", "A4", "666", "董事办", "补时长5", "Ｍ1" 等。
+
+含义：台桌名称/编号，供人阅读。
+
+关系：
+
+与台桌列表中的 table_name 或 table_no 文本一致。
+
+作为冗余字段存在，即使不联表也能看出是哪个桌。
+
+2.3 tableAreaId
+
+类型：整数（long）
+
+示例：2791963816579205 等。
+
+含义：台桌所在区域 ID。
+
+关联：
+
+应对应“区域配置表”的主键（本次导出未包含该表）。
+
+与其他 JSON 中出现的 tableAreaId（比如台费流水、助教流水里的区域字段）是一致的。
+
+2.4 tableArea
+
+类型：字符串（string）
+
+示例值：
+
+"C区", "B区", "A区", "VIP包厢", "K包", "补时长", "666"。
+
+含义：台桌所属区域名称。
+
+说明：
+
+用于展示和报表分区。
+
+与 tableAreaId 一起从“区域维表”中可以查出区域层级信息（本次数据未导出该表）。
+
+3. 助教维度字段
+
+反映是哪一个助教被废除。
+
+3.1 assistantOn
+
+类型：字符串（string）
+
+观测值（本次 15 条记录中）：
+
+'2', '4', '9', '16', '23', '27', '52', '15', '99'
+
+含义：助教编号（工号/序号）。
+
+说明：
+
+虽然是字符串，但内容上是纯数字，实际是编号，不是业务金额。
+
+与 助教流水.json 中的 assistantNo 字段是一致的。
+
+与“助教账号1/2.json” 中的 assistant_no 字段相同，用于识别哪位助教。
+
+枚举性质：
+
+在当前门店范围内，assistantOn 实际上是枚举集合（有限个编号）。
+
+具体编号-姓名的映射关系在“助教账号”表中定义，不在本文件中。
+
+3.2 assistantName
+
+类型：字符串（string）
+
+观测值（本次 15 条中）：
+
+'佳怡'、'璇子'、'周周'、'球球'、'泡芙'、'婉婉'、'小柔'、'七七'、'Amy'
+
+含义：助教姓名/对外展示名称。
+
+关系：
+
+与“助教账号”档案中的 real_name / nickname 对应。
+
+与 助教流水.json 里的 assistantName 字段一致。
+
+注意：
+
+这是被废除的那位助教，不是顾客姓名。
+
+4. 时间与时长字段
+4.1 createTime
+
+类型：字符串（string），格式 YYYY-MM-DD HH:MM:SS
+
+示例："2025-11-09 19:23:29"
+
+含义：这条“助教废除记录”被创建的时间，即系统正式记录“废除”操作的时刻。
+
+与其他时间字段关系：
+
+在 助教流水.json 里有 create_time / ledger_start_time / ledger_end_time 等，本字段通常会落在这些时间点之后，表示在某次服务计时过程后发生了废除操作。
+
+数据特征：
+
+所有记录都有非空时间，精确到秒。
+
+4.2 pdChargeMinutes
+
+类型：整数（int）
+
+示例值：214, 10800, 3602, 3600, 2379, 14400, 10605, 10608, 10611, 0 等。
+
+含义（结构层面）：
+
+“已发生的计费时长（分钟）”，即这次助教服务在被废除前已经累计了多少分钟。
+
+特点：
+
+单位是“分钟”，不是秒。
+
+绝大部分是较大的整数（如 10800 分钟这样的数字，显然系统里有异常/默认值，具体业务含义要结合上下文看，这里只从字段命名和类型说明）。
+
+也有 0 的情况，表示发生废除时尚未有有效计费时间产生（例如刚排钟就撤销）。
+
+与其他字段的关系（结构层面推断，不做业务结论）：
+
+这类字段很可能用于后续计算“应退时长”或“扣费时长”。
+
+对应 助教流水 里关于 real_use_seconds、income_seconds 的记录，可用来判断“废除时已经消耗了多少时间”。
+
+5. 金额字段
+5.1 assistantAbolishAmount
+
+类型：浮点数（float）
+
+示例值：
+
+5.83, 570.0, 108.06, 190.0, 71.37, 392.0, 465.44, 318.24, 318.33, 以及 0.0。
+
+含义（结构层面）：
+
+与“助教废除”关联的金额字段。字面上是“助教废除金额”。
+
+可以理解为本次废除操作对应的一笔金额数值（是扣除、退还、补差，由业务规则决定，这里不做盈利/收益分析）。
+
+特点：
+
+为浮点数，单位为元。
+
+存在 0 值，表示这条废除记录没有产生额外金额变动（纯记录操作）。
+
+可能的用途（从字段角色角度，而不是结论）：
+
+后续在账务模块中，可以用 assistantAbolishAmount 这类字段与其他表（如退款记录、余额变更记录）进行金额对账和逻辑匹配。
+
+6. 废除原因字段
+6.1 trashReason
+
+类型：字符串（string）
+
+当前数据观测：所有 15 条记录都是空字符串 ""。
+
+含义：
+
+用于记录“废除原因”的文本描述，例如“顾客临时有事取消”“录入错误”“更换助教”等。
+
+特点：
+
+可为空字符串，说明系统允许不填原因。
+
+从结构上看，这是一个自由文本字段，不是枚举，不会做严格约束。
+
+与其他字段的关系：
+
+当配合 is_trash（在 助教流水.json 中）使用时，trashReason 可以为那条流水提供“为什么被废除”的说明。
+
+本表专门记录“废除事件”的列表，因此 trashReason 是这张表记录的重要附加信息。
+
+三、字段之间的结构关系与外部关联
+
+虽然本文件字段不多，但从字段设计可以看出它在整个系统中的位置。这里只从“字段结构”和“关联键”的角度说明，不做业务/盈利分析。
+
+1. 与门店表 / 全局维度的关系
+
+siteId 与 siteProfile.id 一致，且与其他 JSON 中的 site_id 一致。
+
+说明：这是典型的“门店维度外键 + 冗余快照”设计：
+
+siteId 作为外键；
+
+siteProfile 作为冗余快照，方便直接展示店名、地址等。
+
+2. 与台桌列表（台桌列表.json）的关系
+
+对应关系：
+
+tableId ↔ 台桌列表中的 id
+
+tableName ↔ 台桌列表中的 table_name / table_no
+
+tableAreaId ↔ 台桌列表中的 area_id（通过区域表可以进一步找到区域名称）
+
+tableArea ↔ 台桌列表中的 area_name
+
+结论（结构层面）：
+
+助教废除.json 中关于桌台的四个字段，是对“台桌维度”信息的引用 + 冗余快照。
+
+当用 tableId 去联查台桌列表时，可以获取更多静态信息（如台费设置、是否可预约等），本文件只保留了最基础的桌号和区域。
+
+3. 与助教档案 / 助教流水的关系
+
+对助教的标识字段：
+
+assistantOn ↔ 助教流水中的 assistantNo ↔ 助教账号中的 assistant_no
+
+assistantName ↔ 助教流水中的 assistantName ↔ 助教账号中的姓名字段
+
+结构上的含义：
+
+助教废除.json 可以看作是“助教服务流水”的一个特殊子集：只记录被废除的部分。
+
+在 助教流水.json 中，存在字段 is_trash、trash_reason 等，它们从主流水视角记录“此条流水已经被废除”这一状态。
+
+在 助教废除.json 中，則以“废除事件”为主视角，列出每一次废除操作的明细（在哪张桌、哪个助教、多少分钟、金额多少）。
+
+需要注意的结构事实：
+
+助教废除.json 里 没有 订单号类字段（例如 order_trade_no、order_assistant_id），因此如果要从“废除事件”反查到具体哪一条助教流水，目前只能通过组合条件关联，例如：
+
+相同门店 siteId；
+
+相同助教 assistantOn + assistantName；
+
+相同台桌 tableId / tableName；
+
+相近时间（createTime 对应助教流水的 create_time/ledger_end_time 附近）。
+
+这说明系统在设计时，把“废除事件”作为独立表存储，但没有在导出中包含可直接联表的订单 ID。结构上就导致“硬外键”缺失，只能做“软匹配”。
+
+4. 与资金/账户类表的潜在关系（结构层面）
+
+关键金额字段：
+
+assistantAbolishAmount 是本表唯一金额字段。
+
+结合字段命名和位置，可以推断结构关系：
+
+如果废除操作产生金额变动（例如退还部分费用或扣除违约金），那么在：
+
+退款记录.json 中可能有对应一笔退款记录；
+
+余额变更记录.json 中可能有对应一条会员卡余额变动（若退到卡里）。
+
+这些表中不会直接有 assistantAbolishAmount 字段，但会有金额字段 + 关联 ID，结构上可能通过金额和时间进行逻辑匹配。
+
+需要强调：
+
+这里只指出“这个字段在系统里承担的是一个‘金额变量’的角色”，不做盈利/损益层面的任何分析或结论。
+
+四、本表本身暴露出的结构性线索
+
+清晰的单一职责
+助教废除.json 不包含订单号、支付信息、会员信息等字段，只保留：
+
+门店/桌台维度；
+
+助教维度；
+
+时间、分钟数；
+
+一个金额字段；
+
+文本原因字段。
+说明这个表的设计就是“专门记录助教废除事件”的事件表，倾向于作为运营日志或审计用途，而不是主结算表。
+
+软外键的设计取向
+
+没有 order_trade_no、order_settle_id 等硬外键字段。
+
+需要通过“时间 + 助教 + 桌台”的组合条件与 助教流水、订单/结算 进行软关联。
+
+在迁移或对接新系统时，如果希望建立强外键，建议在新结构中给废除表补充 order_assistant_id 或 order_trade_no 之类的字段，以便直接关联。
+
+分钟与秒的混用
+
+pdChargeMinutes 单位是“分钟”；
+
+在 助教流水.json 中，同类字段如 income_seconds / real_use_seconds 是“秒”。
+结构层面说明：系统在不同接口/表中用了不同的时间单位。
+在做结构统一或数据建模时，最好统一为一个单位（全部转为秒或全部转为分钟），否则容易出现比较/汇总混乱。
+
+废除原因文本未被使用但结构预留完备
+
+当前 15 条记录中，trashReason 全部为空，说明实际运营中并没有强制填写原因。
+
+但结构上预留了这个字段，将来如果要做“废除原因统计”或“内部稽核”，无需修改结构，只要要求前台填写即可。
+
+数量很少但字段完整
+
+当前总记录数只有 15 条，但已经有完整的门店、桌台、助教、时长、金额、原因字段。
+
+说明设计不是临时补的，而是参照完整流水表（助教流水）设计的一张配套表，只是当前时间范围内“废除事件”确实不多。