Neo-ZQYY/docs/audit/changes/2026-02-28__multi-module-accumulated-changes.md

变更审计记录：多模块累积变更（营业日/核心业务/认证/ETL DWS 重构/参考文档合并）

• 日期：2026-02-28 13:53:50
• Prompt-ID：P20260228-134525
• 审计人：Kiro AI
• 风险标签：root-file, dir:admin-web, dir:backend, dir:etl, dir:miniprogram, dir:db, db-schema-change, dir:shared

变更概览

本次审计覆盖 220 个文件的累积变更（+9,429 / -217,832 行），涉及以下主要模块：

模块	变更文件数	主要内容
admin-web	6	营业日提示组件、任务终止操作、BusinessDayStore
backend	20	微信登录重构（new 状态）、dev-login、核心业务路由（xcx_tasks/xcx_notes）、触发器系统、维客线索、营业日配置
etl	15	DWS 任务 biz_date 重构、base_dws_task 统一、consistency_checker 重写、config 扩展
miniprogram	4	认证流程、app.json 页面注册、app.ts 启动逻辑
db	2	FDW 反向配置更新
shared	2	datetime_utils 新增模块
根目录	3	.env / .env.template / .gitignore
docs/reference	1	bailian-agent-v1 + v2 合并为 bailian-agent-guide

本次对话文件变更（session_diff）

新增文件

• docs/audit/prompt_logs/prompt_log_20260228_134525.md — Prompt 日志
• docs/reference/bailian-agent-guide.md — 百炼 Agent 参考指南（由 v1 + v2 合并）

删除文件

• docs/reference/bailian-agent-v1.md — 已合并至 bailian-agent-guide.md
• docs/reference/bailian-agent-v2.md — 已合并至 bailian-agent-guide.md

高风险文件清单（43 个）

admin-web（6 个）

• apps/admin-web/src/App.tsx
• apps/admin-web/src/api/businessDay.ts
• apps/admin-web/src/components/BusinessDayHint.tsx
• apps/admin-web/src/pages/TaskConfig.tsx
• apps/admin-web/src/pages/TaskManager.tsx
• apps/admin-web/src/store/businessDayStore.ts

backend（19 个）

• apps/backend/app/config.py
• apps/backend/app/main.py
• apps/backend/app/middleware/permission.py
• apps/backend/app/routers/admin_applications.py
• apps/backend/app/routers/business_day.py
• apps/backend/app/routers/member_retention_clue.py
• apps/backend/app/routers/tasks.py
• apps/backend/app/routers/xcx_auth.py
• apps/backend/app/routers/xcx_notes.py
• apps/backend/app/routers/xcx_tasks.py
• apps/backend/app/schemas/member_retention_clue.py
• apps/backend/app/schemas/xcx_auth.py
• apps/backend/app/schemas/xcx_notes.py
• apps/backend/app/schemas/xcx_tasks.py
• apps/backend/app/services/application.py
• apps/backend/app/services/note_reclassifier.py
• apps/backend/app/services/note_service.py
• apps/backend/app/services/recall_detector.py
• apps/backend/app/services/task_expiry.py
• apps/backend/app/services/task_generator.py
• apps/backend/app/services/task_manager.py
• apps/backend/app/services/trigger_scheduler.py
• apps/backend/app/services/wechat.py

etl（13 个）

• apps/etl/connectors/feiqiu/config/defaults.py
• apps/etl/connectors/feiqiu/config/env_parser.py
• apps/etl/connectors/feiqiu/config/settings.py
• apps/etl/connectors/feiqiu/orchestration/flow_runner.py
• apps/etl/connectors/feiqiu/quality/consistency_checker.py
• apps/etl/connectors/feiqiu/tasks/dwd/dwd_load_task.py
• apps/etl/connectors/feiqiu/tasks/dws/assistant_customer_task.py
• apps/etl/connectors/feiqiu/tasks/dws/assistant_daily_task.py
• apps/etl/connectors/feiqiu/tasks/dws/assistant_finance_task.py
• apps/etl/connectors/feiqiu/tasks/dws/assistant_monthly_task.py
• apps/etl/connectors/feiqiu/tasks/dws/assistant_order_contribution_task.py
• apps/etl/connectors/feiqiu/tasks/dws/base_dws_task.py
• apps/etl/connectors/feiqiu/tasks/dws/finance_base_task.py

合规检查

检查项	状态
文档同步缺失	✅ 无缺失（code_without_docs 为空）
新增迁移 SQL	✅ 无新增（new_migration_sql 为空）
BD Manual 文档	⚠️ 未找到（has_bd_manual=false，历史变更已有对应文档）
DDL 基线	⚠️ DDL 基线待合并（has_ddl_baseline=false）
接口变更	✅ 无接口变更（api_changed=false）
OpenAPI Spec	✅ 已同步（openapi_spec_stale=false）

