From 26fde0aff4c31bf9a3afbfd7c77a5076fe4c7fcc Mon Sep 17 00:00:00 2001 From: Rogee Date: Tue, 13 Oct 2026 11:51:49 +0800 Subject: [PATCH] docs(saas-server): record local verification and unchanged business boundary --- AGENTS.md | 2 + docs/evidence/saas-server-v0.1-local.md | 62 +++++++++++++++++++++++++ docs/plan-saas-server-v0.1.md | 6 +-- 3 files changed, 67 insertions(+), 3 deletions(-) create mode 100644 docs/evidence/saas-server-v0.1-local.md diff --git a/AGENTS.md b/AGENTS.md index 03650ed..781977d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -79,6 +79,8 @@ ## 当前范围与权威入口 +- **SaaS Server v0.1（本地测试工具，不改变线上环境）**：`cmd/saas-server` 使用 Fiber/v3，从指定私有 JSON 文件只读加载五类配置；完整快照更新仅内存生效。HTTP/curl 显式发送单条外呼、start/resume/edit 和 SIP 刷新，不自动投递、重发或重启服务；源 `event_id` 原样保留。仅专用 `saas-mock-*` vhost，反馈文件同步保存后 ACK，查询只覆盖本次运行，无历史恢复或发送记录持久化。Dispatcher/Agent、共享业务代码、合同和现有部署不变；不授权部署、真实拨号或 AI/OSS。使用见 [`cmd/saas-server/README.md`](cmd/saas-server/README.md)，本地检查见 [`docs/evidence/saas-server-v0.1-local.md`](docs/evidence/saas-server-v0.1-local.md)。 + - **2026-10-12 接通时长字段已合入并部署登记测试机**：共享契约 `bfa3380` 已推送，本项目业务源码 `8340efd` 已快进合入、推送 `main` 并在 `server.sip` 固定部署。`call.execute.result` 增加 `answered_at` 与 `connected_duration_ms`，原 `duration_ms` 不变；未接通且确认结束为 0，原通道 Up/Destroyed 时间证据缺失为 null，SaaS 不应从 outcome 推断接通时长。重新部署未重置数据、不重启 Asterisk、不抓包/主动试拨；Agent/Dispatcher 均 Debug 开、Capture 关，Asterisk PID 777461 不变，零活动通道，服务均 enabled+active、零重启；实际制品 SHA-256 独立复现。SaaS 探测 `saas_pending`、`business_ready=false`，未观测新字段真实到达、接通通话或生产签收，仍需 SaaS 开发对接与确认。文档后续补记不改变已安装的业务源码版本。详见 [`docs/evidence/connected-call-duration-local.md`](docs/evidence/connected-call-duration-local.md)。 - **SQLite cleanup v0.1 首期（开发分支，本地验收）**：`feat/sqlite-cleanup-v0.1` 仅调整完成数据的本地保留周期。源 `event_id`（含 numberID）原样回传，不新增 `execution_id`，SaaS 如何处理重复结果不在范围；用户在复审中批准仅必要一句文字对齐，共享合同 `7b4448f` 已发布并固定本项目引用，限定首次事实保护为本地执行/回执仍保留期间；接口/Schema/类型/路由不变，不涉及 SaaS 重复处理或等待适配。Agent 不再读写永久 `.approved`；活动 TaskCalls 与 Dispatcher 未决/未知保护保留。已派发呼叫需终结/结果成功及派发回执、最终结果分别 MQ confirm；未发起拒绝只需拒绝确认；取消记录需 durable stopped 和成功 stop confirm。清理事务不删共享配置/任务停止状态，布局仍为 **4**，无迁移/重置。录音仅 delivered 且无未完成 `.results` 引用后删音频、信息、空叶；删除前在私有 `.recording-cleanup` 保存原 delivered 信息临时副本，精确空叶删除并同步父目录后才删副本。info/空叶删除之间硬退出也可按该依据续处理，不泛扫未知空目录、不留永久完成历史；同 OSS 目标在副本清完前拒绝新恢复写入，不再 PUT/报告；拒绝原件按完整回执/原身份/内容精确关联，先全部原件后回执。新原件文件名为回执 SHA-256 与完整记录 SHA-256，仅磁盘关联，不是业务编号；既有完整文件校验读取、不迁移，不能关联的损坏旧文件和潜在依据保留待人工。两角色独立 Asia/Shanghai 每日 24:00 补扫复用实时资格，无 12:00/年龄删除/VACUUM/永久清理历史，清理错误不关闭业务准入。仅测试目录验证 `.approved` 退役，没有实际主机退役、部署、真实数据/OSS 删除、拨号、抓包、AI/OSS 调用或 main 合入/推送；本地通过不代表真实服务验收。检查和逐项证据见 [`docs/evidence/sqlite-cleanup-v0.1-local.md`](docs/evidence/sqlite-cleanup-v0.1-local.md)。此条是开发分支状态，不改变下述线上事实。 diff --git a/docs/evidence/saas-server-v0.1-local.md b/docs/evidence/saas-server-v0.1-local.md new file mode 100644 index 0000000..8b9d43b --- /dev/null +++ b/docs/evidence/saas-server-v0.1-local.md @@ -0,0 +1,62 @@ +# SaaS Server v0.1 本地验收 + +## 结论与范围 + +已按精简后的 [`../plan-saas-server-v0.1.md`](../plan-saas-server-v0.1.md) 完成 `cmd/saas-server`。使用见 [`../../cmd/saas-server/README.md`](../../cmd/saas-server/README.md)。 + +- 配置文件只读，五类配置接口、完整快照内存替换、单条外呼和必要通知、反馈保存/查询可用。 +- 源 `event_id` 原值保留；队列确认、未知、拒绝和最终结果分开处理，不自动重发。 +- 反馈可靠保存后 ACK，查询仅本次运行，重启不恢复历史或保存配置修改。 +- 无独立 CLI、批量、完整任务管理、发送记录持久化、历史索引或新增数据库。 +- 未修改 Dispatcher/Agent、共享业务代码、合同、现有数据库或部署配置。 + +源码提交：`61c1669`（配置服务）和 `d8f9e40`（推送、反馈、操作接口、测试及说明）。后续文档登记不改变业务源码。共享合同固定 `940d9224fd2270791bf2be8d28046f65f7a853f3`，`contracts-update` 校验通过，本次没有合同或子模块指针差异。 + +## 实际执行检查 + +| 检查 | 结果 | +| --- | --- | +| `go test -race ./cmd/saas-server` | 通过 | +| `go test -cover ./cmd/saas-server` | 通过，新命令包覆盖率 **66.1%** | +| `make check` | 最后一次完整执行通过；包括格式、合同/Proto、vet、全量 race、构建及既有隔离 Mock/MQ 检查 | +| `make coverage` | 通过，业务单元覆盖率 **73.1%** | +| `bash cmd/saas-server/check-integration.sh` | 两项实际隔离集成均通过，没有跳过 | +| `make release-check-local` | 本地发布包及合同/队列检查通过，production approved=false；不是部署授权 | +| `python3 -m unittest discover -s deploys/production -p 'test_*.py'` | **26** 项通过 | +| 单独构建 `cmd/saas-server`，执行 `--help` | 通过 | +| `git diff --check`、文档链接及最终变更范围 | 通过 | + +既有 A01–A12/K01–K16 业务范围未改变：仍由现有合同和 Mock 验收门禁检查，新工具不增加旁路或覆盖其业务判断。以上不能代签其中需要真实 SaaS、线路、AI/OSS 或主机的验收项。 + +测试采用先失败再实现的方式，配置服务、启动参数、事件处理、确认状态、内存操作与私密诊断都有对应测试。发现的问题修复后重新执行检查，未用旧的成功日志替代最终结果。 + +## 新工具的端到端证据 + +`TestSaaSServerIsolatedHTTPSMQAgentMTLS`： + +1. 新 Fiber 服务在实际 HTTPS 监听端口提供配置，现有 `configread.Client` 读取。 +2. 使用专用 vhost 的实际 RabbitMQ，不借用现有 SaaS/MQ。 +3. 现有 Dispatcher Runtime 接收测试外呼，经真实双向 TLS 调用 Mock Agent。 +4. Mock Agent 使用合成 PCM 和既有 Mock ASR，经过现有结束/结果反馈链路产生回执与最终结果；没有向反馈队列手工伪造成功消息。 +5. 两类反馈经 MQ 回到新工具，以带特殊字符的原源 ID `numberID-integration/Original:001` 关联并通过校验，原消息证据实际保存。 +6. 输入快照测试前后字节一致。 + +`TestStartupShutdownPreservesConfiguration`：实际启动与关闭新服务，五类配置中的 SIP 读取可用；退出后全部输入文件字节不变，没有自动产生反馈。 + +两项由脚本要求明确 PASS，未配置 broker 时的 SKIP 不算通过。脚本仅创建/移除自己的临时 RabbitMQ 容器，localhost 动态端口、临时存储和随机账号；不自动拉镜像。 + +## 关键回归 + +- 非法配置更新不部分生效，资源身份不可改变；并发读取/替换通过 race。 +- 重启重新加载文件，不恢复内存修改或历史在线查询。 +- 同身份相同请求只发一次，不同内容报错；确认超时/断线保留 unknown，不自动重发。 +- ACK 前实际写入、同步文件和目录；保存失败不 ACK。 +- 同源不同消息类型分别保留；重复消息统计，冲突不覆盖首条。 +- 校验异常明确显示；日志和查询不返回完整原正文或凭据。 +- 使用现有合同诊断保留字段位置，不输出私密值；移除了重复的结果枚举，合法 `answered` 不再被遗漏。 + +集成调试中发现的失败均在测试设置内：JSON map 复用残留任务字段、示例 SIP 缺执行参数、静音 PCM 无语音、反馈目录权限及结果测试数据不匹配。最终改用完整合成测试配置、有语音的合成 PCM 和私有输出目录；没有因此修改现有业务、降低校验或假造执行结果。 + +## 未执行与授权边界 + +没有合入 main、推送、部署、启动/重启现有业务服务、加载真实线路、拨号、抓包、访问真实 AI/OSS、清队列或删除现存业务数据。检查只覆盖本地隔离测试，不代表真实外呼或生产可用。 diff --git a/docs/plan-saas-server-v0.1.md b/docs/plan-saas-server-v0.1.md index 4ab1daa..fa61a0b 100644 --- a/docs/plan-saas-server-v0.1.md +++ b/docs/plan-saas-server-v0.1.md @@ -2,7 +2,7 @@ ## 1. 目标与边界 -需求及本次精简范围已确认；当前仅修改计划，尚未开始实现。 +需求及精简范围已确认，最小实现和本地验收已完成。使用见 [`../cmd/saas-server/README.md`](../cmd/saas-server/README.md)，检查记录见 [`evidence/saas-server-v0.1-local.md`](evidence/saas-server-v0.1-local.md)。本地通过不代表已部署或真实外呼验收。 使用 `Fiber/v3` 在 `cmd/saas-server` 实现独立测试服务，通过 HTTP 接口和 `curl` 替代 SaaS 浏览器/CDP 操作： @@ -22,7 +22,7 @@ ### 2.1 从文件读取配置 -建议启动形式（待实现）： +启动形式： ```sh go run ./cmd/saas-server --config /absolute/path/server.json @@ -105,7 +105,7 @@ go run ./cmd/saas-server --config /absolute/path/server.json - 测试前后比对所有输入配置文件，启动、修改、失败和退出均不改变文件；并发操作通过 race 检查。 - 格式、合同/Proto、`go vet ./...`、`go test -race ./...`、构建及项目既有检查通过，业务单元覆盖率 ≥65%；现有集成检查不因精简而跳过。 - 检查最终变更范围：Dispatcher/Agent、共享业务代码、合同和现有部署配置无改动。 -- 本轮只改计划，检查文档与变更范围，不声称业务功能或真实通话已验证。 +- 本地检查与真实服务验收分别记录；未部署、未拨号，不声称真实通话已验证。 ## 5. 明确不做