callout-server 文档

callout-server 是面向 callflow-esl 的智能外呼控制服务：管理外呼任务（campaign）、联系人、 线路、坐席、策略与合规名单，直连 FreeSWITCH inbound ESL 提交 originate，并提供「AI 通话转人工」 的坐席 ACD 路由与转人工会议管理。配套前端是 apps/callout-webpage。

顶层信息与快速运行见仓库根 apps/callout-server/README.md。 本目录是深入文档：接口、业务代码示例、转人工流程。

它在系统里的位置

                    ┌──────────────────┐   HTTP {ok,data}     ┌──────────────────┐
 运营 / 坐席 ──────▶ │  callout-webpage │ ───────────────────▶ │   callout-server │
                    └──────────────────┘                      │   (本服务 :9920) │
                                                              └───────┬──────────┘
                                                    inbound ESL :8021 │ bgapi originate
                                                                      ▼
                                                            ┌──────────────────┐
                                                            │    FreeSWITCH    │
                                                            └───────┬──────────┘
                                            接通后 &socket(async full) │ 回连
                                                                      ▼
                                                            ┌──────────────────┐
                                  POST /api/call-results    │   callflow-esl   │
                                  POST /api/transfers/route  │  (业务编排 :9911)│
                                  ◀──────────────────────── └──────────────────┘
                                       （业务侧回写 / 转人工路由）

关键事实：外呼派发链路上 callout-server 不通过 HTTP 调用 callflow-esl。它只对 FreeSWITCH 提交 bgapi originate {business_code=...} <dialString> &socket(<callflow-esl> async full)； FreeSWITCH 接通后把通道路由回 callflow-esl（outbound socket :9911），由 business_code 选中业务处理函数。业务在通话中／结束时 反向用 HTTP 回写结果（/api/call-results）和请求转人工（/api/transfers/route）。 唯一 HTTP 例外是浏览器软电话会话代理：callout-server 按 callflowEsl.baseUrl 调 callflow-esl 的 HTTP 端口（:9912），见 softphone-sip.md。

文档导航

文档	内容
configuration.md	配置参考：服务、鉴权、依赖、后台任务与 cell 配置。
operations-background-jobs.md	运行与后台任务：数据库、情绪分析、调度、并发、事件与日志。
outbound-task-lifecycle.md	外呼任务生命周期：自动/手动调度、领取与容量锁、originate 边界、四类记录及三个终态来源。
integration.md	集成契约：originate 命令、注入的通道变量、通话生命周期与状态机、两层并发模型。看任何业务前先读这篇。
api-reference.md	完整 HTTP 接口文档：鉴权、响应信封、全部端点的请求/响应结构与示例。
outbound-business-example.md	外呼业务代码示例：callflow-esl 业务如何读变量、播报、识别、录音、回写结果（含最小骨架 + 完整 demo 解析）。
result-schemas.md	外呼结果约定：/api/call-results 的通话结果、业务 metadata、transcript 与 NLU 摘要推荐结构。
flow-script-nlu-development.md	流程脚本与 NLU profile 开发规范：脚本节点如何声明 extract_profile / decision_profile，以及如何在 NLU 服务注册、测试和验证。
softphone-sip.md	浏览器软电话与坐席 SIP 接入：坐席网页外呼链路、SIP 配置字段、会话生命周期（SSE 事件 / 控制命令）与相关配置。
transfer-to-human.md	转人工业务示例：AI 通话转人工的完整流程、会议会话生命周期、坐席间流转（盲转/协商转）、主管监听/强插。

一次普通外呼的端到端时序

1. 运营在前端创建任务（绑定 businessCode + 至少一条启用线路），导入联系人，启动任务。
2. 后台调度器（或手动 POST /api/campaigns/:id/dispatch）按两层并发取出 pending 联系人， 置 dialing，提交 bgapi originate，写入一条 call_attempts（status=accepted）。
3. FreeSWITCH 接通号码 → 回连 callflow-esl → 按 business_code 进入业务 handler。
4. 业务 answer → 录音 → TTS 播报 → ASR 多轮识别 → 得出意向。
5. 业务（或转人工）结束，POST /api/call-results 回写通话层 + 业务层结果， 联系人状态推进为 completed / failed。
6. 可选：通话后情绪分析 worker 对录音/转写排队分析，结果写回 call_attempts.emotionResult。

一次「转人工」的端到端时序

1. AI 业务识别到转人工意图，生成专属会议室 ID（如 transfer-<uuid>），播报「正在转接」。
2. 业务 POST /api/transfers/route：callout-server 从空闲坐席池原子预占一个在线坐席， bgapi originate 坐席分机入会（business_code=agent-conference-guest + conference_id）， 并登记一条 conference_sessions。
3. 业务把客户腿 ctx.conference.join 进同一会议室；坐席接通入会即完成桥接。
4. 运营/坐席可在同一会议室上做坐席间流转：盲转、协商转、主管监听/强插 （/api/conference-sessions/:id/participants）。
5. 末位坐席离开 / 客户挂断后，由挂机事件或 conferenceReconcile 兜底关闭会话、释放坐席。

详见 transfer-to-human.md。