go-sip/docs/plan-config-read-v0.1.md

Go SIP Agent：配置读取与有界外呼迭代计划 v0.1

当前迭代唯一执行入口；状态：字段提案已建立，新 HTTP 合同/实现/验收均未完成。 本文接替已恢复原始内容并归档的 plan-0918.md。旧计划只作历史证据/背景，不能把旧 W01–W16 的本地通过数写成新接口、多 Dispatcher 或真实 SaaS 的验收。分项设计见 有界消费与控制通道设计，字段草案见 配置读取字段/返回结构提案；分项材料和草案均不替代已发布 Schema。

1. 范围和完成标准

本次要建立两个只读 SaaS→Dispatcher HTTP 配置接口：取得 management 已批准、适用于该 Dispatcher 的完整 SIP 配置；取得归属该 Dispatcher 的单个任务配置（内含获授权的智能体不可变版本/参数）。任务、智能体及 SIP 配置修改后，已接纳的执行保持旧快照；尚未接纳的执行允许在不超过约 60 秒的已核验缓存期内使用旧批准版本。呼叫、控制、查询、补传、recording.uploaded 和业务结果仍唯一经 RabbitMQ；不保留旧 AI/SIP 配置 MQ 回退，也不复活历史业务 HTTP。

当前 P1 仍为单 D/单 Agent/单 Asterisk/单 Cell/单租户，现行已发布 SaaS↔D 全 MQ 契约、静态 SIP 制品、Asia/Shanghai [09:00,20:00) 门禁和旧排队 AI 版本绑定，在新版本逐项发布、替换及验证前继续执行；本计划和字段草案不授权新线路、跨窗真实拨号、SaaS 生产部署或多 D 业务运行。外部真实 SaaS、云资源、供应商联调及拨号须分别获授权。

完成条件分层：

• C（合同）：两接口实际 SaaS/management 来源、路径/身份承载/返回及错误 Schema、版本/摘要/ETag/缓存/修改并发冻结点、现行 call.execute 旧引用如何合法换版，连同必须变更的 MQ 控制语义，以新版本获签收、正反例和哈希校验。当前 项目自拟 Schema只算草案，不是 C。
• L（单 D 本地闭环）：单租户的任务+智能体读缓存、SIP 完整获批加载、有界消费/独立控制、任务×线路时段、ACK/恢复及 outbox 本地隔离故障测试通过；配置失效只停新准入，停止/暂停仍可达。完成本项目格式化、go vet ./...、go test -race ./...、构建和模块覆盖率 ≥65%，留脱敏事实证据。旧本地通过不代替 L。
• M（多 D 后续门禁）：同租户多任务、每任务只归一个 D，不同 D 独占 Agent/Asterisk；D1/D2 任务/缓存/队列隔离、租户/供应商额度份额总和限制、未知占用和非自动迁移故障注入。仅当多 D 开发与授权另行确定时验收，不混入当前单 D 的 L。

2. 权威资料和读法

1. 先读本文件，按第 4 节找到 F 工作包，再读对应的项目现行合同：Go 架构、验收、通信与事件、开源复用及 contracts/upstream/v1/。现行运行依据优先于尚未签收的新目标；差异写进 F01，不从旧严格 Schema 擅加字段。
2. 页面截图分析只证明页面显示的业务含义，不能证明网络请求/响应的 JSON 键、类型或 SIP 实际管理字段。字段提案里的英文键是项目自定义；旧 OpenAPI/MQ 索引也只是历史对照，绝非现网 SaaS API 签收。
3. 第三方对接事件与请求消费顺序只按 SaaS↔Dispatcher 现行 MQ 命令/反馈与拟定 HTTP 两接口的顺序说明请求、返回和字段；是联调读物，不是新 Schema 或外部签收。已归档的原 plan-0918保留旧 W、I/M/G、部署和证据的历史语境；不要继续写旧台账或以旧 §9 当本轮并行授权。每个工作包的新状态只在本文 §8 登记。

3. 已确认方向与不能省略的边界