改动注解

apps/admin-web/src/App.tsx

• 变更类型：修改
• 原始原因：管理后台需要在启动时加载营业日配置，以便日期选择器等组件能感知营业日分割点
• 思路分析：在 App 组件的 useEffect 中新增 initBusinessDay() 调用，利用 zustand store 管理营业日状态，降级策略在 store 内部处理
• 修改结果：管理后台启动时自动请求营业日配置 API，所有依赖营业日的组件可通过 store 获取配置

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

• 变更类型：修改
• 原始原因：任务配置页的日期选择区域需要展示营业日提示，帮助运营人员理解日期分割逻辑
• 思路分析：在日期选择器下方插入 <BusinessDayHint /> 组件，用 Fragment 包裹原有 Row 和新增提示
• 修改结果：日期选择区域下方显示营业日分割点提示信息

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

• 变更类型：修改
• 原始原因：历史任务列表中运行中的任务需要支持手动终止操作
• 思路分析：新增 handleCancelHistory 回调和"操作"列，仅对 status=running 的记录显示终止按钮，使用 Popconfirm 二次确认
• 修改结果：历史任务列表新增终止操作列，运行中任务可手动终止

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

• 变更类型：修改（高风险）
• 原始原因：新增营业日 API 调用层
• 思路分析：封装后端 /api/business-day 端点的请求方法
• 修改结果：admin-web 可通过 API 获取营业日配置

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

• 变更类型：修改（高风险）
• 原始原因：新增营业日提示 UI 组件
• 思路分析：从 businessDayStore 读取配置，展示分割点时间提示
• 修改结果：可复用的营业日提示组件，已集成到 TaskConfig 页面

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

• 变更类型：修改（高风险）
• 原始原因：管理后台需要全局管理营业日配置状态
• 思路分析：使用 zustand 创建 store，init 方法请求 API 并缓存，内置降级策略
• 修改结果：全局营业日状态管理，App 启动时初始化

apps/backend/app/config.py

• 变更类型：修改
• 原始原因：后端需要支持微信小程序配置和营业日分割点配置
• 思路分析：新增 WX_APPID / WX_SECRET / WX_DEV_MODE / BUSINESS_DAY_START_HOUR 四个配置项，从环境变量读取
• 修改结果：后端配置模块支持微信和营业日相关环境变量

apps/backend/app/main.py

• 变更类型：修改
• 原始原因：后端需要注册新路由（维客线索、管理端申请审核、营业日、小程序任务/笔记）和触发器 job handler
• 思路分析：替换 member_birthday 为 member_retention_clue，新增 admin_applications / business_day / xcx_tasks / xcx_notes 路由；在 lifespan 中注册 4 个触发器 job handler
• 修改结果：后端路由从 13 个扩展到 17 个，触发器系统在启动时自动注册

apps/backend/app/routers/tasks.py

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

apps/backend/app/routers/xcx_auth.py

• 变更类型：修改
• 原始原因：小程序认证流程需要区分"新用户"和"已提交申请"两个状态，并支持开发模式 mock 登录
• 思路分析：将新用户初始状态从 pending 改为 new（new → 提交申请 → pending → 审核 → approved）；新增 dev-login 端点，仅在 WX_DEV_MODE=true 时注册，支持指定 openid 和 status 参数
• 修改结果：认证流程更精细（new/pending/rejected/approved 四态），开发调试效率提升

apps/backend/app/schemas/xcx_auth.py

• 变更类型：修改
• 原始原因：新增 DevLoginRequest schema 支持 dev-login 端点
• 思路分析：定义 openid（必填）和 status（可选）字段
• 修改结果：dev-login 端点有完整的请求验证

apps/backend/app/services/application.py

• 变更类型：修改
• 原始原因：用户提交申请时需要自动将状态从 new 更新为 pending
• 思路分析：在 create_application 末尾新增 UPDATE 语句，仅对 new/rejected 状态的用户更新为 pending
• 修改结果：申请提交后用户状态自动流转

apps/backend/app/services/wechat.py

• 变更类型：修改
• 原始原因：微信 code2session 服务需要使用集中配置的 APPID/SECRET
• 思路分析：从 config.get() 改为直接引用 config.WX_APPID / config.WX_SECRET
• 修改结果：配置引用更清晰，与 config.py 中的集中定义一致

apps/backend/app/middleware/permission.py

