Neo-ZQYY/.kiro/specs/dataflow-field-completion/requirements.md

需求文档：数据流字段补全与前后端联调

简介

本特性基于 dataflow_2026-02-19_190440.md 数据流分析报告，完成三大任务：

1. 补全 11 张 ODS/DWD 表中缺失的字段映射（含 DDL 更新、ETL loader/task 代码同步、文档精化）
2. 在 DWS 层新建库存汇总表，支持日/周/月三个粒度的库存数据汇总
3. 管理后台（admin-web）前后端联调，确保 ETL 全流程可通过 Web 界面正确触发和执行

术语表

• ETL_System：飞球连接器 ETL 系统（apps/etl/connectors/feiqiu/），负责从上游 API 抽取数据并经 ODS→DWD→DWS 三层处理
• ODS：Operational Data Store，原始数据层，保留 API 返回的原始字段
• DWD：Data Warehouse Detail，明细数据层，经清洗、标准化后的业务字段
• DDL：Data Definition Language，数据库表结构定义（位于 db/etl_feiqiu/schemas/）
• Loader：ETL 加载器（loaders/），负责将 ODS 数据清洗映射到 DWD 表
• Task：ETL 任务（tasks/），编排 loader 的执行逻辑
• Admin_Web：管理后台（apps/admin-web/），React + Vite + Ant Design 前端
• Backend：FastAPI 后端（apps/backend/），提供 ETL 调度和数据查询 API
• SCD2：缓慢变化维度类型 2，用于维度表历史版本追踪
• BD_Manual：业务数据字典文档（docs/database/），记录字段含义和映射关系
• Field_Mapping：字段映射关系，描述 API JSON → ODS 列 → DWD 列的对应关系
• DWS：Data Warehouse Summary，汇总数据层，按业务维度聚合的统计数据
• BaseDwsTask：DWS 任务基类（tasks/dws/base_dws_task.py），提供 extract/transform/load 三阶段框架

执行依据

本需求文档的字段补全部分基于以下排查结论文档：

• export/SYSTEM/REPORTS/field_audit/field_review_for_user.md — 逐表逐字段的排查结论与操作建议

需求

需求 1：assistant_accounts_master 字段补全

用户故事： 作为数据工程师，我希望将助教账号档案表中 4 个未映射的 ODS 字段（system_role_id、job_num、cx_unit_price、pd_unit_price）补全到 DWD 层，以便下游分析可以使用完整的助教档案数据。

验收标准

1. WHEN ETL_System 执行 assistant_accounts_master 的 DWD 加载任务, THE Loader SHALL 将 ODS 列 system_role_id 映射到 DWD 目标表 dim_assistant_ex 的对应列
2. WHEN ETL_System 执行 assistant_accounts_master 的 DWD 加载任务, THE Loader SHALL 将 ODS 列 job_num、cx_unit_price、pd_unit_price 映射到 DWD 目标表 dim_assistant_ex 的对应列
3. WHEN 新字段被添加到 DWD 表, THE DDL SHALL 在 db/etl_feiqiu/schemas/dwd.sql 中包含对应的 ALTER TABLE 或 CREATE 语句
4. WHEN 字段映射完成后, THE BD_Manual SHALL 更新对应的字段说明文档，消除"待补充""待分析"等模糊描述

需求 2：assistant_service_records 字段补全

用户故事： 作为数据工程师，我希望将助教服务流水表中 3 个未映射的 ODS 字段（site_assistant_id、operator_id、operator_name）补全到 DWD 层，以便追踪服务操作员信息。

验收标准

1. WHEN ETL_System 执行 assistant_service_records 的 DWD 加载任务, THE Loader SHALL 将 ODS 列 site_assistant_id、operator_id、operator_name 映射到 DWD 目标表 dwd_assistant_service_log_ex 的对应列
2. WHEN 新字段被添加到 DWD 表, THE DDL SHALL 在 dwd.sql 中包含对应的列定义
3. WHEN 字段映射完成后, THE BD_Manual SHALL 更新对应的字段说明文档

