diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index 5d172b4..2f4f2bb 100644 --- a/docs/02-architecture-and-code-map.md +++ b/docs/02-architecture-and-code-map.md @@ -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 # 架构与代码地图 @@ -320,3 +320,27 @@ Sense Device/Profile/Area 内部事实 协议不得包含摄像头凭据、RTSP URL、query token、内部绝对路径、数据库模型、用户/JWT/Cookie 或 Bell Alert 语义。当前只冻结契约，没有新增网络端点、机器身份或跨端 connector。 + + +## 标准事件与证据 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 解释为端到端链路已完成。 + diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index f9853d6..fecae9b 100644 --- a/docs/03-business-rules-and-glossary.md +++ b/docs/03-business-rules-and-glossary.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Business-Rules-and-Glossary wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Business-Rules-and-Glossary.- -wiki_revision: feca453cd0873c3ad4cef243acfada08ef3f1e33 -synchronized_at: 2026-08-31T01:38:28Z +wiki_revision: bc4a1a7be268028fa85717b71f48f7dd75cc7e52 +synchronized_at: 2026-08-31T01:59:04Z # 业务规则与术语 @@ -247,3 +247,18 @@ synchronized_at: 2026-08-31T01:38:28Z - **状态边界**：运行/健康错误只形成 Sense 运维投影，不是业务 Event 或 Bell Alert；不得包含用户会话、凭据、内部路径或客户视频。 - **版本兼容**：v1 只接受已冻结语义；破坏性字段或语义变化发布新主版本。未知主版本停止摄取并保留上一有效事实。 + + +## 标准事件、证据和幂等规则 + +- **标准 Event**：匿名、不可变的跨产品安全事实，不是 Bell Alert，也不携带处置或通知状态。 +- **原始生产者**：`producer_id` 始终标识最初产生事件的 Brain 或 Sense 实例；relay 使用独立传输身份，但不得替换业务生产者。 +- **永久幂等键**：精确 UTF-8 对 `(producer_id, source_event_id)`。重试沿用同一键，不生成新事件。 +- **规范摘要**：完整 Event 使用 RFC 8785 JCS 规范化后计算 SHA-256。同键同摘要为重复成功；同键异摘要为终止性冲突，并追加脱敏审计。 +- **时间格式**：Event v1 使用 UTC RFC 3339、三位毫秒和 `Z`；可选字段缺失时省略，不发送 null。 +- **证据引用**：`evidence_id` 与 `owner_id` 是不透明逻辑引用，不是 URL、文件路径或访问凭据。 +- **证据状态**：`pending → processing → success|failed`。success 要求内容类型和摘要/大小；failed 要求稳定错误码和是否可重试。 +- **降级原则**：证据失败、未知或过期不删除 Event，不自动关闭 Alert，也不伪装成完整成功。 +- **Bell 所有权**：Bell 独占内部 Event/Receipt、规则、Alert、ack、close、通知与用户审计；上游不得写入这些状态。 +- **兼容与回退**：未知主版本终止接收但保留已有事实；破坏性变化发布新主版本。回退停用新生产者版本，不删除 Outbox、Receipt、Event 或审计。 + diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 1521d59..3b6e7a0 100644 --- a/docs/04-local-development-and-verification.md +++ b/docs/04-local-development-and-verification.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Local-Development-and-Verification wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Local-Development-and-Verification.- -wiki_revision: 43eb0f69fbb4d573a5cd1c61b97dbc9fc9d2a49b -synchronized_at: 2026-08-31T01:38:33Z +wiki_revision: d11757b202117e028878802e1e8a9ba9df1a8e89 +synchronized_at: 2026-08-31T01:59:13Z # 本地开发与验证 @@ -654,3 +654,28 @@ git diff --check 这些命令只验证冻结契约，不验证 #152 产品 adapter、真实网络传输、机器身份、现场断网恢复或端到端链路。 + + +## 标准事件与证据 v1 契约验证 + +两组测试均只使用 Python 标准库： + +```powershell +python contracts/tests/events-v1/test_contract.py +python contracts/tests/evidence-v1/test_contract.py +``` + +事件测试覆盖匿名危险区域/方向越线样例、Brain producer→Sense relay→Bell consumer mapper fixture、RFC 8785/SHA-256 幂等向量、重复/冲突、未知版本、敏感字段拒绝和 OpenAPI 引用。 + +证据测试覆盖 `pending/processing/success/failed` 状态约束、success 完整性、失败降级、旧 `available` 状态拒绝、敏感访问材料拒绝和证据 API 响应引用。 + +仓库级复核： + +```powershell +python -m unittest discover -s tests -v +python dev_scripts/harness.py check --strict +git diff --check +``` + +这些测试只验证冻结契约，不验证 #153 产品 mapper/relay/ingress、#151 机器身份、实际证据存储/授权、网络断线补投或跨项目 E2E。 + diff --git a/docs/09-product-requirements.md b/docs/09-product-requirements.md index 587a526..309aea8 100644 --- a/docs/09-product-requirements.md +++ b/docs/09-product-requirements.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Product-Requirements wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Product-Requirements.- -wiki_revision: 28dce0d89804013411f8111ba421c93e9a1dfa2c -synchronized_at: 2026-08-31T01:39:04Z +wiki_revision: c9970b0ee8b677b6be13f31af67b3206a3faf956 +synchronized_at: 2026-08-31T02:00:00Z # 产品需求 @@ -282,3 +282,13 @@ BRN-002 的首个解码阶段已通过工单 #13 验收。Brain 通过可替换 这两项只冻结协议和测试，不表示 #152 connector 已实现。Sense 与 Brain 仍可独立运行；Brain 不读取 Sense 数据库，Sense 不读取 Brain 内部状态。既有 `brain.internal.*`、Sense GORM 模型和运维投影继续是项目内部实现，不得直接作为共享协议。 + + +## 标准事件与证据引用冻结契约 + +工单 #150 已于 2026-08-31 通过用户验收并合入 `dev`。Sense/Brain→Bell 标准匿名安全事件的唯一共享事实源为 `contracts/events/v1/`，版本标识 `yovision.event/v1`；证据逻辑引用的唯一共享事实源为 `contracts/evidence/v1/`，版本标识 `yovision.evidence-reference/v1`。 + +事件以原始 `(producer_id, source_event_id)` 永久幂等，Sense relay 不改变原始身份或业务载荷。事件只携带逻辑站点/设备/Profile、事件类型、发生时间、规则/模型版本、匿名观测、区域和证据逻辑引用，不携带用户会话、摄像头凭据、内部路径、人脸特征或 Alert/ack/close 状态。 + +证据状态为 `pending/processing/success/failed`；`success` 必须包含内容类型和 SHA-256 完整性元数据，失败或过期只降级证据，不改写不可变 Event 或 Bell Alert 生命周期。此工单只冻结契约和测试，#153 可靠 connector、机器身份、证据存储与实际授权取证尚未实现。 +