Neo-ZQYY/.kiro/specs/etl-aggregation-fix/requirements.md

需求文档

简介

v8 联调修复了 11 个 BUG，其中 4 个的当前修复方式是"临时止血"，需要更完整的方案。本 Spec 覆盖以下四个需求：

• 需求 A：助教月度聚合按档位分段统计，替代 MAX() 聚合
• 需求 B：多门店会员查询 register_site_id 已知限制标记 + 预留扩展方案
• 需求 C：会员生日字段全链路补齐（C1: ETL 链路 / C2: 手动补录）
• 需求 D：DwdLoadTask.load() 返回值格式规范化

术语表

• DwdLoadTask：DWD 层装载任务，负责将 ODS 原始数据清洗装载至 DWD 明细层
• DWS 任务：数据汇总层任务，从 DWD 层聚合生成业务报表数据
• SCD2：缓慢变化维度类型 2，通过版本化记录维度属性的历史变化
• BaseTask：ETL 任务基类，提供 Extract/Transform/Load 模板方法和计数累加逻辑
• FlowRunner：ETL 流程编排器，按层级顺序执行任务并汇总计数
• dim_member：DWD 层会员维度表，使用 SCD2 管理历史版本
• dws_assistant_monthly_summary：DWS 层助教月度汇总表
• dws_assistant_salary_calc：DWS 层助教工资计算表
• register_site_id：会员注册门店 ID，当前 dim_member 中唯一的门店标识
• assistant_level_code：助教档位代码，助教月内可能因升级/降级而变化
• dim_member_birthday_manual：手动补录生日表（位于 zqyy_app 业务库），存储助教提交的会员生日信息，通过 FDW 只读映射供 ETL DWS 任务读取
• _safe_int()：flow_runner.py 中的类型安全辅助函数，将 int/list/None 统一转为 int
• _accumulate_counts()：BaseTask 中的计数累加方法，合并多段执行的统计结果

需求

需求 1：DwdLoadTask 返回值格式规范化（需求 D）

用户故事： 作为 ETL 开发者，我希望 DwdLoadTask.load() 的返回值格式与其他任务保持一致，以便 FlowRunner 能安全地汇总所有任务的计数。

验收标准

1. WHEN DwdLoadTask.load() 执行完成, THE DwdLoadTask SHALL 返回包含 errors 键（值为 int 类型，等于错误列表长度）和 error_details 键（值为 list[dict] 类型，包含错误详情）的字典
2. WHEN BaseTask._accumulate_counts() 遇到值为 list 类型的计数项, THE BaseTask SHALL 将该值转换为 len(list) 后再累加（防御层）
3. WHEN FlowRunner 汇总所有任务计数, THE FlowRunner SHALL 保留 _safe_int() 作为最终防御层，确保 sum() 不会因类型不一致而崩溃

需求 2：助教月度聚合按档位分段统计（需求 A）

用户故事： 作为运营管理者，我希望助教月度汇总按档位分段统计业绩，以便准确反映助教在不同档位期间的表现和工资计算。

验收标准

1. WHEN 助教在同一月内存在多个 assistant_level_code, THE AssistantMonthlyTask SHALL 按 (assistant_id, stat_month, assistant_level_code) 分组生成多行记录，分别统计各档位的业绩指标
2. THE dws_assistant_monthly_summary 表 SHALL 使用 (site_id, assistant_id, stat_month, assistant_level_code) 作为唯一约束
3. WHEN AssistantMonthlyTask 需要取 nickname 值, THE AssistantMonthlyTask SHALL 按时间倒序取最后一条记录的 nickname，而非使用 MAX() 聚合
4. WHEN AssistantSalaryTask 计算工资, THE AssistantSalaryTask SHALL 按档位分段计算抽成，适配新的多行月度汇总结构
5. WHEN AssistantFinanceTask 提取日度收入需要 nickname, THE AssistantFinanceTask SHALL 按时间倒序取最后一条记录的 nickname，而非使用 MAX() 聚合
6. WHEN AssistantCustomerTask 提取服务对需要 nickname, THE AssistantCustomerTask SHALL 按时间倒序取最后一条记录的 nickname，而非使用 MAX() 聚合

需求 3：多门店会员查询支持（需求 B）

用户故事： 作为运营管理者，我希望 DWS 任务能正确查询跨店消费的会员信息，以便 B 店能看到在 A 店注册但在 B 店消费的会员维度数据。

验收标准

1. WHEN DWS 任务需要查询会员信息, THE DWS 任务 SHALL 通过事实表中的 member_id 反查 dim_member，而非使用 WHERE register_site_id = %s 预筛选
2. WHEN 会员在 A 店注册并在 B 店消费, THE B 店的 DWS 任务 SHALL 能查询到该会员的昵称、手机号等维度信息
3. WHEN DWS 任务执行会员信息提取, THE DWS 任务 SHALL 使用 WHERE member_id IN (SELECT DISTINCT member_id FROM dwd.事实表 WHERE site_id = %s) 模式获取会员维度数据

需求 4：会员生日字段 ETL 链路补齐（需求 C1）

用户故事： 作为运营管理者，我希望会员生日信息能从上游 API 完整传递到 DWS 层，以便用于会员分析和销售线索。

验收标准

1. THE dim_member 表 SHALL 包含 birthday DATE 列
2. WHEN DwdLoadTask 执行 ODS → DWD 装载, THE DwdLoadTask SHALL 在列映射中包含 birthday 字段，将 ODS 中的生日数据装载到 dim_member.birthday
3. WHEN SCD2 更新 dim_member 记录, THE DwdLoadTask SHALL 将 birthday 作为变化检测字段之一，正常处理生日值的变化
4. WHEN MemberVisitTask 等 DWS 任务提取会员信息, THE DWS 任务 SHALL 从 dim_member.birthday 读取生日字段并写入 DWS 目标表

需求 5：助教手动补录会员生日（需求 C2）

用户故事： 作为助教，我希望能手动提交客户的生日信息，以便在上游 API 未提供生日数据时补充这一重要销售线索。

验收标准

1. THE zqyy_app 业务库（开发/测试环境使用 test_zqyy_app）SHALL 包含 member_birthday_manual 表，结构包含 member_id、birthday_value、recorded_by_assistant_id、recorded_by_name、recorded_at、source 字段，唯一约束为 (member_id, recorded_by_assistant_id)
2. WHEN 同一助教对同一会员重复提交生日, THE 系统 SHALL 更新该助教的已有记录（UPSERT），保留所有其他助教的提交记录
3. WHEN DWS 任务需要读取手动补录生日, THE DWS 任务 SHALL 通过 FDW 只读映射从 zqyy_app.member_birthday_manual 读取数据
4. WHEN dim_member.birthday（API 来源）和 member_birthday_manual（手动来源）同时存在, THE DWS 任务 SHALL 优先使用手动补录值
5. WHEN 助教通过后端 API 提交生日, THE 后端 SHALL 提供 POST 接口接收 member_id、birthday_value、assistant_id、assistant_name 参数，执行 UPSERT 写入 zqyy_app.member_birthday_manual
6. WHEN SCD2 更新 dim_member.birthday, THE DwdLoadTask SHALL 正常更新 API 来源的生日值，不影响业务库中手动补录表的数据