docs: 记录 #152/#153 connector 验收

ila
2026-08-31 15:20:16 +08:00
parent 0b0d28c504
commit b25498f58c
+17 -13
@@ -315,27 +315,31 @@ Sense Device/Profile/Area
<!-- sense-brain-contracts-v1:end -->
<!-- standard-event-evidence-v1:start -->
## 标准事件与证据 v1 契约边界
## 标准事件与证据 v1 connector 结构
- 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/`。
共享协议仍位于 `contracts/events/v1/**`、`contracts/evidence/v1/**`,机器身份位于 `contracts/machine-identity/v1/**`。#153 的产品实现位于:
后续 #153 的映射流固定为:
- Brain producer:`Brain/src/yovision_brain/integration/event_export/**`,由 CLI `app/__main__.py` 按配置启用。
- Sense gateway/relay:`Sense/server/app/sense/integration/bell_connector/**`,由 API 启动链注册 `POST /v1/events`、`GET /v1/evidence/:evidence_id` 和 Bell Outbox Worker。
- Bell consumer:`Bell/server/app/bell/integration/event_ingress/**`,由 router registry 注册 `POST /v1/events`。
- 正式迁移:Sense/Bell 各自的 `2026083112000_*connector*.go` / `*event_ingress.go`。
默认数据流为:
```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
Brain internal candidate
→ canonical yovision.event/v1
→ Sense authenticated ingress
→ Sense InboundEvent + EvidenceRecord + Bell Outbox(同事务)
→ HTTPS relay(原 payload/producer/source ID 不变)
→ Bell authenticated ingress
→ permanent Receipt + immutable Event + conflict audit
→ Bell private Rule / Alert / ack / close
```
规范载荷使用 RFC 8785 JCS 与 SHA-256 形成稳定摘要。同键同摘要返回原 Event;同键不同摘要返回冲突并审计,不覆盖原事实。Evidence 只提供逻辑引用与状态/完整性元数据,不授予访问权限,不包含本机路径、签名 URL 或凭据;取证授权由后续机器身份和 connector 工单实现。
规范载荷使用 RFC 8785 JCS 与 SHA-256。同键同摘要返回 duplicate;同键异摘要稳定冲突并审计。机器令牌 replay 与业务幂等分别持久化,传输重试签发新 jti,但不改变业务 ID。证据解析失败或不可用只更新独立降级状态,不允许上游写 Alert 语义。
Brain candidate、Sense candidate/Outbox 与 Bell Event/Receipt/Alert 继续是各自内部模型。当前没有新增可运行的跨端 ingress/relay,不能把冻结 Schema 解释为端到端链路已完成。
Sense 与 Bell 只使用各自默认数据库;连接器关闭时不注册相应入口/Worker,三端继续独立启动。根级部署、真实 PKI/网络和最终 E2E 属于 #154/#155。
<!-- standard-event-evidence-v1:end -->
<!-- machine-identity-v1:start -->