• **配置源：**SaaS 负责任务、智能体及单任务→D 的持久归属；management 是 SIP 唯一编辑/审批面，SaaS 只读分发准确的获批准 SIP 制品。如 management/SaaS 不共享同一权威来源，先证明同步及全量范围，再宣称两接口足够。
• **两接口的响应：**SIP 全量须覆盖适用线路/连接、主叫、媒体、额度、时段及获批制品的版本/摘要；任务响应包含任务时段（周一至周日逐日多段、可选多排除日期）、线路选择、任务额度、所选智能体不可变配置及有效授权。统一 Asia/Shanghai；两种时段必须同时允许，缺失/未知禁止新拨号。供应商 transport/auth/registration 尚未确认时不得为 real 设默认值。UI 已显示但 Agent 无批准 SDK 参数的项记录为缺口，不通过 metadata 偷渡。
• 缓存与变更：每 D 使用自己的 UUID+SECRETKEY 读取；成功校验的任务缓存按租户+任务约 60 秒，活跃且尚有待接纳执行时到期主动复核；SIP 启动/重启取全量，运行中约每 60 秒核对。条件请求的 ETag/304 可省内容，不能延长过期或撤销的 AI 授权。到期失败/答复不明就停新执行准入，不让 Agent 凭过期缓存发起新呼叫；已接纳的执行始终使用持久绑定的快照。SIP 变更先关准入、排空/对账旧使用者并核验 Agent/Asterisk 实际加载，发现变化 ≤约60秒不代表加载 ≤约60秒。任务终结仅删除可重取的配置缓存，不删幂等/执行恢复/outbox 事实。
• **MQ 与任务所有权：**每任务只投递到归属 D/租户的队列，控制也投同一 D；不要求每任务单建队列。D 仅在有可用任务/租户/Cell/线路/AI 名额及配置资格时有界接收、同事务持久绑定执行/占用/outbox 后 ACK。其它呼叫仍留 MQ；控制/查询应有独立通道，满额仍能到达。当前共用队列与 not_found 处理无法保证未接纳任务先收到 stop 后不拨，必须先冻结屏障与乱序语义。缓存延迟不延迟 MQ stop/pause、opt-out、号码白名单或最后发起许可。
• 时间/多 D：目标时间由任务及所选 SIP 线路交集决定，排除日期优先；没有合同和最后拨号门禁前仍执行固定 [09:00,20:00)。多个 D 各有独占执行资源，但单任务归一 D 仅解决该任务的并发；若同一租户或供应商额度跨 D，共享总上限须权威分配有界份额，份额总和不超上限。D1 队列的未知/未决任务不能被 D2 抢收或自动迁移。

4. 分步任务（按依赖顺序）

工作包	输入 / 负责人边界	完成证据 / 未满足时状态
F00 页面与字段预盘点	项目文档负责人：引用截图、现有 AI/静态 SIP Schema 和旧只读索引，逐字段标 P/C/N；两种成功及错误响应草案、示例/正反例	字段提案与项目自拟 Schema本地可校验；草案完成≠ SaaS 实际字段已核验。
F01 新合同冻结（前置于任何 client/管理发布）	SaaS/management 权威负责人分别确认数据源、接口路径/UUID+SECRETKEY承载、字段类型/缺省/范围、批准状态、版本/哈希、响应错误、缓存约60秒与同时修改/接纳的冻结点；本项目集成负责人重版导入 W01 所需权威包并明确废弃旧 AI 配置 MQ 路径及新业务 MQ 拓扑	新版本来源/版本/哈希、严格 Schema、正反例、批准记录；任务字段与线下管理 SIP 完整可用，供应商不明参数、原 call.execute 引用矛盾及 HTTP 304 授权未解决均记 blocked，不能先写旧路客户端。
F02 最小单 D 配置读取（依赖 F01）	SaaS 提供两条只读接口；本项目 D 对 SIP 启动全量与 Agent/Asterisk applied 事实核验，对归属任务按需拉取内含 AI、60秒缓存/ETag/304、失效停新准入；所有密钥/端点受控注入	新 D 无历史广播亦可取全量；HTTP 过期/错误/更新竞态、新旧 Agent 参数及快照不漂移测试；SIP 制品未准确加载拒新执行，控制仍可达。
F03 有界执行队列与控制隔离（依赖 F01）	本项目 D 消费、SQLite 额度/绑定和 MQ 适配：空位才接纳，未接纳留 MQ；执行/控制路由分离须新版合同及 SaaS 发布端配合；旧直写面禁并行	爆量消息 SQLite 未接纳积压不无界增长，MQ 队列有容量/发布拒绝与 SaaS 原消息保留；commit/ACK/confirm 丢失及 stop-before-accept 不拨、不忙重投；unknown 不自动释放。
F04 时段与最后屏障（依赖 F01/F02/F03）	SaaS 批准任务周多段/排除日与 SIP 线路时段，D/Agent 使用同一已加载版本及 Asia/Shanghai 注入时钟；替换固定窗须对应合同/验收同步更新	左闭右开、空日/多个排除日期/任务与线路交集、缓存更新后 ≤约60秒、队列跨窗不自动延迟、D/Agent 最后拨号门禁均通过；仅 Mock 时间不宣称 real 已放行。
F05 多 D 独占资源（后续，依赖 F01–F04 及另获本阶段授权）	SaaS 对 (tenant_key,task_id)→dispatcher_id 持久路由；D1/D2 各占独立 Agent/Asterisk/队列/持久目录，租户和供应商共享额度按 D 分份额	双 D 错投/重启/配置变更/未知通话及份额总和故障注入；不得用 D1/D2 本地合同 fixture 冒充双 D 真实业务或 HA。
F06 验收与切换（依赖相应 F 包）	集成负责人单写现行 §8 台账，模块证据只存脱敏状态、计数、哈希；生产、真实 SIP/OSS/云另行授权	新 C→L→M 门禁分开记录。至少 gofmt、go vet ./...、go test -race ./...、go build ./...、本模块覆盖率≥65%；版本回退不得同时运行旧/新路径、触发第二次拨号。

