# 助教账号主数据 — 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） |
| 时间范围 | 不需要（全量快照） |
| 响应数据路径 | `data.assistantInfos` |

---

## 二、请求

### 请求体（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`：灯控设备联动预留字段，当前未启用

<!--
AI_CHANGELOG:
- 日期: 2026-02-13
- Prompt: P20260213-170000 — API 文档全面重构（模板文档，手工创建）
- 直接原因: 作为 API 参考文档的标准模板，首次创建
- 变更摘要: 创建完整的 assistant_accounts_master API 参考文档，含六大章节结构
- 风险与验证: 纯文档，无运行时影响

- 日期: 2026-02-14
- Prompt: P20260214-060000 / P20260214-061000 — 全量 JSON 刷新 + MD 文档补全 + 数据路径修正
- 直接原因: 旧 JSON 样本仅含单条记录，缺少条件性字段；api_registry.json 中 17 个 data_path 与实际不符
- 变更摘要: 新增「响应数据路径」行（记录 API 实际返回的数据路径）
- 风险与验证: 纯文档变更，无运行时影响；验证：python scripts/refresh_json_and_audit.py 输出 24/24 通过
-->
