Neo-ZQYY/docs/prd/Neo_Specs/review-audit/P5.1-NS3-03.md

P5.1→NS3 缺失项 #3：App3 维客线索生成的触发条件和频率

简要结论

• 状态：✅ 已解决
• 风险等级：🟡 低
• App3 的触发机制已通过事件驱动架构完整实现：消费结算事件触发 → dispatcher 编排调用链 → App3 执行。触发条件和频率在 P5 spec 和代码中均有明确定义。

详细审查

审查范围

• apps/backend/app/ai/dispatcher.py — AI 事件调度与调用链编排器
• apps/backend/app/ai/apps/app3_clue.py — App3 实现
• apps/backend/app/services/trigger_scheduler.py — 触发器调度框架
• apps/backend/app/main.py — AI 事件处理器注册
• docs/prd/specs/P5-miniapp-ai-integration.md — P5 spec 触发条件定义

发现

1. 触发条件：P5 spec AC3 明确定义"应用 3 维客线索在客户新增消费时自动更新"。代码实现完全匹配：

   • dispatcher.py 的 handle_consumption_event() 方法在消费结算事件发生时触发 App3
   • 事件名称：ai_consumption_settled
   • 触发参数：member_id, site_id, settle_id, assistant_id（可选）

2. 触发频率：事件驱动（非定时），每次客户新增消费（结账单）时触发一次。这是 P5 spec 设计的意图——"客户新增消费时自动更新"。

3. 事件注册链路：

   • main.py lifespan 中创建 AIDispatcher 并调用 register_ai_handlers()
   • register_ai_handlers() 将 3 个事件处理器注册到 trigger_scheduler：
     • ai_consumption_settled → handle_consumption_settled
     • ai_note_created → handle_note_created
     • ai_task_assigned → handle_task_assigned
   • 业务代码通过 fire_event("ai_consumption_settled", payload) 触发

4. 调用链编排：消费事件触发后的完整链路：

   消费事件 → App3（线索分析）→ App8（线索整理）→ App7（客户分析）
   如有助教参与 → App4（关系分析）→ App5（话术参考）
   

5. 容错策略：dispatcher.py 文档字符串明确说明：

   • "某步失败记录错误日志，后续应用使用已有缓存继续"
   • "失败应用写入失败 conversation 记录"
   • "整条链后台异步执行，不阻塞业务请求"

证据

dispatcher.py 中的消费事件处理：

async def handle_consumption_event(
    self,
    member_id: int,
    site_id: int,
    settle_id: int,
    assistant_id: int | None = None,
) -> None:
    """消费事件链：App3 → App8 → App7（+ App4 → App5 如有助教）。"""
    # 步骤 1：App3 线索分析
    app3_result = await self._run_step("app3_clue", app3_run, context)
    # 步骤 2：App8 线索整理
    # 步骤 3：App7 客户分析
    # 步骤 4（可选）：App4 → App5

main.py 中的 AI 事件处理器注册：

_dispatcher = AIDispatcher(_bailian, AICacheService(), ConversationService())
register_ai_handlers(_dispatcher)

_create_ai_event_handlers() 中的事件映射：

return {
    "ai_consumption_settled": handle_consumption_settled,
    "ai_note_created": handle_note_created,
    "ai_task_assigned": handle_task_assigned,
}

P5 spec 调用链定义：

消费事件（结账单）: └→ 应用 3（维客线索分析）→ 应用 8（线索整理）→ 应用 7（客户分析）