Neo-ZQYY/docs/audit/changes/2026-03-10__multi-module-ai-apps-task-defense-miniprogram.md

变更审计记录：多模块累积变更 — AI 应用骨架 + 任务队列防卡死 + 小程序页面迁移

字段	值
日期	2026-03-10 00:16:50
Prompt-ID	P20260310-000851
风险标签	dir:backend, dir:etl, dir:miniprogram, dir:db, db-schema-change
变更规模	145 files changed, 6965 insertions(+), 3396 deletions(-)

操作摘要

本次审计覆盖多轮对话的累积变更，涉及三大模块：

1. 后端 AI 应用骨架（P5-A 阶段）：新增 8 个 AI 应用模块（app1_chat ~ app8_consolidation）、dispatcher 路由、prompt 模板、缓存/对话路由，构建完整的 AI 应用框架
2. 任务队列防卡死机制：在 task_queue.py 中新增 _ensure_not_stuck_running 和 _recover_zombie_tasks 两个防御函数，防止任务因异常被静默吞掉后永远卡在 running 状态
3. 小程序页面迁移（H5 → 微信原生）：大量小程序页面的 UI 重构和功能增强，包括看板页面、聊天页面、教练/客户详情页、任务列表/详情页等
4. ETL DWS 任务优化：base_dws_task.py 和 assistant_order_contribution_task.py 的调整，BD 手册文档更新

本次对话文件变更

新增文件

• docs/audit/prompt_logs/prompt_log_20260310_000851.md
• docs/audit/session_logs/2026-03/09/51_413948ee_141806/sub_01_b45509d2.md
• docs/audit/session_logs/_system_prompts/sp_6b01e1f4.md

改动注解

后端 — AI 应用骨架（新增）

apps/backend/app/ai/apps/app1_chat.py

• 变更类型：新增
• 原始原因：P5-A 阶段实现通用对话应用，支持 SSE 流式返回
• 思路分析：每次进入 chat 页面新建 ai_conversations 记录（不复用），首条消息注入页面上下文（source_page、page_context、screen_content），通过 BailianClient.chat_stream 流式获取回复，逐 chunk yield SSEEvent
• 修改结果：完整的流式对话入口，包含 conversation 创建、消息写入、system prompt 构建、异常处理。app_id = "app1_chat"

apps/backend/app/ai/apps/app2_finance.py

• 变更类型：新增
• 原始原因：P5-A 阶段实现财务洞察应用，8 个时间维度独立调用
• 思路分析：定义 8 个时间维度编码（this_month/last_month/this_week 等），实现 compute_time_range 计算日期范围，营业日分界点 08:00（BUSINESS_DAY_START_HOUR 环境变量）。调用百炼后结果写入 ai_cache + ai_conversations
• 修改结果：完整的财务洞察调用链路。app_id = "app2_finance"

apps/backend/app/ai/apps/app3_clue.py

• 变更类型：新增
• 原始原因：P5-A 阶段实现客户数据维客线索分析骨架
• 思路分析：线索 category 限定 3 个枚举值（客户基础/消费习惯/玩法偏好），使用 items_sum 口径禁止 consume_money。Prompt reference 包含 App6 备注分析线索 + 最近 2 套 App8 历史
• 修改结果：骨架实现，data 字段标注"待 P9-T1 补充"。app_id = "app3_clue"

apps/backend/app/ai/apps/app4_analysis.py

• 变更类型：新增
• 原始原因：P5-A 阶段实现关系分析/任务建议骨架
• 思路分析：助教参与新结算或被分配召回任务时自动触发。Prompt reference 包含 App8 最新 + 最近 2 套历史（附 generated_at），缓存不存在时标注"暂无历史线索"
• 修改结果：骨架实现，data 字段标注"待 P6-T4 补充"。app_id = "app4_analysis"

apps/backend/app/ai/apps/app5_tactics.py

• 变更类型：新增
• 原始原因：P5-A 阶段实现维客话术生成骨架
• 思路分析：基于 App3 线索和 App4 分析结果生成维客话术建议
• 修改结果：骨架实现。app_id = "app5_tactics"

apps/backend/app/ai/apps/app6_note.py

