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

## 简介

本特性基于 `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 输出黑盒测试报告，包含每张表的检查结果、差异明细、通过/失败状态