需求 3：assistant_cancellation_records 字段补全

用户故事： 作为数据工程师，我希望将助教废除记录表中 1 个未映射的 ODS 字段（assistanton）补全到 DWD 层。

验收标准

1. WHEN ETL_System 执行 assistant_cancellation_records 的 DWD 加载任务, THE Loader SHALL 将 ODS 列 assistanton 映射到 DWD 目标表 dwd_assistant_trash_event_ex 的对应列
2. WHEN 新字段被添加到 DWD 表, THE DDL SHALL 在 dwd.sql 中包含对应的列定义
3. WHEN 字段映射完成后, THE BD_Manual SHALL 对 assistanton 字段进行语义分析并补充精确说明

需求 4：store_goods_sales_records 字段补全

用户故事： 作为数据工程师，我希望将门店商品销售流水表中 1 个未映射的 ODS 字段（discount_price）补全到 DWD 层，以便分析折后单价。

验收标准

1. WHEN ETL_System 执行 store_goods_sales_records 的 DWD 加载任务, THE Loader SHALL 将 ODS 列 discount_price 映射到 DWD 目标表 dwd_store_goods_sale_ex 的对应列
2. WHEN 新字段被添加到 DWD 表, THE DDL SHALL 在 dwd.sql 中包含对应的列定义，类型为 numeric（金额精度）
3. WHEN 字段映射完成后, THE BD_Manual SHALL 更新对应的字段说明文档

需求 5：member_balance_changes 字段补全

用户故事： 作为数据工程师，我希望将会员余额变动表中 1 个未映射的 ODS 字段（relate_id）补全到 DWD 层，以便关联充值记录或订单。

验收标准

1. WHEN ETL_System 执行 member_balance_changes 的 DWD 加载任务, THE Loader SHALL 将 ODS 列 relate_id 映射到 DWD 目标表 dwd_member_balance_change_ex 的对应列
2. WHEN 新字段被添加到 DWD 表, THE DDL SHALL 在 dwd.sql 中包含对应的列定义
3. WHEN 字段映射完成后, THE BD_Manual SHALL 更新对应的字段说明文档

需求 6：recharge_settlements 字段补全与映射建立

用户故事： 作为数据工程师，我希望将充值结算表中 5 个 ODS→DWD 未映射字段补全，并为 5 个 DWD 无 ODS 源字段建立正确的映射关系，以便电费和券销售额数据完整流转。

验收标准

1. WHEN ETL_System 执行 recharge_settlements 的 DWD 加载任务, THE Loader SHALL 将 ODS 列 electricityadjustmoney、electricitymoney、mervousalesamount、plcouponsaleamount、realelectricitymoney 映射到 DWD 目标表 dwd_recharge_order 的对应列
2. WHEN DWD 表存在无 ODS 源的列（pl_coupon_sale_amount、mervou_sales_amount、electricity_money、real_electricity_money、electricity_adjust_money）, THE Loader SHALL 建立从 ODS 对应列到这些 DWD 列的映射关系
3. WHEN 映射建立后, THE ETL_System SHALL 确保 ODS 列名（驼峰式）与 DWD 列名（蛇形式）之间的命名转换正确
4. WHEN 字段映射完成后, THE DDL SHALL 同步更新，THE BD_Manual SHALL 更新对应的字段说明文档

需求 7：goods_stock_summary 新建 DWD 表与字段映射

用户故事： 作为数据工程师，我希望为库存汇总表新建 DWD 目标表，并将 14 个 ODS 字段完整映射，以便库存数据可在 DWD 层使用。

验收标准