• 变更类型：新增
• 原始原因：P5-A 阶段实现备注分析骨架
• 思路分析：分析助教/教练的备注内容，提取客户线索
• 修改结果：骨架实现。app_id = "app6_note"

apps/backend/app/ai/apps/app7_customer.py

• 变更类型：新增
• 原始原因：P5-A 阶段实现客户画像骨架
• 思路分析：综合客户消费数据生成客户画像
• 修改结果：骨架实现。app_id = "app7_customer"

apps/backend/app/ai/apps/app8_consolidation.py

• 变更类型：新增
• 原始原因：P5-A 阶段实现维客线索整理骨架
• 思路分析：整合 App3/App6 线索，去重合并，生成最终维客线索集
• 修改结果：骨架实现。app_id = "app8_consolidation"

apps/backend/app/ai/dispatcher.py

• 变更类型：新增
• 原始原因：AI 应用路由分发器，根据 app_id 路由到对应应用
• 思路分析：统一入口，根据 app_id 字符串匹配调用对应 app 模块的 run 函数
• 修改结果：8 个应用的路由分发逻辑

apps/backend/app/ai/prompts/app2_finance_prompt.py

• 变更类型：新增
• 原始原因：App2 财务洞察的 Prompt 模板
• 思路分析：构建包含时间维度、当前数据、历史数据的结构化 Prompt
• 修改结果：build_prompt 函数，返回 system + user 消息列表

apps/backend/app/ai/prompts/app8_consolidation_prompt.py

• 变更类型：新增
• 原始原因：App8 维客线索整理的 Prompt 模板
• 思路分析：整合多源线索的 Prompt 构建
• 修改结果：build_prompt 函数

apps/backend/app/routers/xcx_ai_cache.py

• 变更类型：新增
• 原始原因：AI 缓存查询路由，小程序端读取 AI 分析结果
• 思路分析：提供 GET 接口查询 ai_cache 表中的缓存结果
• 修改结果：缓存查询 API 路由

apps/backend/app/routers/xcx_ai_chat.py

• 变更类型：新增
• 原始原因：AI 对话路由，小程序端发起 AI 对话
• 思路分析：SSE 流式接口，调用 app1_chat 的 chat_stream
• 修改结果：流式对话 API 路由

apps/backend/app/main.py

• 变更类型：修改
• 原始原因：注册新增的 AI 路由
• 思路分析：在 FastAPI app 中 include 新增的 xcx_ai_cache 和 xcx_ai_chat 路由
• 修改结果：后端启动时自动加载 AI 相关路由

后端 — 任务队列防卡死机制

apps/backend/app/services/task_queue.py

• 变更类型：修改
• 原始原因：task_queue 中的任务因 task_execution_log.duration_ms 的 integer 溢出异常被静默吞掉，导致 task_queue 永远卡在 running 状态，后续任务全部排队。duration_ms 列已迁移为 bigint，本次增加兜底防御
• 思路分析：新增两个防御函数：(1) _ensure_not_stuck_running(queue_id) 在 _execute_and_update 的 finally 块中调用，检查 task_queue 是否仍为 running 并强制标记 failed；(2) _recover_zombie_tasks(max_running_minutes=180) 在 _process_once 开头调用，回收超过 3 小时仍为 running 的僵尸任务
• 修改结果：双重防御确保任务队列不会因异常卡死。即使单次执行异常未被捕获，finally 块兜底；即使 finally 也失败，定期扫描回收僵尸任务

apps/backend/app/services/task_executor.py

• 变更类型：修改
• 原始原因：配合任务队列防卡死机制的调整
• 思路分析：与 task_queue.py 的防御机制协同工作
• 修改结果：执行器层面的适配

apps/backend/app/services/task_registry.py

• 变更类型：修改
• 原始原因：任务注册表小幅调整
• 思路分析：配合新增 AI 应用的任务注册
• 修改结果：新增任务类型注册

apps/backend/tests/test_task_queue.py

• 变更类型：修改
• 原始原因：更新测试以适配新的防卡死逻辑
• 思路分析：修复 dequeue mock 元组缺少 schedule_id（第 11 列）的 bug，更新 3 个 _process_once 测试的 mock 增加 _recover_zombie_tasks 的 get_connection 调用
• 修改结果：25 个测试全部通过

apps/backend/pyproject.toml

