# 共享契约维护

## 唯一来源与目录边界

最终契约仓库：`git@gitee.com:zzmbac/sip-contracts.git`，分支 `main`。
SaaS 开发人员与本项目共同维护业务规范、Schema、MQ 拓扑和正常示例。
本项目的 `contracts/schema` 是 Git submodule，只记录消费的确定提交，不维护另一份本地定义。
原 `contracts/local` 已移除；`docs/thirds/saas-dispatcher.md` 只提供导航。
内部 `proto/agent/agent.proto` 仍属于本项目，不移入 SaaS 业务契约。

| 位置 | 用途 |
| --- | --- |
| `contracts/schema/` | 双方对接所需的规范、Schema、拓扑和正常示例；README 分开列出 Schema 和 Examples 用途，业务规范及 MQ 拓扑在正文单独链接说明。 |
| `contracts/manifest.json` | 本项目记录的当前规范、冻结历史来源和对接文件完整性 hash；不是 SaaS 对接数据。 |
| `contracts/verify.py`、`contracts/test_verify.py` | 离线检查 Schema 引用、来源和文件完整性，并验证共享目录及 README 的范围。 |
| `contracts/examples/invalid/` | 本项目拒绝错误消息和配置的测试材料，不作为正常对接示例。 |
| `contracts/archive/sources/` | 两份历史来源的原字节，只用于验证，不作为当前规范。 |
| `contracts/AGENTS.md`、`contracts/*_test.go` | 本项目维护规则与契约测试。 |

## 获取项目

```sh
git clone --recurse-submodules git@gitee.com:zzmbac/go-sip-agent.git
# 或在已有项目中获取固定契约版本：
git submodule update --init --recursive
```

构建仅将固定提交的 Schema、拓扑和正常示例嵌入制品，不包含本项目 manifest、错误示例或历史来源，
不在运行时读取 Git checkout 或在线加载引用。普通 `make check` 不自动联网追新。
缺失/未初始化契约、错误来源、未提交修改、指针不一致、hash 错误或未登记的引用均明确失败，没有旧文件兜底。
发布清单分别记录共享仓库地址、准确提交、拓扑 hash 和本项目验证 manifest 的 hash。

## 每次调研或修改契约之前

```sh
# 同步本项目自己的远程分支；失败或分叉时停止，不覆盖现有修改。
git fetch origin
# 依据当前分支的上游进行 --ff-only 合并。
make contracts-update
```

`contracts-update` 获取共享仓库最新 `main` 并只允许快进；更新前验证当前指针、来源及干净状态，
更新后使用本项目 `contracts/` 中的验证材料检查共享契约。检查通过后仅暂存 `contracts/schema` 新指针。
脚本不提交其他文件，不自动改写本项目 manifest；若新提交与本项目记录的 hash 不同，检查失败，
须核对差异后按下述流程显式更新验证记录，不得回退到旧文件。
网络错误、分叉或现有契约修改时停止；不自动 stash/reset，不改写已有历史。
若指针有意改变但尚未暂存，须先核对该提交再 `git add contracts/schema`，不能用脚本掩盖未知版本。

## 修改与同步交付

1. 确认已完成上述更新；在共享仓库修改对应 Schema、业务规范、拓扑或正常示例。
   定义只维护一次，聚合入口只引用独立 Schema；README 将 Schema 与 Examples 分表，业务规范和 MQ 拓扑使用独立链接说明。
2. 在本项目补充错误示例或测试，并核对共享文件变更后显式更新验证记录：

   ```sh
   python3 contracts/verify.py --write
   python3 contracts/verify.py
   python3 -m unittest discover -s contracts -p 'test_*.py' -v
   go test ./contracts
   ```

   `--write` 只更新现行规范/bundle hash，不允许重算冻结历史来源来掩盖改写。
3. 提交并推送共享仓库，只选择本次修改的对接文件：

   ```sh
   git -C contracts/schema add <本次契约文件>
   git -C contracts/schema commit -m '<契约变更说明>'
   git -C contracts/schema push origin HEAD:main
   git add contracts/schema
   make contracts-update
   ```

4. 同步本项目实现、测试和文档；运行 `make contract-check`、`make check`、`make release-check-local`。
5. 明确暂存本次项目改动及 `contracts/schema` 指针，提交本项目；通知 SaaS 开发人员按同一 commit SHA 同步。

**仅推送契约仓库不算完成。所有契约变更必须同步修改本项目；双方评审和联调需记录同一准确提交。**
已有 P01–P08、A01–A12、K01–K16 项目内证据见 `docs/evidence/saas-dispatcher-p08-acceptance.md`。
本次目录整理不改变业务规则、不部署、不拨号；Mock、hash 或离线验证不替代 SaaS、供应商或生产签收。