1. WHEN ETL_System 需要加载 goods_stock_summary 数据到 DWD 层, THE DDL SHALL 在 dwd.sql 中创建新的 DWD 目标表（如 dwd_goods_stock_summary）
2. WHEN DWD 目标表创建后, THE Loader SHALL 将全部 14 个 ODS 列（sitegoodsid、goodsname、goodsunit、goodscategoryid、goodscategorysecondid、categoryname、rangestartstock、rangeendstock、rangein、rangeout、rangesale、rangesalemoney、rangeinventory、currentstock）映射到 DWD 目标表
3. WHEN 新表创建后, THE ETL_System SHALL 创建对应的 DWD loader 和 task 代码
4. WHEN 新表创建后, THE BD_Manual SHALL 为新表编写完整的字段说明文档

需求 8：goods_stock_movements 新建 DWD 表与字段映射

用户故事： 作为数据工程师，我希望为库存变化记录表新建 DWD 目标表，并将 19 个 ODS 字段完整映射，以便库存变动明细可在 DWD 层使用。

验收标准

1. WHEN ETL_System 需要加载 goods_stock_movements 数据到 DWD 层, THE DDL SHALL 在 dwd.sql 中创建新的 DWD 目标表（如 dwd_goods_stock_movement）
2. WHEN DWD 目标表创建后, THE Loader SHALL 将全部 19 个 ODS 列映射到 DWD 目标表
3. WHEN 新表创建后, THE ETL_System SHALL 创建对应的 DWD loader 和 task 代码
4. WHEN 新表创建后, THE BD_Manual SHALL 为新表编写完整的字段说明文档

需求 9：site_tables_master 字段补全

用户故事： 作为数据工程师，我希望将台桌维表中 14 个未映射的 ODS 字段补全到 DWD 层，以便台桌配置信息完整可用。

验收标准

1. WHEN ETL_System 执行 site_tables_master 的 DWD 加载任务, THE Loader SHALL 将 14 个 ODS 列（sitename、appletQrCodeUrl、audit_status、charge_free、create_time、delay_lights_time、is_rest_area、light_status、only_allow_groupon、order_delay_time、self_table、tablestatusname、temporary_light_second、virtual_table）映射到 DWD 目标表 dim_table_ex 的对应列
2. WHEN 新字段被添加到 DWD 表, THE DDL SHALL 在 dwd.sql 中包含对应的列定义
3. WHEN 字段映射完成后, THE BD_Manual SHALL 更新对应的字段说明文档，消除"待补充""待分析"等模糊描述

需求 10：store_goods_master 字段补全与嵌套展开

用户故事： 作为数据工程师，我希望将门店商品档案表中的平层未映射字段、嵌套对象字段、ODS→DWD 未映射字段全部补全，以便商品档案数据完整。

验收标准

1. WHEN ETL_System 执行 store_goods_master 的 ODS 加载任务, THE Loader SHALL 将 API 平层字段 time_slot_sale 映射到 ODS 表的对应列
2. WHEN ETL_System 执行 store_goods_master 的 ODS 加载任务, THE Loader SHALL 将嵌套对象 goodsStockWarningInfo 的 4 个子字段（site_goods_id、sales_day、warning_day_max、warning_day_min）展开并映射到 ODS 表的对应列
3. WHEN ETL_System 执行 store_goods_master 的 DWD 加载任务, THE Loader SHALL 将 ODS 列 batch_stock_quantity、provisional_total_cost 以及展开后的库存预警字段映射到 DWD 目标表（根据字段用途自动分配到 dim_store_goods 或 dim_store_goods_ex）
4. WHEN 新字段被添加, THE DDL SHALL 同步更新 ods.sql 和 dwd.sql
5. WHEN 字段映射完成后, THE BD_Manual SHALL 更新对应的字段说明文档

需求 11：tenant_goods_master 字段补全

用户故事： 作为数据工程师，我希望将租户商品档案表中 1 个未映射的 ODS 字段（commoditycode）补全到 DWD 层。

验收标准