• 变更类型：修改
• 原始原因：添加 asyncio_mode = "auto" 到 pytest 配置
• 思路分析：使 async 测试在 uv run 环境下正常运行，无需逐个标注 @pytest.mark.asyncio
• 修改结果：pytest 配置优化

ETL — DWS 任务优化

apps/etl/connectors/feiqiu/tasks/dws/base_dws_task.py

• 变更类型：修改
• 原始原因：DWS 基础任务类调整
• 思路分析：优化 DWS 任务的通用逻辑
• 修改结果：影响所有继承 BaseDWSTask 的任务

apps/etl/connectors/feiqiu/tasks/dws/assistant_order_contribution_task.py

• 变更类型：修改
• 原始原因：助教订单贡献任务调整
• 思路分析：配合 base_dws_task 的变更
• 修改结果：任务逻辑适配

ETL — 文档更新

• apps/etl/connectors/feiqiu/docs/database/DWD/main/BD_manual_dwd_settlement_head.md — 结算单 BD 手册更新
• apps/etl/connectors/feiqiu/docs/database/DWS/main/BD_manual_cfg_area_category.md — 台区分类 BD 手册更新（+139 行）
• 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 任务文档更新

小程序 — H5 → 微信原生迁移（简要注解）

大量小程序页面的 UI 重构和功能增强，属于 H5 → 微信小程序原生迁移的持续工作：

• app.wxss — 全局样式新增 +165 行（通用组件样式）
• board-coach/ — 教练看板页面（json/ts/wxml/wxss 全部更新）
• board-customer/ — 客户看板页面（json/ts/wxml/wxss 全部更新）
• board-finance/ — 财务看板页面（ts +131, wxml +57, wxss +101）
• chat/ — AI 对话页面（json/ts/wxml/wxss 全部更新）
• chat-history/ — 对话历史页面（json/ts/wxml/wxss 全部更新）
• coach-detail/ — 教练详情页（ts +280, wxml +206, wxss +701）
• customer-detail/ — 客户详情页（ts +182, wxml +160, wxss +408）
• customer-service-records/ — 客户服务记录页
• my-profile/ — 个人中心页
• notes/ — 备注页面
• performance/ — 业绩页面
• performance-records/ — 业绩记录页
• task-list/ — 任务列表页（ts +389, wxml +305, wxss +562）
• task-detail/ — 任务详情页（ts +182, wxml +171, wxss +815）
• task-detail-callback/ — 回访任务详情页
• task-detail-priority/ — 优先级任务详情页
• task-detail-relationship/ — 关系任务详情页
• assets/icons/ai-robot-sm.svg — AI 机器人小图标（新增）

数据库 — DDL 基线与种子数据

• db/etl_feiqiu/seeds/seed_dws_config.sql — DWS 配置种子数据更新（+148/-）
• docs/database/ddl/etl_feiqiu__dws.sql — ETL DWS DDL 基线微调
• docs/database/ddl/zqyy_app__public.sql — 业务库 DDL 基线微调

其他

• docs/h5_ui/anchors/board-finance-mp-instructions.json — 删除（H5 锚点文件，迁移后不再需要）
• docs/h5_ui/anchors/board-finance.json — 删除
• docs/h5_ui/screenshots/*.png — 批量删除 H5 截图（迁移到小程序后原始截图不再需要）
• docs/h5_ui/icon-mapping.md — 图标映射更新
• docs/prd/specs/P8-miniapp-fe-boards.md — PRD spec 微调
• docs/prd/specs/P9-miniapp-fe-details.md — PRD spec 微调
• scripts/ops/_daily_revenue_0305.py — 日营收脚本微调
• scripts/ops/daily_revenue_report.py — 日营收报告脚本微调
• scripts/ops/screenshot_h5_pages.py — H5 截图脚本调整

DDL/迁移检查

• 新增迁移 SQL：无（new_migration_sql 为空）
• DDL 基线已更新：etl_feiqiu__dws.sql 和 zqyy_app__public.sql 有微调
• ⚠️ DDL 基线状态：has_ddl_baseline 为 false，基线文件虽有变更但未标记为已合并

合规检查

• 文档同步缺失：无（code_without_docs 为空）
• API 接口变更：无（api_changed 为 false）
• OpenAPI spec：无需同步