root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ded6dfb9d8b3252d96e9545412156172f91fd492
Neo-ZQYY/.kiro/specs/etl-task-documentation/design.md

15 KiB
Raw Blame History

设计文档：ETL 任务说明文档

概述

本设计描述如何为飞球 ETL 系统生成一套完整的任务说明文档，放置于 docs/etl_tasks/ 目录下。文档以 Markdown 格式编写，按数据层（ODS / DWD / DWS / INDEX / Utility）分文件组织，并提供一个总览 README 作为入口。

文档的目标读者是开发者和运维人员，需要覆盖：

  • 每个任务的代码标识、Python 类、数据来源与目标
  • Extract / Transform / Load 各阶段的处理逻辑
  • CLI 参数与管道执行方式
  • BaseTask 公共机制

架构

文档为纯静态 Markdown 文件，不涉及运行时代码变更。整体结构如下：

docs/etl_tasks/
├── README.md                  # 总览：任务清单 + 跳转链接 + 执行方式
├── ods_tasks.md               # ODS 层任务详解
├── dwd_tasks.md               # DWD 层任务详解
├── dws_tasks.md               # DWS 层任务详解
├── index_tasks.md             # INDEX 层任务详解
├── utility_tasks.md           # 工具类任务详解
└── base_task_mechanism.md     # BaseTask 公共机制与执行参数

graph TD
    README["README.md<br/>总览入口"] --> ODS["ods_tasks.md"]
    README --> DWD["dwd_tasks.md"]
    README --> DWS["dws_tasks.md"]
    README --> IDX["index_tasks.md"]
    README --> UTL["utility_tasks.md"]
    README --> BASE["base_task_mechanism.md"]

组件与接口

本 spec 不涉及代码组件。产出物为 7 个 Markdown 文件，各文件的内容范围如下：

README.md（总览）

章节 内容
系统简介 飞球 ETL 系统概述、数据流向（API → ODS → DWD → DWS）
任务清单 按层分组的表格：任务代码、Python 类、简要说明、跳转链接
管道类型 7 种管道（api_ods / api_ods_dwd / api_full / ods_dwd / dwd_dws / dwd_dws_index / dwd_index）的层组合
处理模式 increment_only / verify_only / increment_verify 的区别
数据源模式 online / offline / hybrid 的区别
CLI 参数速查 所有 CLI 参数的表格（参数名、类型、默认值、说明）
常见命令示例 典型使用场景的命令行示例

ods_tasks.md（ODS 层）

每个 ODS 任务一个小节，包含：

  • 任务代码与 Python 类
  • API 端点与请求参数
  • 字段解析逻辑（transform 阶段）
  • 目标 ODS 表与写入策略
  • 特殊说明（如分页、去重、content_hash 等）

需区分两种 ODS 任务模式：

  1. 独立任务类（如 OrdersTask、MembersTask）：继承 BaseTask，有独立的 E/T/L 实现
  2. 通用 ODS 任务（由 ods_tasks.py 中 OdsTaskSpec + BaseOdsTask 动态生成）：通过声明式配置定义端点、列映射等

已注册的 ODS 任务（14 个独立 + N 个通用）：

任务代码 Python 类 API 端点 目标表
ORDERS OrdersTask /Site/GetAllOrderSettleList billiards_ods.fact_order
PAYMENTS PaymentsTask 支付相关端点 billiards_ods.fact_payment
MEMBERS MembersTask /MemberProfile/GetTenantMemberList billiards_ods.dim_member
PRODUCTS ProductsTask 商品相关端点 billiards_ods 商品表
TABLES TablesTask 台桌相关端点 billiards_ods 台桌表
ASSISTANTS AssistantsTask 助教相关端点 billiards_ods 助教表
PACKAGES_DEF PackagesDefTask 套餐相关端点 billiards_ods 套餐表
REFUNDS RefundsTask 退款相关端点 billiards_ods 退款表
COUPON_USAGE CouponUsageTask 优惠券相关端点 billiards_ods 优惠券表
INVENTORY_CHANGE InventoryChangeTask 库存变动端点 billiards_ods 库存表
TOPUPS TopupsTask 充值相关端点 billiards_ods 充值表
TABLE_DISCOUNT TableDiscountTask 台费折扣端点 billiards_ods 折扣表
ASSISTANT_ABOLISH AssistantAbolishTask 助教取消端点 billiards_ods 取消表
LEDGER LedgerTask 台账端点 billiards_ods 台账表

