root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b25308c3f4481a8e66abd388fdd621fd510b0bbe
Neo-ZQYY/.kiro/specs/dataflow-field-completion/tasks.md

18 KiB
Raw Blame History

实现计划：数据流字段补全与前后端联调

概述

按"先排查确认 → 再 DDL 变更 → 再代码映射 → 再移除废弃表 → 再 DWS 汇总 → 再文档精化 → 最后联调"的顺序，分阶段推进。每个表的字段补全遵循"先确认再新增"原则。

执行依据：export/SYSTEM/REPORTS/field_audit/field_review_for_user.md（逐表逐字段排查结论）

任务

  • 1. 字段排查脚本与基础设施

    • 1.1 编写字段排查脚本 scripts/ops/field_audit.py

      • 连接数据库，对每张目标表执行排查流程：查 DWD 现有列、查 FACT_MAPPINGS 现状、查 ODS 列、查自动映射
      • 输出排查记录表（markdown 格式），标注每个字段的排查结论和建议操作
      • 覆盖 11 张表的所有疑似缺失字段
      • Requirements: 1.1-1.4, 2.1-2.3, 3.1-3.3, 4.1-4.3, 5.1-5.3, 6.1-6.4, 7.1-7.4, 8.1-8.4, 9.1-9.3, 10.1-10.5, 11.1-11.3

    • 1.2 执行排查脚本，生成排查报告

      • 运行脚本，审查输出结果
      • Requirements: 1.1-1.4

    • 1.3 逐字段调查与推测，确认排查结论（由 Kiro 执行）

      • 结论文档：export/SYSTEM/REPORTS/field_audit/field_review_for_user.md
      • 脚本输出仅为线索，不能直接作为最终结论
      • 对脚本标记为"缺失"或"对不齐"的每个字段，Kiro 需逐一执行以下调查：
        • 查阅 FACT_MAPPINGS 源码，确认是否已以其他名称/表达式映射
        • 查阅 DWD DDL，确认是否已有同语义列（命名差异）
        • 查阅 ODS loader 代码，确认 ODS 列是否真实写入
        • 结合字段命名规律、上下文语义、业务逻辑进行推测
        • 必要时查询数据库实际数据（SELECT DISTINCT / 采样）辅助判断
      • 对每个字段标注最终决策：无需变更 / 仅补映射 / 新增列+映射 / 跳过（附理由）
      • 将调查过程和推测依据记录到排查报告中，确保可追溯
      • Requirements: 1.1-1.4, 2.1-2.3, 3.1-3.3, 4.1-4.3, 5.1-5.3, 6.1-6.4, 7.1-7.4, 8.1-8.4, 9.1-9.3, 10.1-10.5, 11.1-11.3

  • 2. Checkpoint - 排查结果确认

    • 此项已完成，最终文档为：export/SYSTEM/REPORTS/field_audit/field_review_for_user.md

  • 3. 🔴 映射错误修复（高优先级）

    • 依据：field_review_for_user.md 映射错误修复章节

    • 3.1 assistant_service_records — site_assistant_id 映射错误修正

      • 当前问题：DWD dwd_assistant_service_log.site_assistant_id 错误映射自 ODS order_assistant_id（订单级 ID），应映射自 ODS site_assistant_id（助教档案 ID）
      • 修正 FACT_MAPPINGS：将 DWD site_assistant_id 的 ODS 源从 order_assistant_id 改为 site_assistant_id
      • 新增 DWD 列 order_assistant_id（bigint）到 dwd_assistant_service_log，映射 ODS order_assistant_id
      • 编写迁移脚本
      • 需重新加载历史数据
      • Requirements: 2.1, 2.2

    • 3.2 store_goods_sales_records — discount_price 列名误导修正

      • 当前问题：DWD discount_price 实际映射自 ODS discount_money（折扣金额），而非 ODS discount_price（折后单价）
      • 将 DWD 列名 discount_price 重命名为 discount_money
      • 新增 DWD 列 discount_price（numeric），映射 ODS discount_price（折后单价）
      • 编写迁移脚本
      • Requirements: 4.1, 4.2

    • 3.3 store_goods_master — batch_stock_qty 和 provisional_total_cost 映射源修正

      • batch_stock_qty 的 FACT_MAPPINGS 从 stock（当前库存）改为 batch_stock_quantity（批次库存）
      • provisional_total_cost 的 FACT_MAPPINGS 从 total_purchase_cost（实际采购成本）改为 provisional_total_cost（暂估成本）
      • 需重新加载历史数据
      • Requirements: 10.3

  • 4. A 类表：新增 DWD 列 + FACT_MAPPINGS

    • 依据：field_review_for_user.md 各表"待新增/补映射字段"

    • 4.1 assistant_accounts_master — 新增 4 个字段到 dim_assistant_ex

      • 新增列：system_role_id（bigint）、job_num（text）、cx_unit_price（numeric(18,2)）、pd_unit_price（numeric(18,2)）
      • 更新 dwd.sql，添加 FACT_MAPPINGS 条目
      • 编写迁移脚本
      • Requirements: 1.1, 1.2, 1.3

    • 4.2 assistant_service_records — 新增 2 个字段到 dwd_assistant_service_log_ex

      • 新增列：operator_id（bigint）、operator_name（text）
      • 跳过 siteprofile（jsonb 嵌套列）
      • 更新 dwd.sql，添加 FACT_MAPPINGS 条目
      • 编写迁移脚本
      • Requirements: 2.1, 2.2

    • 4.3 assistant_cancellation_records — 更新 FACT_MAPPINGS

      • 更新映射：ODS assistanton → DWD dwd_assistant_trash_event.assistant_no
      • 跳过 siteprofile（jsonb 嵌套列）
      • Requirements: 3.1

    • 4.4 member_balance_changes — 新增 1 个字段到 dwd_member_balance_change_ex

      • 新增列：relate_id（bigint）— 关联业务单据 ID
      • 更新 dwd.sql，添加 FACT_MAPPINGS 条目
      • 编写迁移脚本
      • Requirements: 5.1, 5.2

    • 4.5 site_tables_master — 新增 14 个字段到 dim_table_ex

      • 新增列：create_time（timestamptz）、light_status（integer）、tablestatusname（text）、sitename（text）、appletQrCodeUrl（text）、audit_status（integer）、charge_free（integer）、delay_lights_time（integer）、is_rest_area（integer）、only_allow_groupon（integer）、order_delay_time（integer）、self_table（integer）、temporary_light_second（integer）、virtual_table（integer）
      • 更新 dwd.sql，添加 FACT_MAPPINGS 条目
      • 编写迁移脚本
      • Requirements: 9.1, 9.2

    • 4.6 tenant_goods_master — 无需变更（跳过）

      • commoditycode 与 commodity_code 100% 冗余（花括号包裹格式），已确认跳过
      • Requirements: 11.1（已确认无需操作）

    • 4.7 编写 A 类表字段映射属性测试

      • Property 1: FACT_MAPPINGS 字段映射正确性
      • Validates: Requirements 1.1, 1.2, 2.1, 3.1, 4.1, 5.1, 9.1

  • 5. B 类表：仅补 FACT_MAPPINGS / 修正映射

    • 依据：field_review_for_user.md B 类表章节

    • 5.1 recharge_settlements — 补充 5 个 FACT_MAPPINGS 条目

      • 仅补映射（DWD 列已存在，ODS/DWD 两侧数据全为 0，业务未启用）：
        • plcouponsaleamount → pl_coupon_sale_amount
        • mervousalesamount → mervou_sales_amount
        • electricitymoney → electricity_money
        • realelectricitymoney → real_electricity_money
        • electricityadjustmoney → electricity_adjust_money
      • 无需 DDL 变更，无需迁移脚本
      • Requirements: 6.1, 6.2, 6.3

    • 5.2 编写 B 类表属性测试

      • Property 2: FACT_MAPPINGS 引用完整性
      • Validates: Requirements 6.3

  • 5.5. Checkpoint - 映射修复与 A/B 类表完成确认

    • 确保所有映射错误已修正、A/B 类表的 FACT_MAPPINGS、DDL、迁移脚本都已更新
    • Ask the user if questions arise.

  • 6. C 类表：新建 DWD 表与完整映射

    • 依据：field_review_for_user.md C 类表章节

    • 6.1 goods_stock_summary — 修改 ODS 配置 + 新建 DWD 表

      • 步骤 1：修改 ODS 任务配置 requires_window=True + time_fields=("startTime", "endTime")
      • 步骤 2：重新采集历史数据（按时间窗口分批）
      • 步骤 3：编写 DDL 创建 dwd.dwd_goods_stock_summary（14 个字段）
      • 步骤 4：在 TABLE_MAP 中注册，在 FACT_MAPPINGS 中添加映射
      • 步骤 5：创建 DWD loader 和 task 代码
      • 编写迁移脚本
      • Requirements: 7.1, 7.2, 7.3

    • 6.2 goods_stock_movements — 新建 DWD 表

      • 编写 DDL 创建 dwd.dwd_goods_stock_movement（19 个字段，事实表，按 createtime 增量加载）
      • 在 TABLE_MAP 中注册，在 FACT_MAPPINGS 中添加映射（驼峰 → 蛇形命名）
      • 创建 DWD loader 和 task 代码
      • 编写迁移脚本
      • Requirements: 8.1, 8.2, 8.3

    • 6.3 编写 C 类表属性测试

      • Property 3: TABLE_MAP 覆盖完整性
      • Validates: Requirements 7.2, 8.2

  • 7. Checkpoint - 全部字段补全完成

    • 确保所有 11 张表的字段补全工作完成，所有测试通过，ask the user if questions arise.

  • 7.3. 彻底移除 settlement_ticket_details

    • 7.3.1 移除 ETL 核心代码中的 settlement_ticket_details

      • 从 tasks/ods/ods_tasks.py 中移除：OdsTaskSpec("ODS_SETTLEMENT_TICKET", ...)、OdsSettlementTicketTask 类、ENABLED_ODS_CODES 中的条目、ODS_TASK_CLASSES 覆盖
      • 从 tasks/verification/dwd_verifier.py 中移除主键映射条目
      • 从 tasks/verification/ods_verifier.py 中移除相关注释和特殊处理
      • 从 tasks/utility/manual_ingest_task.py 中移除表映射和配置
      • 从 utils/json_store.py 中移除 /order/getordersettleticketnew 路径映射
      • Requirements: 17.1, 17.3

    • 7.3.2 移除 DDL、种子数据和迁移脚本

      • 从 db/etl_feiqiu/schemas/ods.sql 和 schema_ODS_doc.sql 中移除建表语句和注释
      • 从 db/etl_feiqiu/seeds/seed_ods_tasks.sql 中移除 ODS_SETTLEMENT_TICKET
      • 编写迁移脚本：DROP TABLE IF EXISTS ods.settlement_ticket_details、DROP INDEX、DELETE FROM meta.ods_task_registry
      • Requirements: 17.2, 17.4, 17.6

    • 7.3.3 移除分析脚本和工具中的引用

      • 从 scripts/ops/ 下移除：gen_full_dataflow_doc.py、gen_field_review_doc.py、gen_api_field_mapping.py、field_audit.py、export_dwd_field_review.py、dataflow_analyzer.py、check_ods_latest_indexes.py 中的相关引用
      • 从 scripts/check/check_ods_gaps.py 中移除 _check_settlement_tickets 函数及调用
      • 从 scripts/debug/debug_blackbox.py 中移除跳过逻辑
      • Requirements: 17.7

    • 7.3.4 移除文档和测试中的引用

      • 从 docs/database/etl_feiqiu_schema_migration.md 中移除索引条目
      • 从 apps/etl/connectors/feiqiu/docs/etl_tasks/ 中移除任务表格条目
      • 从 tests/unit/test_ods_tasks.py 中移除 test_ods_settlement_ticket_by_payment_relate_ids
      • Requirements: 17.5, 17.8

  • 7.5. DWS 库存汇总（日/周/月）

    • 前置依赖：任务 6.1（goods_stock_summary DWD 表）完成、ODS 任务配置修改（requires_window=True）完成并重新采集数据

    • 7.5.1 编写 DWS 库存汇总 DDL 与迁移脚本

      • 在 db/etl_feiqiu/schemas/dws.sql 中添加三张表的建表语句：dws_goods_stock_daily_summary、dws_goods_stock_weekly_summary、dws_goods_stock_monthly_summary
      • 编写迁移脚本 db/etl_feiqiu/migrations/{date}__create_dws_goods_stock_summary.sql
      • 主键：(site_id, stat_date, site_goods_id)
      • 字段：site_id, tenant_id, stat_date, site_goods_id, goods_name, goods_unit, goods_category_id, goods_category_second_id, category_name, range_start_stock, range_end_stock, range_in, range_out, range_sale, range_sale_money, range_inventory, current_stock, stat_period, created_at, updated_at
      • Requirements: 12.5, 12.6, 12.8

    • 7.5.2 实现 DWS_GOODS_STOCK_DAILY 任务

      • 在 apps/etl/connectors/feiqiu/tasks/dws/ 下创建 goods_stock_daily_task.py
      • 继承 BaseDwsTask，实现 extract / transform / load 三阶段
      • extract：从 dwd.dwd_goods_stock_summary 按时间范围查询
      • transform：按日粒度汇总，stat_period='daily'
      • load：upsert 写入 dws.dws_goods_stock_daily_summary
      • Requirements: 12.2, 12.7

    • 7.5.3 实现 DWS_GOODS_STOCK_WEEKLY 任务

      • 创建 goods_stock_weekly_task.py，按 ISO 周分组，stat_date = 周一日期，stat_period='weekly'
      • Requirements: 12.3, 12.7

    • 7.5.4 实现 DWS_GOODS_STOCK_MONTHLY 任务

      • 创建 goods_stock_monthly_task.py，按自然月分组，stat_date = 月首日期，stat_period='monthly'
      • Requirements: 12.4, 12.7

    • 7.5.5 注册 DWS 库存汇总任务到任务调度

      • 在任务注册表中添加 DWS_GOODS_STOCK_DAILY、DWS_GOODS_STOCK_WEEKLY、DWS_GOODS_STOCK_MONTHLY
      • 确保任务依赖关系正确（依赖 DWD goods_stock_summary 加载完成）
      • Requirements: 12.9

    • 7.5.6 编写 DWS 库存汇总属性测试

      • Property 8: DWS 库存汇总粒度聚合正确性
      • Validates: Requirements 12.2, 12.3, 12.4, 12.5, 12.6

  • 8. 文档精化

    • 8.1 精化 A/B/C 类表涉及的 BD_Manual 文档

      • 逐个文档、逐项排查所有"待补充""待处理""未确定""未定义"等缺失内容
      • 将"金额字段""XX 相关""XXX 类"等粗略说明替换为精确的字段语义描述
      • 通过字段名称分析、上下文推测、遍历值/枚举值分析、代码取用情况分析确定字段含义
      • 确保每个字段说明包含：字段类型、业务含义、取值范围或枚举值、在代码中的使用位置
      • Requirements: 13.1, 13.2, 13.3, 13.4

    • 8.2 更新 dataflow 分析报告中涉及表的字段说明

      • 同步更新 docs/database/ 下对应的文档
      • Requirements: 1.4, 2.3, 3.3, 4.3, 5.3, 6.4, 7.4, 8.4, 9.3, 10.5, 11.3

  • 9. Checkpoint - 文档精化完成

    • 确保所有文档更新完毕，无遗留的"待补充"标记，ask the user if questions arise.

  • 10. Admin-Web 前后端联调

    • 10.1 排查并修复后端 ETL 执行 API

      • 检查 apps/backend/app/routers/ 中 ETL 执行相关路由
      • 确保参数解析正确：全部门店、api_full、仅校验修复且校验前从 API 获取、自定义范围 2025-11-01 至 2026-02-20、窗口切分 10 天、force-full、全选常用功能
      • 确保参数正确转换为 ETL CLI 命令
      • Requirements: 14.1, 14.2

    • 10.2 排查并修复前端 TaskManager 页面

      • 检查 apps/admin-web/src/pages/TaskManager.tsx 中的参数配置表单
      • 确保所有参数选项可正确选择和提交
      • 确保任务执行状态实时展示（WebSocket 日志流）
      • Requirements: 14.3

    • 10.3 实现 ETL 执行计时器模块

      • 在 apps/etl/connectors/feiqiu/utils/ 中新增计时器工具
      • 记录每个步骤和分步骤的开始时间、结束时间、耗时（精确到毫秒）
      • 全部任务完成后输出计时结果文档
      • Requirements: 15.1, 15.2, 15.3

    • 10.4 编写计时器属性测试

      • Property 7: 计时器记录完整性
      • Validates: Requirements 15.2

    • 10.5 编写 ETL 参数解析属性测试

      • Property 5: ETL 参数解析与 CLI 命令构建正确性
      • Validates: Requirements 14.1, 14.2

  • 11. 黑盒测试机制

    • 11.1 实现数据一致性检查器

      • 在 apps/etl/connectors/feiqiu/quality/ 中新增一致性检查模块
      • 实现 API 源数据 vs ODS 落库数据的字段完整性对比
      • 实现 ODS 数据 vs DWD 落库数据的映射正确性对比
      • 输出黑盒测试报告（每张表的检查结果、差异明细、通过/失败状态）
      • Requirements: 16.1, 16.2, 16.3, 16.4

    • 11.2 编写数据一致性检查属性测试

      • Property 6: 数据一致性检查正确性
      • Validates: Requirements 16.2, 16.3

  • 12. 端到端联调验证

    • 12.1 执行完整 ETL 流程并验证数据正确性

      • 将 EtlTimer 集成到 orchestration/flow_runner.py 的 FlowRunner.run() 方法中
      • 增量 ETL 和校验分支均包裹计时步骤（INCREMENT_ETL、VERIFICATION、FETCH_BEFORE_VERIFY）
      • timer.finish(write_report=True) 在 Flow 结束时自动输出计时报告到 ETL_REPORT_ROOT
      • 产出物：export/ETL-Connectors/feiqiu/REPORTS/etl_timing_*.md
      • Requirements: 14.4, 15.3

    • 12.2 执行黑盒测试并生成报告

      • 将 ConsistencyChecker 集成到 FlowRunner.run() 的 _run_post_consistency_check() 方法中
      • ETL Flow 完成后自动运行一致性检查（API vs ODS + ODS vs DWD），输出报告到 ETL_REPORT_ROOT
      • 独立验证脚本 scripts/ops/run_post_etl_reports.py 确认报告生成正常
      • 实际执行结果：API vs ODS 22/22 通过，ODS vs DWD 38/42 通过
      • 产出物：export/ETL-Connectors/feiqiu/REPORTS/consistency_report_*.md
      • Requirements: 16.1, 16.4

    • 12.3 前后端浏览器联调验证（2026-02-20）

      • 启动后端 uvicorn app.main:app --reload（localhost:8000）+ 前端 pnpm dev（localhost:5173）
      • 浏览器登录管理后台，进入"任务配置"页面
      • 配置：Flow=ods_dwd, 处理模式=仅增量, dry-run=✓, 本地JSON=✓, 回溯24h
      • 点击"直接执行"→ 自动跳转"任务管理 > 历史"tab
      • 验证结果：status=success, duration=22.5s, exit_code=0
      • CLI 命令正确构建：python -m cli.main --flow ods_dwd --processing-mode increment_only --tasks DWD_LOAD_FROM_ODS --lookback-hours 24 --overlap-seconds 600 --dry-run --data-source offline --store-id 2790685415443269
      • 执行日志实时推送到前端 Modal（WebSocket /ws/logs/{id}）✅
      • 计时报告自动生成：etl_timing_20260220_073610.md（2步骤，总耗时20.78s）✅
      • 一致性检查报告自动生成：consistency_report_20260220_073610.md ✅
      • Requirements: 14.1, 14.2, 14.3, 14.4, 15.3, 16.4

  • 13. Final checkpoint - 全部完成

    • 确保所有字段补全、文档精化、前后端联调、黑盒测试均已完成，ask the user if questions arise.

备注

  • 标记 * 的任务为可选，可跳过以加速 MVP
  • 每个任务引用具体需求编号以确保可追溯
  • Checkpoint 确保增量验证
  • 属性测试验证通用正确性属性，单元测试验证具体示例和边界情况
  • 所有涉及 loaders/、tasks/、db/ 的变更属于高风险路径，完成后需触发 /audit
Reference in New Issue View Git Blame Copy Permalink