在前后端开发联调前 的提交20260223

docs/database/BD_Manual_assistant_accounts_master.md

@@ -0,0 +1,106 @@
+# BD_Manual：assistant_accounts_master（助教账号档案）
+
+> ODS 表：`ods.assistant_accounts_master`
+> DWD 表：`dwd.dim_assistant`（主表）、`dwd.dim_assistant_ex`（扩展表）
+> API 接口：助教账号列表
+> JSON 路径：`assistant_accounts_master.json → data.assistantInfos`
+> 装载方式：SCD2 维度合并（`DwdLoadTask`）
+> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`
+
+---
+
+## 1. dim_assistant（主表）
+
+| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
+|----------|------|---------|---------|---------|-------------|
+| `assistant_id` | BIGINT | `id` | FACT_MAPPINGS | 助教唯一标识（PK 之一） | 飞球系统雪花 ID，如 `2947562271297029` |
+| `user_id` | BIGINT | `user_id` | FACT_MAPPINGS | 关联的系统用户 ID，0 表示未绑定用户账号 | `0` 或飞球用户 ID |
+| `assistant_no` | TEXT | `assistant_no` | 自动映射 | 助教编号（门店内序号），用于排班和展示 | 如 `31`、`1` |
+| `real_name` | TEXT | `real_name` | 自动映射 | 助教真实姓名 | 如 `张静然` |
+| `nickname` | TEXT | `nickname` | 自动映射 | 助教昵称，用于小程序端展示 | 如 `小然` |
+| `mobile` | TEXT | `mobile` | 自动映射 | 助教手机号 | 11 位手机号 |
+| `tenant_id` | BIGINT | `tenant_id` | 自动映射 | 所属租户 ID | 飞球租户 ID |
+| `site_id` | BIGINT | `site_id` | 自动映射 | 所属门店 ID | 飞球门店 ID |
+| `team_id` | BIGINT | `team_id` | 自动映射 | 所属团队 ID，0 表示未分组 | `0` 或团队 ID |
+| `team_name` | TEXT | `team_name` | 自动映射 | 团队名称 | 如 `1组`，NULL 表示未分组 |
+| `level` | INTEGER | `level` | 自动映射 | 助教等级（技能等级编号） | 如 `20`（对应"高级"等） |
+| `entry_time` | TIMESTAMPTZ | `entry_time` | 自动映射 | 入职时间 | ISO 时间戳 |
+| `resign_time` | TIMESTAMPTZ | `resign_time` | 自动映射 | 离职时间，NULL 表示在职 | ISO 时间戳或 NULL |
+| `leave_status` | INTEGER | `leave_status` | 自动映射 | 在职状态：0=在职，1=已离职 | `0` / `1` |
+| `assistant_status` | INTEGER | `assistant_status` | 自动映射 | 助教状态：1=正常，2=停用 | `1` / `2` |
+| `scd2_start_time` | TIMESTAMPTZ | — | DWD 元数据 | SCD2 版本生效起点 | — |
+| `scd2_end_time` | TIMESTAMPTZ | — | DWD 元数据 | SCD2 版本失效时间，`9999-12-31` 表示当前版本 | — |
+| `scd2_is_current` | INT | — | DWD 元数据 | 当前版本标记：1=当前，0=历史 | `0` / `1` |
+| `scd2_version` | INT | — | DWD 元数据 | SCD2 版本号（自增） | — |
+
+---
+
+## 2. dim_assistant_ex（扩展表）
+
+| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
+|----------|------|---------|---------|---------|-------------|
+| `assistant_id` | BIGINT | `id` | FACT_MAPPINGS | 助教唯一标识（PK 之一） | 同主表 |
+| `gender` | INTEGER | `gender` | 自动映射 | 性别：0=未设置 | `0` |
+| `birth_date` | TIMESTAMPTZ | `birth_date` | 自动映射 | 出生日期 | `0001-01-01` 表示未设置 |
+| `avatar` | TEXT | `avatar` | 自动映射 | 头像 URL | HTTPS 链接 |
+| `introduce` | TEXT | `introduce` | FACT_MAPPINGS | 个人简介文本 | 自由文本或 NULL |
+| `video_introduction_url` | TEXT | `video_introduction_url` | 自动映射 | 视频介绍 URL | HTTPS 链接或 NULL |
+| `height` | NUMERIC(5,2) | `height` | 自动映射 | 身高（cm），0 表示未填写 | `0.00` 或实际身高 |
+| `weight` | NUMERIC(5,2) | `weight` | 自动映射 | 体重（kg），0 表示未填写 | `0.00` 或实际体重 |
+| `shop_name` | TEXT | `shop_name` | 自动映射 | 所属门店名称快照 | 如 `朗朗桌球` |
+| `group_id` | BIGINT | `group_id` | 自动映射 | 分组 ID，0 表示未分组 | `0` 或分组 ID |
+| `group_name` | TEXT | `group_name` | FACT_MAPPINGS | 分组名称 | NULL 或分组名 |
+| `person_org_id` | BIGINT | `person_org_id` | 自动映射 | 人事组织 ID | 飞球组织 ID |
+| `staff_id` | BIGINT | `staff_id` | 自动映射 | 员工 ID，0 表示未绑定员工档案 | `0` 或员工 ID |
+| `staff_profile_id` | BIGINT | `staff_profile_id` | 自动映射 | 员工档案 ID，0 表示无档案 | `0` 或档案 ID |
+| `assistant_grade` | DOUBLE PRECISION | `assistant_grade` | 自动映射 | 助教评分（客户评价均分） | `0.0` ~ `5.0` |
+| `sum_grade` | DOUBLE PRECISION | `sum_grade` | 自动映射 | 累计评分总和 | `0.0` 或累计值 |
+| `get_grade_times` | INTEGER | `get_grade_times` | 自动映射 | 被评价次数 | `0` 或正整数 |
+| `charge_way` | INTEGER | `charge_way` | 自动映射 | 计费方式：2=按时长计费（当前门店全部为 2） | `2` |
+| `allow_cx` | INTEGER | `allow_cx` | 自动映射 | 是否允许促销服务：1=允许（当前全部为 1） | `1` |
+| `is_guaranteed` | INTEGER | `is_guaranteed` | 自动映射 | 是否保底：0=不保底，1=保底 | `0` / `1` |
+| `salary_grant_enabled` | INTEGER | `salary_grant_enabled` | 自动映射 | 工资发放开关：2=启用 | `2` |
+| `entry_type` | INTEGER | `entry_type` | 自动映射 | 入职类型：1=正常入职 | `1` |
+| `entry_sign_status` | INTEGER | `entry_sign_status` | 自动映射 | 入职签到状态：0=未签到 | `0` |
+| `resign_sign_status` | INTEGER | `resign_sign_status` | 自动映射 | 离职签到状态：0=未签到 | `0` |
+| `work_status` | INTEGER | `work_status` | 自动映射 | 工作状态：1=在岗，2=离岗 | `1` / `2` |
+| `show_status` | INTEGER | `show_status` | 自动映射 | 展示状态：1=展示 | `1` |
+| `show_sort` | INTEGER | `show_sort` | 自动映射 | 展示排序序号 | 正整数 |
+| `online_status` | INTEGER | `online_status` | 自动映射 | 在线状态：1=在线 | `1` |
+| `is_delete` | INTEGER | `is_delete` | 自动映射 | 软删除标记：0=正常，1=已删除 | `0` / `1` |
+| `criticism_status` | INTEGER | `criticism_status` | 自动映射 | 差评处理状态：1=正常 | `1` |
+| `create_time` | TIMESTAMPTZ | `create_time` | 自动映射 | 助教记录创建时间 | ISO 时间戳 |
+| `update_time` | TIMESTAMPTZ | `update_time` | 自动映射 | 助教记录最后更新时间 | ISO 时间戳 |
+| `start_time` | TIMESTAMPTZ | `start_time` | 自动映射 | 合同/排班开始时间 | ISO 时间戳 |
+| `end_time` | TIMESTAMPTZ | `end_time` | 自动映射 | 合同/排班结束时间 | ISO 时间戳 |
+| `last_table_id` | BIGINT | `last_table_id` | 自动映射 | 最近服务的台桌 ID，0 表示无 | `0` 或台桌 ID |
+| `last_table_name` | TEXT | `last_table_name` | 自动映射 | 最近服务的台桌名称 | 如 `TV`、`1号台` |
+| `last_update_name` | TEXT | `last_update_name` | 自动映射 | 最后操作人姓名（带职位前缀） | 如 `管理员：郑丽珊` |
+| `order_trade_no` | BIGINT | `order_trade_no` | 自动映射 | 当前关联的订单交易号，0 表示空闲 | `0` 或订单号 |
+| `ding_talk_synced` | INTEGER | `ding_talk_synced` | 自动映射 | 钉钉同步状态：1=已同步 | `1` |
+| `site_light_cfg_id` | BIGINT | `site_light_cfg_id` | 自动映射 | 门店灯控配置 ID，0 表示未配置 | `0` 或配置 ID |
+| `light_equipment_id` | TEXT | `light_equipment_id` | FACT_MAPPINGS | 灯控设备 ID | NULL 或设备编号 |
+| `light_status` | INTEGER | `light_status` | 自动映射 | 台灯状态：2=已开灯 | `1` / `2` |
+| `is_team_leader` | INTEGER | `is_team_leader` | 自动映射 | 是否组长：0=否，1=是 | `0` / `1` |
+| `serial_number` | BIGINT | `serial_number` | 自动映射 | 序列号，0 表示未分配 | `0` 或序列号 |
+| `system_role_id` | BIGINT | `system_role_id` | FACT_MAPPINGS | 系统角色 ID，标识助教在系统中的角色类型。当前门店全部为 10 | `10` |
+| `job_num` | TEXT | `job_num` | FACT_MAPPINGS | 工号，助教的内部编号标识。当前门店未启用，全部为 NULL | NULL |
+| `cx_unit_price` | NUMERIC(18,2) | `cx_unit_price` | FACT_MAPPINGS | 促销单价（元），助教提供促销服务时的计费单价。当前门店未在账号表层面设置，全部为 0.00 | `0.00` |
+| `pd_unit_price` | NUMERIC(18,2) | `pd_unit_price` | FACT_MAPPINGS | 陪打单价（元），助教提供陪打服务时的计费单价。当前门店未在账号表层面设置，全部为 0.00 | `0.00` |
+| `scd2_*` | — | — | DWD 元数据 | SCD2 慢变维度追踪字段（同主表） | — |
+
+---
+
+## 3. 跳过字段说明
+
+| ODS 字段 | 跳过原因 |
+|---------|---------|
+| `siteprofile` | JSONB 嵌套列，已由 `dim_site` / `dim_site_ex` 通过 JSONB 提取映射 |
+
+---
+
+## 4. 代码引用
+
+- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dim_assistant"]` / `FACT_MAPPINGS["dwd.dim_assistant_ex"]`
+- TABLE_MAP：`"dwd.dim_assistant" → "ods.assistant_accounts_master"`
+- DWS 下游：`dws_assistant_daily_task.py`（助教日业绩汇总）、`dws_salary_task.py`（工资计算）