5. 必测边界与阻塞项

1. **返回与缓存：**两接口 200/条件 304/错误、未知字段拒绝、任务归属错 D 拒绝、已有任务/线路版本不一致、摘要与实际加载不一致、授权过期、缓存第 59/60 秒、SaaS 断连、Dispatcher 重启、内存配置清理但恢复事实仍在；配置不完整绝不发新呼叫。
2. **消费与故障：**MQ 爆量/队列满发布端保留、D DB 满盘、ACK 丢失、旧命令重新投递、控制先到未入库执行、停/暂停与配置更新并发、执行中未知占用、不同任务落不同 D 的租户和运营商总额度；没有多 D 份额合同就不开放跨 D 测试。
3. **时间与安全边界：**任务/线路时段变化允许的约60秒延迟必须与“已接纳不变、未接纳可能旧版”区分；MQ stop/pause 和号码白名单不可延迟；配置过期则拒新准入，队列消息期限不可让旧任务次日自动拨。真实外呼只在获得明确安排、实际已通过相应门禁后才能尝试。
4. **缺失权威：**页面截图没有现网 JSON 键，config-read-v0.1.schema.json 为项目自拟；SIP 线路完整管理信息、供应商鉴权/注册、AI UI 扩展和 snapshot_sha256 规范仍未获发布或外部签收；不能把 Mock 数据、旧 OpenAPI、计划或字段草案记为 SaaS/production 验收。

6. 文档/写入边界

新接口版本必须在本项目 docs/ 与导入的版本化 contracts/ 保持唯一来源；UI 截图盘点不改造成第二套 SaaS Schema，字段索引只读生成。当前严格旧合同只描述运行中的 MQ-only 路径，新合同获得批准前不偷加 HTTP client、旧 MQ 配置回退或新任务路由键。原 plan-0918.md 已恢复 HEAD 字节内容归档，归档与本轮状态均不回写旧台账。docs/README.md 和 AGENTS.md 要始终指向本文件；有并行授权时明确一 lane 一工作区/唯一写集合，公共合同、台账和集成状态由集成负责人单写。不得提交、暂存或清理无关修改；大规模重构前另开分支。

7. 当前责任与前置（I/M/G）

• **I = 契约来源/授权：**F00 仅盘点完成；F01 的 SaaS/management 源字段签收、HTTP 合同、MQ 控制/执行新协议及 SIP/AI 不确定项仍为 blocked/pending。没有 I，不开始 F02–F04 的真实配置接入，更不能借 Mock 名义发外呼。
• **M = 本地 Mock/代码验证：**现有已归档计划中的 MQ/AI/静态 SIP 通过只说明旧版局部行为，不是本次新 HTTP/缓存/时段版本通过；按 F02–F04 重做。未获准真实 SaaS 时限于隔离 Mock 与本地合同测试。
• **G = 部署/切换前置：**目标 D/Agent 配置实际加载、broker 状态/队列、运行版本、SHA-256、systemd/Asterisk 状态/日志及非生产诊断必须留脱敏证据；生产安全屏障和资源变更另获批准。单 D 的 L 不授权 F05 多 D 或真实供应商验收。

8. 本轮状态总台账（本文件唯一更新处）

项目	当前事实	下一门禁
历史计划	docs/archive/plan-0918.md 从 HEAD 原样保存；原 W00–W16 状态只作历史	不再向归档文件写新状态。
F00	页面来源分级、两种成功/错误响应 Schema 及 Mock 示例已形成项目自拟草案；第三方事件顺序及字段说明已整理现行 MQ 与目标 HTTP 的分界，均不能称作 SaaS 原 JSON 或签收	校验 Schema/正反例并取得 SaaS/management 字段来源与事件顺序签收。
F01	新 HTTP+业务 MQ 方向获用户同意，精确接口/返回/批准来源未签收	版本化合同、哈希和更新/接纳竞态语义冻结。
F02–F04	未实现；当前代码仍为旧 MQ-only/固定时段/单 D 静态交接	I 先通过；TDD 测试先失败后实施，隔离链路验证。
F05	单任务单 D、资源独占方向确认，多 D 运行/配额份额未验收	后续另获阶段范围、资源及额度权威批准。
F06	新闭环未执行；旧本地测试不能代签	按 C/L/M 分层留证，不写假完成数。

9. 协作和版本记录

本轮只有当前负责人可更新本文件 §8 和共同合同/索引；子任务若获明确并行授权，必须独占文件/测试资源、不得从未跟踪文件假定 HEAD/worktree 已含它，合并每批后统一回归。没有明确真实线路/供应商/云/生产授权，不自动操作外部资源。旧计划的 §8/§9 仅为归档历史；新工作一律以本文件 §7–§9 为入口。版本 v0.1 是规划与项目字段草案，不是 W01/SaaS 的正式发布版本。