通用 ODS 任务由 ODS_TASK_CLASSES 字典动态注册，每个任务通过 OdsTaskSpec 声明：

  • endpoint：API 端点路径
  • table：目标 ODS 表名
  • columns：列定义列表（ColumnSpec）
  • page_size、data_path、list_key：分页参数
  • pk_columns：主键列
  • snapshot_mode：快照模式（content_hash 去重）

dwd_tasks.md（DWD 层）

DWD 层有 5 个已注册任务：

任务代码 Python 类 说明
DWD_LOAD_FROM_ODS DwdLoadTask 核心装载任务：遍历 TABLE_MAP，维度走 SCD2，事实走增量
TICKET_DWD TicketDwdTask 结账小票明细 → fact_order / fact_order_goods / fact_table_usage / fact_assistant_service
PAYMENTS_DWD PaymentsDwdTask ODS 支付记录 → fact_payment
MEMBERS_DWD MembersDwdTask ODS 会员记录 → dim_member
DWD_QUALITY_CHECK DwdQualityTask ODS 与 DWD 行数/金额核对，输出 JSON 报表

核心任务 DWD_LOAD_FROM_ODS 的处理逻辑：

  • TABLE_MAP 定义了 40+ 对 DWD→ODS 表映射
  • 维度表（dim_*）：检测 SCD2 列是否存在，有则执行 SCD2 合并（关闭旧版+插入新版），无则执行 Type1 Upsert
  • 事实表（dwd_、fact_）：按 fetched_at 水位线增量插入，支持 upsert 或 insert-only
  • FACT_MAPPINGS 定义了列名映射（ODS 驼峰命名 → DWD 下划线命名）
  • 每张表独立事务，单表失败不影响后续表

SCD2 处理流程：

  1. 从 ODS 取最新快照（DISTINCT ON 按业务主键 + fetched_at DESC）
  2. 与 DWD 当前版本（scd2_is_current=1）逐列对比
  3. 有变更：关闭旧版（scd2_end_time=now, scd2_is_current=0）+ 插入新版（version+1）
  4. 无变更：跳过

dws_tasks.md（DWS 层）

DWS 层有 15 个已注册任务，按业务域分组：

助教业绩域：

任务代码 Python 类 目标表 粒度
DWS_ASSISTANT_DAILY AssistantDailyTask dws_assistant_daily_detail 日期+助教
DWS_ASSISTANT_MONTHLY AssistantMonthlyTask dws_assistant_monthly_summary 月份+助教
DWS_ASSISTANT_CUSTOMER AssistantCustomerTask dws_assistant_customer_stats 日期+助教+会员
DWS_ASSISTANT_SALARY AssistantSalaryTask dws_assistant_salary_calc 月份+助教
DWS_ASSISTANT_FINANCE AssistantFinanceTask dws_assistant_finance_analysis 日期+助教

会员分析域：

任务代码 Python 类 目标表 粒度
DWS_MEMBER_CONSUMPTION MemberConsumptionTask dws_member_consumption_summary 日期+会员
DWS_MEMBER_VISIT MemberVisitTask dws_member_visit_detail 日期+会员+结账单

财务统计域：

任务代码 Python 类 目标表 粒度
DWS_FINANCE_DAILY FinanceDailyTask dws_finance_daily_summary 日期
DWS_FINANCE_RECHARGE FinanceRechargeTask dws_finance_recharge_summary 日期
DWS_FINANCE_INCOME_STRUCTURE FinanceIncomeStructureTask dws_finance_income_structure 日期+收入类型
DWS_FINANCE_DISCOUNT_DETAIL FinanceDiscountDetailTask dws_finance_discount_detail 日期+折扣类型

运维任务：

