chore(audit): 补追 96 份未入仓审计孤本 — 覆盖 2026-02-26 ~ 2026-04-08

这些审计记录原本堆积在 docs/audit/changes/changes/ 嵌套误产物目录下（由开发机迁移 79d3c2e 前后的不明批量操作产生）。由于同期 .gitignore 屏蔽了 docs/audit/ 全目录，它们从未入过 git 任何分支 history。删除即永久丢失。按 docs/specs/audit-gap-recovery/tasks.md 阶段 1 执行，将全部 96 份 D 类孤本（主目录无同名、git history 亦无记录）复制到 docs/audit/changes/ 主目录入仓。涵盖主题: P1-P18 全栈集成 / 多模块累积变更 / ETL bug 修复 / 业务日切 / 召回与任务引擎改造 / 租户管理与审批 / 董事会财务 / 客户与助教详情 / DDL 基线合并 / Kiro 到 Claude Code 迁移阶段 2（B 类内容漂移 1 份）和阶段 4（嵌套目录删除）独立推进。 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-20 06:35:42 +08:00
parent 80bda9b991
commit 14a12342b5
96 changed files with 9521 additions and 0 deletions
--- a/docs/audit/changes/2026-02-28__multi-module-accumulated-changes.md
+++ b/docs/audit/changes/2026-02-28__multi-module-accumulated-changes.md
@@ -0,0 +1,404 @@
+# 变更审计记录：多模块累积变更（营业日/核心业务/认证/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 文档覆盖。