# BD_Manual：assistant_service_records（助教服务流水）

> ODS 表：`ods.assistant_service_records`
> DWD 表：`dwd.dwd_assistant_service_log`（主表）、`dwd.dwd_assistant_service_log_ex`（扩展表）
> API 接口：助教服务记录列表
> JSON 路径：`assistant_service_records.json → data.orderAssistantLedgers`
> 装载方式：事实表增量插入（`DwdLoadTask`）
> 代码位置：`apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py`

---

## 1. dwd_assistant_service_log（主表，33 列）

| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `assistant_service_id` | BIGINT | `id` | FACT_MAPPINGS | 助教服务记录唯一标识（PK） | 飞球雪花 ID |
| `order_trade_no` | BIGINT | `order_trade_no` | 自动映射 | 关联的订单交易号 | 飞球订单号 |
| `order_settle_id` | BIGINT | `order_settle_id` | 自动映射 | 关联的结算单 ID | 飞球结算单 ID |
| `order_pay_id` | BIGINT | `order_pay_id` | 自动映射 | 关联的支付单 ID | 飞球支付单 ID |
| `order_assistant_id` | BIGINT | `order_assistant_id` | 自动映射 | 订单级助教明细 ID，标识本次服务在订单中的唯一记录 | 飞球雪花 ID |
| `order_assistant_type` | INTEGER | `order_assistant_type` | 自动映射 | 助教服务类型：1=陪打，2=促销 | `1` / `2` |
| `tenant_id` | BIGINT | `tenant_id` | 自动映射 | 租户 ID | 飞球租户 ID |
| `site_id` | BIGINT | `site_id` | 自动映射 | 门店 ID | 飞球门店 ID |
| `site_table_id` | BIGINT | `site_table_id` | 自动映射 | 服务台桌 ID，关联 `dim_table.table_id` | 飞球台桌 ID |
| `tenant_member_id` | BIGINT | `tenant_member_id` | 自动映射 | 租户维度会员 ID | 飞球会员 ID 或 0 |
| `system_member_id` | BIGINT | `system_member_id` | 自动映射 | 系统维度会员 ID（跨租户唯一） | 飞球会员 ID 或 0 |
| `assistant_no` | VARCHAR(64) | `assistantno` | FACT_MAPPINGS | 助教编号（门店内序号） | 如 `31` |
| `nickname` | VARCHAR(64) | `nickname` | 自动映射 | 助教昵称 | 如 `小张` |
| `site_assistant_id` | BIGINT | `site_assistant_id` | FACT_MAPPINGS | 门店维度助教档案 ID，关联 `dim_assistant.assistant_id`。⚠️ 已于 2026-02-20 修正映射源（原错误映射自 `order_assistant_id`） | 飞球助教 ID |
| `user_id` | BIGINT | `user_id` | 自动映射 | 助教用户 ID | 飞球用户 ID |
| `assistant_team_id` | BIGINT | `assistant_team_id` | 自动映射 | 助教团队 ID | 飞球团队 ID |
| `person_org_id` | BIGINT | `person_org_id` | 自动映射 | 人员组织 ID | 飞球组织 ID |
| `assistant_level` | INTEGER | `assistant_level` | 自动映射 | 助教等级编码 | 枚举值 |
| `level_name` | VARCHAR(64) | `levelname` | FACT_MAPPINGS | 助教等级名称 | 如 `高级`、`中级` |
| `skill_id` | BIGINT | `skill_id` | 自动映射 | 服务技能 ID | 飞球技能 ID |
| `skill_name` | VARCHAR(64) | `skillname` | FACT_MAPPINGS | 服务技能名称 | 如 `陪打`、`促销` |
| `ledger_unit_price` | NUMERIC(10,2) | `ledger_unit_price` | 自动映射 | 分账单价（元/小时） | 金额值 |
| `ledger_amount` | NUMERIC(10,2) | `ledger_amount` | 自动映射 | 分账总金额（元） | 金额值 |
| `projected_income` | NUMERIC(10,2) | `projected_income` | 自动映射 | 预计收入（元） | 金额值 |
| `coupon_deduct_money` | NUMERIC(10,2) | `coupon_deduct_money` | 自动映射 | 优惠券抵扣金额（元） | `0.00` ~ 金额值 |
| `income_seconds` | INTEGER | `income_seconds` | 自动映射 | 计费时长（秒） | 正整数 |
| `real_use_seconds` | INTEGER | `real_use_seconds` | 自动映射 | 实际使用时长（秒） | 正整数 |
| `add_clock` | INTEGER | `add_clock` | 自动映射 | 加钟次数 | `0` ~ 正整数 |
| `create_time` | TIMESTAMPTZ | `create_time` | 自动映射 | 记录创建时间 | ISO 时间戳 |
| `start_use_time` | TIMESTAMPTZ | `start_use_time` | 自动映射 | 服务开始时间 | ISO 时间戳 |
| `last_use_time` | TIMESTAMPTZ | `last_use_time` | 自动映射 | 最后使用时间（服务结束时间） | ISO 时间戳 |
| `is_delete` | INTEGER | `is_delete` | 自动映射 | 是否已删除：0=正常，1=已删除 | `0` / `1` |
| `real_service_money` | NUMERIC(18,2) | `real_service_money` | FACT_MAPPINGS | 实际服务金额（元），扣除折扣后的实收 | `0.00` ~ 金额值 |