任务代码 Python 类 说明
DWS_BUILD_ORDER_SUMMARY DwsBuildOrderSummaryTask 构建订单汇总中间表
DWS_RETENTION_CLEANUP DwsRetentionCleanupTask 按时间分层清理历史数据
DWS_MV_REFRESH_FINANCE_DAILY DwsMvRefreshFinanceDailyTask 刷新财务日报物化视图
DWS_MV_REFRESH_ASSISTANT_DAILY DwsMvRefreshAssistantDailyTask 刷新助教日报物化视图

所有 DWS 任务继承 BaseDwsTask，共享以下机制：

  • 时间分层范围计算（TimeLayer: LAST_2_DAYS / LAST_1_MONTH / LAST_3_MONTHS / LAST_6_MONTHS / ALL）
  • 配置缓存（ConfigCache）：业绩档位、等级价格、奖金规则、区域分类、技能类型
  • delete-before-insert 更新策略（按日期范围先删后插，保证幂等）
  • bulk_insert / upsert 写入方法

index_tasks.md（INDEX 层）

INDEX 层有 4 个已注册任务：

任务代码 Python 类 目标表 指数类型
DWS_WINBACK_INDEX WinbackIndexTask dws_member_winback_index WBI（回流指数）
DWS_NEWCONV_INDEX NewconvIndexTask dws_member_newconv_index NCI（新客转化指数）
DWS_RELATION_INDEX RelationIndexTask dws_relation_index RS（关系指数）
DWS_ML_MANUAL_IMPORT MlManualImportTask dws_ml_manual_ledger ML（手动台账导入）

所有指数任务继承 BaseIndexTask，共享：

  • 参数从 billiards_dws.cfg_index_parameters 表加载
  • 百分位历史记录（PercentileHistory）
  • 标准化的指数计算流程

utility_tasks.md（工具类）

任务代码 Python 类 用途
INIT_ODS_SCHEMA InitOdsSchemaTask 执行 ODS + etl_admin DDL，创建必要目录
INIT_DWD_SCHEMA InitDwdSchemaTask 执行 DWD DDL
INIT_DWS_SCHEMA InitDwsSchemaTask 执行 DWS DDL
MANUAL_INGEST ManualIngestTask 从本地 JSON 文件手动入库到 ODS
ODS_JSON_ARCHIVE OdsJsonArchiveTask 归档 ODS JSON 文件
CHECK_CUTOFF CheckCutoffTask 检查数据截止时间
SEED_DWS_CONFIG SeedDwsConfigTask 初始化 DWS 配置种子数据
DATA_INTEGRITY_CHECK DataIntegrityTask 数据完整性校验

base_task_mechanism.md（公共机制）

覆盖内容：

  • BaseTask 模板方法流程（execute → build_context → [分段] → extract → transform → load → commit）
  • TaskContext 字段说明
  • 时间窗口计算逻辑（优先级：手动覆盖 > 游标 > 闲忙时段默认值）
  • 窗口分段（build_window_segments）
  • TaskRegistry 注册方式与元数据（TaskMeta: task_class, requires_db_config, layer, task_type）
  • PipelineRunner 管道执行流程
  • 校验框架（Verifier）概述

数据模型

本 spec 不涉及数据模型变更。文档中引用的数据模型均为现有系统中的表结构，包括：

ODS 层表（billiards_ods schema）：

  • settlement_records, table_fee_transactions, assistant_service_records, member_profiles, payment_transactions, refund_transactions 等 20+ 表

DWD 层表（billiards_dwd schema）：

  • 维度表：dim_site, dim_table, dim_assistant, dim_member, dim_member_card_account, dim_tenant_goods, dim_store_goods, dim_goods_category, dim_groupbuy_package（各含 _ex 扩展表）
  • 事实表：dwd_settlement_head, dwd_table_fee_log, dwd_table_fee_adjust, dwd_store_goods_sale, dwd_assistant_service_log, dwd_assistant_trash_event, dwd_member_balance_change, dwd_groupbuy_redemption, dwd_platform_coupon_redemption, dwd_recharge_order, dwd_payment, dwd_refund（各含 _ex 扩展表）

