282 lines
13 KiB
Markdown
282 lines
13 KiB
Markdown
# 助教账号主数据 — 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`：灯控设备联动预留字段，当前未启用
|