# ETL 聚合修复与生日字段补齐 — Spec 需求输入

> 本文档汇总 v8 联调中发现的 4 个需要深度修复的问题，合并为一个 Spec。
> 用户可复制本文档内容开启 Spec 流程。

---

## 背景

v8 联调修复了 11 个 BUG，其中 4 个的当前修复方式是"临时止血"，需要更完整的方案：

| 编号 | 原 BUG | 当前临时修复 | 问题 |
|------|--------|-------------|------|
| A | BUG 2 | MAX() 聚合 nickname/level_code | 不精确，应按时间取最后记录；且未来档位不同需分段统计 |
| B | BUG 3+4 | site_id → register_site_id | 单门店可用，多门店场景会漏掉跨店消费的会员 |
| C | BUG 5 | 移除 birthday 字段 | 生日是重要销售线索，应全链路保留 + 支持手动补录 |
| D | BUG 11 | _safe_int() 下游防御 | 应从源头规范 DwdLoadTask.load() 返回值格式 |

---

## 需求 A：助教月度聚合 — 档位分段统计

### 现状
- `dws_assistant_monthly_summary` 唯一约束：`(site_id, assistant_id, stat_month)`
- `assistant_monthly_task.py` 的 `_extract_daily_aggregates()` 按 `(assistant_id, month)` GROUP BY
- 助教月内如果升级/降级，nickname/level_code/level_name 会变化，当前用 `MAX()` 取值
- `MAX(assistant_level_code)` 取数值最大的等级代码，不是时间上最后的等级

### 目标
1. 月度汇总按 `(assistant_id, stat_month, assistant_level_code)` 分组，保留多行，分别统计各档位的业绩
2. 唯一约束改为 `(site_id, assistant_id, stat_month, assistant_level_code)`
3. 工资计算（`assistant_salary_task.py`）适配：按档位分段计算抽成
4. nickname 取值改为按时间取最后一条记录（`ORDER BY date DESC LIMIT 1` 或窗口函数）

### 受影响的同类场景（需一并处理）
| 文件 | 方法 | 聚合粒度 | 维度字段 | 处理方式 |
|------|------|---------|---------|---------|
| `assistant_monthly_task.py` | `_extract_daily_aggregates` | assistant_id + month | nickname, level_code, level_name | 改为分段保留 |
| `assistant_finance_task.py` | `_extract_daily_revenue` | date + assistant_id | nickname | 改为按时间取最后 |
| `assistant_customer_task.py` | `_extract_service_pairs` | assistant_id + member_id | nickname | 改为按时间取最后 |

### 涉及变更
- DDL：`dws.dws_assistant_monthly_summary` 唯一约束变更
- 代码：`assistant_monthly_task.py`、`assistant_salary_task.py`、`assistant_finance_task.py`、`assistant_customer_task.py`
- 迁移脚本：`db/etl_feiqiu/migrations/`

---

## 需求 B：多门店会员查询 — register_site_id 潜在问题

### 现状
- `dim_member` 没有 `site_id` 列，只有 `register_site_id`（会员注册门店）
- 所有 DWS 任务用 `WHERE register_site_id = %s` 筛选会员
- 单门店场景下无问题

### 潜在问题
- 会员在 A 店注册、B 店消费 → B 店的 DWS 任务查不到该会员信息
- 会员昵称、手机号等维度信息缺失，DWS 记录不完整

### 目标
1. 评估当前业务是否存在跨店消费场景（如果只有一个门店，可标记为"已知限制"暂不处理）
2. 如果需要支持多门店：改为通过事实表的 `member_id` 反查 `dim_member`，不再按 `register_site_id` 预筛选
3. 受影响的任务：所有使用 `_extract_member_info(site_id)` 的 DWS 任务

### 建议
- 当前单门店场景下，标记为"已知限制"，在代码中加注释说明
- 预留多门店扩展方案：将 `WHERE register_site_id = %s` 改为 `WHERE member_id IN (SELECT DISTINCT member_id FROM dwd.事实表 WHERE site_id = %s)`

---

## 需求 C：会员生日字段全链路补齐 + 手动补录

### 现状
- 上游 API `member_profiles` 可能返回生日字段（当前可能全为空）
- ODS `billiards_ods.member_profiles` 保留 API 原始 payload（JSON 中有则保留）
- DWD `dim_member` 没有 `birthday` 列 → ODS → DWD 装载时未映射
- DWS `member_visit_task.py` 原本引用 `birthday`，BUG 5 临时修复时移除了

### 目标

#### C1：ETL 链路生日字段补齐
1. DWD `dim_member` 主表（不是 `_ex` 表）新增 `birthday DATE` 列
2. DWD 装载映射：`DwdLoadTask` 的列映射中加入 `birthday`
3. DWS 恢复 `member_birthday` 引用：`member_visit_task.py` 等任务从 `dim_member.birthday` 读取
4. SCD2 更新时正常处理 birthday 变化