---

## 2. dwd_assistant_service_log_ex（扩展表，33 列）

| DWD 列名 | 类型 | ODS 源列 | 映射方式 | 业务含义 | 取值范围/示例 |
|----------|------|---------|---------|---------|-------------|
| `assistant_service_id` | BIGINT | `id` | FACT_MAPPINGS | 助教服务记录唯一标识（PK） | 同主表 |
| `table_name` | VARCHAR(64) | `tablename` | FACT_MAPPINGS | 台桌名称快照 | 如 `1号台` |
| `assistant_name` | VARCHAR(64) | `assistantname` | FACT_MAPPINGS | 助教姓名快照 | 如 `张静然` |
| `ledger_name` | VARCHAR(128) | `ledger_name` | 自动映射 | 分账项名称 | 如 `陪打费` |
| `ledger_group_name` | VARCHAR(128) | `ledger_group_name` | FACT_MAPPINGS | 分账组名称 | 分账组名或 NULL |
| `ledger_count` | INTEGER | `ledger_count` | 自动映射 | 分账数量 | 正整数 |
| `member_discount_amount` | NUMERIC(10,2) | `member_discount_amount` | 自动映射 | 会员折扣金额（元） | `0.00` ~ 金额值 |
| `manual_discount_amount` | NUMERIC(10,2) | `manual_discount_amount` | 自动映射 | 手动折扣金额（元） | `0.00` ~ 金额值 |
| `service_money` | NUMERIC(10,2) | `service_money` | 自动映射 | 服务原价金额（元） | 金额值 |
| `returns_clock` | INTEGER | `returns_clock` | 自动映射 | 退钟次数 | `0` ~ 正整数 |
| `ledger_start_time` | TIMESTAMPTZ | `ledger_start_time` | 自动映射 | 分账开始时间 | ISO 时间戳 |
| `ledger_end_time` | TIMESTAMPTZ | `ledger_end_time` | 自动映射 | 分账结束时间 | ISO 时间戳 |
| `ledger_status` | INTEGER | `ledger_status` | 自动映射 | 分账状态 | 枚举值 |
| `is_confirm` | INTEGER | `is_confirm` | 自动映射 | 是否已确认：0=未确认，1=已确认 | `0` / `1` |
| `is_single_order` | INTEGER | `is_single_order` | 自动映射 | 是否单独订单 | `0` / `1` |
| `is_not_responding` | INTEGER | `is_not_responding` | 自动映射 | 是否未响应 | `0` / `1` |
| `is_trash` | INTEGER | `is_trash` | 自动映射 | 是否已废除：0=正常，1=已废除 | `0` / `1` |
| `trash_applicant_id` | BIGINT | `trash_applicant_id` | 自动映射 | 废除申请人 ID | 员工 ID 或 NULL |
| `trash_applicant_name` | VARCHAR(64) | `trash_applicant_name` | FACT_MAPPINGS | 废除申请人姓名 | 姓名或 NULL |
| `trash_reason` | VARCHAR(255) | `trash_reason` | FACT_MAPPINGS | 废除原因 | 自由文本或 NULL |
| `salesman_user_id` | BIGINT | `salesman_user_id` | 自动映射 | 销售员用户 ID | 用户 ID 或 NULL |
| `salesman_name` | VARCHAR(64) | `salesman_name` | FACT_MAPPINGS | 销售员姓名 | 姓名或 NULL |
| `salesman_org_id` | BIGINT | `salesman_org_id` | 自动映射 | 销售员组织 ID | 组织 ID 或 NULL |
| `skill_grade` | INTEGER | `skill_grade` | 自动映射 | 技能评分 | 评分值 |
| `service_grade` | INTEGER | `service_grade` | 自动映射 | 服务评分 | 评分值 |
| `composite_grade` | NUMERIC(5,2) | `composite_grade` | 自动映射 | 综合评分 | 如 `4.50` |
| `sum_grade` | NUMERIC(10,2) | `sum_grade` | 自动映射 | 累计评分 | 累计值 |
| `get_grade_times` | INTEGER | `get_grade_times` | 自动映射 | 获评次数 | 正整数 |
| `grade_status` | INTEGER | `grade_status` | 自动映射 | 评分状态 | 枚举值 |
| `composite_grade_time` | TIMESTAMPTZ | `composite_grade_time` | 自动映射 | 综合评分时间 | ISO 时间戳 |
| `assistant_team_name` | TEXT | `assistantteamname` | FACT_MAPPINGS | 助教团队名称快照 | 如 `1组` |
| `operator_id` | BIGINT | `operator_id` | FACT_MAPPINGS | 操作员 ID，录入/结算这条助教服务的员工。0 表示系统自动 | `0` 或员工 ID |
| `operator_name` | TEXT | `operator_name` | FACT_MAPPINGS | 操作员姓名（带职位前缀），便于直接阅读 | 如 `收银员:郑丽珊`，NULL 表示系统自动 |

