go-sip/docs/evidence/task-control-receipt-fields-20261010.md

任务控制回执补齐 — 2026-10-10

范围与来源

• 使用者确认恢复任务控制成功回执的五个字段，覆盖 start/pause/resume/stop/edit。
• 使用者进一步确认：整条消息未通过 Schema，不能据此丢弃其中有效的任务编号和动作；拒绝回执仅省略自身无效或确实无法取得的字段，不填 null，不推测任务状态。
• 调研前已同步项目与共享合同，基线为项目 e48ef85、共享合同 8e6c332。
• 共享合同变更 e750fe4618e6472821ceaa74f6c6227d11f998e3 已推送到共享仓库 main；消费方实现与合同指针一起提交为 b1ae50a，推送到本项目 check-task-control-receipt-task-id 分支。
• 未合入本项目 main、未部署、未向真实 SaaS/MQ 发送消息、未拨号、未读取或重置现存业务数据。

SaaS 开发同步说明

共享仓库 git@gitee.com:zzmbac/sip-contracts.git 的 main 已更新至 e750fe4。请 SaaS 开发同步读取以下权威入口；本文件不维护另一份字段定义：

• contracts/schema/mq-task-control-receipt.schema.json
• contracts/schema/saas-dispatcher.md 的任务控制与拒绝反馈规则
• contracts/schema/examples/mq-control-ack.json
• contracts/schema/examples/mq-control-rejected.json

成功回执恢复任务关联和实际状态；拒绝回执仍保留具体原因，分别按共享字段定义读取有效身份与动作。已存的原回执不会因任务状态后来变化被改写。队列确认不代表 SaaS 应用已处理。

本次共享合同已经发布，但消费方代码尚未合入 main 或部署，不能据此要求当前线上服务已经返回新结构。此说明供使用者直接转达 SaaS；没有独立的 SaaS 通知送达或应用签收证据。

实现边界

• 成功与业务拒绝的任务状态在持久回执所在事务内读取，限定 Dispatcher、租户、任务归属。
• 结构拒绝逐字段使用共享 Schema 的字段定义验证；缺少 issued_at、reason 类型错误、无效动作或无效任务编号不会丢失其他有效字段。
• 先按原始 JSON 字段拆分，再分别解码目标字段；其他字段含超出浮点范围的数值也不会抹掉有效任务编号。
• 请求自带的状态不作为事实；查不到归属内任务时省略状态，数据库读取失败则明确返回错误并回滚，不能以省略状态掩盖故障。
• 原回执重发保持原消息身份与原状态；不同动作不能复用同一回执身份。
• 增加收发方向判定：补齐任务编号和动作后的回执仍不能作为入站控制命令执行。
• 未新增业务表、旧库迁移、旧回执兼容或回退路径。

验证结果

• 新增 Schema、存储测试先失败后通过；入站方向与实际 MQ 收发断言通过。
• go test ./contracts ./internal/store ./internal/mq ./internal/dispatcher -count=1 通过。
• make check 通过：格式、Proto/来源、共享合同、Go vet、全部 race 测试、构建、隔离 RabbitMQ 与本机 HTTP/HTTPS/双向 TLS 测试。
• 隔离 RabbitMQ 的 TestBrokerSharedResultQueueAndNoConfigure 直接读取队列里的成功和结构拒绝回执，核对任务关联、动作、实际状态、原因及发送前后正文相等；不是仅检查构造函数或本机数据库。
• make coverage 通过，业务单元覆盖率 72.6%，高于要求的 65%。
• 固定提交 b1ae50a 的 make release-check-local 通过，source dirty=false，合同固定为 e750fe4，本地制品 SHA-256 为 a87168962e4e6bef828a02a7ce92eafb71c759707547cac8c2aba8978731684f；production approved=false。

本地隔离验证不代替真实 SaaS 接收或生产签收。本次未验证线上新回执、真实 SIP/AI/OSS、主机部署或呼叫。