Neo-ZQYY/docs/audit/changes/2026-03-01__dwd-cleanup-ods-fix-dim-staff-repair.md

审计记录：DWD 清理 + ODS 商品销售修复 + dim_staff_ex 修复

日期：2026-03-01 02:27:26 Prompt-ID：P20260301-021708 审计触发原因：root-file, dir:admin-web, dir:backend, dir:etl, dir:miniprogram, dir:db, db-schema-change, dir:shared 变更规模：226 files changed, 9454 insertions(+), 217885 deletions(-)

---

变更概述

本次为跨模块大批量变更，核心工作包括三个独立任务：

1. assistant_trash_event 残留清理：已 DROP 的表（2026-02-22）的代码引用和 DDL 文档残留清理
2. ODS_STORE_GOODS_SALES 窗口配置修复：requires_window=False → True，恢复商品销售数据拉取
3. dim_staff_ex FACT_MAPPINGS 列名修复：驼峰列名 → 下划线列名，修复 SCD2 合并失败

同时包含前序累积的多模块变更（admin-web 营业日功能、backend 新路由/服务、miniprogram 认证流程、shared datetime_utils 等）。

---

本次对话文件变更

新增文件

• docs/audit/prompt_logs/prompt_log_20260301_021708.md — 本次对话的 Prompt 日志
• docs/database/BD_Manual_20260301_cleanup_and_fixes.md — DB 变更手册（三项修复）

修改文件（本次对话期间）

• apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py — dim_staff_ex FACT_MAPPINGS 列名修复
• apps/etl/connectors/feiqiu/tasks/ods/ods_tasks.py — ODS_STORE_GOODS_SALES 窗口配置修复
• docs/database/ddl/etl_feiqiu__dwd.sql — 移除 assistant_trash_event 残留约束/索引
• docs/database/ddl/etl_feiqiu__ods.sql — 移除 assistant_cancellation_records 残留约束/索引
• docs/prd/specs/dwd-amount-duration-calibration.md — 移除 assistant_trash_event 章节

---

高风险文件分类

admin-web（6 文件）

营业日功能集成：App.tsx 初始化 businessDayStore、TaskConfig.tsx 添加 BusinessDayHint 组件、TaskManager.tsx 添加历史任务终止按钮。新增 businessDay.ts API、BusinessDayHint.tsx 组件、businessDayStore.ts 状态管理。

backend（20 文件）

• 配置：新增 WX_APPID/WX_SECRET/WX_DEV_MODE/BUSINESS_DAY_START_HOUR
• 路由：member_birthday → member_retention_clue 重构；新增 admin_applications、business_day、xcx_tasks、xcx_notes
• 服务：新增 task_generator、task_expiry、recall_detector、note_reclassifier、trigger_scheduler
• 认证：xcx_auth 新增 dev-login 端点，用户状态 pending → new/pending 分离
• main.py：lifespan 注册触发器 job handler

etl（14 文件）

• config：defaults/env_parser/settings 小幅调整
• orchestration：flow_runner 调整
• quality：consistency_checker 移除 assistant_cancellation_records 引用
• tasks/dwd：dwd_load_task.py dim_staff_ex 列名修复
• tasks/ods：ods_tasks.py ODS_STORE_GOODS_SALES 窗口修复
• tasks/dws：多个 DWS 任务调整（assistant_customer/daily/finance/monthly）
• scripts：多个脚本清理 assistant_trash_event 引用

db（2 文件）

• db/fdw/setup_fdw_reverse.sql / setup_fdw_reverse_test.sql：FDW 配置更新

---

合规检查

检查项	状态
BD Manual 文档	✅ 已创建 BD_Manual_20260301_cleanup_and_fixes.md
DDL 基线同步	✅ 已更新 etl_feiqiu__dwd.sql + etl_feiqiu__ods.sql
新增迁移 SQL	无（本次为文档清理 + 代码修复，无新增迁移）
API 接口变更	否（api_changed=false）
OpenAPI Spec	无需同步（openapi_spec_stale=false）
ETL 任务文档同步	⚠️ 已补齐（见下方文档校对段落）

---

文档校对补齐

1. apps/etl/connectors/feiqiu/tasks/ods/ods_tasks.py → ETL 任务文档

• 更新 apps/etl/connectors/feiqiu/docs/etl_tasks/ods_tasks.md：ODS_STORE_GOODS_SALES 的「需要窗口」列从「否」改为「是」，反映 requires_window=True 修复

2. apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py → ETL 任务文档

• 更新 apps/etl/connectors/feiqiu/docs/etl_tasks/dwd_tasks.md：
  • 移除事实表映射中的 dwd_assistant_trash_event / _ex 两行
  • 新增 dim_staff / dim_staff_ex 维度映射（已存在但确认无误）
  • 映射总数从 40 对调整为 38 对

---

改动注解

apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py

