simplify SaaS SIP configuration response

2026-09-28 16:06:24 +08:00
parent bd2e5ad2b1
commit efb2b86f5e
23 changed files with 700 additions and 169 deletions
@@ -1,4 +1,4 @@
- 本文是新版项目内字段与状态语义的说明；v0.1 文档及证据仅留历史，不作为新版运行契约。四条拟定 GET 的响应字段、路径和外部兼容性尚待真实 SaaS 核对。机器校验文件为[配置读取 Schema](../contracts/config-read-v0.1.schema.json)、[任务发现 Schema](../contracts/task-discovery-v0.2-proposal.schema.json)、[命令/控制 Schema](../contracts/command-next-v0.1-proposal.schema.json)、[最终结果 Schema](../contracts/call-result-v0.1-proposal.schema.json)，队列拓扑为[MQ 拓扑文件](../contracts/mq-topology-v0.1-proposal.json)。它们均为项目内版本，不修改现行上游 v1 契约。
+- 本文是新版项目内字段与状态语义的说明；v0.1 文档及证据仅留历史，不作为新版运行契约。四条拟定 GET 的响应字段、路径和外部兼容性尚待真实 SaaS 核对。SIP 新版机器校验为[配置读取 v0.2 Schema](../contracts/config-read-v0.2.schema.json)（旧 SIP v0.1 Schema 保留历史）；其他配置字段仍沿用原合同。机器校验文件另有[原配置读取 Schema](../contracts/config-read-v0.1.schema.json)、[任务发现 Schema](../contracts/task-discovery-v0.2-proposal.schema.json)、[命令/控制 Schema](../contracts/command-next-v0.1-proposal.schema.json)、[最终结果 Schema](../contracts/call-result-v0.1-proposal.schema.json)，队列拓扑为[MQ 拓扑文件](../contracts/mq-topology-v0.1-proposal.json)。它们均为项目内版本，不修改现行上游 v1 契约。
 - 每个 SaaS↔D JSON 消息体按 UTF-8 序列化后最多 **8,388,608 bytes**。超限结果保留在持久 outbox，标记 `blocked_payload_too_large` 并记录 event_id/字节数/SHA-256；不发布、不截断、不拆分、不丢弃，需由显式版本变更处理。
 - 对已接纳且预期有录音的通话，上传阶段最迟在 `call.ended_at + 15m` 收口；OSS 成功发送 `uploaded`，明确 PUT 失败立即发送 `unavailable`，仍无确定结果则到期发送 `unavailable`。授权固定 15 分钟；每个录音/upload_id/object_key 组合最多一次 PUT。授权在 PUT 前过期时，Agent 可在上述截止时间内显式向 D 为同一 upload_id/object_key 重新申请授权；不自动续期或创建第二份资产，任何已发起 PUT 都不得重试。确认未产生录音的 `not_created` 立即收口。`call.result` 只生成一次，MQ 重投复用原 event_id。
 - 控制按 task 串行处理，并核对最新任务状态：pause 只接受权威状态 `paused`，resume 只接受 `running` 且本地未 stopped，stop 只接受 `stopped`；乱序/不一致时保持准入关闭并拒绝，stopped 不可逆。控制本身无 command_id/expected revision，不按消息身份去重，重复动作只保持状态幂等。
@@ -59,7 +59,7 @@ SaaS 创建并绑定：

 四个 GET 均**无请求 JSON 体**，统一使用 `X-DISPATCHER-ID`（全局唯一 D UUID）和 `X-DISPATCHER-SECRET-KEY`（HEADER 头统一转小写判定匹配）。本地 Mock 使用隔离测试凭据；真实 SaaS 地址、认证实现及轮换未验证，不阻塞本地开发。SIP 返回本 D 全量；单任务按路径中的 `task_id` 查询，SaaS 必须核对归属 D 与原值 `tenant_key`，任务发现则按 D 返回归属清单。**不使用 ETag、If-None-Match 或 304**：任务与 SIP 配置约 60 秒缓存到期时 GET 完整 200 响应，失败只停新准入，已接纳执行保持绑定快照；MQ 控制不等待配置缓存。`tasks` 的每 30 秒增量轮询另见 §2.5。

-### 2.1 SIP 配置：200，返回本 D 的完整获批快照
+### 2.1 SIP 配置：200，返回本 D 的完整获批线路（项目内新版；其他 v0.2 历史内容不变）

 请求（地址/Header 仍待 SaaS 实现确认）：

