docs: 记录标准事件与证据 v1 契约 (#150)

This commit is contained in:
QiuSW
2026-08-31 10:04:39 +08:00
parent 23a85278cb
commit b548b05874
4 changed files with 82 additions and 8 deletions
+26 -2
View File
@@ -2,8 +2,8 @@
generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件)
wiki_page: Architecture-and-Code-Map
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Architecture-and-Code-Map.-
wiki_revision: 3327861dbd77ae63fd10246533b87e0b99a69220
synchronized_at: 2026-08-31T01:38:23Z
wiki_revision: 812e822990d8c8e82445bd19ced67aca8c10aba4
synchronized_at: 2026-08-31T01:58:55Z
<!-- gitea-wiki-mirror:end -->
# 架构与代码地图
@@ -320,3 +320,27 @@ Sense Device/Profile/Area 内部事实
协议不得包含摄像头凭据、RTSP URL、query token、内部绝对路径、数据库模型、用户/JWT/Cookie 或 Bell Alert 语义。当前只冻结契约,没有新增网络端点、机器身份或跨端 connector。
<!-- sense-brain-contracts-v1:end -->
<!-- standard-event-evidence-v1:start -->
## 标准事件与证据 v1 契约边界
- Event Schema:`contracts/events/v1/event.schema.json`,版本 `yovision.event/v1`。
- Bell 接入描述:`contracts/events/v1/openapi.json`,返回创建、重复、幂等冲突和不支持版本等明确结果。
- Evidence Schema/API:`contracts/evidence/v1/evidence-reference.schema.json`、`openapi.json`,版本 `yovision.evidence-reference/v1`。
- 共同测试:`contracts/tests/events-v1/`、`contracts/tests/evidence-v1/`。
后续 #153 的映射流固定为:
```text
Brain internal candidate / Sense local event
→ yovision.event/v1 producer mapper
→ Sense Outbox relay(默认拓扑,保持原 producer/source ID)
→ Bell v1 ingress
→ Bell private immutable Event + permanent Receipt
→ Bell private Rule / Alert / ack / close
```
规范载荷使用 RFC 8785 JCS 与 SHA-256 形成稳定摘要。同键同摘要返回原 Event;同键不同摘要返回冲突并审计,不覆盖原事实。Evidence 只提供逻辑引用与状态/完整性元数据,不授予访问权限,不包含本机路径、签名 URL 或凭据;取证授权由后续机器身份和 connector 工单实现。
Brain candidate、Sense candidate/Outbox 与 Bell Event/Receipt/Alert 继续是各自内部模型。当前没有新增可运行的跨端 ingress/relay,不能把冻结 Schema 解释为端到端链路已完成。
<!-- standard-event-evidence-v1:end -->