• 变更类型：修改
• 原始原因：dim_staff_ex 表始终为 0 行，排查发现 FACT_MAPPINGS 中 ODS 列名使用驼峰风格（如 cashierpointid），但 ODS 表 staff_info_master 实际列名为下划线风格（cashier_point_id），导致 SCD2 合并 SQL 执行报错，整表被静默跳过
• 思路分析：修正 7 个字段的 ODS 列名映射（驼峰 → 下划线），使 SQL 查询能正确引用 ODS 列。选择直接修改映射而非添加别名，因为 ODS 表列名已经是标准下划线风格
• 修改结果：dim_staff_ex 从 0 行恢复到 15 行（与 dim_staff 一致），SCD2 合并正常执行。影响范围仅限 DWD 装载流程中 dim_staff_ex 的处理

apps/etl/connectors/feiqiu/tasks/ods/ods_tasks.py

• 变更类型：修改
• 原始原因：dwd_store_goods_sale 数据停滞在 2025-12-19（手动导入），排查发现 ODS_STORE_GOODS_SALES 的 requires_window=False 导致 API /TenantGoods/GetGoodsSalesList 不传时间参数，始终返回 0 条记录
• 思路分析：将 requires_window 改为 True 并添加 time_fields=("startTime", "endTime")，使 API 请求携带时间窗口参数。这与其他需要时间窗口的 ODS 任务（如 ODS_SETTLEMENT_RECORDS）保持一致
• 修改结果：ODS 层新增 26,759 条商品销售记录，DWD 层 dwd_store_goods_sale 数据延伸至 2026-02-25。后续 DWS 层商品相关报表数据将恢复完整

docs/database/ddl/etl_feiqiu__dwd.sql

• 变更类型：修改
• 原始原因：dwd_assistant_trash_event 和 _ex 表已于 2026-02-22 DROP，但 DDL 基线文件中仍残留 PK 约束和索引定义
• 思路分析：移除已不存在表的约束和索引行，保持 DDL 基线与数据库实际状态一致
• 修改结果：DDL 基线文件清理完毕，不再包含已删除表的引用

docs/database/ddl/etl_feiqiu__ods.sql

• 变更类型：修改
• 原始原因：上游 ODS 表 assistant_cancellation_records 已同步 DROP，DDL 基线残留 PK 约束和索引
• 思路分析：同上，清理残留定义
• 修改结果：DDL 基线文件清理完毕

docs/prd/specs/dwd-amount-duration-calibration.md

• 变更类型：修改
• 原始原因：文档中包含已删除的 dwd_assistant_trash_event 表的章节（2.11）、存疑字段和数据新鲜度行
• 思路分析：移除与已删除表相关的所有文档段落，避免误导
• 修改结果：文档不再引用已删除的表

docs/audit/prompt_logs/prompt_log_20260301_021708.md

• 变更类型：新增
• 原始原因：审计流程自动记录本次对话的 Prompt 日志，用于变更溯源
• 修改结果：记录了完整的对话上下文转移摘要，包含 5 个任务的状态和详细信息

docs/database/BD_Manual_20260301_cleanup_and_fixes.md

• 变更类型：新增
• 原始原因：本次涉及 db-schema-change（DDL 文档变更 + 数据修复），需按规范创建 BD Manual
• 思路分析：将三个独立修复（trash_event 清理、ODS 窗口修复、dim_staff_ex 列名修复）合并为一份 BD Manual，包含完整的变更说明、兼容性影响、回滚策略和验证 SQL
• 修改结果：BD Manual 文档完整覆盖三项变更，提供 5 条验证 SQL

简要注解（非高风险修改文件）

文件	说明
apps/admin-web/src/App.tsx	启动时初始化 businessDayStore
apps/admin-web/src/pages/TaskConfig.tsx	日期选择区域添加 BusinessDayHint 组件
apps/admin-web/src/pages/TaskManager.tsx	历史任务列表添加终止按钮（running 状态）
apps/backend/app/config.py	新增微信小程序配置项 + 营业日分割点配置
apps/backend/app/main.py	路由注册更新 + lifespan 注册触发器 job handler
apps/backend/app/routers/tasks.py	同步检查添加 ETL_ONLY_EXPECTED 白名单，避免误报
apps/backend/app/routers/xcx_auth.py	新增 dev-login 端点，用户状态 new/pending 分离
apps/backend/app/schemas/xcx_auth.py	新增 DevLoginRequest schema
apps/backend/app/services/application.py	提交申请时自动更新用户状态 new→pending
apps/backend/app/services/wechat.py	微信 code2Session 调用调整

---

DDL/迁移检查

• 新增迁移 SQL：无
• DDL 基线状态：✅ 已同步更新

---

DB 文档对账摘要

• BD Manual 已创建：BD_Manual_20260301_cleanup_and_fixes.md
• 覆盖变更：assistant_trash_event 清理、ODS_STORE_GOODS_SALES 修复、dim_staff_ex 修复
• 验证 SQL：5 条（确认表删除、数据回填、dim_staff_ex 恢复）

注：全量 DB 文档对账需连接测试库执行，本次审计记录中标注待执行状态。因 reasons 含 db-schema-change，全量对账应在后续专项执行。

---

审计完成时间：2026-03-01 02:27:26 (Asia/Shanghai)