ai-kefu-jc/docs/2026-09-28-lead-push-changelog.md

询盘推送 UniService · 改动记录(2026-09-28)

设计: docs/superpowers/specs/2026-09-28-lead-push-to-uniservice-design.md 契约: docs/AI_INQUIRY_PUSH_API.md(UniService v1) 实施计划: docs/superpowers/plans/2026-09-28-lead-push-to-uniservice.md

改动面

• 新表 lead_push_logs(app/models/database.py): 推送审计,状态 pending/success/failed/skipped,outcome 记 accepted/duplicated
• 新服务 app/services/lead_push_service.py: dispatch(SAVEPOINT 隔离, 吞异常,与 SMTP 成败解耦)→ fire(commit 后 create_task,任务不读库 只写结果)→ _run_push(httpx + 分类重试: 5xx/传输退避 3 次、401/400 快败、200 逐条解析含 duplicated、非 JSON 200 诚实落 failed)
• 接线 app/services/conversation.py: _maybe_send_lead_email 三发信 分支各调一次 dispatch(lead/returning/correction 跟随邮件类型); 主事务 commit 后 fire;fire-after-commit 顺序有变异检测级测试钉住
• 启动清扫: main.py lifespan → sweep_stale_pending(30 分钟 stale → failed "interrupted by restart");engine connect_args timeout=30 (后台写结果撞 SMTP 窗口锁时忙等上限抬高,等待在工作线程不阻塞事件循环)
• 配置: PUSH_ENABLED(默认 false)/PUSH_API_URL/PUSH_API_KEY/ PUSH_EXTERNAL_KEY_PREFIX/PUSH_TIMEOUT_SECONDS/PUSH_MAX_ATTEMPTS/ PUSH_RETRY_BACKOFF_BASE(.env.example 同步)

暂缓项

• admin 查询接口 GET /api/admin/push-logs(设计 §9): 用户定夺先完成 推送链路,后续补;期间查结果直接开 data/cc_ai_kefu.db 的 lead_push_logs 表

上线/联调步骤

1. .env 填 PUSH_API_KEY=<UniService 开通分配>,PUSH_ENABLED=true,重启服务生效
2. 产生 1-2 条真实询盘(客户留手机号/邮箱)→ 查 lead_push_logs 表: select status,outcome,response_status,error_message,created_at from lead_push_logs order by created_at desc limit 5;
3. 与 UniService 核对 accepted/duplicated/failed 与归档内容 (首验: 手机号国际区号格式——对方要求带区号,不符整条被拒)
4. 核对无误转正式运行