@@ -74,54 +74,19 @@ X-DISPATCHER-SECRET-KEY: <受控注入，不展示实际密钥>

 ```json
 {
-  "schema_version": "config-read.v0.1",
+  "schema_version": "config-read.v0.2",
  "resource": "sip_config",
  "dispatcher_id": "c046b893-8628-4589-ae50-619d049248a6",
  "revision": 1,
-  "snapshot_sha256": "cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
  "approved_at": "2026-09-21T08:00:00+08:00",
-  "artifact": {
-    "artifact_id": "artifact-cell-mock-1",
-    "source_release": "mock-release-1",
-    "source_digest": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-    "approval_reference": "mock-approval-1",
-    "cell_id": "cell-mock",
-    "revision": 1,
-    "config_sha256": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
-    "mode": "mock",
-    "allowed_targets": [
-      "15003164745",
-      "15830461047"
-    ],
-    "trunks": [
-      {
-        "trunk_id": "trunk-mock",
-        "provider_id": "provider-mock",
-        "egress_pool_id": "egress-mock",
-        "codec": "PCMA",
-        "caller_profile_ids": [
-          "caller-profile-mock"
-        ],
-        "dial_prefix": "",
-        "enabled": true,
-        "sip_endpoint_ref": "sip-endpoint-mock",
-        "credential_ref": null,
-        "media_profile_id": "pcma-8k"
-      }
-    ],
-    "media_profiles": {
-      "pcma-8k": {
-        "format": "alaw",
-        "sample_rate_hz": 8000,
-        "channels": 1,
-        "payload_type": 8
-      }
-    },
-    "load_evidence": null
-  },
-  "trunk_details": [
+  "trunks": [
    {
      "trunk_id": "trunk-mock",
+      "provider_id": "provider-mock",
+      "egress_pool_id": "egress-mock",
+      "codec": "PCMA",
+      "dial_prefix": "",
+      "enabled": true,
      "server_host": "sip.example.invalid",
      "server_port": 5060,
      "transport": null,
@@ -179,11 +144,10 @@ X-DISPATCHER-SECRET-KEY: <受控注入，不展示实际密钥>
 **字段说明／消费动作：**
 > Cell：一个外呼应用Asterisk实例（当前阶段不扩展复杂分布式，写死单实例数据，仅填充Trunk 数据列表，后期根据需求调整分布式架构）；
 > Trunk: 一条外呼线路；
- `schema_version/resource`：草案版本 `config-read.v0.1`、资源 `sip_config`；`dispatcher_id`：只能与发起请求的 D 相同。
- `revision/snapshot_sha256/approved_at`：整份获批快照的修订、摘要、批准时间；摘要生成规则和版本来源仍待双方确定，示例摘要仅为占位值。 **（预留，暂不验证）**
- `artifact`：静态 Cell 制品；`artifact_id/source_release/source_digest/approval_reference` 标识制品、来源版本/摘要和批准引用；`cell_id/revision/config_sha256` 标识执行单元及制品版本；`mode` 是 mock/real 范围；`allowed_targets` 是允许的原始号码；`load_evidence` 为可空加载证据。`trunks[]` 中 `trunk_id/provider_id/egress_pool_id` 定义线路、供应商、出口；`codec` 为 PCMA；`caller_profile_ids` 为主叫引用；`dial_prefix` 仅本线路前缀；`enabled` 是否启用；`sip_endpoint_ref/credential_ref/media_profile_id` 为连接、凭据和媒体配置引用，不传实际密码。`media_profiles` 下 `format/sample_rate_hz/channels/payload_type` 定义媒体格式。
- `trunk_details[]`：每项的 `trunk_id` 必须与 `artifact.trunks[]` 一一对应；`server_host/server_port` 为 SIP 服务端；`transport/auth_mode/registration_required` 是传输、认证和注册方式；`max_concurrent_calls` 是分配到该 D 的线路额度；`null` 代表未知，不可用于真实外呼。`caller_profiles[].caller_profile_id/caller_id` 给出主叫引用/原始标识（如含 `BD`），不可清洗成纯数字。
- `schedule.time_zone/weekly_windows`：Asia/Shanghai 的周一至周日多时段，`start/end` 是每日左闭右开时间；空日禁止外呼。D 校验获批版本与线路完整性并自行核对生效，不能仅凭 HTTP `200` 就认为已加载。
+- `schema_version/resource`：草案版本 `config-read.v0.2`、资源 `sip_config`；`dispatcher_id`：只能与发起请求的 D 相同。
+- `revision/approved_at`：本 D 获批的完整 SIP 线路版本和批准时间。每次更新均须递增 revision；同版本内容不得变化。D 持久核验同版内容不漂移，不接纳倒退版本。
+- `trunks[]`：唯一的线路列表；`trunk_id/provider_id/egress_pool_id` 定义线路、供应商及出口，`codec` 为 PCMA，`dial_prefix` 只用于该线路，`enabled` 控制线路是否可用。`server_host/server_port/transport/auth_mode/registration_required` 为连接方式；未知传输、鉴权、注册或额度不得放行真实外呼。`max_concurrent_calls` 为分配给本 D 的线路额度；`caller_profiles[].caller_profile_id/caller_id` 为主叫引用及原值（可含 `BD`）。`schedule` 是 Asia/Shanghai 每周逐日多时段、左闭右开，空日不可呼。线路 ID 和主叫引用不能重复。
+- SaaS 只提供 SIP 连接及线路拨号约束，不下发 Agent/Asterisk 的 Cell、ARI、媒体、录音、部署制品、全局号码白名单或运行模式。白名单和部署设置由本地受控配置承担。D 只用一个 SIP `revision` 与 Agent 回报的**实际已加载 SIP 版本**核对；加载/核验失败关闭新准入，不以 HTTP `200` 或仅收到配置冒充 Asterisk 已加载。部署时确定的 Agent/Cell 身份由本地核对，不由 SaaS 控制。

 ### 2.2 任务配置：200，ASR + LLM + TTS 模式