1. WHEN ETL_System 执行 tenant_goods_master 的 DWD 加载任务, THE Loader SHALL 将 ODS 列 commoditycode 映射到 DWD 目标表 dim_tenant_goods_ex 的对应列
2. WHEN 新字段被添加到 DWD 表, THE DDL SHALL 在 dwd.sql 中包含对应的列定义
3. WHEN 字段映射完成后, THE BD_Manual SHALL 更新对应的字段说明文档

需求 12：DWS 库存汇总（日/周/月）

用户故事： 作为数据分析师，我希望在 DWS 层拥有日度、周度、月度三个粒度的库存汇总表，以便按不同时间维度分析商品库存变化趋势。

验收标准

1. WHEN 需求 7（goods_stock_summary 新建 DWD 表）完成且 ODS 任务配置已修改（requires_window=True + time_fields=("startTime", "endTime")）并重新采集数据后, THE ETL_System SHALL 具备构建 DWS 库存汇总的数据基础
2. WHEN ETL_System 执行 DWS_GOODS_STOCK_DAILY 任务, THE ETL_System SHALL 从 DWD 层 dwd_goods_stock_summary 提取数据，按日粒度汇总并写入 dws.dws_goods_stock_daily_summary
3. WHEN ETL_System 执行 DWS_GOODS_STOCK_WEEKLY 任务, THE ETL_System SHALL 从 DWD 层提取数据，按周粒度汇总并写入 dws.dws_goods_stock_weekly_summary
4. WHEN ETL_System 执行 DWS_GOODS_STOCK_MONTHLY 任务, THE ETL_System SHALL 从 DWD 层提取数据，按月粒度汇总并写入 dws.dws_goods_stock_monthly_summary
5. THE DWS 库存汇总表 SHALL 包含以下字段：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（汇总粒度标识：'daily'/'weekly'/'monthly'）
6. THE DWS 库存汇总表 SHALL 以 (site_id, stat_date, site_goods_id) 为主键，支持按门店、日期、商品维度的唯一性约束
7. WHEN DWS 库存汇总任务执行时, THE ETL_System SHALL 继承 BaseDwsTask，实现 extract / transform / load 三阶段
8. WHEN DWS 库存汇总表创建后, THE DDL SHALL 在 db/etl_feiqiu/schemas/dws.sql 中包含建表语句，迁移脚本放在 db/etl_feiqiu/migrations/
9. WHEN DWS 库存汇总任务代码创建后, THE ETL_System SHALL 将任务代码放在 apps/etl/connectors/feiqiu/tasks/dws/ 目录下

需求 17：彻底移除 settlement_ticket_details

用户故事： 作为数据工程师，我希望从项目中彻底移除 settlement_ticket_details（结账小票详情）相关的所有代码、DDL、配置、文档和数据，以便简化系统维护并消除无用的数据流。

验收标准

1. WHEN 移除任务完成后, THE ETL_System SHALL 不再包含 ODS_SETTLEMENT_TICKET 任务代码（从 ods_tasks.py 的 ENABLED_ODS_CODES、ODS_TASK_CLASSES、OdsSettlementTicketTask 类中移除）
2. WHEN 移除任务完成后, THE DDL SHALL 不再包含 ods.settlement_ticket_details 表定义（从 ods.sql / schema_ODS_doc.sql 中移除建表语句和注释）
3. WHEN 移除任务完成后, THE ETL_System SHALL 从以下位置移除所有 settlement_ticket_details 引用：
   • tasks/ods/ods_tasks.py（OdsTaskSpec、OdsSettlementTicketTask 类、ENABLED_ODS_CODES）
   • tasks/verification/dwd_verifier.py、tasks/verification/ods_verifier.py
   • tasks/utility/manual_ingest_task.py
   • utils/json_store.py
   • scripts/check/check_ods_gaps.py
   • scripts/debug/debug_blackbox.py
