diff --git a/docs/02-architecture-and-code-map.md b/docs/02-architecture-and-code-map.md index e4428c2..5d172b4 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: 14b961599d6954357142713a5667fb37d38e86b7 -synchronized_at: 2026-08-29T12:37:31Z +wiki_revision: 3327861dbd77ae63fd10246533b87e0b99a69220 +synchronized_at: 2026-08-31T01:38:23Z # 架构与代码地图 @@ -296,3 +296,27 @@ Brain 解码层位于 `Brain/src/yovision_brain/decode/`，只依赖 #11 的内 内部候选包含逻辑输入引用、规则/模型版本、发生时间、匿名框和解释原因，不包含摄像头凭据、客户隐私、人脸、生物特征、机器绝对路径或证据引用。该格式不是 Brain→Bell 共享契约；Bell API、Outbox、机器身份、证据和跨项目投递必须由协调工单另行实现。 + + +## Sense↔Brain v1 契约边界 + +- Sense→Brain 配置：`contracts/source-config/v1/source-config.schema.json`；版本 `yovision.source-config/v1`。 +- Brain→Sense 状态：`contracts/runtime-status/v1/runtime-status.schema.json`；版本 `yovision.runtime-status/v1`。 +- 共同测试：`contracts/tests/source-config-v1/`、`contracts/tests/runtime-status-v1/`。 +- 生产者/消费者 mapper 责任分别记录在 `mapper-fields.md` 与 `mapping.md`；产品 adapter 后续由 #152 实现。 + +数据流固定为： + +```text +Sense Device/Profile/Area 内部事实 + → source-config/v1 mapper + → Brain adapter（后续 #152） + → Brain 内部配置与运行 + → runtime-status/v1 mapper + → Sense 只读运维投影（后续 #152） +``` + +共享契约统一使用 snake_case 与 `schema_version: yovision./v1`。源配置使用 `config_id + integer revision`；运行状态以 `configurations[]` 按 `config_id` 回报实际应用 revision。未知主版本、重复配置 ID、倒序状态、摘要失败或敏感字段必须拒绝，且不得覆盖最后已知有效配置/投影。 + +协议不得包含摄像头凭据、RTSP URL、query token、内部绝对路径、数据库模型、用户/JWT/Cookie 或 Bell Alert 语义。当前只冻结契约，没有新增网络端点、机器身份或跨端 connector。 + diff --git a/docs/03-business-rules-and-glossary.md b/docs/03-business-rules-and-glossary.md index 625b133..f9853d6 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: 27749cbf699093d997284afc277ea53e73a5876f -synchronized_at: 2026-08-29T12:37:41Z +wiki_revision: feca453cd0873c3ad4cef243acfada08ef3f1e33 +synchronized_at: 2026-08-31T01:38:28Z # 业务规则与术语 @@ -233,3 +233,17 @@ synchronized_at: 2026-08-29T12:37:41Z - 确认和恢复都要求 6–256 字符原因、当前版本和允许的状态；旧版本或错误状态返回冲突。所有动作写入独立流转历史和 GoAdmin 操作审计。 - 运维告警永远设置为 Sense 内部运维记录，不创建本地安全事件或 Bell Alert，不进入跨项目 Outbox，也不实现通知升级。 + + +## Sense↔Brain 配置与状态规则 + +- **配置流**：由稳定 `config_id` 和严格递增的正整数 `revision` 标识；revision 不得复用或倒退。 +- **无凭据媒体引用**：`media.ref` 是由后续 connector 解析的不透明逻辑引用，不是 RTSP URL、本机路径或数据库主键。 +- **Profile 绑定**：规则集必须与 Profile ID、宽高一致；Profile 变化必须形成新 revision，并在需要时标记 `recalibration_required`，旧几何不得静默重投影。 +- **规则坐标**：区域与方向线使用 0–1 归一化坐标，规则 ID 在同一规则集内唯一；退化多边形和重合线端点无效。 +- **完整性**：源配置对移除 `integrity` 后的 JCS 表示计算 SHA-256；校验失败保留上一有效 revision。 +- **配置应用状态**：Brain 在 `configurations[]` 中按 `config_id` 报告 `not_configured/applying/applied/rejected` 与实际 `applied_revision`；同一消息重复 ID 整条拒绝。 +- **状态时序**：Brain 实例 sequence 单调递增；Sense 拒绝倒序消息。观测时间超过约定 90 秒时由 Sense 标记陈旧，不用未知值覆盖最后已知投影。 +- **状态边界**：运行/健康错误只形成 Sense 运维投影，不是业务 Event 或 Bell Alert；不得包含用户会话、凭据、内部路径或客户视频。 +- **版本兼容**：v1 只接受已冻结语义；破坏性字段或语义变化发布新主版本。未知主版本停止摄取并保留上一有效事实。 + diff --git a/docs/04-local-development-and-verification.md b/docs/04-local-development-and-verification.md index 0d7e5c9..1521d59 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: e6068ff0e42765d32ff4e0ee0e8e51cf7d79b7da -synchronized_at: 2026-08-29T12:37:58Z +wiki_revision: 43eb0f69fbb4d573a5cd1c61b97dbc9fc9d2a49b +synchronized_at: 2026-08-31T01:38:33Z # 本地开发与验证 @@ -624,3 +624,33 @@ Brain\.venv\Scripts\python.exe -m yovision_brain.app --config Brain\tests\fixtur CLI 将内部事件 JSON Lines 写入 stdout，并把 completed/cancelled、帧数、检测数和事件数摘要写入 stderr。配置文件必须显式提供，当前使用 JSON；无命中正常返回零事件，读取/配置/模块失败返回非零且不回显机器路径。命令不启动 Sense/Bell、不连接摄像头或网络。 + + +## Sense↔Brain v1 契约验证 + +源/规则配置契约： + +```powershell +pwsh -NoProfile -File contracts/tests/source-config-v1/run.ps1 +``` + +脚本在系统临时目录创建隔离虚拟环境，按固定依赖运行 Schema、跨字段语义、JCS/SHA-256、版本/重校准和秘密拒绝测试，结束后清理所属临时目录。 + +运行状态契约不需要第三方包： + +```powershell +python contracts/tests/runtime-status-v1/test_contract.py +``` + +测试覆盖六态运行状态、30 秒未来时间偏差、90 秒陈旧边界、空/多配置流、四种配置应用状态、重复 `config_id`、integer revision mismatch、倒序消息、未知主版本、回退保留和敏感字段拒绝。 + +仓库级复核： + +```powershell +python -m unittest discover -s tests -v +python dev_scripts/harness.py check --strict +git diff --check +``` + +这些命令只验证冻结契约，不验证 #152 产品 adapter、真实网络传输、机器身份、现场断网恢复或端到端链路。 + diff --git a/docs/09-product-requirements.md b/docs/09-product-requirements.md index 54867cd..587a526 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: eac307b5aa55ff770ff034c53a65b70dc01cb00d -synchronized_at: 2026-08-29T12:39:32Z +wiki_revision: 28dce0d89804013411f8111ba421c93e9a1dfa2c +synchronized_at: 2026-08-31T01:39:04Z # 产品需求 @@ -272,3 +272,13 @@ BRN-002 的首个解码阶段已通过工单 #13 验收。Brain 通过可替换 内部候选只含逻辑输入引用、规则/模型版本、发生时间、匿名观测和解释原因，不含摄像头凭据、客户隐私、人脸、生物特征、机器绝对路径或伪造证据。该格式不是正式 Brain→Bell 契约；证据、机器身份、Outbox/可靠投递和跨项目 E2E 仍须协调工单实现。 + + +## Sense↔Brain 首批冻结契约 + +工单 #148、#149 已于 2026-08-31 通过用户验收并合入 `dev`。Sense→Brain 源/规则配置的唯一共享事实源为 `contracts/source-config/v1/`，版本标识为 `yovision.source-config/v1`；Brain→Sense 运行状态的唯一共享事实源为 `contracts/runtime-status/v1/`，版本标识为 `yovision.runtime-status/v1`。 + +源配置按 `config_id + integer revision` 形成不可复用的配置流，携带逻辑站点/设备/Profile、无凭据媒体引用、归一化区域/方向线、规则版本与完整性摘要。运行状态按同一 `config_id` 在 `configurations[]` 中报告实际应用 revision，并包含 Brain 实例、运行/模型版本、健康、输入和稳定错误码。 + +这两项只冻结协议和测试，不表示 #152 connector 已实现。Sense 与 Brain 仍可独立运行；Brain 不读取 Sense 数据库，Sense 不读取 Brain 内部状态。既有 `brain.internal.*`、Sense GORM 模型和运维投影继续是项目内部实现，不得直接作为共享协议。 + diff --git a/docs/delivery/deployment-and-operations.md b/docs/delivery/deployment-and-operations.md index 23bcbd1..7c30106 100644 --- a/docs/delivery/deployment-and-operations.md +++ b/docs/delivery/deployment-and-operations.md @@ -2,8 +2,8 @@ generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件) wiki_page: Deployment-and-Operations wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Deployment-and-Operations.- -wiki_revision: b21bbc64f323f465b78b557537c38e334de31f45 -synchronized_at: 2026-08-29T12:41:01Z +wiki_revision: 0a772b0511044d98430ebd93304faa3dee57183d +synchronized_at: 2026-08-31T01:39:35Z # YoVision 部署与运维 @@ -134,3 +134,11 @@ Sense\start_sense.bat 运维告警排错不得粘贴设备地址、Stream URI、摄像头凭据、JWT、Cookie 或数据库连接。需要回退时可停止使用刷新/处置入口，但不得删除 `sense_ops_alerts` 或 `sense_ops_alert_transitions` 历史；规则语义变化必须另建工单。 + + +## Sense↔Brain 契约部署边界 + +`yovision.source-config/v1` 与 `yovision.runtime-status/v1` 已冻结，但当前没有因此新增监听端口、服务进程、机器凭据或根级编排。#148/#149 只交付 `contracts/**` Schema、样例、兼容说明和契约测试；实际 Sense↔Brain 传输、认证、超时、退避、重启恢复及配置/状态 adapter 由后续 #151、#152 实现和验收。 + +因此现阶段部署仍按 Sense、Brain 各自独立入口进行，不得手工共享数据库、用户 JWT/Cookie、摄像头凭据、文件目录或临时 JSON 字段来提前打通。需要停用或回退时保持两端独立运行，并保留上一已确认的配置与最后已知状态；未知协议主版本必须停止摄取而不是覆盖投影。 +