• 变更类型：修改（高风险）
• 原始原因：权限中间件需要适配新的路由和认证状态
• 修改结果：权限检查逻辑更新

apps/backend/app/routers/admin_applications.py

• 变更类型：修改（高风险）
• 原始原因：管理端需要审核用户申请的路由
• 修改结果：管理端申请审核 CRUD 端点

apps/backend/app/routers/business_day.py

• 变更类型：修改（高风险）
• 原始原因：提供营业日配置查询 API
• 修改结果：GET /api/business-day 端点

apps/backend/app/routers/member_retention_clue.py

• 变更类型：修改（高风险）
• 原始原因：维客线索重构，替代原 member_birthday 路由
• 修改结果：维客线索 CRUD 端点

apps/backend/app/routers/xcx_notes.py

• 变更类型：修改（高风险）
• 原始原因：小程序核心业务——笔记模块路由
• 修改结果：笔记 CRUD + 分类 + 搜索端点

apps/backend/app/routers/xcx_tasks.py

• 变更类型：修改（高风险）
• 原始原因：小程序核心业务——任务模块路由
• 修改结果：任务列表/详情/状态流转端点

apps/backend/app/schemas/member_retention_clue.py

• 变更类型：修改（高风险）
• 原始原因：维客线索 schema 定义
• 修改结果：请求/响应模型

apps/backend/app/schemas/xcx_notes.py

• 变更类型：修改（高风险）
• 原始原因：笔记模块 schema 定义
• 修改结果：笔记请求/响应模型

apps/backend/app/schemas/xcx_tasks.py

• 变更类型：修改（高风险）
• 原始原因：任务模块 schema 定义
• 修改结果：任务请求/响应模型

apps/backend/app/services/note_reclassifier.py

• 变更类型：修改（高风险）
• 原始原因：笔记自动重分类后台任务
• 修改结果：触发器系统可调度的 note_reclassify_backfill job

apps/backend/app/services/note_service.py

• 变更类型：修改（高风险）
• 原始原因：笔记业务逻辑服务层
• 修改结果：笔记 CRUD + 分类逻辑

apps/backend/app/services/recall_detector.py

• 变更类型：修改（高风险）
• 原始原因：回访完成检测后台任务
• 修改结果：触发器系统可调度的 recall_completion_check job

apps/backend/app/services/task_expiry.py

• 变更类型：修改（高风险）
• 原始原因：任务过期检查后台任务
• 修改结果：触发器系统可调度的 task_expiry_check job

apps/backend/app/services/task_generator.py

• 变更类型：修改（高风险）
• 原始原因：任务自动生成后台任务
• 修改结果：触发器系统可调度的 task_generator job

apps/backend/app/services/task_manager.py

• 变更类型：修改（高风险）
• 原始原因：任务状态管理服务层
• 修改结果：任务状态流转（待处理→进行中→已完成/已过期）

apps/backend/app/services/trigger_scheduler.py

• 变更类型：修改（高风险）
• 原始原因：触发器调度系统，管理定时 job 的注册和执行
• 修改结果：register_job 接口，lifespan 中注册 4 个核心业务 job

apps/backend/app/services/wechat.py

• 变更类型：修改
• 原始原因：微信 code2session 服务配置引用方式统一
• 思路分析：从 config.get() 改为直接引用 config.WX_APPID / config.WX_SECRET
• 修改结果：配置引用更清晰

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

• 变更类型：修改
• 原始原因：ETL 配置默认值扩展
• 修改结果：新增默认配置项

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

• 变更类型：修改
• 原始原因：环境变量解析器扩展
• 修改结果：支持新增配置项解析

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

• 变更类型：修改
• 原始原因：ETL 配置类扩展，支持营业日分割点等新配置
• 修改结果：Settings 类新增字段

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

• 变更类型：修改
• 原始原因：流程编排器适配 DWS 任务重构
• 修改结果：flow_runner 调用方式更新

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

• 变更类型：修改（+136/-136 行，重写）
• 原始原因：数据一致性检查器全面重构
• 思路分析：重写检查逻辑以适配 biz_date 重构后的 DWS 表结构
• 修改结果：一致性检查器与新 DWS 结构对齐

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

• 变更类型：修改
• 原始原因：DWD 加载任务微调
• 修改结果：适配上游变更

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

• 变更类型：修改（+65/-65 行，重构）
• 原始原因：DWS 基类统一 biz_date 逻辑，所有 DWS 任务共享日期分割计算
• 思路分析：将 biz_date 计算从各子任务提取到基类，统一使用 BUSINESS_DAY_START_HOUR 配置
• 修改结果：所有 DWS 任务继承统一的 biz_date 处理逻辑

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

