初始提交：飞球 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_accounts_master.md
+++ b/docs/api-reference/assistant_accounts_master.md
@@ -0,0 +1,281 @@
+# 助教账号主数据 — SearchAssistantInfo
+
+> 模块：`PersonnelManagement` · ODS 表：`assistant_accounts_master` · 维度表（快照）
+
+---
+
+## 一、接口概述
+
+查询门店下所有助教账号的基础信息，包括人事档案、等级配置、薪资开关、在线状态等。每条记录对应一名助教账号，是典型的维度表，与助教流水等事实表通过 `id` / `user_id` / `team_id` 关联。
+
+| 属性 | 值 |
+|------|-----|
+| 完整路径 | `POST /PersonnelManagement/SearchAssistantInfo` |
+| Base URL | `https://pc.ficoo.vip/apiprod/admin/v1/` |
+| 鉴权 | `Authorization: Bearer <token>` |
+| 分页 | `page` + `limit`（最大 100） |
+| 时间范围 | 不需要（全量快照） |
+
+---
+
+## 二、请求
+
+### 请求体（JSON）
+
+```json
+{
+  "workStatusEnum": 0,
+  "dingTalkSynced": 0,
+  "leaveId": 0,
+  "criticismStatus": 0,
+  "signStatus": -1,
+  "page": 1,
+  "limit": 100
+}
+```
+
+### 参数说明
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `workStatusEnum` | int | 是 | 工作状态筛选。`0` = 全部，`1` = 在岗，`2` = 离岗 |
+| `dingTalkSynced` | int | 是 | 钉钉同步状态筛选。`0` = 全部，`1` = 已同步 |
+| `leaveId` | int | 是 | 离职状态筛选。`0` = 全部，`1` = 已离职 |
+| `criticismStatus` | int | 是 | 投诉状态筛选。`0` = 全部，`1` = 正常，`2` = 有投诉 |
+| `signStatus` | int | 是 | 合同签署状态筛选。`-1` = 全部，`0` = 未签署 |
+| `page` | int | 是 | 页码，从 1 开始 |
+| `limit` | int | 是 | 每页条数，最大 100 |
+
+---
+
+## 三、响应结构
+
+```
+{
+  "code": 200,
+  "data": {
+    "list": [ { ... }, { ... } ],
+    "total": 50
+  }
+}
+```
+
+`data.list` 中每个对象即为一条助教记录，共 61 个字段，按逻辑分组说明如下。
+
+---
+
+## 四、响应字段详解（61 个字段）
+
+### 4.1 主键与账号身份
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `id` | int | `2947562271297029` | 助教账号主键 ID。所有助教相关事实表（助教流水、排班等）通过此 ID 关联。在助教流水中对应 `site_assistant_id` |
+| `user_id` | int | `2947562270838277` | 系统级用户账号 ID，对应登录账号。用于统一人员在不同角色/模块下的身份，区别于岗位级的 `id`。在助教流水中有同名字段 |
+| `assistant_no` | string | `"31"` | 助教工号/编号，便于业务侧识别。编号不唯一（不同助教可能重复）。在助教流水中对应 `assistantNo` |
+| `job_num` | string | `""` | 备用工号字段，当前门店未启用，全部为空字符串 |
+| `serial_number` | int | `0` | 系统内部序列号/排序标识，部分为 0，部分为较大整数（如 2738），用于全局排序或数据迁移 |
+| `system_role_id` | int | `10` | 系统角色 ID，标识该账号在系统中的角色类型 |
+
+### 4.2 个人基础信息
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `real_name` | string | `"张静然"` | 助教真实姓名。在助教流水中对应 `assistantName` |
+| `nickname` | string | `"小然"` | 前台展示昵称，用于顾客侧展示，与真实姓名区分。在助教流水中有同名字段 |
+| `gender` | int | `0` | 性别枚举：`0` = 未填/保密，`1` = 男，`2` = 女 |
+| `birth_date` | string | `"0001-01-01 00:00:00"` | 出生日期。`0001-01-01` 为默认无效日期（未填写），少量为真实日期 |
+| `mobile` | string | `"15119679931"` | 手机号（11 位），用于登录绑定、通知、钉钉同步。每个账号基本唯一 |
+| `avatar` | string | `"https://oss.ficoo.vip/...defaultAvatar.png"` | 头像 URL。大量为默认头像，少量为自定义头像 |
+| `introduce` | string | `""` | 个人简介文案，预留字段，当前全部为空 |
+| `video_introduction_url` | string | `""` | 个人视频介绍 URL（OSS 存储），绝大多数为空，极少数有值 |
+| `height` | float | `0.0` | 身高（厘米）。`0` 表示未填写，有值时如 163.0、170.0 |
+| `weight` | float | `0.0` | 体重（公斤）。`0` 表示未填写，有值时如 55.0、90.0 |
+
+### 4.3 组织、团队与门店
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `tenant_id` | int | `2790683160709957` | 品牌/租户 ID，所有记录相同。多门店场景下用于区分不同商户 |
+| `site_id` | int | `2790685415443269` | 门店 ID，所有记录相同。与其他业务表（台费流水、库存等）的 `site_id` 一致 |
+| `shop_name` | string | `"朗朗桌球"` | 门店名称，冗余展示字段 |
+| `team_id` | int | `2792011585884037` | 助教所属团队 ID。在助教流水中对应 `assistant_team_id` |
+| `team_name` | string | `"1组"` | 团队名称，展示用，与 `team_id` 一一对应 |
+| `group_id` | int | `0` | 上层分组 ID（集团/事业部），预留字段，当前门店未使用 |
+| `group_name` | string | `""` | `group_id` 对应名称，当前为空 |
+| `person_org_id` | int | `2947562271215109` | 人事组织 ID，表示"门店-助教部-小组"等层级。每条记录不同。在助教流水中有同名字段。用于人力组织维度统计和权限控制 |
+| `staff_id` | int | `0` | 人事系统员工 ID，预留字段，当前未接入外部 HR 系统 |
+| `staff_profile_id` | int | `0` | 人事档案 ID，预留字段，当前未启用 |
+
+### 4.4 等级、计费与薪资
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `level` | int | `20` | 助教等级枚举：`8` = 助教管理/管理员，`10` = 初级，`20` = 中级，`30` = 高级，`40` = 资深/专家。在助教流水中以 `assistant_level` + `levelName` 体现 |
+| `charge_way` | int | `2` | 计费方式枚举：`2` = 计时收费（当前门店），其他值（1、3）可能对应按局、按课时 |
+| `pd_unit_price` | float | `0.0` | 普通时段单价，当前未在账号层面配置（实际单价在助教商品/套餐配置中） |
+| `cx_unit_price` | float | `0.0` | 促销时段单价，当前未在账号层面配置 |
+| `allow_cx` | int | `1` | 是否允许参与促销计费：`1` = 允许，其他值 = 不允许 |
+| `is_guaranteed` | int | `1` | 是否配置保底薪酬/保底时长：`1` = 有保底规则 |
+| `salary_grant_enabled` | int | `2` | 薪资发放配置开关。`2` 为当前门店统一值，具体含义需参照系统配置 |
+| `assistant_grade` | float | `0.0` | 助教综合评分（平均分快照），当前未启用评分功能 |
+| `sum_grade` | float | `0.0` | 评分总和，用于计算平均分（`assistant_grade = sum_grade / get_grade_times`） |
+| `get_grade_times` | int | `0` | 累计被评分次数，当前为 0 |
+
+### 4.5 入职、离职与合同签署
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `entry_time` | string | `"2025-11-02 08:00:00"` | 入职时间 |
+| `resign_time` | string | `"2025-11-03 08:00:00"` | 离职日期。在职员工使用远未来日期（如 `2225-xx-xx`）作为占位，已离职员工为真实日期 |
+| `entry_type` | int | `1` | 入职类型：`1` = 正式入职，其他值可能表示实习/兼职（当前未出现） |
+| `entry_sign_status` | int | `0` | 入职协议签署状态：`0` = 未签署（当前未启用电子签功能） |
+| `resign_sign_status` | int | `0` | 离职协议签署状态：`0` = 未签署 |
+| `leave_status` | int | `1` | 离职状态：`0` = 在职（`resign_time` 为远未来占位），`1` = 已离职（`resign_time` 为真实日期） |
+| `work_status` | int | `2` | 工作状态：`1` = 在岗/可排班（`leave_status=0` 时），`2` = 离岗/停止安排（`leave_status=1` 时） |
+
+### 4.6 账号启用、展示与在线状态
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `assistant_status` | int | `1` | 账号启用状态：`1` = 启用，`2` = 停用/冻结（可能未离职但账号被禁用） |
+| `show_status` | int | `1` | 前台展示状态：`1` = 在助教选择界面展示 |
+| `show_sort` | int | `31` | 前台展示排序权重，数值越小排序越靠前，与 `assistant_no` 有一定对应关系 |
+| `online_status` | int | `1` | 在线状态：`1` = 在线 |
+| `is_delete` | int | `0` | 逻辑删除标记：`0` = 未删除，`1` = 已逻辑删除（数据保留，前台不可见） |
+
+### 4.7 评价与投诉
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `criticism_status` | int | `1` | 投诉/差评状态：`1` = 正常/无投诉，`2` = 有投诉记录 |
+
+> `assistant_grade` / `sum_grade` / `get_grade_times` 见 4.4 节。当前全部为 0，表示该门店尚未产生助教评价数据。
+
+### 4.8 时间元数据与最近服务
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `create_time` | string | `"2025-11-02 15:55:26"` | 账号创建时间 |
+| `update_time` | string | `"2025-11-03 18:32:07"` | 账号最近修改时间（如修改等级、昵称等） |
+| `start_time` | string | `"2025-11-01 08:00:00"` | 当前配置生效开始日期（周期性排班/合同周期），多为整月开始 |
+| `end_time` | string | `"2025-12-01 08:00:00"` | 当前配置生效结束日期 |
+| `last_table_id` | int | `0` | 最近一次服务的球台 ID，`0` 表示无记录 |
+| `last_table_name` | string | `""` | 最近服务球台名称（展示用），如 `"TV"`、`"888"` |
+| `last_update_name` | string | — | 最近修改该账号配置的管理员名称，如 `"助教管理员:黄月柳"` |
+| `order_trade_no` | int | `0` | 最近一次关联的订单号，`0` 表示无记录。仅为"影子值"，真正的订单明细在订单表中 |
+
+### 4.9 系统集成（钉钉 / 灯控）
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `ding_talk_synced` | int | `1` | 是否已同步至钉钉：`1` = 已同步 |
+| `site_light_cfg_id` | int | `0` | 门店灯控配置 ID，当前门店未在助教维度启用 |
+| `light_equipment_id` | string | `""` | 灯控设备 ID，用于"助教开台自动控灯"场景，当前未启用 |
+| `light_status` | int | `2` | 灯光控制状态：`2` = 不启用（预留字段） |
+
+### 4.10 其他标志
+
+| 字段 | 类型 | 示例 | 说明 |
+|------|------|------|------|
+| `is_team_leader` | int | `0` | 是否为团队长/组长：`0` = 普通助教，`1` = 团队长（当前门店未指定） |
+
+---
+
+## 五、响应样例（单条记录）
+
+```json
+{
+  "id": 2947562271297029,
+  "user_id": 2947562270838277,
+  "assistant_no": "31",
+  "job_num": "",
+  "serial_number": 0,
+  "system_role_id": 10,
+  "real_name": "张静然",
+  "nickname": "小然",
+  "gender": 0,
+  "birth_date": "0001-01-01 00:00:00",
+  "mobile": "15119679931",
+  "avatar": "https://oss.ficoo.vip/maUiImages/images/defaultAvatar.png",
+  "introduce": "",
+  "video_introduction_url": "",
+  "height": 0.0,
+  "weight": 0.0,
+  "tenant_id": 2790683160709957,
+  "site_id": 2790685415443269,
+  "shop_name": "朗朗桌球",
+  "team_id": 2792011585884037,
+  "team_name": "1组",
+  "group_id": 0,
+  "group_name": "",
+  "person_org_id": 2947562271215109,
+  "staff_id": 0,
+  "staff_profile_id": 0,
+  "level": 20,
+  "charge_way": 2,
+  "pd_unit_price": 0.0,
+  "cx_unit_price": 0.0,
+  "allow_cx": 1,
+  "is_guaranteed": 1,
+  "salary_grant_enabled": 2,
+  "assistant_grade": 0.0,
+  "sum_grade": 0.0,
+  "get_grade_times": 0,
+  "entry_time": "2025-11-02 08:00:00",
+  "resign_time": "2025-11-03 08:00:00",
+  "entry_type": 1,
+  "entry_sign_status": 0,
+  "resign_sign_status": 0,
+  "leave_status": 1,
+  "work_status": 2,
+  "assistant_status": 1,
+  "show_status": 1,
+  "show_sort": 31,
+  "online_status": 1,
+  "is_delete": 0,
+  "criticism_status": 1,
+  "create_time": "2025-11-02 15:55:26",
+  "update_time": "2025-11-03 18:32:07",
+  "start_time": "2025-11-01 08:00:00",
+  "end_time": "2025-12-01 08:00:00",
+  "last_table_id": 0,
+  "last_table_name": "",
+  "order_trade_no": 0,
+  "ding_talk_synced": 1,
+  "site_light_cfg_id": 0,
+  "light_equipment_id": "",
+  "light_status": 2,
+  "is_team_leader": 0
+}
+```
+
+---
+
+## 六、跨表关联
+
+### 与助教流水（`assistant_service_records`）
+
+| 本表字段 | 关联表字段 | 说明 |
+|----------|-----------|------|
+| `id` | `site_assistant_id` | 助教主键 → 流水中的助教 ID |
+| `user_id` | `user_id` | 系统用户 ID，完全一致 |
+| `team_id` | `assistant_team_id` | 团队 ID |
+| `person_org_id` | `person_org_id` | 人事组织 ID |
+| `level` | `assistant_level` | 助教等级（流水中还有 `levelName` 文本） |
+| `nickname` | `nickname` | 昵称 |
+
+> 助教流水是事实表，本表是对应的助教维表。
+
+### 与门店维度
+
+所有业务表的 `tenant_id`、`site_id` 一致，共享门店维度。台费流水、销售记录、库存变化等表通过 `site_id` / `shop_name` 关联。
+
+### 与订单相关表
+
+`order_trade_no` 仅为"最近订单号"的影子值，真正的订单明细在订单表/小票详情中。助教与订单的关联通过助教流水这张桥接事实表实现。
+
+### 与外部系统
+
+- `ding_talk_synced` / `staff_profile_id` / `staff_id`：企业内部人事系统/钉钉集成预留字段
+- `site_light_cfg_id` / `light_equipment_id` / `light_status`：灯控设备联动预留字段，当前未启用