Neo-ZQYY/docs/audit/changes/2026-02-27__biz-day-cutoff-prd-sync-check.md

变更审计：营业日分割规则 PRD 同步检查 + 全栈集成收口

• 日期: 2026-02-27 08:11:17
• Prompt-ID: P20260227-075054
• 风险等级: 🔴 高（DB schema + 鉴权 + ETL 配置 + 管理后台 + 小程序 + 共享包）
• 触发原因: root-file, dir:admin-web, dir:backend, dir:etl, dir:miniprogram, dir:db, db-schema-change, dir:shared

---

1. 变更概览

本次审计覆盖 213 个文件（+7873 / -217792 行），核心为营业日分割规则（BUSINESS_DAY_START_HOUR=8）全栈贯通、小程序鉴权流程优化（new→pending→approved 三态）、管理后台任务终止功能、ETL DWS 任务 biz_date 重构、以及大量历史临时文件清理。

用户原始 Prompt：「8:00作为天的分割规则，是否也同步到了 docs/prd/specs 相应的说明中？帮我检查。」

2. 变更范围

2.1 管理后台（admin-web）

• App.tsx：启动时初始化营业日配置 store
• TaskConfig.tsx：日期选择器下方新增 BusinessDayHint 组件
• TaskManager.tsx：历史记录表新增「终止」操作列（running 状态可终止）
• api/businessDay.ts、components/BusinessDayHint.tsx、store/businessDayStore.ts：营业日配置 API + 提示组件 + zustand store（新增文件）

2.2 后端（backend）

• config.py：新增 WX_APPID/WX_SECRET/WX_DEV_MODE/BUSINESS_DAY_START_HOUR 配置项
• main.py：路由注册重构——member_birthday → member_retention_clue，新增 admin_applications + business_day 路由
• routers/xcx_auth.py：用户状态三态（new/pending/approved）+ dev-login mock 端点
• routers/tasks.py：ETL_ONLY_EXPECTED 白名单，避免同步检查误报
• routers/admin_applications.py、routers/business_day.py、routers/member_retention_clue.py：新增路由
• schemas/xcx_auth.py：新增 DevLoginRequest schema
• schemas/member_retention_clue.py：维客线索 schema
• services/application.py：申请提交后自动 new→pending 状态流转
• services/wechat.py：WX_APPID/WX_SECRET 改为模块级常量引用
• middleware/permission.py：权限中间件调整

2.3 ETL（feiqiu connector）