4. WHEN 移除任务完成后, THE ETL_System SHALL 从 db/etl_feiqiu/seeds/seed_ods_tasks.sql 中移除 ODS_SETTLEMENT_TICKET
5. WHEN 移除任务完成后, THE BD_Manual SHALL 从 docs/database/etl_feiqiu_schema_migration.md 和 ETL 任务文档中移除相关条目
6. WHEN 移除任务完成后, THE ETL_System SHALL 编写迁移脚本 DROP TABLE IF EXISTS ods.settlement_ticket_details 和 DROP INDEX IF EXISTS ods.idx_ods_settlement_ticket_details_latest
7. WHEN 移除任务完成后, THE ETL_System SHALL 从 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）中移除相关引用
8. WHEN 移除任务完成后, THE ETL_System SHALL 从单元测试 tests/unit/test_ods_tasks.py 中移除 test_ods_settlement_ticket_by_payment_relate_ids 测试

需求 13：文档精化

用户故事： 作为数据工程师，我希望对所有涉及的 BD_Manual 文档进行精细化更新，消除所有模糊描述，以便团队成员可以准确理解每个字段的含义。

验收标准

1. WHEN 文档精化任务执行时, THE BD_Manual SHALL 逐个文档、逐项排查所有"待补充""待处理""未确定""未定义"等缺失内容
2. WHEN 文档精化任务执行时, THE BD_Manual SHALL 将"金额字段""XX 相关""XXX 类"等粗略说明替换为精确的字段语义描述
3. WHEN 字段说明需要精化时, THE ETL_System SHALL 通过手动字段名称分析、上下文推测、遍历值/枚举值分析、代码取用情况分析来确定字段含义
4. WHEN 文档更新完成后, THE BD_Manual SHALL 确保每个字段说明包含：字段类型、业务含义、取值范围或枚举值、在代码中的使用位置

需求 14：Admin-Web 前后端联调

用户故事： 作为系统管理员，我希望通过管理后台 Web 界面触发 ETL 全流程执行，以便可视化管理数据处理任务。

验收标准

1. WHEN 管理员在 Admin_Web 中配置 ETL 参数（全部门店、api_full、仅校验修复且校验前从 API 获取、自定义范围 2025-11-01 至 2026-02-20、窗口切分 10 天、force-full、全选常用功能）, THE Backend SHALL 正确接收并解析这些参数
2. WHEN Backend 接收到 ETL 执行请求, THE Backend SHALL 将参数转换为 ETL_System 可识别的命令并触发执行
3. WHEN ETL 任务执行时, THE Admin_Web SHALL 实时展示任务执行状态和进度
4. WHEN 所有选中的任务执行完成后, THE ETL_System SHALL 确保数据处理结果正确（源数据与落库数据/字段一致）

需求 15：ETL 执行计时机制

用户故事： 作为系统管理员，我希望 ETL 执行过程中有详细的计时记录，以便分析各步骤的性能瓶颈。

验收标准

1. WHEN ETL 任务开始执行, THE ETL_System SHALL 启动计时器，记录每个步骤和分步骤的开始时间
2. WHEN 每个步骤完成时, THE ETL_System SHALL 记录该步骤的耗时（精确到毫秒）
3. WHEN 全部任务执行完成后, THE ETL_System SHALL 输出详细颗粒度的计时结果文档，包含每个步骤名称、开始时间、结束时间、耗时

需求 16：黑盒测试机制

用户故事： 作为质量保证工程师，我希望在 ETL 全流程完成后执行黑盒测试，验证数据源与落库数据的一致性。

验收标准

1. WHEN 所有 ETL 步骤顺利完成后, THE ETL_System SHALL 以黑盒测试者角度检查数据源和落库数据/字段情况是否一致
2. WHEN 黑盒测试执行时, THE ETL_System SHALL 对比 API 源数据与 ODS 落库数据的字段完整性
3. WHEN 黑盒测试执行时, THE ETL_System SHALL 对比 ODS 数据与 DWD 落库数据的映射正确性
4. WHEN 黑盒测试完成后, THE ETL_System SHALL 输出黑盒测试报告，包含每张表的检查结果、差异明细、通过/失败状态