diff --git a/docs/README.md b/docs/README.md index 4801830..15dcc02 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,6 +30,7 @@ ### 证据 +- [`evidence/README.md`](evidence/README.md):证据与开发文档的职责边界、保留和归档规则。 - `evidence/` 保存可复核的运行事实、测试结果和边界说明;历史证据不因当前契约变化而改写。 - 当前 MQ-only 本地结论以 [`plan-0918.md` §8.2](plan-0918.md) 和 [`20260922-mq-only-local-final.md`](evidence/20260922-mq-only-local-final.md) 为准。 - 证据中的 `mock`、`mixed`、`real` 必须按原记录理解;本地或隔离通过不等于真实 SaaS、供应商、生产或容量验收通过。 diff --git a/docs/archive/README.md b/docs/archive/README.md index 4426bc8..9b040c4 100644 --- a/docs/archive/README.md +++ b/docs/archive/README.md @@ -8,6 +8,7 @@ - `evidence/20260920-local-p1-acceptance.md`:修订前的单节点本地 P1 汇总,不能覆盖当前 MQ-only 修订。 - `evidence/20260920-local-oss-mq-integration.md`:旧 OSS/MQ 验证,仍保留 `recording.ready` 等历史事实。 - `evidence/20260921-mq-only-adjustment-baseline.md`:MQ-only 改造前基线,已被当前实现和 [`evidence/20260922-mq-only-local-final.md`](../evidence/20260922-mq-only-local-final.md) 取代。 +- `evidence/20260920-nonprod-capture-preflight.json`、`evidence/20260920-nonprod-capture-preflight-v6.json`、`evidence/20260920-nonprod-capture-preflight-v7-package.json`:同一 capture-first 入口的中间无呼叫预检;最终 parser 修正版仍保留在当前证据目录。 - `references/a.md`:无项目入站引用的外部 FreeSWITCH 资料,不属于本项目契约或验收依据。 -归档证据只用于还原当时的环境、命令和结果,不得用来宣称当前实现、真实供应商、生产 SaaS/MQ receipt 或生产切换已通过。 \ No newline at end of file +归档证据只用于还原当时的环境、命令和结果,不得用来宣称当前实现、真实供应商、生产 SaaS/MQ receipt 或生产切换已通过。 diff --git a/docs/evidence/20260920-nonprod-capture-preflight-v6.json b/docs/archive/evidence/20260920-nonprod-capture-preflight-v6.json similarity index 100% rename from docs/evidence/20260920-nonprod-capture-preflight-v6.json rename to docs/archive/evidence/20260920-nonprod-capture-preflight-v6.json diff --git a/docs/evidence/20260920-nonprod-capture-preflight-v7-package.json b/docs/archive/evidence/20260920-nonprod-capture-preflight-v7-package.json similarity index 100% rename from docs/evidence/20260920-nonprod-capture-preflight-v7-package.json rename to docs/archive/evidence/20260920-nonprod-capture-preflight-v7-package.json diff --git a/docs/evidence/20260920-nonprod-capture-preflight.json b/docs/archive/evidence/20260920-nonprod-capture-preflight.json similarity index 100% rename from docs/evidence/20260920-nonprod-capture-preflight.json rename to docs/archive/evidence/20260920-nonprod-capture-preflight.json diff --git a/docs/evidence/README.md b/docs/evidence/README.md new file mode 100644 index 0000000..2612046 --- /dev/null +++ b/docs/evidence/README.md @@ -0,0 +1,43 @@ +# 运行证据 + +`docs/evidence/` 只保存可复核的运行事实,不保存新的设计结论,也不是每次单元测试的输出目录。 + +## 文档职责 + +- 方案、契约、决策和 `plan-0918.md`:记录当前应遵循的规则、范围和结论。 +- 本目录:记录某个 commit、制品、环境和命令实际得到的结果、失败边界和阻塞原因。 +- `docs/archive/evidence/`:保存已被当前基线替代、但仍有追溯价值的历史证据。 + +证据不能单独把“方向已确认”升级为“实现完成”,也不能把本地、Mock 或隔离结果升级为真实供应商、生产或容量验收。当前状态以 [`../plan-0918.md`](../plan-0918.md) 的台账和适用契约为准。 + +## 当前入口 + +- [`../plan-0918.md`](../plan-0918.md):当前状态、范围和下一步的唯一开发台账。 +- [`20260922-mq-only-local-final.md`](20260922-mq-only-local-final.md):当前 MQ-only 单节点/单 Cell/单租户本地汇总。 +- [`20260920-scope-amendment.md`](20260920-scope-amendment.md):本轮范围修订事实。 +- [`20260921-mq-v1-contracts.md`](20260921-mq-v1-contracts.md):MQ-only v1 本地契约验证事实。 +- [`mq-ai-local-roundtrip.md`](mq-ai-local-roundtrip.md)、[`mq-control-recovery.md`](mq-control-recovery.md):本地 MQ、AI 和恢复边界的专项事实。 + +## 应保留 + +- 当前验收边界的最新汇总; +- 外部运行环境、供应商响应、部署状态和故障注入结果; +- 会影响后续设计或回归判断的失败、阻塞和限制; +- 代码、制品、契约、依赖的版本或哈希,以及可复现命令。 + +## 不应写入 + +- 密钥、密码、私钥、完整 TOKEN、签名 URL; +- 完整录音、完整用户对话、完整识别文本或原始用户数据; +- 原始 PCAP、完整运行日志和仅用于一次排错的临时文件; +- 与已有结果没有新增事实的逐次单测输出或重复重试快照。 + +原始诊断材料如确有必要,只能写入受限的非生产证据目录并按保留期清理;提交到 Git 的内容应是脱敏摘要、计数、状态码、限制和哈希。 + +## 新增与归档规则 + +1. 先更新开发文档中的当前结论,再决定是否需要新增证据。 +2. 只有实现验证、外部环境事实、失败/阻塞或可回归边界才新增证据;普通单元测试由测试和 CI 记录即可。 +3. 同一流程只保留最新汇总和仍有独立决策价值的失败记录;中间版本移到 `docs/archive/evidence/`,不改写历史事实。 +4. 移动证据后必须更新引用;归档证据只能用于还原当时的环境和结果,不能作为当前实现或验收依据。 +5. 新证据至少注明:时间、环境(`mock`/`mixed`/`real`)、代码或制品标识、命令、预期、实际结果、退出码、限制和是否允许据此验收。 diff --git a/docs/plan-0918.md b/docs/plan-0918.md index f2e874c..ed2d23f 100644 --- a/docs/plan-0918.md +++ b/docs/plan-0918.md @@ -218,7 +218,7 @@ go build ./... 另做自有源码格式检查,输出差异而非静默改动第三方/生成物;核验实际Go 1.27.1及构建镜像/依赖锁。当前入口还须运行 `buf lint/build/generate`、`scripts/check-contracts.sh`、`scripts/check-proto.sh`、`make acceptance-local`;对应任务还须运行源生成一致性、真实隔离DB/MQ、协议、故障注入及实际构建入口的检查。以上命令不代表所有验收完成。 -证据使用稳定的项目相对路径(后续可在 `docs/evidence/` 下按W/工作包保存,不提前建空目录),记录环境/mock-mixed-real、代码base/head/integration commit、制品/合同/依赖版本、命令、预期与实际、退出码、时间和风险。工作包证据按实际范围归档;集成负责人将证据绑定到实际合并提交后记G。禁止存密钥、完整音频/对话,不复制旧报告冒充验收。 +证据使用稳定的项目相对路径(维护规则见 [`docs/evidence/README.md`](evidence/README.md);后续可在 `docs/evidence/` 下按W/工作包保存,不提前建空目录),记录环境/mock-mixed-real、代码base/head/integration commit、制品/合同/依赖版本、命令、预期与实际、退出码、时间和风险。工作包证据按实际范围归档;集成负责人将证据绑定到实际合并提交后记G。禁止存密钥、完整音频/对话,不复制旧报告冒充验收。 ## 8. 当前执行台账(后续 Agent 必须维护)