# 变更审计记录：多模块累积变更（营业日/核心业务/认证/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

## 验证建议

```bash
# 后端启动验证
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 文档覆盖。