root/Neo-ZQYY
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
14a12342b5165d83602a2656e230f2e67ede729e
Neo-ZQYY/docs/audit/changes/2026-03-12__multi-module-ai-taskdefense-miniprogram-etl.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

12 KiB
Raw Blame History

变更审计记录：多模块累积变更 — 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-012026-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 个页面同时重构，建议逐页面回归测试
Reference in New Issue View Git Blame Copy Permalink