Neo
14a12342b5
这些审计记录原本堆积在 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>
203 lines
12 KiB
Markdown
203 lines
12 KiB
Markdown
# 变更审计记录：多模块累积变更 — AI 对话系统 + 任务防御 + 小程序 UI 重构 + ETL DWS
|
||
|
||
| 字段 | 值 |
|
||
|------|-----|
|
||
| 日期 | 2026-03-12 01:01:13 |
|
||
| Prompt-ID | P20260312-002152 |
|
||
| Session-ID | N/A（索引无匹配） |
|
||
| Session 路径 | N/A |
|
||
| 变更指纹 | 627a7c34a7f79b9e22f7ca933df0303dfab5a40e |
|
||
|
||
## 操作摘要
|
||
|
||
本次审计覆盖 51 个变更文件的累积变更，跨越 4 个主要模块：
|
||
|
||
1. **后端 AI 对话系统**（新建）：8 个 AI App（闲聊/财务/线索/分析/战术/备注/客户/综合）+ 调度器 + Prompt 模板 + SSE 路由 + 缓存路由
|
||
2. **后端任务防御机制**（增强）：task_queue 多实例隔离（enqueued_by）、僵尸任务回收、running 状态兜底修正；task_executor 路径防护 + 实例标识注入
|
||
3. **微信小程序 UI 重构**（大规模）：~20 个页面的样式/交互/数据绑定全面重构，涉及看板、详情、任务列表、聊天等核心页面
|
||
4. **ETL DWS 层**：base_dws_task 模板方法重构、助教订单贡献任务调整、BD 手册更新、seed 配置更新
|
||
|
||
## 变更统计
|
||
|
||
- 358 files changed, 7,600 insertions(+), 16,045,285 deletions(-)
|
||
- 大量删除主要来自 `export/` 目录下的 JSON 数据文件清理（非代码变更）
|
||
|
||
## 本次对话文件变更
|
||
|
||
### 新增文件
|
||
- `docs/audit/changes/2026-03-12__pixel-audit-structured-methodology.md`
|
||
- `docs/audit/prompt_logs/prompt_log_20260312_002152.md`
|
||
- `docs/audit/session_logs/2026-03/11/` 下多个 session 子代理日志（约 30 个文件）
|
||
|
||
### 修改文件
|
||
- `docs/audit/audit_dashboard.md`
|
||
- `docs/audit/session_logs/` 下多个主对话日志
|
||
- `docs/h5_ui/compare/AGENT-PLAYBOOK.md`
|
||
- `docs/h5_ui/compare/ORCHESTRATION-PLAN.md`
|
||
|
||
|
||
## 改动注解
|
||
|
||
### `apps/backend/app/ai/apps/app1_chat.py` ~ `app8_consolidation.py`（8 个文件）
|
||
- 变更类型：新增
|
||
- 原始原因：P5 AI 需求——为小程序提供 AI 对话能力，按业务域拆分为 8 个独立 App（闲聊、财务分析、线索跟进、数据分析、战术建议、备注管理、客户洞察、综合调度）
|
||
- 思路分析：每个 App 封装独立的 Prompt 模板和业务逻辑，通过 dispatcher 统一调度。采用 SSE 流式输出，支持上下文对话。App8 综合调度负责跨域问题的路由分发
|
||
- 修改结果：后端具备完整的 AI 对话能力，支持 8 种业务场景的智能问答
|
||
|
||
### `apps/backend/app/ai/dispatcher.py`
|
||
- 变更类型：新增
|
||
- 原始原因：AI App 需要统一的调度入口，根据用户消息内容路由到对应的业务 App
|
||
- 思路分析：dispatcher 接收用户消息，通过关键词/意图识别分发到具体 App，同时管理对话上下文和缓存服务
|
||
- 修改结果：AI 对话系统的核心调度层，连接路由层和业务 App 层
|
||
|
||
### `apps/backend/app/ai/prompts/app2_finance_prompt.py`
|
||
- 变更类型：新增
|
||
- 原始原因：财务分析 App 需要专用的 Prompt 模板，包含财务口径定义和查询模板
|
||
- 思路分析：Prompt 中内嵌了 DWD-DOC 标杆文档的关键规则（consume_money 口径、支付渠道恒等式等），确保 AI 回答符合业务口径
|
||
- 修改结果：财务 AI 回答基于权威数据口径，避免金额计算错误
|
||
|
||
### `apps/backend/app/ai/prompts/app8_consolidation_prompt.py`
|
||
- 变更类型：新增
|
||
- 原始原因：综合调度 App 需要 Prompt 模板定义路由规则和跨域问答策略
|
||
- 思路分析：定义了 8 个 App 的能力边界和路由关键词，综合 App 作为兜底处理无法明确归类的问题
|
||
- 修改结果：用户提问可被准确路由到最合适的业务 App
|
||
|
||
### `apps/backend/app/routers/xcx_ai_chat.py`
|
||
- 变更类型：新增
|
||
- 原始原因：小程序需要 AI 对话的 HTTP 接口，支持 SSE 流式输出和历史对话查询
|
||
- 思路分析：提供 `/xcx/ai/chat` SSE 端点和 `/xcx/ai/conversations` 历史查询端点，集成认证和门店隔离
|
||
- 修改结果：小程序可通过标准 HTTP 接口与 AI 对话
|
||
|
||
### `apps/backend/app/routers/xcx_ai_cache.py`
|
||
- 变更类型：新增
|
||
- 原始原因：AI 对话结果需要缓存机制，避免重复计算相同问题
|
||
- 思路分析：提供缓存查询和管理接口，按 site_id 隔离
|
||
- 修改结果：AI 响应可被缓存和复用，降低 API 调用成本
|
||
|
||
### `apps/backend/app/main.py`
|
||
- 变更类型：修改
|
||
- 原始原因：需要注册新增的 AI 路由和初始化 AI 服务
|
||
- 思路分析：在 lifespan 中初始化 BailianClient + AIDispatcher + 事件处理器注册；新增启动横幅打印关键路径配置；新增 `/debug/config-paths` 诊断端点
|
||
- 修改结果：后端启动时自动初始化 AI 服务，并提供路径诊断能力
|
||
|
||
### `apps/backend/app/services/task_queue.py`
|
||
- 变更类型：新增
|
||
- 原始原因：发现多后端实例共享同一 DB 时任务被错误实例执行，需要任务隔离机制
|
||
- 思路分析：引入 `enqueued_by` 列实现"谁入队谁消费"；新增僵尸任务回收（running 超 180 分钟自动标记 failed）；新增 `_ensure_not_stuck_running` 兜底防止 task_queue 永远卡在 running
|
||
- 修改结果：多实例环境下任务不会被错误消费，僵尸任务可自动恢复
|
||
|
||
### `apps/backend/app/services/task_executor.py`
|
||
- 变更类型：修改
|
||
- 原始原因：ETL 子进程命令中出现非预期路径（D 盘 junction 穿透），需要运行时防护
|
||
- 思路分析：新增路径防护检测（D 盘路径 + 多环境子目录）；实时从 config 模块读取 ETL 路径（避免 import 时值拷贝过期）；命令前缀注入实例标识便于多实例区分
|
||
- 修改结果：拒绝执行包含异常路径的 ETL 命令，防止跨实例污染
|
||
|
||
### `apps/backend/app/services/task_registry.py`
|
||
- 变更类型：修改
|
||
- 原始原因：ETL 侧新增/调整了多个任务定义，后端静态注册表需同步
|
||
- 思路分析：新增 DWS_ASSISTANT_PROJECT_TAG、DWS_MEMBER_PROJECT_TAG（项目标签）；新增 DWS_GOODS_STOCK_DAILY/WEEKLY/MONTHLY（库存汇总）；移除已废弃的 ODS_SETTLEMENT_TICKET；新增 DWD 库存表定义
|
||
- 修改结果：后端任务注册表与 ETL 侧保持同步
|
||
|
||
### `apps/backend/pyproject.toml`
|
||
- 变更类型：修改
|
||
- 原始原因：AI 功能引入新依赖
|
||
- 思路分析：添加 AI 相关依赖包
|
||
- 修改结果：后端可正常导入 AI SDK
|
||
|
||
### `apps/backend/tests/test_task_queue.py`
|
||
- 变更类型：修改
|
||
- 原始原因：task_queue 新增了多实例隔离和僵尸回收逻辑，需要对应测试
|
||
- 思路分析：更新测试用例覆盖 enqueued_by 过滤、僵尸回收、兜底修正等新逻辑
|
||
- 修改结果：task_queue 核心逻辑有测试覆盖
|
||
|
||
### `apps/etl/connectors/feiqiu/tasks/dws/base_dws_task.py`
|
||
- 变更类型：修改
|
||
- 原始原因：DWS 子类中存在大量重复的 extract/load 样板代码，需要提取到基类
|
||
- 思路分析：新增 DATE_COL 类属性 + 默认 extract()/load() 模板方法，子类只需实现 _do_extract()
|
||
- 修改结果：DWS 任务代码量减少，新增任务只需关注业务逻辑
|
||
|
||
### `apps/etl/connectors/feiqiu/tasks/dws/assistant_order_contribution_task.py`
|
||
- 变更类型：修改
|
||
- 原始原因：配合 base_dws_task 模板方法重构，调整任务实现
|
||
- 思路分析：适配新的基类接口
|
||
- 修改结果：任务正常运行，代码更简洁
|
||
|
||
### `apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_dwd_settlement_head.md`
|
||
- 变更类型：修改
|
||
- 原始原因：结算主表 BD 手册需要同步更新字段说明
|
||
- 思路分析：更新字段描述和业务规则说明
|
||
- 修改结果：BD 手册与实际表结构保持一致
|
||
|
||
### `apps/etl/connectors/feiqiu/docs/database/DWS/main/BD_manual_cfg_area_category.md`
|
||
- 变更类型：修改
|
||
- 原始原因：cfg_area_category 分类规则变更（BILLIARD_VIP 废弃，V1-V4 归入 BILLIARD，V5 归入 SNOOKER）
|
||
- 思路分析：更新分类代码说明和映射规则文档
|
||
- 修改结果：BD 手册反映最新的台桌分类映射规则
|
||
|
||
### `apps/etl/connectors/feiqiu/docs/database/DWS/main/BD_manual_dws_finance_income_structure.md`
|
||
- 变更类型：修改
|
||
- 原始原因：收入结构表文档需要同步更新
|
||
- 思路分析：更新字段说明和计算口径
|
||
- 修改结果：收入结构 BD 手册与实际表结构一致
|
||
|
||
### `apps/etl/connectors/feiqiu/docs/etl_tasks/dws_tasks.md`
|
||
- 变更类型：修改
|
||
- 原始原因：新增/调整了多个 DWS 任务，任务文档需同步
|
||
- 思路分析：更新任务列表和说明
|
||
- 修改结果：DWS 任务文档与代码保持一致
|
||
|
||
### `db/etl_feiqiu/seeds/seed_dws_config.sql`
|
||
- 变更类型：修改
|
||
- 原始原因：绩效档位配置需要更新（新增 2025-01-01~2026-02-28 统一提成方案）
|
||
- 思路分析：三段时间线设计——旧方案(~2024-12-31)、统一提成(2025-01-01~2026-02-28)、新方案(2026-03-01~)；同时更新保底奖金规则和区域分类配置
|
||
- 修改结果：DWS 配置表种子数据覆盖完整的历史口径时间线
|
||
|
||
### 小程序页面文件（约 20 个页面，简要注解）
|
||
- `apps/miniprogram/miniprogram/app.json` — 修改：页面路由配置调整
|
||
- `apps/miniprogram/miniprogram/app.wxss` — 新增：全局样式定义
|
||
- `apps/miniprogram/miniprogram/components/filter-dropdown/filter-dropdown.wxss` — 修改：筛选下拉组件样式调整
|
||
- `apps/miniprogram/miniprogram/pages/board-coach/*` — 修改：助教看板页面重构（布局/交互/数据绑定）
|
||
- `apps/miniprogram/miniprogram/pages/board-customer/*` — 修改：客户看板页面重构
|
||
- `apps/miniprogram/miniprogram/pages/board-finance/*` — 修改：财务看板页面重构（大量样式和交互变更）
|
||
- `apps/miniprogram/miniprogram/pages/chat/*` — 修改：AI 聊天页面（对接后端 SSE 接口）
|
||
- `apps/miniprogram/miniprogram/pages/chat-history/*` — 修改：聊天历史页面
|
||
- `apps/miniprogram/miniprogram/pages/coach-detail/*` — 修改：助教详情页重构
|
||
- `apps/miniprogram/miniprogram/pages/customer-detail/*` — 修改：客户详情页重构
|
||
- `apps/miniprogram/miniprogram/pages/task-list/*` — 修改：任务列表页重构（大量交互变更）
|
||
- `apps/miniprogram/miniprogram/pages/task-detail/*` — 修改：任务详情页重构
|
||
- `apps/miniprogram/miniprogram/pages/task-detail-callback/*` — 修改：回访任务详情重构
|
||
- `apps/miniprogram/miniprogram/pages/task-detail-priority/*` — 修改：优先任务详情重构
|
||
- `apps/miniprogram/miniprogram/pages/task-detail-relationship/*` — 修改：关系维护任务详情重构
|
||
- `apps/miniprogram/miniprogram/pages/notes/*` — 修改：备注页面重构
|
||
- `apps/miniprogram/miniprogram/pages/performance/*` — 修改：业绩页面重构
|
||
- `apps/miniprogram/miniprogram/pages/performance-records/*` — 修改：业绩记录页面重构
|
||
- `apps/miniprogram/miniprogram/pages/my-profile/*` — 修改：个人中心页面调整
|
||
- `apps/miniprogram/miniprogram/pages/apply/apply.ts` — 修改：申请页面微调
|
||
- 其他页面文件 — 修改：样式和交互的统一调整
|
||
|
||
## 合规检查
|
||
|
||
| 检查项 | 状态 | 说明 |
|
||
|--------|------|------|
|
||
| 新增迁移 SQL | ✅ 无 | compliance.new_migration_sql 为空 |
|
||
| DDL 基线 | ⚠️ 待确认 | has_ddl_baseline=false，但本次无新增迁移 |
|
||
| API 接口变更 | ✅ 无需同步 | api_changed=false |
|
||
| OpenAPI spec 同步 | ✅ 不适用 | openapi_spec_stale=false |
|
||
| 文档同步 | ✅ 已完成 | code_without_docs 为空 |
|
||
| BD 手册 | ✅ 已更新 | 3 个 BD 手册文件已在变更列表中 |
|
||
|
||
## DB 文档对账
|
||
|
||
`db-schema-change` 标签由 `db/etl_feiqiu/seeds/seed_dws_config.sql` 变更触发。经核实，本次仅为 seed 数据变更（绩效档位配置更新），无 DDL/schema 变更，无新增迁移 SQL。跳过全量 DB 对账。
|
||
|
||
相关 BD 手册已在本次变更中同步更新：
|
||
- `BD_manual_dwd_settlement_head.md`（结算主表字段说明）
|
||
- `BD_manual_cfg_area_category.md`（区域分类映射规则）
|
||
- `BD_manual_dws_finance_income_structure.md`（收入结构字段说明）
|
||
|
||
## 风险标注
|
||
|
||
- **多实例任务隔离**：task_queue 的 `enqueued_by` 机制依赖 `platform.node()` 返回唯一主机名，若多实例部署在同一主机需额外区分
|
||
- **AI 服务初始化**：main.py 中 AI 初始化失败时静默降级（warning 日志），不影响其他功能，但 AI 对话将不可用
|
||
- **小程序大规模重构**：约 20 个页面同时重构，建议逐页面回归测试
|