• config/defaults.py + config/env_parser.py + config/settings.py：新增 business_day_start_hour 配置
• orchestration/flow_runner.py：调度逻辑调整
• quality/consistency_checker.py：一致性检查重构（136 行变更）
• tasks/dws/*.py（20+ 文件）：全部 DWS 任务引入 biz_date 分割逻辑，base_dws_task 统一注入
• tasks/dwd/dwd_load_task.py：DWD 加载微调
• tasks/verification/index_verifier.py：指标验证调整

2.4 共享包（shared）

• packages/shared/src/neozqyy_shared/__init__.py：导出新增
• packages/shared/src/neozqyy_shared/datetime_utils.py：新增营业日计算工具（92 行）

2.5 数据库（db）

• db/fdw/setup_fdw_reverse.sql + setup_fdw_reverse_test.sql：FDW 反向映射更新
• DDL 基线多文件更新（etl_feiqiu 六层 + zqyy_app auth/public）

2.6 小程序（miniprogram）

• app.json、app.ts、typings/index.d.ts：应用配置 + 启动逻辑 + 类型定义调整

2.7 根目录

• .env + .env.template：新增 WX_APPID/WX_SECRET/WX_DEV_MODE/BUSINESS_DAY_START_HOUR
• .gitignore：新增忽略规则

3. 风险与回滚

风险点	等级	回滚要点
营业日分割逻辑全栈贯通	🔴 高	回退 BUSINESS_DAY_START_HOUR 配置 + ETL base_dws_task biz_date 注入
用户状态三态（new/pending/approved）	🟡 中	回退 xcx_auth.py + application.py 状态流转逻辑
member_birthday → member_retention_clue 路由替换	🟡 中	恢复 member_birthday 路由注册
DWS 任务批量重构（20+ 文件）	🔴 高	git revert 整批 DWS 任务文件
ETL_ONLY_EXPECTED 白名单	🟢 低	删除白名单集合即可

4. 验证

• 管理后台：启动后检查 BusinessDayHint 是否正确显示营业日分割时间
• 后端：GET /api/business-day/config 返回 {"start_hour": 8}
• ETL：--dry-run 模式验证 DWS 任务 biz_date 计算是否以 08:00 为分割点
• 小程序鉴权：dev-login 端点测试 new→pending→approved 状态流转
• 数据库：检查 DDL 基线与测试库实际结构一致

5. 本次对话文件变更

新增文件

• docs/audit/prompt_logs/prompt_log_20260227_075054.md
• scripts/ops/_check_etl_log_tail.py

删除文件

（无）

6. 合规检查

检查项	状态
文档同步（code_without_docs）	✅ 无缺失
新增迁移 SQL	✅ 无新增
BD_Manual 文档	⚠️ has_bd_manual=false（见 DB 对账段落）
DDL 基线	⚠️ has_ddl_baseline=false
接口变更	✅ api_changed=false
OpenAPI Spec	✅ 已同步

改动注解

apps/admin-web/src/App.tsx

• 变更类型：修改
• 原始原因：营业日分割规则需要在管理后台启动时加载，供日期选择器等组件使用
• 思路分析：在 App 组件 useEffect 中调用 businessDayStore.init()，与 authStore.hydrate 并行执行；降级策略封装在 store 内部，App 层不处理异常
• 修改结果：管理后台启动时自动拉取营业日配置，BusinessDayHint 等下游组件可直接消费 store 数据

apps/admin-web/src/api/businessDay.ts

• 变更类型：新增（非 session_diff.added，为累积变更）
• 原始原因：管理后台需要调用后端营业日配置接口
• 思路分析：封装 GET /api/business-day/config 的 API 调用
• 修改结果：提供 fetchBusinessDayConfig() 供 store 使用

apps/admin-web/src/components/BusinessDayHint.tsx

• 变更类型：新增
• 原始原因：任务配置页日期选择器需要提示用户当前营业日分割时间
• 思路分析：读取 businessDayStore 中的 start_hour，渲染为灰色提示文字
• 修改结果：TaskConfig 页面日期选择器下方显示「营业日以 XX:00 为分割点」提示

apps/admin-web/src/pages/TaskConfig.tsx

• 变更类型：修改
• 原始原因：日期选择区域需要展示营业日分割提示
• 思路分析：在日期范围选择 Row 下方插入 BusinessDayHint 组件，用 Fragment 包裹避免 JSX 单根节点限制
• 修改结果：用户在配置任务日期时可看到营业日分割时间提示

apps/admin-web/src/pages/TaskManager.tsx

• 变更类型：修改
• 原始原因：历史记录中 running 状态的任务需要支持手动终止
• 思路分析：新增 handleCancelHistory 回调 + 操作列（Popconfirm 确认后调用 cancelExecution API）；仅 running 状态显示终止按钮
• 修改结果：管理后台历史记录表支持终止正在运行的任务

apps/admin-web/src/store/businessDayStore.ts

• 变更类型：新增
• 原始原因：营业日配置需要全局状态管理
• 思路分析：zustand store，init() 调用 API 获取配置，失败时降级为默认值 8
• 修改结果：全局可用的营业日配置 store

apps/backend/app/config.py

• 变更类型：修改
• 原始原因：后端需要读取微信小程序配置和营业日分割点配置
• 思路分析：新增 WX_APPID/WX_SECRET/WX_DEV_MODE（微信鉴权）+ BUSINESS_DAY_START_HOUR（营业日分割），均从环境变量读取并提供默认值
• 修改结果：后端配置模块统一管理微信和营业日相关配置

apps/backend/app/main.py

• 变更类型：修改
• 原始原因：路由注册需要反映模块重构（member_birthday→member_retention_clue）和新增路由
• 思路分析：替换 member_birthday 为 member_retention_clue，新增 admin_applications + business_day 路由注册
• 修改结果：后端路由表更新，新增 3 个路由模块

apps/backend/app/routers/tasks.py

• 变更类型：修改
• 原始原因：ETL 同步检查误报——部分 ETL 任务（一次性初始化/未上线）不应出现在差异列表中
• 思路分析：定义 ETL_ONLY_EXPECTED 白名单集合，从 etl_only 差集中排除这些任务
• 修改结果：同步检查不再误报 INIT_*_SCHEMA / SEED_DWS_CONFIG / DWS_ASSISTANT_ORDER_CONTRIBUTION

apps/backend/app/routers/xcx_auth.py

• 变更类型：修改
• 原始原因：小程序鉴权流程优化——新用户应为 new 状态（未提交申请），提交申请后才变为 pending
• 思路分析：引入三态流转（new→pending→approved），新用户 INSERT 时 status='new'；新增 dev-login 端点（仅 WX_DEV_MODE=true 时注册），支持开发环境跳过微信 code2Session
• 修改结果：鉴权流程更精确区分「未申请」和「待审核」状态；开发环境可直接 mock 登录

apps/backend/app/schemas/xcx_auth.py

• 变更类型：修改
• 原始原因：dev-login 端点需要请求 schema
• 思路分析：新增 DevLoginRequest（openid + 可选 status）
• 修改结果：开发模式登录接口有明确的请求校验

apps/backend/app/schemas/member_retention_clue.py

• 变更类型：新增/修改
• 原始原因：member_birthday 重构为 member_retention_clue（维客线索）
• 思路分析：扩展 schema 以支持维客线索的完整字段
• 修改结果：维客线索 API 有完整的请求/响应 schema

apps/backend/app/services/application.py

• 变更类型：修改
• 原始原因：用户提交申请后需要自动将状态从 new 流转为 pending
• 思路分析：在 create_application 末尾新增 UPDATE auth.users SET status='pending' WHERE status IN ('new','rejected')
• 修改结果：申请提交后用户状态自动流转，前端可据此显示「审核中」页面

apps/backend/app/services/wechat.py

• 变更类型：修改
• 原始原因：WX_APPID/WX_SECRET 应从 config 模块级常量读取，而非每次调用时 get()
• 思路分析：改为 from app.config import WX_APPID, WX_SECRET，减少重复环境变量读取
• 修改结果：微信配置读取更高效、更一致

apps/etl/connectors/feiqiu/config/defaults.py

• 变更类型：修改
• 原始原因：ETL 配置需要支持 business_day_start_hour 参数
• 思路分析：在 DEFAULTS["app"] 中新增 business_day_start_hour: 8
• 修改结果：ETL 配置默认值包含营业日分割点

apps/etl/connectors/feiqiu/config/env_parser.py

• 变更类型：修改
• 原始原因：BUSINESS_DAY_START_HOUR 环境变量需要映射到配置路径
• 思路分析：ENV_MAP 新增 BUSINESS_DAY_START_HOUR → app.business_day_start_hour
• 修改结果：环境变量可覆盖默认的营业日分割点

apps/etl/connectors/feiqiu/config/settings.py

• 变更类型：修改
• 原始原因：AppConfig 需要暴露 business_day_start_hour 属性
• 思路分析：新增属性或配置项读取 app.business_day_start_hour
• 修改结果：ETL 任务可通过 AppConfig 获取营业日分割点

apps/etl/connectors/feiqiu/orchestration/flow_runner.py

• 变更类型：修改
• 原始原因：调度逻辑需要适配营业日分割
• 思路分析：flow_runner 调整以传递 biz_date 上下文给下游任务
• 修改结果：ETL 调度链路支持营业日感知

apps/etl/connectors/feiqiu/quality/consistency_checker.py

• 变更类型：修改
• 原始原因：一致性检查需要适配 biz_date 分割逻辑
• 思路分析：大幅重构（136 行变更），检查逻辑按营业日而非自然日对齐
• 修改结果：数据一致性检查与营业日分割规则对齐

apps/etl/connectors/feiqiu/tasks/dws/base_dws_task.py

• 变更类型：修改
• 原始原因：所有 DWS 任务需要统一的 biz_date 计算逻辑
• 思路分析：在 base 类中注入 biz_date 计算（基于 business_day_start_hour），子类自动继承
• 修改结果：DWS 任务基类统一提供营业日分割能力，20+ 子类无需各自实现

DWS 子任务批量变更（简要）

• assistant_customer_task.py、assistant_daily_task.py、assistant_finance_task.py、assistant_monthly_task.py、assistant_order_contribution_task.py：助教相关 DWS 任务适配 biz_date
• finance_base_task.py、finance_discount_task.py、finance_income_task.py、finance_recharge_task.py：财务 DWS 任务适配 biz_date
• goods_stock_daily_task.py、goods_stock_monthly_task.py、goods_stock_weekly_task.py：库存 DWS 任务适配 biz_date
• index/member_index_base.py、index/relation_index_task.py、index/spending_power_index_task.py：指标任务适配 biz_date
• member_consumption_task.py、member_visit_task.py：会员 DWS 任务适配 biz_date
• tasks/verification/index_verifier.py：指标验证适配
• tasks/dwd/dwd_load_task.py：DWD 加载微调

packages/shared/src/neozqyy_shared/datetime_utils.py

• 变更类型：新增
• 原始原因：营业日计算逻辑需要跨模块共享（ETL + 后端 + 未来小程序）
• 思路分析：提供 get_business_date() 等工具函数，以 start_hour 为参数计算当前营业日
• 修改结果：共享包提供统一的营业日计算工具，避免各模块重复实现

apps/backend/app/middleware/permission.py

• 变更类型：修改
• 原始原因：权限中间件需要适配新的用户状态三态
• 思路分析：调整权限检查逻辑以识别 new/pending/approved 状态
• 修改结果：权限中间件正确处理三态用户的访问控制

apps/backend/app/routers/admin_applications.py

• 变更类型：新增
• 原始原因：管理端需要审核用户申请的接口
• 思路分析：提供申请列表查询 + 审批/拒绝操作的 REST 端点
• 修改结果：管理端可查看和处理用户申请

apps/backend/app/routers/business_day.py

• 变更类型：新增
• 原始原因：管理后台需要查询营业日配置
• 思路分析：GET /api/business-day/config 返回 start_hour
• 修改结果：前端可获取营业日分割配置

apps/backend/app/routers/member_retention_clue.py

• 变更类型：新增（替换 member_birthday）
• 原始原因：member_birthday 功能重构为更通用的维客线索模块
• 思路分析：扩展原有生日提醒为完整的维客线索管理
• 修改结果：后端提供维客线索 CRUD 接口

本次对话新增文件

docs/audit/prompt_logs/prompt_log_20260227_075054.md

• 变更类型：新增
• 原始原因：Prompt 审计日志自动记录
• 思路分析：agent-on-stop hook 自动生成
• 修改结果：本次对话的 Prompt 已归档

scripts/ops/_check_etl_log_tail.py

• 变更类型：新增
• 原始原因：运维需要快速查看 ETL 最近日志尾部
• 思路分析：一次性运维脚本，读取 ETL 日志文件末尾内容
• 修改结果：提供便捷的 ETL 日志查看工具

文件清单（Files changed）

共 53 个高风险/业务文件（不含 .kiro 内部、docs/prd、tmp 清理等）：

#	文件	变更类型
1	.env	修改
2	.env.template	修改
3	.gitignore	修改
4	apps/admin-web/src/App.tsx	修改
5	apps/admin-web/src/api/businessDay.ts	新增
6	apps/admin-web/src/components/BusinessDayHint.tsx	新增
7	apps/admin-web/src/pages/TaskConfig.tsx	修改
8	apps/admin-web/src/pages/TaskManager.tsx	修改
9	apps/admin-web/src/store/businessDayStore.ts	新增
10	apps/backend/README.md	修改
11	apps/backend/app/config.py	修改
12	apps/backend/app/main.py	修改
13	apps/backend/app/middleware/permission.py	修改
14	apps/backend/app/routers/admin_applications.py	新增
15	apps/backend/app/routers/business_day.py	新增
16	apps/backend/app/routers/member_retention_clue.py	新增
17	apps/backend/app/routers/tasks.py	修改
18	apps/backend/app/routers/xcx_auth.py	修改
19	apps/backend/app/schemas/member_retention_clue.py	修改
20	apps/backend/app/schemas/xcx_auth.py	修改
21	apps/backend/app/services/application.py	修改
22	apps/backend/app/services/wechat.py	修改
23	apps/etl/connectors/feiqiu/config/defaults.py	修改
24	apps/etl/connectors/feiqiu/config/env_parser.py	修改
25	apps/etl/connectors/feiqiu/config/settings.py	修改
26	apps/etl/connectors/feiqiu/orchestration/flow_runner.py	修改
27	apps/etl/connectors/feiqiu/quality/consistency_checker.py	修改
28	apps/etl/connectors/feiqiu/scripts/debug/debug_blackbox.py	修改
29	apps/etl/connectors/feiqiu/scripts/run_update.py	修改
30	apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py	修改
31	apps/etl/connectors/feiqiu/tasks/dws/assistant_customer_task.py	修改
32	apps/etl/connectors/feiqiu/tasks/dws/assistant_daily_task.py	修改
33	apps/etl/connectors/feiqiu/tasks/dws/assistant_finance_task.py	修改
34	apps/etl/connectors/feiqiu/tasks/dws/assistant_monthly_task.py	修改
35	apps/etl/connectors/feiqiu/tasks/dws/assistant_order_contribution_task.py	修改
36	apps/etl/connectors/feiqiu/tasks/dws/base_dws_task.py	修改
37	apps/etl/connectors/feiqiu/tasks/dws/finance_base_task.py	修改
38	apps/etl/connectors/feiqiu/tasks/dws/finance_discount_task.py	修改
39	apps/etl/connectors/feiqiu/tasks/dws/finance_income_task.py	修改
40	apps/etl/connectors/feiqiu/tasks/dws/finance_recharge_task.py	修改
41	apps/etl/connectors/feiqiu/tasks/dws/goods_stock_daily_task.py	修改
42	apps/etl/connectors/feiqiu/tasks/dws/goods_stock_monthly_task.py	修改
43	apps/etl/connectors/feiqiu/tasks/dws/goods_stock_weekly_task.py	修改
44	apps/etl/connectors/feiqiu/tasks/dws/index/member_index_base.py	修改
45	apps/etl/connectors/feiqiu/tasks/dws/index/relation_index_task.py	修改
46	apps/etl/connectors/feiqiu/tasks/dws/index/spending_power_index_task.py	修改
47	apps/etl/connectors/feiqiu/tasks/dws/member_consumption_task.py	修改
48	apps/etl/connectors/feiqiu/tasks/dws/member_visit_task.py	修改
49	apps/etl/connectors/feiqiu/tasks/verification/index_verifier.py	修改
50	apps/etl/connectors/feiqiu/tests/unit/test_config.py	修改
51	packages/shared/src/neozqyy_shared/__init__.py	修改
52	packages/shared/src/neozqyy_shared/datetime_utils.py	新增
53	scripts/ops/_check_etl_log_tail.py	新增

DB 文档全量对账

对账时间：2026-02-27 08:11:17（测试库：test_etl_feiqiu + test_zqyy_app）

指标	数值
数据库实际表总数	131
已有文档引用数	150
缺失文档的表数	57

缺失文档的表（按 schema 分组）

core 层（7 表）：

• core.dim_assistant（9 列）、core.dim_goods_category（5 列）、core.dim_member（8 列）
• core.dim_site（6 列）、core.dim_table（5 列）
• core.fact_payment（7 列）、core.fact_settlement（12 列）

dwd 层（16 表）：

• dwd.dim_goods_category（16 列）、dwd.dim_groupbuy_package（22 列）、dwd.dim_groupbuy_package_ex（25 列）
• dwd.dim_member_card_account_ex（61 列）、dwd.dim_member_ex（14 列）
• dwd.dim_site（17 列）、dwd.dim_site_ex（25 列）
• dwd.dwd_assistant_trash_event（11 列）、dwd.dwd_assistant_trash_event_ex（4 列）
• dwd.dwd_groupbuy_redemption（25 列）、dwd.dwd_groupbuy_redemption_ex（28 列）
• dwd.dwd_payment（12 列）、dwd.dwd_platform_coupon_redemption（20 列）、dwd.dwd_platform_coupon_redemption_ex（6 列）
• dwd.dwd_refund（12 列）、dwd.dwd_refund_ex（20 列）
• dwd.dwd_settlement_head_ex（30 列）、dwd.dwd_table_fee_adjust（16 列）
• dwd.dwd_table_fee_adjust_ex（13 列）、dwd.dwd_table_fee_log_ex（13 列）

dws 层（4 表）：

• dws.cfg_area_category（10 列）、dws.cfg_skill_type（9 列）
• dws.dws_ml_manual_order_alloc（19 列）、dws.dws_ml_manual_order_source（27 列）

meta 层（3 表）：

• meta.etl_cursor（10 列）、meta.etl_run（23 列）、meta.etl_task（12 列）

ods 层（11 表）：

• ods.assistant_cancellation_records（19 列）、ods.group_buy_packages（43 列）
• ods.group_buy_redemption_records（57 列）、ods.member_profiles（26 列）
• ods.member_stored_value_cards（80 列）、ods.payment_transactions（17 列）
• ods.platform_coupon_redemption_records（31 列）、ods.refund_transactions（37 列）
• ods.settlement_records（71 列）、ods.stock_goods_category_tree（16 列）
• ods.table_fee_discount_records（33 列）、ods.table_fee_transactions（47 列）

zqyy_app public 层（10 表）：

• public.admin_users（8 列）、public.approvals（7 列）、public.permissions（4 列）
• public.role_permissions（2 列）、public.roles（5 列）
• public.scheduled_tasks（13 列）、public.task_execution_log（14 列）
• public.task_queue（10 列）、public.tasks（9 列）
• public.user_roles（3 列）、public.users（8 列）

对账结论

• 新增文档数：0（本次仅记录缺失清单，未自动生成）
• 更新文档数：0
• 废弃标注数：0
• ⚠️ 57 张表缺少 BD_Manual 文档，建议分批补全（优先级：core/meta > dws > dwd > ods > public）
• ⚠️ DDL 基线（has_ddl_baseline=false）待合并