docs: clarify evidence retention policy
This commit is contained in:
@@ -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、供应商、生产或容量验收通过。
|
||||
|
||||
@@ -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 或生产切换已通过。
|
||||
归档证据只用于还原当时的环境、命令和结果,不得用来宣称当前实现、真实供应商、生产 SaaS/MQ receipt 或生产切换已通过。
|
||||
|
||||
@@ -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`)、代码或制品标识、命令、预期、实际结果、退出码、限制和是否允许据此验收。
|
||||
+1
-1
@@ -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 必须维护)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user