#### C2：助教手动补录生日（独立于 ETL 链路）
1. 新建表 `dwd.dim_member_birthday_manual`：
   - `member_id BIGINT NOT NULL` — 会员 ID
   - `birthday_value DATE NOT NULL` — 生日值
   - `recorded_by_assistant_id BIGINT` — 补录助教 ID
   - `recorded_by_name VARCHAR(50)` — 补录人姓名
   - `recorded_at TIMESTAMPTZ NOT NULL DEFAULT NOW()` — 补录时间
   - `source VARCHAR(20) DEFAULT 'assistant'` — 来源标记
   - 唯一约束：`(member_id, recorded_by_assistant_id)` — 同一助教对同一客户只保留最新一条
2. 可能有多个助教对同一客户提交生日信息，需要处理冲突：
   - 保留所有提交记录（不删除）
   - DWS 读取时取最早提交的记录（第一个发现的助教优先），或取最多人提交的相同值
3. 与 ETL 链路的 `dim_member.birthday` 隔离：
   - DWS 读取优先级：`dim_member_birthday_manual`（手动值）> `dim_member.birthday`（API 值）
   - SCD2 更新 `dim_member.birthday` 时不覆盖手动补录值
4. 后端 API：助教提交生日的接口（POST）
5. 小程序：助教端提交客户生日的 UI 入口

### 涉及变更
- DDL：`dwd.dim_member` 加列 + 新建 `dwd.dim_member_birthday_manual`
- DWD 装载：`dwd_load_task.py` 列映射
- DWS 任务：`member_visit_task.py` 等恢复 birthday 引用
- 后端 API：新增生日提交接口
- 小程序：助教端 UI
- 迁移脚本

---

## 需求 D：DwdLoadTask 返回值格式规范化

### 现状
- `DwdLoadTask.load()` 返回 `{"tables": summary, "errors": errors}`，其中 `errors` 是 `list[dict]`
- 其他任务返回 `{"counts": {"fetched": 0, "inserted": 10, "errors": 0}}`，`errors` 是 `int`
- `BaseTask._accumulate_counts()` 对 `list` 类型做 `setdefault` 保留原值
- `flow_runner.py` 的 `sum()` 遇到 `list` 类型崩溃
- 当前 `_safe_int()` 是下游防御，不是根本修复

### 目标
1. `DwdLoadTask.load()` 返回值中 `errors` 改为 `int`（`len(errors)`）
2. 错误详情放到单独的 key（如 `error_details: list[dict]`）
3. `BaseTask._accumulate_counts()` 对 `list` 类型做 `len()` 累加（防御层保留）
4. `flow_runner.py` 的 `_safe_int()` 保留作为最终防御层

### 涉及变更
- `apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py` — load() 返回值
- `apps/etl/connectors/feiqiu/tasks/base_task.py` — _accumulate_counts()
- `apps/etl/connectors/feiqiu/orchestration/flow_runner.py` — _safe_int() 保留

---

## 优先级建议

| 需求 | 优先级 | 理由 |
|------|--------|------|
| D | P0 | 改动最小，消除类型不一致的隐患 |
| C1 | P1 | 生日字段是重要销售线索，ETL 链路先通 |
| B | P1 | 加注释标记已知限制，预留扩展方案 |
| A | P2 | 涉及 DDL 变更 + 多任务重写，影响面最大 |
| C2 | P2 | 依赖后端 API + 小程序 UI，需要跨团队协调 |

---

## 关键 DDL 参考

### dim_member 当前结构（无 birthday）
```sql
CREATE TABLE dim_member (
    member_id BIGINT,
    system_member_id BIGINT,
    tenant_id BIGINT,
    register_site_id BIGINT,    -- 注意：没有 site_id
    mobile TEXT,
    nickname TEXT,
    member_card_grade_code BIGINT,
    member_card_grade_name TEXT,
    create_time TIMESTAMPTZ,
    update_time TIMESTAMPTZ,
    pay_money_sum NUMERIC(18,2),
    recharge_money_sum NUMERIC(18,2),
    SCD2_start_time TIMESTAMPTZ,
    SCD2_end_time TIMESTAMPTZ,
    SCD2_is_current INT,
    SCD2_version INT,
    PRIMARY KEY (member_id, scd2_start_time)
);
```

### dws_assistant_monthly_summary 当前唯一约束
```sql
CONSTRAINT uk_dws_assistant_monthly UNIQUE (site_id, assistant_id, stat_month)
-- 需改为: UNIQUE (site_id, assistant_id, stat_month, assistant_level_code)
```

### DwdLoadTask.load() 当前返回值
```python
return {"tables": summary, "errors": errors}
# errors 是 list[dict]，如 [{"table": "dim_assistant_ex", "error": "year -1 is out of range"}]
# 应改为: return {"tables": summary, "errors": len(errors), "error_details": errors}
```