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：无需同步