---

## 3. 映射修正记录

| 日期 | 字段 | 修正内容 |
|------|------|---------|
| 2026-02-20 | `site_assistant_id` | ODS 源从 `order_assistant_id`（订单级 ID）修正为 `site_assistant_id`（助教档案 ID） |
| 2026-02-26 | （下游）`table_area_name` | DWS 任务 `_extract_service_records()` 原错误引用 `asl.table_area_name`（本表无此列），改为 JOIN `dwd.dim_table` 取 `site_table_area_name`。详见 `BD_Manual_fix_dws_assistant_daily_table_area.md` |

---

## 4. 跳过字段说明

| ODS 字段 | 跳过原因 |
|---------|---------|
| `siteprofile` | JSONB 嵌套列，已由 `dim_site` / `dim_site_ex` 通过 JSONB 提取映射 |

---

## 5. 代码引用

- FACT_MAPPINGS：`dwd_load_task.py` → `FACT_MAPPINGS["dwd.dwd_assistant_service_log"]` / `FACT_MAPPINGS["dwd.dwd_assistant_service_log_ex"]`
- TABLE_MAP：`"dwd.dwd_assistant_service_log" → "ods.assistant_service_records"`
- DWS 下游：`dws_assistant_daily_task.py`（助教日业绩汇总）
- 迁移脚本：`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-20__fix_assistant_service_site_assistant_id.sql`（已归档）、`db/_archived/ddl_baseline_2026-02-22/db/etl_feiqiu/migrations/2026-02-20__add_assistant_service_log_ex_fields.sql`（已归档）
