初始提交：飞球 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_cancellation_records.md
+++ b/docs/api-reference/assistant_cancellation_records.md
@@ -0,0 +1,194 @@
+# 助教撤销记录 — GetAbolitionAssistant
+
+> 模块：`AssistantPerformance` · ODS 表：`assistant_cancellation_records` · 事件表（增量）
+
+---
+
+## 一、接口概述
+
+查询门店下助教服务被撤销（废除）的记录。每条记录对应一次"助教排钟后被取消"的事件，包含台桌、助教、已计费时长、废除金额等信息。本表是助教流水的配套事件表，专门记录废除操作的明细，用于运营审计和对账。
+
+| 属性 | 值 |
+|------|-----|
+| 完整路径 | `POST /AssistantPerformance/GetAbolitionAssistant` |
+| 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 | 是 | 查询起始时间，格式 `YYYY-MM-DD HH:MM:SS` |
+| `endTime` | string | 是 | 查询结束时间，格式 `YYYY-MM-DD HH:MM:SS` |
+| `siteId` | int | 是 | 门店 ID |
+| `page` | int | 是 | 页码，从 1 开始 |
+| `limit` | int | 是 | 每页条数，最大 100 |
+
+---
+
+## 三、响应结构
+
+```
+{
+  "code": 200,
+  "data": {
+    "list": [ { ... }, { ... } ],
+    "total": 15
+  }
+}
+```
+
+`data.list` 中每个对象即为一条助教撤销记录，共 13 个字段，按逻辑分组说明如下。
+
+---
+
+## 四、响应字段详解（13 个字段）
+
+### 4.1 主键与门店
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `id` | int | `2957675849518789` | 撤销记录主键 ID，唯一标识一条废除事件 |
+| `siteId` | int | `2790685415443269` | 门店 ID，与 `siteProfile.id` 一致 |
+| `siteProfile` | object | `{...}` | 门店信息快照（冗余），包含门店名称、地址、经纬度等 26 个子字段。结构与其他接口的 `siteProfile` 完全一致，此处为空壳式冗余，不再逐字段展开 |
+
+### 4.2 台桌维度
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `tableId` | int | `2793016660660357` | 台桌 ID，对应台桌配置表的主键。标识废除发生在哪张台 |
+| `tableName` | string | `"C1"` | 台桌名称/编号，冗余展示字段。常见值如 `"C1"`、`"B9"`、`"VIP1"`、`"A4"`、`"666"`、`"董事办"` 等 |
+| `tableAreaId` | int | `2791963816579205` | 台桌所在区域 ID，对应区域配置表主键 |
+| `tableArea` | string | `"C区"` | 台桌所属区域名称。已知值：`"A区"`、`"B区"`、`"C区"`、`"VIP包厢"`、`"K包"`、`"补时长"`、`"666"` |
+
+### 4.3 助教维度
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `assistantOn` | string | `"27"` | 助教编号（工号），虽为字符串类型但内容为纯数字。对应助教账号表的 `assistant_no`、助教流水的 `assistantNo` |
+| `assistantName` | string | `"泡芙"` | 助教姓名/昵称，冗余展示字段。对应助教账号表的 `nickname` / `real_name` |
+
+### 4.4 时间与时长
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `createTime` | string | `"2025-11-09 19:23:29"` | 废除记录创建时间，即系统记录废除操作的时刻。格式 `YYYY-MM-DD HH:MM:SS` |
+| `pdChargeMinutes` | int | `214` | 废除前已累计的计费时长，单位为**分钟**。`0` 表示刚排钟即撤销，尚未产生有效计费时间。注意：助教流水中类似字段（`real_use_seconds`）单位为秒 |
+
+### 4.5 金额与原因
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `assistantAbolishAmount` | float | `5.83` | 助教废除金额（元/人民币），本次废除操作对应的金额数值。`0.0` 表示纯记录操作，未产生金额变动 |
+| `trashReason` | string | `""` | 废除原因，自由文本字段。当前数据中全部为空字符串，说明系统允许不填原因。预留用于记录如"顾客临时取消""录入错误""更换助教"等说明 |
+
+---
+
+## 五、响应样例（单条记录）
+
+```json
+{
+  "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,
+    "attendance_distance": 0,
+    "wifi_name": "",
+    "wifi_password": "",
+    "customer_service_qrcode": "",
+    "customer_service_wechat": "",
+    "fixed_pay_qrCode": "",
+    "prod_env": 1,
+    "light_status": 1,
+    "light_type": 0,
+    "site_type": 1,
+    "light_token": "",
+    "site_label": "A",
+    "attendance_enabled": 1,
+    "shop_status": 1
+  },
+  "createTime": "2025-11-09 19:23:29",
+  "id": 2957675849518789,
+  "siteId": 2790685415443269,
+  "tableAreaId": 2791963816579205,
+  "tableId": 2793016660660357,
+  "tableArea": "C区",
+  "tableName": "C1",
+  "assistantOn": "27",
+  "assistantName": "泡芙",
+  "pdChargeMinutes": 214,
+  "assistantAbolishAmount": 5.83,
+  "trashReason": ""
+}
+```
+
+---
+
+## 六、跨表关联
+
+### 与助教流水（`assistant_service_records`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `assistantOn` | `assistantNo` | 助教编号 |
+| `assistantName` | `assistantName` | 助教姓名 |
+| `siteId` | `site_id` | 门店 ID |
+| `tableId` | `site_table_id` | 台桌 ID |
+
+> 本表**没有** `order_trade_no` 等硬外键字段，无法直接关联到具体哪条助教流水。需通过"门店 + 助教 + 台桌 + 相近时间"的组合条件做软匹配。助教流水中的 `is_trash` 字段从主流水视角标记"已废除"状态，本表则以"废除事件"为主视角记录明细。
+
+### 与助教账号（`assistant_accounts_master`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `assistantOn` | `assistant_no` | 助教工号 |
+| `assistantName` | `nickname` / `real_name` | 助教姓名 |
+
+### 与台桌配置
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `tableId` | 台桌列表 `id` | 台桌主键 |
+| `tableName` | 台桌列表 `table_name` | 台桌名称 |
+| `tableAreaId` | 区域配置表主键 | 台桌区域 ID |
+| `tableArea` | 区域配置表 `area_name` | 区域名称 |
+
+### 与门店维度
+
+`siteId` 与所有业务表的 `site_id` 一致，共享门店维度。`siteProfile` 为冗余快照。
+
+<!--
+AI_CHANGELOG:
+- 日期: 2026-02-13
+- Prompt: P20260213-183000 — 使用子代理并行处理剩余 API 文档重构
+- 直接原因: 按标杆文档格式重写高质量 API 参考文档
+- 变更摘要: 新建 docs/api-reference/assistant_cancellation_records.md，按逻辑分组详解所有字段，含跨表关联
+- 风险与验证: 纯文档，无运行时影响；验证方式：对比 endpoints/ 和 samples/ 确认字段覆盖完整
+-->