root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
41087c392ff44358887358fc0c9f1dcf67d49d3f
Neo-ZQYY/docs/audit/changes/2026-02-28__multi-module-accumulated-changes.md
Neo 14a12342b5 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

405 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 变更审计记录：多模块累积变更（营业日/核心业务/认证/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 文档覆盖。
Reference in New Issue View Git Blame Copy Permalink