DWS 层表（billiards_dws schema）：

  • 助教域：dws_assistant_daily_detail, dws_assistant_monthly_summary, dws_assistant_customer_stats, dws_assistant_salary_calc, dws_assistant_finance_analysis
  • 会员域：dws_member_consumption_summary, dws_member_visit_detail
  • 财务域：dws_finance_daily_summary, dws_finance_recharge_summary, dws_finance_income_structure, dws_finance_discount_detail
  • 指数域：dws_member_winback_index, dws_member_newconv_index, dws_relation_index, dws_ml_manual_ledger
  • 配置表：cfg_index_parameters, cfg_skill_type, cfg_performance_tier, cfg_level_price, cfg_bonus_rule, cfg_area_category

正确性属性

正确性属性是一种在系统所有有效执行中都应成立的特征或行为——本质上是关于系统应该做什么的形式化陈述。属性是人类可读规范与机器可验证正确性保证之间的桥梁。

由于本 spec 的产出物是文档（Markdown 文件），而非运行时代码，正确性属性主要关注文档的完整性和一致性——即文档是否覆盖了所有已注册任务。

Property 1: ODS 任务文档覆盖完整性 对于所有在 task_registry.py 中注册且 layer="ODS" 的任务代码，ods_tasks.md 中应包含该任务代码的说明章节，并列出其目标表。 Validates: Requirements 2.1, 2.4

Property 2: DWD 任务文档覆盖完整性 对于所有在 task_registry.py 中注册且 layer="DWD" 的任务代码，dwd_tasks.md 中应包含该任务代码的说明章节，并列出其源表和目标表。 Validates: Requirements 3.1

Property 3: DWS 任务文档覆盖完整性 对于所有在 task_registry.py 中注册且 layer="DWS" 的任务代码，dws_tasks.md 中应包含该任务代码的说明章节，并标注其更新策略。 Validates: Requirements 4.1, 4.4

Property 4: INDEX 任务文档覆盖完整性 对于所有在 task_registry.py 中注册且 layer="INDEX" 的任务代码，index_tasks.md 中应包含该任务代码的说明章节。 Validates: Requirements 5.1

Property 5: Utility 任务文档覆盖完整性 对于所有在 task_registry.py 中注册且 task_type="utility" 的任务代码，utility_tasks.md 中应包含该任务代码的说明章节。 Validates: Requirements 6.1

Property 6: CLI 参数文档覆盖完整性 对于所有在 cli/main.py 的 parse_args() 中定义的 CLI 参数，README.md 或 base_task_mechanism.md 中应包含该参数的说明。 Validates: Requirements 7.1

Property 7: 管道类型文档覆盖完整性 对于所有在 PipelineRunner.PIPELINE_LAYERS 中定义的管道类型，README.md 中应包含该管道类型的层组合说明。 Validates: Requirements 7.2

错误处理

本 spec 为文档生成任务，不涉及运行时错误处理。文档编写过程中需注意：

  1. 若源代码中的任务类或注册信息发生变更，文档可能过时——应在 README.md 中注明"最后更新日期"和"基于代码版本"
  2. 若某个任务的 API 端点或参数无法从代码中直接读取（如动态配置），应在文档中标注"参见配置文件"

测试策略

单元测试（示例验证）：

  • 验证所有 7 个 Markdown 文件存在于 docs/etl_tasks/ 目录下
  • 验证 README.md 包含指向其他 6 个文件的链接
  • 验证每个分层文件中包含对应层的所有已注册任务代码

属性测试（覆盖完整性验证）：

  • 使用 pytest 编写脚本，从 task_registry.py 动态读取已注册任务列表
  • 解析对应的 Markdown 文件，检查每个任务代码是否出现在文档中
  • 从 cli/main.py 解析 CLI 参数列表，检查文档中是否覆盖
  • 属性测试库：pytest（本项目已使用），配合 parametrize 实现参数化验证
  • 每个属性测试标注对应的设计属性编号

测试标注格式：

# Feature: etl-task-documentation, Property 1: ODS 任务文档覆盖完整性
def test_ods_task_coverage():
    ...

由于本 spec 的产出物是静态文档，属性测试的核心价值在于确保文档与代码的一致性，防止文档遗漏任务。测试应在文档生成后运行一次即可，无需持续集成。

Reference in New Issue View Git Blame Copy Permalink