• 变更类型：修改（+58/-58 行，重构）
• 原始原因：财务基类适配 biz_date 重构
• 修改结果：财务类 DWS 任务统一使用基类 biz_date 逻辑

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

• 变更类型：修改
• 原始原因：助教客户任务适配 biz_date 重构
• 修改结果：使用基类统一的日期分割逻辑

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

• 变更类型：修改
• 原始原因：助教日报任务适配 biz_date 重构
• 修改结果：使用基类统一的日期分割逻辑

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

• 变更类型：修改
• 原始原因：助教财务任务适配 biz_date 重构
• 修改结果：使用基类统一的日期分割逻辑

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

• 变更类型：修改
• 原始原因：助教月报任务适配 biz_date 重构
• 修改结果：使用基类统一的日期分割逻辑

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

• 变更类型：修改
• 原始原因：助教订单贡献任务适配 biz_date 重构
• 修改结果：使用基类统一的日期分割逻辑

docs/reference/bailian-agent-guide.md

• 变更类型：新增
• 原始原因：用户要求将 bailian-agent-v1.md 和 bailian-agent-v2.md 合并为一份文档
• 思路分析：将两份百炼 Agent 参考文档的内容整合，消除重复，统一结构
• 修改结果：单一参考文档替代原有两份，v1 和 v2 已删除

docs/reference/bailian-agent-v1.md

• 变更类型：删除
• 原始原因：已合并至 bailian-agent-guide.md

docs/reference/bailian-agent-v2.md

• 变更类型：删除
• 原始原因：已合并至 bailian-agent-guide.md

回滚策略

本次变更涉及多个独立功能模块，回滚需按模块分别处理：

1. 营业日功能：回滚 admin-web 的 BusinessDayHint/Store + backend 的 business_day 路由 + config.py 中 BUSINESS_DAY_START_HOUR
2. 核心业务路由：回滚 xcx_tasks / xcx_notes 路由 + 对应 services + main.py 中的路由注册和 job 注册
3. 认证重构：回滚 xcx_auth.py 中 new 状态逻辑 + dev-login 端点 + application.py 状态流转
4. ETL DWS 重构：回滚 base_dws_task.py + 所有子任务的 biz_date 相关改动
5. 参考文档合并：恢复 bailian-agent-v1.md 和 v2.md，删除 bailian-agent-guide.md

验证建议

# 后端启动验证
cd apps/backend && uvicorn app.main:app --reload

# ETL 单元测试
cd apps/etl/connectors/feiqiu && pytest tests/unit -v

# 属性测试
cd C:\Project\NeoZQYY && pytest tests/ -v

# 管理后台构建验证
cd apps/admin-web && pnpm build

DB 文档全量对账

对账时间：2026-02-28 13:53:50 测试库连接：✅ ETL 测试库（test_etl_feiqiu）+ ✅ App 测试库（test_zqyy_app）

数据库实际表统计

库	Schema	表数
test_etl_feiqiu	ods	20
test_etl_feiqiu	dwd	40
test_etl_feiqiu	dws	36
test_etl_feiqiu	core	6
test_etl_feiqiu	meta	3
test_zqyy_app	auth	8
test_zqyy_app	biz	4
test_zqyy_app	public	12

文档覆盖情况

文档类型	覆盖范围	状态
BD_Manual_auth_tables.md	auth Schema 8 张表	✅ 已覆盖
BD_Manual_biz_tables.md	biz Schema 4 张表（coach_tasks/coach_task_history/notes/trigger_jobs）	✅ 已覆盖
BD_Manual_member_retention_clue.md	public.member_retention_clue	✅ 已覆盖
BD_Manual_fdw_etl_setup.md	FDW 跨库配置	✅ 已覆盖
BD_Manual_app_schema_rls_views.md	app Schema RLS 视图	✅ 已覆盖
DDL 基线文件（10 个）	ETL 六层 Schema + App 三个 Schema + FDW	✅ 已覆盖
各 BD_Manual_*.md（ODS 表）	ODS 层主要表	✅ 部分覆盖（通过专题文档）

对账摘要

• 新增文档数：0（无新增表需要单独建文档）
• 更新文档数：0（现有文档与数据库结构一致）
• 废弃标注数：0（无已删除的表）
• ⚠️ DDL 基线待合并（has_ddl_baseline=false）：DDL 基线文件已存在但可能未包含最新变更

注：ETL 库的 ods/dwd/dws/core/meta 层表结构由 DDL 基线文件（docs/database/ddl/）统一管理，不需要逐表建立 BD_Manual 文档。App 库的 auth/biz/public 表已有对应 BD_Manual 文档覆盖。