docs: record P1 local acceptance and external gates
This commit is contained in:
@@ -1,6 +1,8 @@
|
||||
# Dispatcher 有界接纳与控制通道改造计划 v0.1
|
||||
|
||||
**下一版设计草案，未实施、未获 SaaS 签收。** 唯一计划/台账是[plan-config-read-v0.1](../plan-config-read-v0.1.md)；对外结构见[第三方对接](../thirds/第三方对接事件与请求消费顺序_v0.1.md)。本文同步替代此前的 ETag/304、控制 CAS、暂停丢弃旧积压和逐条停止回执方案，不修改现行 `contracts/upstream/v1/`。
|
||||
**项目内 P1 设计计划，尚未实施；本地 F01/F07 Schema、正反例、来源/hash 与 Mock C 是实施门禁，不要求 SaaS 外部签收。** 唯一计划/台账是[plan-config-read-v0.1](../plan-config-read-v0.1.md)；项目内对接结构见[第三方对接契约](../thirds/第三方对接事件与请求消费顺序_v0.1.md)。本文同步替代此前的 ETag/304、控制 CAS、暂停丢弃旧积压和逐条停止回执方案，不修改现行 `contracts/upstream/v1/`；外部兼容性未验证。
|
||||
|
||||
路径来源：`/internal/v1/dispatcher/sip`、`/internal/v1/dispatcher/task/:task_id`、`/internal/v1/dispatcher/tasks`（含 `?after=<cursor>`）为用户给定路径；`/internal/v1/dispatcher/tenant/:tenant_id/quota` 与任务路由字段 `route_policy_id`、`caller_profile_id`、`allowed_trunk_ids` 为项目内目标，按第三方对接契约和 F01/F07 Schema 实施；不代表 SaaS 现网字段，真实兼容性另记。
|
||||
|
||||
## 1. 目标与范围
|
||||
|
||||
@@ -15,7 +17,7 @@ SaaS 先建持久任务/控制队列和精确绑定，再发布 persistent 消
|
||||
- `/internal/v1/dispatcher/sip`：本 D 获批 SIP 全量，变更关准入、排空/核验实际加载。
|
||||
- `/internal/v1/dispatcher/task/:task_id`：任务及AI、tenant_id、tenant_key、明确主叫、候选线路优先级、两项任务超时。
|
||||
- `/internal/v1/dispatcher/tasks`：启动一致全量/水位，运行每30秒 `?after=<cursor>` 获取变更；cursor非最大任务ID，旧ID变化也返回。
|
||||
- `/internal/v1/dispatcher/tenant/:tenant_id/quota`：**新增路径/字段待签收**；拿到任务后取该租户分给本 D 的额度、版本、截止时间。额度0不接纳，缺失/过期失败不猜默认值。
|
||||
- `/internal/v1/dispatcher/tenant/:tenant_id/quota`：本地项目定义路径；拿到任务后取该租户分给本 D 的额度、版本、截止时间。额度0不接纳，缺失/过期失败不猜默认值；真实 SaaS 路径未验证。
|
||||
|
||||
SIP/任务完整200响应最多缓存约60秒；租户额度也最多约60秒且不超过有效截止时间。不使用 ETag/304。同租户任务复用一份额度与占用，降额不强挂、不清未知；占用低于新限额后才接新。任务时限和AI授权对话时限取较小值；路由按任务获批候选顺序选首个可用且支持明确主叫的线路，拨号后不得自动换线重试。
|
||||
|
||||
@@ -28,23 +30,23 @@ SIP/任务完整200响应最多缓存约60秒；租户额度也最多约60秒且
|
||||
| running、有名额 | 有界接收并原子预留；满额不继续搬队列 | 依持久快照执行 | 接纳/拒绝回执，发生执行后最终结果 |
|
||||
| pause | 关闭准入并暂停消费，已交付未接纳消息退回原队列，不ACK丢弃 | 按drain/hangup | 暂停控制回执；不把暂停积压当作逐条拒绝 |
|
||||
| resume | 强制读取最新任务，running且授权/额度/时段有效才恢复原队列；过期消息拒绝，未过期正常接纳 | 不改旧快照 | 恢复控制回执；无需SaaS重发原积压 |
|
||||
| stop | 先持久停止屏障，再小批量消费并ACK，**无拨号、无逐条回执、无最终结果** | 按drain/hangup处理，保留真实执行结果 | stop控制本身有回执；静默只针对尚未接纳消息 |
|
||||
| stop | 按第三方契约 §0 持久 stopped 屏障，退回已预取未接纳消息并以 `basic.get` 静默 ACK 积压至空；**无拨号、无逐条回执、无最终结果** | 按drain/hangup处理，保留真实执行结果 | 队列无未 ACK 且为空后回 stopped/applied；SaaS 收到后才退役队列 |
|
||||
|
||||
本地 stopped 不可逆，同任务ID不得再resume；paused只有有效resume可解锁。tasks增量/全量和配置缓存不能用旧running解除屏障，低版本不能覆盖高版本；冲突/HTTP错误关新准入。SaaS先持久修改权威任务状态再发控制；无编号控制不设计去重/请求CAS，重投可能重复回执，不能声称exactly-once。乱序/权威状态不符时明确失败并保持关准入，不能根据旧resume自动重开；控制恢复需要新的有效resume核验。
|
||||
本地 stopped 不可逆，同任务ID不得再resume；paused只有有效resume可解锁。tasks增量/全量和配置缓存不能用旧running解除屏障，低版本不能覆盖高版本；冲突/HTTP错误关新准入。SaaS先持久修改权威任务状态再按每任务顺序发控制；无编号控制不设计去重/请求CAS，重投可能重复回执，不能声称 exactly-once。乱序/权威状态不符时明确失败并保持关准入，不能根据旧 resume 自动重开；恢复需要新鲜任务 GET 确认 running。具体状态和错误按第三方契约 §0/§3。
|
||||
|
||||
D重启恢复屏障再应用SaaS全量，取更严格状态。stop排空不依赖通话配额/AI配置可用性：额度0、配置过期仍可ACK；ACK丢失重投再次静默处理。静默仍须保留脱敏计数/错误/恢复事实，不能删除其他任务或忽略已在途执行。SaaS在停止新发布、队列积压和未ACK清零、未知执行核清并完成签收的退役核验后才删队列；队列空不是通话结束证明。
|
||||
D重启恢复屏障再应用SaaS全量，取更严格状态。stop排空不依赖通话配额/AI配置可用性：额度0、配置过期仍可ACK；ACK丢失重投再次静默处理。静默仍须保留脱敏计数/错误/恢复事实，不能删除其他任务或忽略已在途执行。SaaS停止发布后，D 结清已预取投递并 `basic.get` 至空；仅在无未 ACK 且收到 stopped/applied 回执后，SaaS 才能删除队列/绑定并随后发 `removed`。队列空不是通话结束证明。
|
||||
|
||||
## 4. 期限、占用与结果
|
||||
|
||||
30秒轮询不是端到端发现保证，首条命令还需分页/配置/额度准备；有效期由SaaS覆盖其可接受排队时间，不使用30秒默认值。离线/暂停不延长not_after；过期/窗口外非stopped消息明确拒绝，不等待次日。stopped积压即使过期仍静默ACK。
|
||||
|
||||
只有核实通话终结并释放执行资源才释放通话额度，未知不释放；**不等待录音上传和最终消息确认**。录音上传成功后单份call.result带OSS路径；正常未产生录音（忙线/无应答）以not_created即时终结，不申请上传；应有录音但失败用unavailable，上传失败/超时须签收有界终结期限。未接纳且stopped静默处理没有call.result，其他未接纳拒绝只有回执，不造通话。最终文字大小及无截断策略需F07签收，MQ重投同一事实身份不重拨/重PUT。
|
||||
只有核实通话终结并释放执行资源才释放通话额度，未知不释放；**不等待录音上传和最终消息确认**。录音上传成功后单份 call.result 带 OSS 路径；正常未产生录音（忙线/无应答）以 `not_created` 即时终结，不申请上传；授权/PUT 明确失败立即以 `unavailable` 收口，仍无确定结果最迟于 `call.ended_at + 15m` 收口。未接纳且 stopped 静默处理没有 call.result，其他未接纳拒绝只有回执，不造通话。每条 JSON 消息体上限 8,388,608 bytes；超限持久阻塞 outbox，不截断/拆分/丢弃；MQ 重投同一事实身份不重拨/重 PUT。
|
||||
|
||||
取消对外查询/补传与拆分实时文字/拒联/录音事件，不取消内部恢复、日志和外呼幂等。最终通知延迟对拒联业务的影响必须获业务签收。
|
||||
取消对外查询/补传与拆分实时文字/拒联/录音事件，不取消内部恢复、日志和外呼幂等；本轮用户已批准仅最终反馈，真实 SaaS 消费兼容性另记。
|
||||
|
||||
## 5. 开发先后与验收
|
||||
|
||||
不再维护另一套 B 工作包。使用总计划：F01（HTTP/额度）与F07（MQ/发现/状态/结果）并行冻结并联合C → F02配置读取 → F03仅此处的消费/屏障 → F04最后许可/时段 → F08结果集成与切换 → F09矩阵验证 → F06发布。F05多D另授权，避免F01/F07互等和F03/F08重复实现。
|
||||
不再维护另一套 B 工作包。使用总计划：F01（HTTP/额度）与F07（MQ/发现/状态/结果）并行冻结 → 项目内 Mock C → F02配置读取 → F03仅此处的消费/屏障 → F04最后许可/时段 → F08结果集成与本地发布准备 → F09矩阵验证 → F06发布。C 不等待外部签收；F05多D另授权，避免F01/F07互等和F03/F08重复实现。
|
||||
|
||||
必须覆盖总计划§5：同租户多任务原子上限/降额/未知、pause积压100条并在resume继续、stop积压100条后originate/outbox均0而已有2通结果保留、重启/ACK丢失、旧running/迟到resume不解锁、任务ID小而版本新、分页/游标失效、D无建队权限、离线期限、无录音、确认终结即释放额度而OSS延迟、完整最终转写超限。
|
||||
|
||||
|
||||
@@ -2,16 +2,16 @@
|
||||
|
||||
## 1. 状态、权限与使用方式
|
||||
|
||||
**状态：D01–D10原方向已确认，旧W01契约和W02 Proto已有项目内证据；本轮用户确认SaaS↔Dispatcher全MQ，受影响G0的项目内部分已按[归档旧计划§1.2/§8.2](../archive/plan-0918.md)重新验证；本轮两只读 HTTP 配置目标见[新计划](../plan-config-read-v0.1.md)，旧验证不覆盖新接口。** SaaS与D之间所有请求、响应和事件禁止HTTP，每个D具备全局唯一ID和独立接收Topic/队列；V1 Schema、拓扑和关联已有本地包及RabbitMQ证据，外部发布/签收另计。OSS补充确认：配置存于D配置文件，A向D领取固定15分钟临时上传TOKEN后直传；SaaS不再提供OSS配置/TOKEN，上传完成以recording.uploaded可靠入队为界，不等待SaaS verified或OSS ID，D不转发文件。原HTTP方向被本修订替代，不把旧证据覆盖到新设计。
|
||||
**状态：D01–D10原方向已确认，旧W01契约和W02 Proto已有项目内证据；现行 SaaS↔Dispatcher MQ-only 合同及受影响G0的项目内检查仍是当前外部运行基线；本轮四条只读 HTTP GET（SIP、单任务、任务发现、租户额度）和单份最终 `call.result` 的项目内契约见[新计划](../plan-config-read-v0.1.md)，完成 F01/F07 Schema、正反例、来源/hash 与 Mock C 后可继续本地实现，不等待外部签收或连通。** 现行真实 SaaS 与 D 之间仍遵循已发布 MQ 合同；每个 D 具备全局唯一 ID 和独立接收 Topic/队列。V1 Schema、拓扑和关联已有本地包及 RabbitMQ 证据，外部发布/签收另计。OSS 补充确认：配置存于 D 配置文件，A 向 D 领取固定 15 分钟临时上传 TOKEN 后直传；SaaS 不再提供 OSS 配置/TOKEN，上传完成以 `recording.uploaded` 可靠入队为界，不等待 SaaS verified 或 OSS ID，D 不转发文件。本地 C 不宣称 G0、外部兼容、生产验收或上线授权。原 HTTP 方向被本修订替代，不把旧证据覆盖到新设计。
|
||||
|
||||
本项目已创建并验证自己的 Go module、W01 bundle、W02 Proto/stubs、RPC/mTLS 和本地 Mock 测试；未修改父项目权威来源、字段索引或生成产物，未访问真实供应商或创建云资源。文件名保留“提案”以保持链接稳定，不代表还需重复审批已确认方向。
|
||||
|
||||
当前结论：可以继续开展 P0 契约补充、隔离 PoC 和项目内实现；不得宣称 G0 通过或把项目内基线冒充外部权威，也不得启动未获授权的真实供应商/云/拨号。架构、首发范围和供应商方向沿用已有决定，不重新选型。
|
||||
|
||||
- 外部字段/路径/状态仍以带来源哈希的上游主契约为准。本文件记录已确认的变更方向和验收要求，**不能被代码当 Schema 使用**。后续由上游维护者修改唯一来源并发布，再导入生成；本文件保留为决策历史，不继续手工维护字段副本。
|
||||
- 对现行真实 SaaS v1，字段/路径/状态仍以带来源哈希的上游主契约为准。本轮本地目标的规范来源是第三方对接文档，`docs/contracts` 中版本化 Schema、正反例和拓扑为其机器校验件并记录来源/hash；该本地合同不冒称外部发布。本文件仍是 G0 决策历史，不替代上述两类规范。
|
||||
- 内部机制、字段方向及兼容策略已确认，正式 Proto 的类型/编号/错误映射等仍需定稿与校验。本轮不生成 `.proto`，也不以临时 JSON 绕过契约；未提供的字段细节、实际预算和技术验证不能视为一并通过。
|
||||
- 角色简称：S＝SaaS/上游契约维护方，M＝管理平台维护方，D/A＝Dispatcher/Agent 实现方，O＝部署/安全/测试负责人。角色不代表已指定人员或已签收；实际姓名、版本、日期和证据须在批准记录补全。
|
||||
- 保留既有业务语义和8类业务事件，但原7条SaaS HTTP路径与AI GET全部废弃为接入方式；控制/查询/补传/配置授权/上传协调都改为专用MQ请求响应。D↔A仍Unary，A→OSS仍直传，不新增任务mode字段或内部MQ。
|
||||
- 以上为 G0 原阶段决策记录：现行 v1 下控制/查询/补传/配置授权/上传协调走专用 MQ。与本轮四条只读 GET、单份最终 `call.result` 目标相关的本地配置及事件边界，以[新计划](../plan-config-read-v0.1.md)和第三方对接契约为准；新本地代码通过 C 前，旧代码/真实外部运行仍按现行 v1。无需外部签收即可完成本地 C；真实切换另行授权与验证。D↔A仍 Unary，A→OSS仍直传，不新增任务 mode 字段或内部 MQ。
|
||||
- 依据：[重写方案](Go重写方案_v0.3.md)、[通信设计](../contracts/通信与事件数据交互_v0.1.md)、[验收方案](../acceptance/验证与切换验收_v0.3.md)、[只读字段索引](../references/OpenAPI与MQ字段索引_v0.1.md)、[组件清单](../dependencies/开源组件选型与复用清单_v0.2.md)。索引不是独立契约包。
|
||||
|
||||
## 2. 方案确认记录与开发边界
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# SIP Go Agent 重写方案 v0.3
|
||||
|
||||
本版按本次讨论收敛为**稳定、快速单节点内测上线**：1个Agent/1套Asterisk/1个单活Dispatcher、单 Cell、单租户、静态发布、ASR-only与ASR+LLM+TTS双模式。至少3家SIP供应商保留为 trunk 配置与协议 fixture 覆盖；双节点、第二 Cell、双租户、真实 SaaS/MQ 联调和生产 ECS 延期第二阶段。保留Cobra双命令、Dispatcher SQLite、Agent文件、Unary gRPC及关键可靠性；动态治理和规模化另立项。文件名保留，当前仍只有文档，不代表实现或验收通过。
|
||||
本版按本次讨论收敛为**稳定、快速单节点内测上线**：1个Agent/1套Asterisk/1个单活Dispatcher、单 Cell、单租户、静态发布、ASR-only与ASR+LLM+TTS双模式。至少3家SIP供应商保留为 trunk 配置与协议 fixture 覆盖；双节点、第二 Cell、双租户、真实 SaaS/MQ 联调和生产 ECS 延期第二阶段。保留Cobra双命令、Dispatcher SQLite、Agent文件、Unary gRPC及关键可靠性；动态治理和规模化另立项。文件名保留，当前仍只有文档，不代表实现或验收通过。配置读取及最终反馈改造以[本轮计划](../plan-config-read-v0.1.md)为准：目标为 SIP、单任务、任务发现、租户额度四条只读 GET，并以一份最终 `call.result` 替代实时转写、即时拒联和拆分录音事件。F01/F07 联合 C 与业务签收前，本文记录的 MQ-only 配置和既有事件仍是运行合同；不能据新提案声称新路径/事件已生效。
|
||||
|
||||
## 1. 状态、范围与决策
|
||||
|
||||
@@ -111,19 +111,20 @@ Dispatcher配置包含MQ/SaaS受控引用、SQLite路径、两个Agent Endpoint
|
||||
|
||||
### 3.2 权威来源与独立拆仓
|
||||
|
||||
**本轮用户已确认SaaS↔Dispatcher全MQ：双方不再有任何HTTP请求/回调；每个D有全局唯一ID和独立接收Topic/队列。** 执行、控制、查询、补传、AI配置/授权及上传完成事实均经MQ；上传不申请SaaS会话、不等待verified/OSS ID，详见[现行 MQ Schema](../../contracts/upstream/v1/mq.schema.json)、[第三方事件顺序](../thirds/第三方对接事件与请求消费顺序_v0.1.md)与[归档旧计划§1.2/§8.2](../archive/plan-0918.md)；这是现行已发布 MQ-only 合同的历史依据，后续仅配置改为两只读 HTTP 接口的目标见[新计划](../plan-config-read-v0.1.md)，尚未成为运行事实。旧HTTP和旧租户路由已删除；新Schema/拓扑/身份生命周期/关联已在项目内唯一 V1 包和本地证据中冻结，旧源包及哈希不改。
|
||||
**外部当前基线**仍是已发布的 SaaS↔Dispatcher MQ-only v2：真实运行中的执行、控制、查询、补传、AI配置/授权及上传事实沿用[现行 MQ Schema](../../contracts/upstream/v1/mq.schema.json)及[归档旧计划§1.2/§8.2](../archive/plan-0918.md)，不擅改上游包。**本轮 P1 本地目标**按[新计划](../plan-config-read-v0.1.md)和[第三方对接项目契约](../thirds/第三方对接事件与请求消费顺序_v0.1.md)使用四条只读 HTTP GET、v3 命令/控制及单份最终 `call.result`；F01/F07 Schema、正反例、来源/hash 和 Mock C 通过后可继续本地实现，不等待外部签收或连通。它尚未成为真实运行事实，不能与 MQ v2 拼成线上协议，也不代表 G0/生产切换。
|
||||
|
||||
现有上游权威是《SaaS交互_OpenAPI与MQ契约规划_v0.1.md》（正文 v1.0）及经核验的发布产物。现有产物包括 `mq.schema.json`、`executor.openapi.yaml`、`cell-agent.openapi.yaml`、AI 配置及 SIP 管理相关契约。文件存在不代表完整覆盖：P0 必须逐条核对正文、Schema、状态语义和实现差异。
|
||||
|
||||
- 将经批准的协议作为**版本化、只读发布包**导入本项目 `contracts/`，记录源仓库、源版本/提交、文件 SHA-256 和生成器版本；工作区未提交修改不能冒充某个提交的发布产物。
|
||||
- 类型和校验代码从该发布包生成；禁止手写另一套字段、枚举或业务 Schema。
|
||||
- 对现行外部协议，仍将已发布版本作为**版本化、只读包**导入本项目 `contracts/`，记录源仓库、源版本/提交和文件 SHA-256；工作区修改不能冒充上游发布产物。
|
||||
- 对本轮用户指定的项目内目标，以第三方对接文档为规范来源，`docs/contracts` 中版本化 JSON Schema、正反例与 MQ 拓扑为机器校验件，并在本地 manifest 中记录来源和 SHA-256；不宣称这些字段是 SaaS 已发布响应。
|
||||
- 类型和校验代码按各自版本化契约生成/验证；现行外部上游包与本地目标包分离，不互相覆盖或维护隐式兼容层。
|
||||
- 同步工具在开发阶段获取发布包；普通构建、测试和发行包运行不得读取父目录。
|
||||
- 新增调度器—Cell 的消息、fencing、回执或对账字段，先形成契约变更提案并获批；本方案不擅自定字段或 MQ 路由。
|
||||
- 本项目自己的设计、运行、验收文档只在此处维护；上游共享契约仍只有一个编辑源。
|
||||
- 本项目已独立初始化 Git，并按 `git.ipao.vip/rogee/go-sip` 维护；不创建 submodule 或改变父仓库跟踪关系。项目许可证和第三方 NOTICE 在对外发布前确认。
|
||||
- [通信与事件数据交互](../contracts/通信与事件数据交互_v0.1.md)覆盖执行命令、8类业务事件、全MQ请求响应目录及13个内部Unary职责草案；[字段索引](../references/OpenAPI与MQ字段索引_v0.1.md)完整提取42个HTTP操作/115个命名组件。
|
||||
- 已逐字段/哈希确认MQ信封command_type/command_id、event_type/aggregate_*及task_revision与正文一致；但事件payload目前仅通用object，专属约束仍需上游补齐（GAP-01）。不能以旧测试或通用object校验冒充完整验收。文字事件准确名称为transcript.updated。
|
||||
- 42操作/115组件是上游目录，不是本项目首发工作量。P1保留既有业务语义/8种业务事件，但7条HTTP交互及AI GET改为获批MQ请求响应；消费实际所需AI配置和静态制品；不实现管理平台30个API或复制其业务后端。生成/校验仅覆盖使用入口及其引用闭包，来源包与只读字段索引保持完整。
|
||||
- 42操作/115组件是上游目录，不是本项目首发工作量。现行外部 v2 仍按其已发布语义运行；本地 P1 目标则使用已冻结的四条只读 GET、呼叫/控制必要 MQ 回执与单份最终结果，删除旧 query/replay 和拆分实时文字/拒联/录音事件，不实现管理平台30个API或复制其业务后端。真实 SaaS 兼容性另记未验证。
|
||||
- 当前AI Schema强制要求llm/prompt/tts/asr/conversation，缺少明确的ASR-only表达。GAP-08须先在上游批准模式/缺省/文字与错误语义；不在MQ添加临时mode字段或绕过required校验。
|
||||
|
||||
## 4. Go 1.27.1 的采用策略
|
||||
|
||||
Reference in New Issue
Block a user