Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
 QiuSW
|
a22d3ce0f1 | ||
|
QiuSW
|
54c58551ae | ||
|
QiuSW
|
e4fed702c4 | ||
 ila
|
49aa79f3b9 | ||
|
QiuSW
|
64e20e6aed | ||
|
ila
|
19c0868c5d |
@@ -0,0 +1,47 @@
|
||||
# Brain → Sense 运行与健康状态契约 v1
|
||||
|
||||
本目录是 Brain 运行状态到 Sense 运维投影的版本化事实源。Brain 只发布脱敏状态事实；Sense 不读取 Brain 的缓存、数据库或内部运行对象，也不能借此契约执行远程命令。
|
||||
|
||||
## 消息与时间语义
|
||||
|
||||
- `schema_version` 固定为 `yovision.runtime-status/v1`。生产者必须先通过 `runtime-status.schema.json` 再发布。
|
||||
- `status_id` 是消息幂等键；`sequence` 在单个 `brain_instance_ref` 内单调递增。重复消息可忽略；小于当前已保存 sequence 的消息不得覆盖投影。
|
||||
- `observed_at` 是 Brain 完成该次观测的 UTC RFC 3339 时间，不是 Sense 的接收时间。允许最大 30 秒未来时钟偏差；超过时拒绝该消息，并保留最后已知投影。
|
||||
- Brain 的推荐发布周期是 30 秒。Sense 以 `evaluation_time - observed_at > 90 秒` 推导 `stale`；恰好 90 秒仍为 fresh。`stale` 和 `offline` 都是 Sense 的传输/时间投影，不是 Brain 写入的运行状态。
|
||||
- 未收到任何有效状态时显示 `not_received`；传输断开但最后状态未过期时显示 `offline_fresh`；传输断开或无新消息且超过 90 秒时显示 `offline_stale` / `stale`，同时保留最后已知状态及其观测时间。
|
||||
|
||||
## 状态机
|
||||
|
||||
Brain 报告的 `runtime.state` 和每个输入的 `state` 使用同一枚举：
|
||||
|
||||
| 状态 | 含义 | 允许的下一状态 |
|
||||
|---|---|---|
|
||||
| `unconfigured` | 尚无可运行配置 | `starting`, `stopped` |
|
||||
| `starting` | 已接受启动，资源准备中 | `running`, `degraded`, `failed`, `stopped` |
|
||||
| `running` | 正常提供推理 | `degraded`, `failed`, `stopped` |
|
||||
| `degraded` | 仍提供有限服务 | `running`, `failed`, `stopped` |
|
||||
| `failed` | 无法继续提供服务 | `starting`, `stopped` |
|
||||
| `stopped` | 已有序停止 | `starting`, `unconfigured` |
|
||||
|
||||
首次有效消息可为任一状态；Sense 只校验同实例连续消息的迁移。`stale`、`offline_*` 不参与 Brain 状态迁移。恢复连接后，只有 schema、时间、sequence 和状态迁移均有效的新消息才能更新投影。
|
||||
|
||||
## 配置流与 revision
|
||||
|
||||
`configurations` 按 #148 的配置流报告，可以为空，也可以包含多个配置。每项 `config_id` 必须唯一，并与 `yovision.source-config/v1` 的 `config_id` 一致；重复 ID 使整条状态无效，不能覆盖最后已知投影。`applied_revision` 是 Brain 对该配置流已实际应用的 integer revision。Sense 必须逐个 `config_id` 与自己已投递的期望 revision 比较：相等为 synchronized，不相等为 mismatch；Sense 的期望 revision 不进入本消息，避免产生第二事实源。
|
||||
|
||||
- `not_configured`：尚未应用该配置，revision 必须为 null。
|
||||
- `applying`：正在应用；revision 为 null 或仍在运行的上一个 revision。
|
||||
- `applied`：应用成功，revision 必须是大于等于 1 的整数。
|
||||
- `rejected`：本次应用被拒绝；revision 为 null 或最后成功 revision，且必须带稳定错误码。
|
||||
|
||||
## 兼容与回退
|
||||
|
||||
- v1 字段语义冻结，未知字段被拒绝。新增可选字段或错误码前必须更新本契约及双方测试；改变字段语义或删除字段发布新主版本。
|
||||
- 消费者必须按 `schema_version` 先分派到对应版本验证器。未知主版本停止摄取并记录 `UNSUPPORTED_SCHEMA_VERSION`，不得清空或覆盖最后已知投影。
|
||||
- 回退时 Sense 停止摄取新版本，继续使用上一冻结版本的 adapter 和最后已知投影。回退不触发 Brain 重启或运行态修改。
|
||||
|
||||
## 安全边界
|
||||
|
||||
只允许 Schema 列出的字段。逻辑引用不允许 `/` 或 `\\`，因此不能携带绝对路径。消息不得包含凭据/token、堆栈、内部路径、用户会话、客户视频/图像、人脸信息或业务 Alert。结构化错误只传稳定错误码，不传自由文本错误详情。
|
||||
|
||||
错误码、映射责任和可复制验证分别见 `error-codes.md`、`mapping.md` 与 `../../tests/runtime-status-v1/README.md`。
|
||||
@@ -0,0 +1,16 @@
|
||||
# v1 稳定错误码
|
||||
|
||||
生产者可以发布以下稳定错误码。消费者遇到符合格式但尚未认识的 v1 错误码时显示“未识别的远端错误”，保留原始代码用于排障，不把它转换成业务 Alert。
|
||||
|
||||
| 错误码 | 责任域 | 含义 |
|
||||
|---|---|---|
|
||||
| `CONFIG_INVALID` | 配置 | 配置结构或值无效 |
|
||||
| `CONFIG_REVISION_UNAVAILABLE` | 配置 | 指定 revision 无法取得 |
|
||||
| `INPUT_UNREACHABLE` | 输入 | 逻辑输入暂时不可达 |
|
||||
| `INPUT_DECODE_FAILED` | 输入 | 输入解码失败 |
|
||||
| `MODEL_LOAD_FAILED` | 模型 | 模型载入失败 |
|
||||
| `INFERENCE_FAILED` | 推理 | 推理管线失败 |
|
||||
| `RESOURCE_PRESSURE` | 运行 | 资源压力导致降级 |
|
||||
| `INTERNAL_COMPONENT_FAILED` | 运行 | 内部组件失败；不随消息暴露组件路径或堆栈 |
|
||||
|
||||
`UNSUPPORTED_SCHEMA_VERSION`、`FUTURE_OBSERVATION`、`OUT_OF_ORDER_STATUS` 与 `INVALID_STATUS_TRANSITION` 是 Sense adapter 的本地摄取错误，不由 Brain 发布。
|
||||
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d205",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 1,
|
||||
"observed_at": "2026-08-31T00:00:00Z",
|
||||
"runtime": { "state": "running", "version": "1.0.0", "started_at": null },
|
||||
"model": { "model_ref": "people-detection", "version": "1.0.0" },
|
||||
"configurations": [
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 1, "error_code": null }
|
||||
],
|
||||
"health": { "overall": "healthy", "error_codes": [], "metrics": { "load_percent": 1, "queue_depth": 0, "latency_ms": 1 } },
|
||||
"inputs": [],
|
||||
"alert": { "kind": "intrusion" }
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d202",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 1,
|
||||
"observed_at": "2026-08-31T00:00:00Z",
|
||||
"runtime": { "state": "running", "version": "1.0.0", "started_at": null },
|
||||
"model": { "model_ref": "people-detection", "version": "1.0.0" },
|
||||
"configurations": [
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 1, "error_code": null }
|
||||
],
|
||||
"health": { "overall": "healthy", "error_codes": [], "metrics": { "load_percent": 1, "queue_depth": 0, "latency_ms": 1 } },
|
||||
"inputs": [],
|
||||
"access_token": "forbidden-example"
|
||||
}
|
||||
@@ -0,0 +1,19 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d206",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 47,
|
||||
"observed_at": "2026-08-31T00:05:00Z",
|
||||
"runtime": { "state": "degraded", "version": "1.0.0", "started_at": "2026-08-30T23:55:00Z" },
|
||||
"model": { "model_ref": "people-detection", "version": "2026.08.1" },
|
||||
"configurations": [
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 21, "error_code": null },
|
||||
{ "config_id": "gate-primary", "apply_state": "rejected", "applied_revision": 20, "error_code": "CONFIG_INVALID" }
|
||||
],
|
||||
"health": {
|
||||
"overall": "degraded",
|
||||
"error_codes": ["CONFIG_INVALID"],
|
||||
"metrics": { "load_percent": 42, "queue_depth": 1, "latency_ms": 31 }
|
||||
},
|
||||
"inputs": []
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d203",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 1,
|
||||
"observed_at": "2026-08-31T00:00:00Z",
|
||||
"runtime": { "state": "running", "version": "1.0.0", "started_at": null },
|
||||
"model": { "model_ref": "C:\\models\\private.pt", "version": "1.0.0" },
|
||||
"configurations": [
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 1, "error_code": null }
|
||||
],
|
||||
"health": { "overall": "healthy", "error_codes": [], "metrics": { "load_percent": 1, "queue_depth": 0, "latency_ms": 1 } },
|
||||
"inputs": []
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v2",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d201",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 1,
|
||||
"observed_at": "2026-08-31T00:00:00Z",
|
||||
"runtime": { "state": "running", "version": "1.0.0", "started_at": null },
|
||||
"model": { "model_ref": "people-detection", "version": "1.0.0" },
|
||||
"configurations": [
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 1, "error_code": null }
|
||||
],
|
||||
"health": { "overall": "healthy", "error_codes": [], "metrics": { "load_percent": 1, "queue_depth": 0, "latency_ms": 1 } },
|
||||
"inputs": []
|
||||
}
|
||||
@@ -0,0 +1,15 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d204",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 1,
|
||||
"observed_at": "2026-08-31T00:00:00Z",
|
||||
"runtime": { "state": "running", "version": "1.0.0", "started_at": null },
|
||||
"model": { "model_ref": "people-detection", "version": "1.0.0" },
|
||||
"configurations": [
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 1, "error_code": null }
|
||||
],
|
||||
"health": { "overall": "healthy", "error_codes": [], "metrics": { "load_percent": 1, "queue_depth": 0, "latency_ms": 1 } },
|
||||
"inputs": [],
|
||||
"user_session": { "user": "forbidden" }
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d103",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 43,
|
||||
"observed_at": "2026-08-31T00:01:00Z",
|
||||
"runtime": { "state": "running", "version": "1.0.0", "started_at": "2026-08-30T23:55:00Z" },
|
||||
"model": { "model_ref": "people-detection", "version": "2026.08.1" },
|
||||
"configurations": [
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 20, "error_code": null }
|
||||
],
|
||||
"health": {
|
||||
"overall": "healthy",
|
||||
"error_codes": [],
|
||||
"metrics": { "load_percent": 40.0, "queue_depth": 0, "latency_ms": 22.0 }
|
||||
},
|
||||
"inputs": []
|
||||
}
|
||||
@@ -0,0 +1,21 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d107",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 46,
|
||||
"observed_at": "2026-08-31T00:04:30Z",
|
||||
"runtime": { "state": "degraded", "version": "1.0.0", "started_at": "2026-08-30T23:55:00Z" },
|
||||
"model": { "model_ref": "people-detection", "version": "2026.08.1" },
|
||||
"configurations": [
|
||||
{ "config_id": "new-stream", "apply_state": "not_configured", "applied_revision": null, "error_code": null },
|
||||
{ "config_id": "yard-secondary", "apply_state": "applying", "applied_revision": 8, "error_code": null },
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 21, "error_code": null },
|
||||
{ "config_id": "warehouse", "apply_state": "rejected", "applied_revision": 3, "error_code": "CONFIG_INVALID" }
|
||||
],
|
||||
"health": {
|
||||
"overall": "degraded",
|
||||
"error_codes": ["CONFIG_INVALID"],
|
||||
"metrics": { "load_percent": 42, "queue_depth": 1, "latency_ms": 31 }
|
||||
},
|
||||
"inputs": []
|
||||
}
|
||||
@@ -0,0 +1,26 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d102",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 42,
|
||||
"observed_at": "2026-08-31T00:00:30Z",
|
||||
"runtime": { "state": "degraded", "version": "1.0.0", "started_at": "2026-08-30T23:55:00Z" },
|
||||
"model": { "model_ref": "people-detection", "version": "2026.08.1" },
|
||||
"configurations": [
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 21, "error_code": null },
|
||||
{ "config_id": "yard-secondary", "apply_state": "applying", "applied_revision": 8, "error_code": null }
|
||||
],
|
||||
"health": {
|
||||
"overall": "degraded",
|
||||
"error_codes": ["RESOURCE_PRESSURE"],
|
||||
"metrics": { "load_percent": 91.5, "queue_depth": 7, "latency_ms": 115.0 }
|
||||
},
|
||||
"inputs": [
|
||||
{
|
||||
"input_ref": "camera-gate-01",
|
||||
"state": "degraded",
|
||||
"error_codes": ["INPUT_DECODE_FAILED"],
|
||||
"metrics": { "load_percent": 5.2, "queue_depth": 3, "latency_ms": 92.0 }
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,16 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d106",
|
||||
"brain_instance_ref": "brain-east-02",
|
||||
"sequence": 1,
|
||||
"observed_at": "2026-08-31T00:00:00Z",
|
||||
"runtime": { "state": "unconfigured", "version": "1.0.0", "started_at": null },
|
||||
"model": { "model_ref": "people-detection", "version": "2026.08.1" },
|
||||
"configurations": [],
|
||||
"health": {
|
||||
"overall": "healthy",
|
||||
"error_codes": [],
|
||||
"metrics": { "load_percent": 0, "queue_depth": 0, "latency_ms": 0 }
|
||||
},
|
||||
"inputs": []
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d104",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 44,
|
||||
"observed_at": "2026-08-31T00:01:30Z",
|
||||
"runtime": { "state": "degraded", "version": "1.0.0", "started_at": "2026-08-30T23:55:00Z" },
|
||||
"model": { "model_ref": "people-detection", "version": "2026.08.1" },
|
||||
"configurations": [
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 21, "error_code": null }
|
||||
],
|
||||
"health": {
|
||||
"overall": "degraded",
|
||||
"error_codes": ["INPUT_UNREACHABLE"],
|
||||
"metrics": { "load_percent": 30.0, "queue_depth": 1, "latency_ms": 30.0 }
|
||||
},
|
||||
"inputs": []
|
||||
}
|
||||
@@ -0,0 +1,18 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d105",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 45,
|
||||
"observed_at": "2026-08-31T00:04:00Z",
|
||||
"runtime": { "state": "running", "version": "1.0.0", "started_at": "2026-08-30T23:55:00Z" },
|
||||
"model": { "model_ref": "people-detection", "version": "2026.08.1" },
|
||||
"configurations": [
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 21, "error_code": null }
|
||||
],
|
||||
"health": {
|
||||
"overall": "healthy",
|
||||
"error_codes": [],
|
||||
"metrics": { "load_percent": 36.0, "queue_depth": 0, "latency_ms": 20.0 }
|
||||
},
|
||||
"inputs": []
|
||||
}
|
||||
@@ -0,0 +1,25 @@
|
||||
{
|
||||
"schema_version": "yovision.runtime-status/v1",
|
||||
"status_id": "018f4d6a-8d1b-4a25-8b37-9085f9c0d101",
|
||||
"brain_instance_ref": "brain-east-01",
|
||||
"sequence": 41,
|
||||
"observed_at": "2026-08-31T00:00:00Z",
|
||||
"runtime": { "state": "running", "version": "1.0.0", "started_at": "2026-08-30T23:55:00Z" },
|
||||
"model": { "model_ref": "people-detection", "version": "2026.08.1" },
|
||||
"configurations": [
|
||||
{ "config_id": "gate-primary", "apply_state": "applied", "applied_revision": 21, "error_code": null }
|
||||
],
|
||||
"health": {
|
||||
"overall": "healthy",
|
||||
"error_codes": [],
|
||||
"metrics": { "load_percent": 38.5, "queue_depth": 0, "latency_ms": 21.4 }
|
||||
},
|
||||
"inputs": [
|
||||
{
|
||||
"input_ref": "camera-gate-01",
|
||||
"state": "running",
|
||||
"error_codes": [],
|
||||
"metrics": { "load_percent": 5.2, "queue_depth": 0, "latency_ms": 18.1 }
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,20 @@
|
||||
# Brain → Sense mapper 字段责任
|
||||
|
||||
| 契约字段 | Brain 生产者责任 | Sense 消费者投影责任 |
|
||||
|---|---|---|
|
||||
| `schema_version` | 固定发布 `yovision.runtime-status/v1` | 先按主版本分派；未知版本不覆盖最后投影 |
|
||||
| `status_id` | 每次观测生成唯一幂等键 | 去重，不把重复消息当成新观测 |
|
||||
| `brain_instance_ref` | 发布部署时分配的逻辑引用 | 映射到内部 edge node；不把它当数据库主键 |
|
||||
| `sequence` | 同实例单调递增 | 拒绝倒序消息，保留最后已知投影 |
|
||||
| `observed_at` | 发布观测完成时间 | 校验未来偏差；用它推导 fresh/stale，不用接收时间覆盖 |
|
||||
| `runtime.*` | 报告真实运行状态和脱敏版本 | 校验迁移并形成只读运维状态 |
|
||||
| `model.*` | 报告逻辑模型引用及版本，不报告文件路径 | 显示版本差异，不推导模型下载或重启命令 |
|
||||
| `configurations[]` | 每个 `config_id` 报告真实应用结果和 integer revision；同一消息内 ID 唯一 | 按 `config_id` 与 Sense 内部期望 revision 比较；拒绝重复 ID，不回写 Brain 状态 |
|
||||
| `health.*` | 聚合无敏感健康与有界指标 | 展示健康、指标和稳定错误码，不生成业务 Alert |
|
||||
| `inputs[]` | 按逻辑输入发布安全摘要 | 按 `input_ref` 映射运维投影，不读取视频或检测内容 |
|
||||
|
||||
## 契约测试责任
|
||||
|
||||
- Brain：对所有发布消息执行 Schema 校验；覆盖各运行状态、配置应用结果、降级/失败以及敏感字段拒绝。
|
||||
- Sense：使用同一有效/无效样例；覆盖版本分派、幂等与倒序、30 秒未来偏差、90 秒陈旧边界、状态迁移、offline/recovery、revision mismatch 及回退不覆盖最后投影。
|
||||
- 协调契约：`contracts/tests/runtime-status-v1/test_contract.py` 是双方最小共同测试。产品 adapter 仍需在各自工单中增加本地模型映射测试。
|
||||
@@ -0,0 +1,172 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://yovision.local/contracts/runtime-status/v1/runtime-status.schema.json",
|
||||
"title": "YoVision Brain runtime status v1",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"schema_version",
|
||||
"status_id",
|
||||
"brain_instance_ref",
|
||||
"sequence",
|
||||
"observed_at",
|
||||
"runtime",
|
||||
"model",
|
||||
"configurations",
|
||||
"health",
|
||||
"inputs"
|
||||
],
|
||||
"properties": {
|
||||
"schema_version": { "const": "yovision.runtime-status/v1" },
|
||||
"status_id": {
|
||||
"type": "string",
|
||||
"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
|
||||
},
|
||||
"brain_instance_ref": { "$ref": "#/$defs/logicalRef" },
|
||||
"sequence": { "type": "integer", "minimum": 0 },
|
||||
"observed_at": { "type": "string", "format": "date-time" },
|
||||
"runtime": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["state", "version"],
|
||||
"properties": {
|
||||
"state": { "$ref": "#/$defs/runtimeState" },
|
||||
"version": { "$ref": "#/$defs/version" },
|
||||
"started_at": { "type": ["string", "null"], "format": "date-time" }
|
||||
}
|
||||
},
|
||||
"model": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["model_ref", "version"],
|
||||
"properties": {
|
||||
"model_ref": { "$ref": "#/$defs/logicalRef" },
|
||||
"version": { "$ref": "#/$defs/version" }
|
||||
}
|
||||
},
|
||||
"configurations": {
|
||||
"type": "array",
|
||||
"maxItems": 4096,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["config_id", "apply_state", "applied_revision", "error_code"],
|
||||
"properties": {
|
||||
"config_id": { "$ref": "#/$defs/configId" },
|
||||
"apply_state": {
|
||||
"type": "string",
|
||||
"enum": ["not_configured", "applying", "applied", "rejected"]
|
||||
},
|
||||
"applied_revision": {
|
||||
"type": ["integer", "null"],
|
||||
"minimum": 1
|
||||
},
|
||||
"error_code": { "$ref": "#/$defs/nullableErrorCode" }
|
||||
},
|
||||
"allOf": [
|
||||
{
|
||||
"if": {
|
||||
"required": ["apply_state"],
|
||||
"properties": { "apply_state": { "const": "not_configured" } }
|
||||
},
|
||||
"then": { "properties": { "applied_revision": { "type": "null" } } }
|
||||
},
|
||||
{
|
||||
"if": {
|
||||
"required": ["apply_state"],
|
||||
"properties": { "apply_state": { "const": "applied" } }
|
||||
},
|
||||
"then": { "properties": { "applied_revision": { "type": "integer", "minimum": 1 } } }
|
||||
},
|
||||
{
|
||||
"if": {
|
||||
"required": ["apply_state"],
|
||||
"properties": { "apply_state": { "const": "rejected" } }
|
||||
},
|
||||
"then": { "properties": { "error_code": { "$ref": "#/$defs/errorCode" } } }
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"health": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["overall", "error_codes", "metrics"],
|
||||
"properties": {
|
||||
"overall": {
|
||||
"type": "string",
|
||||
"enum": ["healthy", "degraded", "unhealthy"]
|
||||
},
|
||||
"error_codes": {
|
||||
"type": "array",
|
||||
"uniqueItems": true,
|
||||
"maxItems": 32,
|
||||
"items": { "$ref": "#/$defs/errorCode" }
|
||||
},
|
||||
"metrics": { "$ref": "#/$defs/metrics" }
|
||||
}
|
||||
},
|
||||
"inputs": {
|
||||
"type": "array",
|
||||
"maxItems": 4096,
|
||||
"items": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["input_ref", "state", "error_codes", "metrics"],
|
||||
"properties": {
|
||||
"input_ref": { "$ref": "#/$defs/logicalRef" },
|
||||
"state": { "$ref": "#/$defs/runtimeState" },
|
||||
"error_codes": {
|
||||
"type": "array",
|
||||
"uniqueItems": true,
|
||||
"maxItems": 16,
|
||||
"items": { "$ref": "#/$defs/errorCode" }
|
||||
},
|
||||
"metrics": { "$ref": "#/$defs/metrics" }
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
"$defs": {
|
||||
"configId": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"maxLength": 128,
|
||||
"pattern": "^[A-Za-z0-9][A-Za-z0-9._~-]*$"
|
||||
},
|
||||
"logicalRef": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"maxLength": 128,
|
||||
"pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$"
|
||||
},
|
||||
"version": {
|
||||
"type": "string",
|
||||
"minLength": 1,
|
||||
"maxLength": 64,
|
||||
"pattern": "^[A-Za-z0-9][A-Za-z0-9._+-]{0,63}$"
|
||||
},
|
||||
"runtimeState": {
|
||||
"type": "string",
|
||||
"enum": ["unconfigured", "starting", "running", "degraded", "failed", "stopped"]
|
||||
},
|
||||
"errorCode": {
|
||||
"type": "string",
|
||||
"pattern": "^[A-Z][A-Z0-9_]{2,63}$"
|
||||
},
|
||||
"nullableErrorCode": {
|
||||
"type": ["string", "null"],
|
||||
"pattern": "^[A-Z][A-Z0-9_]{2,63}$"
|
||||
},
|
||||
"metrics": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": ["load_percent", "queue_depth", "latency_ms"],
|
||||
"properties": {
|
||||
"load_percent": { "type": "number", "minimum": 0, "maximum": 100 },
|
||||
"queue_depth": { "type": "integer", "minimum": 0 },
|
||||
"latency_ms": { "type": "number", "minimum": 0 }
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,9 @@
|
||||
# yovision.runtime-status/v1 契约测试
|
||||
|
||||
从仓库根目录运行：
|
||||
|
||||
```powershell
|
||||
python -m unittest discover -s contracts/tests/runtime-status-v1 -p "test_*.py" -v
|
||||
```
|
||||
|
||||
测试只使用 Python 标准库，不安装依赖、不访问网络。它对冻结 Schema 的已用关键字执行验证，并覆盖状态迁移、时间/陈旧边界、offline/recovery、空/多配置流、四种配置应用状态、重复 `config_id`、integer revision mismatch、未知主版本、倒序消息、回退保留和敏感字段拒绝。产品 adapter 还需在各自工单中运行本地模型映射测试。
|
||||
@@ -0,0 +1,318 @@
|
||||
import copy
|
||||
import json
|
||||
import re
|
||||
import unittest
|
||||
from datetime import datetime, timedelta, timezone
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
TEST_DIR = Path(__file__).resolve().parent
|
||||
CONTRACT_DIR = TEST_DIR.parents[1] / "runtime-status" / "v1"
|
||||
SCHEMA = json.loads((CONTRACT_DIR / "runtime-status.schema.json").read_text(encoding="utf-8"))
|
||||
VALID_DIR = CONTRACT_DIR / "examples" / "valid"
|
||||
INVALID_DIR = CONTRACT_DIR / "examples" / "invalid"
|
||||
|
||||
|
||||
def parse_datetime(value):
|
||||
if not isinstance(value, str):
|
||||
raise ValueError("not a string")
|
||||
parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
|
||||
if parsed.tzinfo is None:
|
||||
raise ValueError("timezone is required")
|
||||
return parsed.astimezone(timezone.utc)
|
||||
|
||||
|
||||
def matches_type(value, expected):
|
||||
if expected == "null":
|
||||
return value is None
|
||||
if expected == "object":
|
||||
return isinstance(value, dict)
|
||||
if expected == "array":
|
||||
return isinstance(value, list)
|
||||
if expected == "string":
|
||||
return isinstance(value, str)
|
||||
if expected == "integer":
|
||||
return isinstance(value, int) and not isinstance(value, bool)
|
||||
if expected == "number":
|
||||
return isinstance(value, (int, float)) and not isinstance(value, bool)
|
||||
if expected == "boolean":
|
||||
return isinstance(value, bool)
|
||||
raise AssertionError(f"unsupported schema type in test validator: {expected}")
|
||||
|
||||
|
||||
def resolve_ref(ref):
|
||||
if not ref.startswith("#/"):
|
||||
raise AssertionError(f"external refs are not supported: {ref}")
|
||||
node = SCHEMA
|
||||
for part in ref[2:].split("/"):
|
||||
node = node[part.replace("~1", "/").replace("~0", "~")]
|
||||
return node
|
||||
|
||||
|
||||
def validate(instance, schema=None, path="$", errors=None):
|
||||
schema = SCHEMA if schema is None else schema
|
||||
errors = [] if errors is None else errors
|
||||
if "$ref" in schema:
|
||||
return validate(instance, resolve_ref(schema["$ref"]), path, errors)
|
||||
|
||||
for subschema in schema.get("allOf", []):
|
||||
validate(instance, subschema, path, errors)
|
||||
if "if" in schema:
|
||||
condition_errors = validate(instance, schema["if"], path, [])
|
||||
branch = schema.get("then") if not condition_errors else schema.get("else")
|
||||
if branch is not None:
|
||||
validate(instance, branch, path, errors)
|
||||
|
||||
if "type" in schema:
|
||||
allowed = schema["type"] if isinstance(schema["type"], list) else [schema["type"]]
|
||||
if not any(matches_type(instance, expected) for expected in allowed):
|
||||
errors.append(f"{path}: expected {allowed}")
|
||||
return errors
|
||||
|
||||
if "const" in schema and instance != schema["const"]:
|
||||
errors.append(f"{path}: expected constant {schema['const']!r}")
|
||||
if "enum" in schema and instance not in schema["enum"]:
|
||||
errors.append(f"{path}: value is not in enum")
|
||||
|
||||
if isinstance(instance, dict):
|
||||
required = schema.get("required", [])
|
||||
for name in required:
|
||||
if name not in instance:
|
||||
errors.append(f"{path}: missing required property {name}")
|
||||
properties = schema.get("properties", {})
|
||||
if schema.get("additionalProperties") is False:
|
||||
for name in instance:
|
||||
if name not in properties:
|
||||
errors.append(f"{path}: additional property {name}")
|
||||
for name, value in instance.items():
|
||||
if name in properties:
|
||||
validate(value, properties[name], f"{path}.{name}", errors)
|
||||
|
||||
if isinstance(instance, list):
|
||||
if "maxItems" in schema and len(instance) > schema["maxItems"]:
|
||||
errors.append(f"{path}: too many items")
|
||||
if schema.get("uniqueItems"):
|
||||
encoded = [json.dumps(item, sort_keys=True) for item in instance]
|
||||
if len(encoded) != len(set(encoded)):
|
||||
errors.append(f"{path}: duplicate items")
|
||||
if "items" in schema:
|
||||
for index, value in enumerate(instance):
|
||||
validate(value, schema["items"], f"{path}[{index}]", errors)
|
||||
|
||||
if isinstance(instance, str):
|
||||
if "minLength" in schema and len(instance) < schema["minLength"]:
|
||||
errors.append(f"{path}: string is too short")
|
||||
if "maxLength" in schema and len(instance) > schema["maxLength"]:
|
||||
errors.append(f"{path}: string is too long")
|
||||
if "pattern" in schema and re.fullmatch(schema["pattern"], instance) is None:
|
||||
errors.append(f"{path}: pattern mismatch")
|
||||
if schema.get("format") == "date-time":
|
||||
try:
|
||||
parse_datetime(instance)
|
||||
except (TypeError, ValueError):
|
||||
errors.append(f"{path}: invalid date-time")
|
||||
|
||||
if isinstance(instance, (int, float)) and not isinstance(instance, bool):
|
||||
if "minimum" in schema and instance < schema["minimum"]:
|
||||
errors.append(f"{path}: below minimum")
|
||||
if "maximum" in schema and instance > schema["maximum"]:
|
||||
errors.append(f"{path}: above maximum")
|
||||
return errors
|
||||
|
||||
|
||||
def load(path):
|
||||
return json.loads(path.read_text(encoding="utf-8"))
|
||||
|
||||
|
||||
def validate_contract(instance):
|
||||
errors = validate(instance)
|
||||
configurations = instance.get("configurations") if isinstance(instance, dict) else None
|
||||
if isinstance(configurations, list):
|
||||
config_ids = [item.get("config_id") for item in configurations if isinstance(item, dict)]
|
||||
duplicates = {config_id for config_id in config_ids if config_ids.count(config_id) > 1}
|
||||
if duplicates:
|
||||
errors.append(f"$.configurations: duplicate config_id {sorted(duplicates)!r}")
|
||||
return errors
|
||||
|
||||
|
||||
def freshness(observed_at, evaluation_time):
|
||||
age = evaluation_time - parse_datetime(observed_at)
|
||||
if age < timedelta(seconds=-30):
|
||||
return "future_rejected"
|
||||
return "stale" if age > timedelta(seconds=90) else "fresh"
|
||||
|
||||
|
||||
ALLOWED_TRANSITIONS = {
|
||||
"unconfigured": {"starting", "stopped"},
|
||||
"starting": {"running", "degraded", "failed", "stopped"},
|
||||
"running": {"degraded", "failed", "stopped"},
|
||||
"degraded": {"running", "failed", "stopped"},
|
||||
"failed": {"starting", "stopped"},
|
||||
"stopped": {"starting", "unconfigured"},
|
||||
}
|
||||
|
||||
|
||||
def may_transition(previous, current):
|
||||
return previous == current or current in ALLOWED_TRANSITIONS[previous]
|
||||
|
||||
|
||||
def may_replace(previous, candidate, evaluation_time):
|
||||
if candidate["schema_version"] != "yovision.runtime-status/v1":
|
||||
return False
|
||||
if validate_contract(candidate):
|
||||
return False
|
||||
if freshness(candidate["observed_at"], evaluation_time) == "future_rejected":
|
||||
return False
|
||||
if candidate["brain_instance_ref"] != previous["brain_instance_ref"]:
|
||||
return False
|
||||
if candidate["sequence"] <= previous["sequence"]:
|
||||
return False
|
||||
return may_transition(previous["runtime"]["state"], candidate["runtime"]["state"])
|
||||
|
||||
|
||||
class RuntimeStatusV1ContractTests(unittest.TestCase):
|
||||
@classmethod
|
||||
def setUpClass(cls):
|
||||
cls.running = load(VALID_DIR / "running.json")
|
||||
|
||||
def test_schema_declares_frozen_version_and_closed_objects(self):
|
||||
self.assertEqual(SCHEMA["$schema"], "https://json-schema.org/draft/2020-12/schema")
|
||||
self.assertEqual(SCHEMA["properties"]["schema_version"]["const"], "yovision.runtime-status/v1")
|
||||
self.assertFalse(SCHEMA["additionalProperties"])
|
||||
for name in ("runtime", "model", "health"):
|
||||
self.assertFalse(SCHEMA["properties"][name]["additionalProperties"])
|
||||
self.assertFalse(SCHEMA["properties"]["configurations"]["items"]["additionalProperties"])
|
||||
|
||||
def test_all_valid_examples_satisfy_schema(self):
|
||||
paths = sorted(VALID_DIR.glob("*.json"))
|
||||
self.assertGreaterEqual(len(paths), 7)
|
||||
for path in paths:
|
||||
with self.subTest(path=path.name):
|
||||
self.assertEqual(validate_contract(load(path)), [])
|
||||
|
||||
def test_all_invalid_examples_are_rejected(self):
|
||||
paths = sorted(INVALID_DIR.glob("*.json"))
|
||||
self.assertGreaterEqual(len(paths), 6)
|
||||
for path in paths:
|
||||
with self.subTest(path=path.name):
|
||||
self.assertNotEqual(validate_contract(load(path)), [])
|
||||
|
||||
def test_every_runtime_state_is_schema_valid(self):
|
||||
for state in ALLOWED_TRANSITIONS:
|
||||
message = copy.deepcopy(self.running)
|
||||
message["runtime"]["state"] = state
|
||||
with self.subTest(state=state):
|
||||
self.assertEqual(validate_contract(message), [])
|
||||
|
||||
def test_state_transition_matrix(self):
|
||||
self.assertTrue(may_transition("unconfigured", "starting"))
|
||||
self.assertTrue(may_transition("starting", "running"))
|
||||
self.assertTrue(may_transition("running", "degraded"))
|
||||
self.assertTrue(may_transition("degraded", "running"))
|
||||
self.assertTrue(may_transition("running", "failed"))
|
||||
self.assertTrue(may_transition("failed", "stopped"))
|
||||
self.assertFalse(may_transition("unconfigured", "running"))
|
||||
self.assertFalse(may_transition("stopped", "running"))
|
||||
|
||||
def test_stale_and_future_boundaries(self):
|
||||
observed = parse_datetime(self.running["observed_at"])
|
||||
self.assertEqual(freshness(self.running["observed_at"], observed + timedelta(seconds=90)), "fresh")
|
||||
self.assertEqual(freshness(self.running["observed_at"], observed + timedelta(seconds=91)), "stale")
|
||||
self.assertEqual(freshness(self.running["observed_at"], observed - timedelta(seconds=30)), "fresh")
|
||||
self.assertEqual(freshness(self.running["observed_at"], observed - timedelta(seconds=31)), "future_rejected")
|
||||
|
||||
def test_offline_keeps_last_known_and_recovery_replaces_it(self):
|
||||
last_known = load(VALID_DIR / "offline-last-known.json")
|
||||
evaluation = parse_datetime(last_known["observed_at"]) + timedelta(seconds=180)
|
||||
self.assertEqual(freshness(last_known["observed_at"], evaluation), "stale")
|
||||
self.assertEqual(last_known["runtime"]["state"], "degraded")
|
||||
recovered = load(VALID_DIR / "recovered.json")
|
||||
self.assertTrue(may_replace(last_known, recovered, parse_datetime(recovered["observed_at"])))
|
||||
|
||||
def test_unknown_version_and_out_of_order_do_not_replace_projection(self):
|
||||
unknown = load(INVALID_DIR / "unknown-major.json")
|
||||
evaluation = parse_datetime(self.running["observed_at"])
|
||||
self.assertFalse(may_replace(self.running, unknown, evaluation))
|
||||
older = copy.deepcopy(self.running)
|
||||
older["sequence"] = self.running["sequence"] - 1
|
||||
self.assertFalse(may_replace(self.running, older, evaluation))
|
||||
duplicate = load(INVALID_DIR / "duplicate-config-id.json")
|
||||
self.assertFalse(may_replace(self.running, duplicate, parse_datetime(duplicate["observed_at"])))
|
||||
|
||||
def test_configuration_revision_mismatch_is_consumer_derived(self):
|
||||
message = load(VALID_DIR / "config-mismatch.json")
|
||||
desired_revisions = {"gate-primary": 21}
|
||||
self.assertEqual(validate_contract(message), [])
|
||||
report = message["configurations"][0]
|
||||
self.assertNotEqual(report["applied_revision"], desired_revisions[report["config_id"]])
|
||||
self.assertNotIn("desired_revision", report)
|
||||
|
||||
def test_configuration_apply_state_invariants(self):
|
||||
valid_cases = [
|
||||
("not_configured", None, None),
|
||||
("applying", None, None),
|
||||
("applying", 1, None),
|
||||
("applied", 1, None),
|
||||
("rejected", None, "CONFIG_INVALID"),
|
||||
("rejected", 1, "CONFIG_INVALID"),
|
||||
]
|
||||
for apply_state, revision, error_code in valid_cases:
|
||||
message = copy.deepcopy(self.running)
|
||||
message["configurations"] = [{
|
||||
"config_id": "gate-primary",
|
||||
"apply_state": apply_state,
|
||||
"applied_revision": revision,
|
||||
"error_code": error_code,
|
||||
}]
|
||||
with self.subTest(apply_state=apply_state):
|
||||
self.assertEqual(validate_contract(message), [])
|
||||
|
||||
invalid_cases = [
|
||||
("not_configured", 1, None),
|
||||
("applied", None, None),
|
||||
("rejected", 1, None),
|
||||
]
|
||||
for apply_state, revision, error_code in invalid_cases:
|
||||
message = copy.deepcopy(self.running)
|
||||
message["configurations"] = [{
|
||||
"config_id": "gate-primary",
|
||||
"apply_state": apply_state,
|
||||
"applied_revision": revision,
|
||||
"error_code": error_code,
|
||||
}]
|
||||
with self.subTest(invalid_apply_state=apply_state):
|
||||
self.assertNotEqual(validate_contract(message), [])
|
||||
|
||||
def test_empty_multiple_and_duplicate_configuration_streams(self):
|
||||
empty = load(VALID_DIR / "empty-configurations.json")
|
||||
multiple = load(VALID_DIR / "configuration-states.json")
|
||||
duplicate = load(INVALID_DIR / "duplicate-config-id.json")
|
||||
self.assertEqual(validate_contract(empty), [])
|
||||
self.assertEqual(validate_contract(multiple), [])
|
||||
self.assertEqual(len(multiple["configurations"]), 4)
|
||||
self.assertTrue(any("duplicate config_id" in error for error in validate_contract(duplicate)))
|
||||
|
||||
def test_sensitive_and_business_fields_are_rejected_by_name(self):
|
||||
for forbidden in ("access_token", "password", "credential", "internal_path", "stack", "user_session", "video", "face", "alert"):
|
||||
message = copy.deepcopy(self.running)
|
||||
message[forbidden] = "forbidden"
|
||||
with self.subTest(forbidden=forbidden):
|
||||
self.assertTrue(any("additional property" in error for error in validate_contract(message)))
|
||||
|
||||
def test_logical_references_reject_paths(self):
|
||||
for value in ("C:\\models\\private.pt", "/srv/models/private.pt", "../private.pt"):
|
||||
message = copy.deepcopy(self.running)
|
||||
message["model"]["model_ref"] = value
|
||||
with self.subTest(value=value):
|
||||
self.assertNotEqual(validate_contract(message), [])
|
||||
|
||||
def test_mapper_responsibilities_are_documented(self):
|
||||
mapping = (CONTRACT_DIR / "mapping.md").read_text(encoding="utf-8")
|
||||
for field in ("schema_version", "status_id", "brain_instance_ref", "sequence", "observed_at", "runtime.*", "model.*", "configurations[]", "health.*", "inputs[]"):
|
||||
self.assertIn(f"`{field}`", mapping)
|
||||
self.assertIn("Brain", mapping)
|
||||
self.assertIn("Sense", mapping)
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Project-Profile
|
||||
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Project-Profile.-
|
||||
wiki_revision: 5894b3f4e3152420bd9addd63c1ce80205a6fd80
|
||||
synchronized_at: 2026-08-27T15:22:01Z
|
||||
wiki_revision: 3ec1fe54504a9c5eabb76dc19f0e46eb6c58ba08
|
||||
synchronized_at: 2026-08-29T12:37:08Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 项目档案
|
||||
@@ -19,7 +19,7 @@ synchronized_at: 2026-08-27T15:22:01Z
|
||||
| 首期客户场景 | 民办寄宿学校，默认 16 路高风险点位 |
|
||||
| 首期规则 | 越线、危险区域、聚集等匿名安全规则；不启用人脸 |
|
||||
| 产品形态 | Sense 与 Bell 两个独立销售产品，Brain 为独立推理交付单元 |
|
||||
| 当前阶段 | Sense 独立纵切、Brain Python 骨架、Bell GoAdmin 产品骨架已通过用户验收并合入 `dev`；旧实现归档于 `explore`，`main` 仍为审核基线 |
|
||||
| 当前阶段 | MVP #8 三项目首个独立纵切已于 2026-08-29 通过用户验收并合入 `dev`：Sense 完成摄像头接入到区域配置，Brain 完成合成输入到匿名本地事件，Bell 完成合成事件到 Alert ack/close；旧实现归档于 `explore`，`main` 仍为审核基线 |
|
||||
| 历史来源 | `D:\OPC\yovision_old`，只读追溯 |
|
||||
|
||||
## DevHarness 来源与基线
|
||||
@@ -54,7 +54,7 @@ YoVision 采用 DevHarness 的共同工作流、统一 `harness.py` 命令、Git
|
||||
- 证据：客户侧 MinIO/S3 兼容对象存储；常态录像优先留在客户已有 NVR。
|
||||
- 首期验证平台：NVIDIA x86/Jetson；M1-M3 不承诺 GB/T 28181、信创或原生 App。
|
||||
|
||||
2026-08-14 起，原 Sense、Bell 实现只在 `explore` 和原功能分支中作为迁移参考，不再作为新开发基础。当前 `dev` 中的 Sense、Bell 已分别从下述冻结 go-admin/go-admin-ui 完整提交派生；实施时仍必须核对冻结 go-admin-doc。Brain 已建立独立 Python/PyTorch 包骨架，但尚未包含推理业务能力。
|
||||
2026-08-14 起，原 Sense、Bell 实现只在 `explore` 和原功能分支中作为迁移参考，不再作为新开发基础。当前 `dev` 中的 Sense、Bell 已分别从下述冻结 go-admin/go-admin-ui 完整提交派生；实施时仍必须核对冻结 go-admin-doc。Brain 已在独立 Python/PyTorch 包骨架上完成合成/本地输入、解码、匿名检测与单路跟踪、区域/方向越线判定和项目内匿名事件输出；真实 GPU、生产模型和跨项目契约仍属后续范围。
|
||||
|
||||
## 阅读入口
|
||||
|
||||
@@ -108,20 +108,20 @@ Sense、Bell 共用的可复现技术基线记录在仓库根 `goadmin-baseline.
|
||||
<!-- sense-runtime:start -->
|
||||
## Sense 重建状态
|
||||
|
||||
Sense 已从冻结 go-admin/go-admin-ui 源码独立派生，并完成设备、视频接入、MediaMTX、单路监看、区域配置与 Windows 交付的独立纵切。工单 #71 已从当前源码重新打包并通过隔离 PostgreSQL 17、Digest ONVIF/合成 RTSP、独立 MediaMTX、Chrome 外壳和冷启动回归；当前成果已合入 `dev`，并于 2026-08-27 通过用户验收。现场真机、16 路长稳和跨项目链路不在本轮结论内。
|
||||
Sense 已从冻结 go-admin/go-admin-ui 源码独立派生，并完成设备、视频接入、MediaMTX、单路监看、区域配置与 Windows 交付的独立纵切。工单 #71 已从当前源码重新打包并通过隔离 PostgreSQL 17、Digest ONVIF/合成 RTSP、独立 MediaMTX、Chrome 外壳和冷启动回归；#145 又修复默认验收入口的受控源码复制、UDP 端口探测、临时清理和脱敏诊断。当前成果已合入 `dev`，并随 MVP #8 于 2026-08-29 通过三项目独立纵切验收。现场真机、16 路长稳和跨项目链路不在本轮结论内。
|
||||
<!-- sense-runtime:end -->
|
||||
|
||||
|
||||
<!-- bell-runtime:start -->
|
||||
## Bell 重建状态
|
||||
|
||||
Bell 已从与 Sense 相同的冻结 go-admin/go-admin-ui 基线独立派生到 `Bell/server/` 与 `Bell/ui/`，保留来源和 MIT 许可证证据，以及独立 PostgreSQL、JWT、token key 和首次管理员边界。当前最小启用骨架已通过后端、前端和隔离 PostgreSQL smoke，并于 2026-08-27 通过用户验收、合入 `dev`；事件、规则、Alert 等业务能力继续按独立工单迁移。
|
||||
Bell 已从与 Sense 相同的冻结 go-admin/go-admin-ui 基线独立派生到 `Bell/server/` 与 `Bell/ui/`，保留来源和 MIT 许可证证据，以及独立 PostgreSQL、JWT、token key 和首次管理员边界。#131–#134 已完成 Event/Receipt、合成事件、规则匹配、Alert ack/close、审计时间线、Windows 交付和独立 E2E；生产验证码、最小菜单和 GoAdmin 外壳缺陷也已闭环。当前成果已合入 `dev`，并随 MVP #8 于 2026-08-29 通过三项目独立纵切验收。
|
||||
<!-- bell-runtime:end -->
|
||||
|
||||
<!-- brain-runtime:start -->
|
||||
## Brain 初始化状态
|
||||
|
||||
Brain 已建立 CPython 3.11.15 / PyTorch 2.12.1 的无界面包骨架，提供安装、版本、runtime-info 与 CPU/CUDA smoke 入口。CPU wheel、包测试和 CPU tensor smoke 已通过，并于 2026-08-27 通过用户验收、合入 `dev`；CUDA wheel、真实 GPU、视频、模型、规则、事件与部署尚未验证或实现。
|
||||
Brain 已在 CPython 3.11.15 / PyTorch 2.12.1 无界面包骨架上完成合成与本地视频输入、可替换解码、匿名检测与单路跟踪、危险区域与方向越线判定，以及项目内匿名事件输出。独立验收中 43 项测试通过，CLI 合成输入实际生成 `brain.internal.event-candidate/v1` 匿名事件；当前成果已合入 `dev`，并随 MVP #8 于 2026-08-29 通过用户验收。CUDA wheel、真实 GPU、生产模型、容量和跨项目事件契约仍未验证。
|
||||
<!-- brain-runtime:end -->
|
||||
|
||||
## 分支治理
|
||||
|
||||
@@ -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: 578ddbaae3d7e846037d958085e40609cd398bef
|
||||
synchronized_at: 2026-08-28T08:02:32Z
|
||||
wiki_revision: 14b961599d6954357142713a5667fb37d38e86b7
|
||||
synchronized_at: 2026-08-29T12:37:31Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 架构与代码地图
|
||||
@@ -236,3 +236,63 @@ PostgreSQL 表 `sense_provisioning_batches` 保存幂等键、配额快照和汇
|
||||
- GoAdmin 路由位于 `Sense/server/app/admin/router/sense_media_shard.go`，只开放列表、详情和迁移预检三个 GET 接口。go-admin-ui 页面位于 `Sense/ui/src/views/sense/media-shard/`，复用 BasicLayout、Element Plus 表格、进度、Dialog、Tag、Alert 和权限指令。
|
||||
- 迁移 `2026082814000_media_shard.go` 建表、注册动态菜单并为 implementation_operator、site_admin、viewer 建立只读权限；生产迁移和启动不写入合成分片。
|
||||
<!-- sense-media-shards:end -->
|
||||
|
||||
<!-- sense-outbox:start -->
|
||||
## Sense 内部可靠投递入口
|
||||
|
||||
工单 #78 在 `Sense/server/app/sense/outbox/` 建立内部事务 Outbox。业务写入通过同一 GORM 事务创建领域记录与 outbox；`Sense/server/app/sense/local_event/outbox.go` 是当前首个原子写入入口。GoAdmin 路由位于 `Sense/server/app/admin/router/sense_outbox.go`，迁移与菜单/RBAC 位于 `Sense/server/cmd/migrate/migration/version/2026082815000_outbox.go`，前端页面位于 `Sense/ui/src/views/sense/outbox/index.vue`。
|
||||
|
||||
内部状态为 pending、processing、retry、dead、delivered。relay 使用数据库 claim、lease 和版本号避免并发重复领取；失败按退避进入 retry，超过上限进入 dead，租约过期可恢复。成功投递写入永久幂等收据。当前模块不定义 Brain/Bell 正式 schema、connector 或机器身份，内部 payload 也不通过管理 API 暴露。
|
||||
<!-- sense-outbox:end -->
|
||||
|
||||
<!-- sense-ops-alerts:start -->
|
||||
## Sense 运维告警代码路径
|
||||
|
||||
工单 #79 在 `Sense/server/app/sense/ops_alert/` 建立持久化运维告警：`sense_ops_alerts` 以“告警类型 + 对象类型 + 对象 ID”唯一指纹保存当前生命周期，`sense_ops_alert_transitions` 追加发现、确认、健康恢复、恢复确认、恢复失败和再次发生历史。健康事实只读取既有设备接入、媒体路由、媒体分片和边缘节点投影，不建立第二套设备或媒体状态事实源。
|
||||
|
||||
GoAdmin 路由位于 `Sense/server/app/admin/router/sense_ops_alert.go`，API 为 `GET /api/v1/ops-alerts`、`GET /api/v1/ops-alerts/:id`、`POST /api/v1/ops-alerts/evaluate`、`POST /api/v1/ops-alerts/:id/acknowledge` 和 `POST /api/v1/ops-alerts/:id/recover`。前端入口为 `Sense/ui/src/views/sense/ops-alert/index.vue`，继续复用 GoAdmin BasicLayout、动态菜单、Axios、Element Plus 表格/表单/分页/Dialog/Tag/Alert 和权限指令。
|
||||
|
||||
本模块只写 Sense 运维告警和 GoAdmin 操作审计，不导入或写入本地安全事件、Brain、Bell、Outbox 或共享契约模型。viewer 只读；implementation_operator 与 site_admin 可刷新健康事实、确认和恢复。
|
||||
<!-- sense-ops-alerts:end -->
|
||||
|
||||
<!-- brain-input-v1:start -->
|
||||
## Brain 内部输入与配置边界
|
||||
|
||||
Brain 的首个独立输入边界位于 `Brain/src/yovision_brain/input/`，项目内配置模型位于 `Brain/src/yovision_brain/config/`。配置显式标记为 `brain.internal.input/v1`，只用于 Brain 独立开发与测试，不是 Sense→Brain 共享契约。
|
||||
|
||||
输入端口当前提供确定性 RGB 合成源和显式本地文件源。两者携带逻辑设备、Profile 与分辨率元数据；合成源提供固定种子、帧序列和确定性时间基准，本地文件源提供可替换解码器消费的容器字节、EOF 和协作取消边界。错误只暴露安全文件标签，不把机器绝对路径、凭据或客户数据写入日志/事件。
|
||||
|
||||
正式 RTSP、Sense 源配置、共享区域契约和跨项目投递仍由协调工单建立版本化 `contracts/` 适配器，不得把本内部模型直接发布给 Sense 或 Bell。
|
||||
<!-- brain-input-v1:end -->
|
||||
|
||||
<!-- brain-decode-v1:start -->
|
||||
## Brain 可替换解码边界
|
||||
|
||||
Brain 解码层位于 `Brain/src/yovision_brain/decode/`，只依赖 #11 的内部 `InputPacket` 端口，向后续视觉模块输出顺序、纳秒时间戳、逻辑设备、Profile、分辨率、像素格式和尺寸变化标记明确的 `DecodedFrame`。具体后端通过 `DecoderBackend` 注册，不要求检测、跟踪或规则层依赖某个编解码 SDK。
|
||||
|
||||
当前独立纵切支持确定性 RGB24 合成帧，以及标准库实现的最小 YUV4MPEG2 C444 本地视频流。Y4M 只用于匿名本地/合成验证；生产 RTSP、FFmpeg/PyAV、NVIDIA 硬件解码、重连和多路调度仍是后续范围。损坏输入、不支持格式、Profile 尺寸不匹配和安全大小上限均产生明确错误；正常 EOF 与主动取消不伪装成失败。
|
||||
<!-- brain-decode-v1:end -->
|
||||
|
||||
<!-- brain-vision-v1:start -->
|
||||
## Brain 匿名检测与单路跟踪边界
|
||||
|
||||
`Brain/src/yovision_brain/vision/` 定义可替换 Detector、匿名边界框观测和会话内单路 IoU 跟踪。输出仅包含类别 `anonymous_target`、置信度、边界框、帧时间和当前进程内轨迹 ID；轨迹 ID 不跨进程、不跨摄像头，也不是自然人身份。
|
||||
|
||||
当前基线是版本 `1.0.0` 的 YoVision first-party 亮度连通区域算法，并提供 PyTorch 2.12.1 张量实现；不分发外部模型权重，PyTorch 许可已在 Brain 第三方清单记录。它用于验证匿名检测/跟踪链路，不代表人员检测效果，不承诺召回率或误报率。人脸、生物特征和跨摄像头 ReID 均未启用。
|
||||
<!-- brain-vision-v1:end -->
|
||||
|
||||
<!-- brain-rules-v1:start -->
|
||||
## Brain 区域与方向越线规则边界
|
||||
|
||||
`Brain/src/yovision_brain/rules/` 只消费匿名轨迹。轨迹框底边中心是归一化规则锚点；多边形边界视为区域内，状态区分 outside、entered、inside。有向警戒线按起点→终点的左右侧定义 `left_to_right` / `right_to_left`，deadband 内不触发且保留上一次显著侧。
|
||||
|
||||
每个结果绑定规则配置版本、Profile、分辨率、锚点和可解释原因。结果是 Brain 内部候选，不是标准事件或 Bell Alert；时段、持续时间、冷却、聚集和正式 Sense 配置契约不在本阶段。
|
||||
<!-- brain-rules-v1:end -->
|
||||
|
||||
<!-- brain-local-events-v1:start -->
|
||||
## Brain 独立纵切与内部事件边界
|
||||
|
||||
`Brain/src/yovision_brain/app/` 编排输入、解码、匿名检测/跟踪和规则端口；`Brain/src/yovision_brain/events/` 将触发结果映射为 `brain.internal.event-candidate/v1` 并写入可替换 JSON Lines sink。事件 ID 基于规范化输入事实与版本的 SHA-256，同一输入、配置和实现版本重复运行保持稳定。
|
||||
|
||||
内部候选包含逻辑输入引用、规则/模型版本、发生时间、匿名框和解释原因，不包含摄像头凭据、客户隐私、人脸、生物特征、机器绝对路径或证据引用。该格式不是 Brain→Bell 共享契约；Bell API、Outbox、机器身份、证据和跨项目投递必须由协调工单另行实现。
|
||||
<!-- brain-local-events-v1:end -->
|
||||
|
||||
@@ -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: 999eb1aee3558ff75cfa929acac77841af20b742
|
||||
synchronized_at: 2026-08-28T08:02:42Z
|
||||
wiki_revision: 27749cbf699093d997284afc277ea53e73a5876f
|
||||
synchronized_at: 2026-08-29T12:37:41Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 业务规则与术语
|
||||
@@ -210,3 +210,26 @@ synchronized_at: 2026-08-28T08:02:42Z
|
||||
- 跨分片迁移预检是只读操作，只检查源状态、全部受影响路径和候选目标容量；即使预检通过也不授予执行权限。实际迁移必须另建高风险工单并取得人工确认。
|
||||
- 额外分片只能配置为 external，Control API 必须使用无用户信息、无查询参数、无路径的本机回环 HTTP 地址。Sense 不停止外部实例。
|
||||
<!-- sense-media-shards:end -->
|
||||
|
||||
<!-- sense-outbox:start -->
|
||||
## Sense 内部 Outbox 业务规则
|
||||
|
||||
- 领域记录与 outbox 必须在同一 PostgreSQL 事务中提交；任一写入失败时两者一起回滚。
|
||||
- 幂等键在消息表唯一，成功后还保留永久投递收据；重试和人工恢复沿用原业务记录与幂等键。
|
||||
- worker 只能领取到期的 pending/retry 或租约已过期的 processing 记录；同一记录不能被两个 worker 同时成功领取。
|
||||
- 失败保留脱敏错误与尝试历史，按退避等待；达到最大次数进入 dead。人工重新排队必须填写原因并记录操作者，不删除历史。
|
||||
- implementation_operator、site_admin、viewer 可查看；只有 implementation_operator、site_admin 可重新排队。
|
||||
- 未配置外部 connector 时保留内部记录且不阻断 Sense 核心功能。测试 sink 在 prod/production 模式禁止启用。
|
||||
- 管理 API 不返回内部 payload、外部凭据或机器身份；Brain/Bell 正式协议属于后续协调工单。
|
||||
<!-- sense-outbox:end -->
|
||||
|
||||
<!-- sense-ops-alerts:start -->
|
||||
## Sense 运维告警规则
|
||||
|
||||
- 六类运维告警固定为：设备/边缘节点离线、设备认证失败、设备时间漂移、媒体状态对账失败、媒体分片异常、控制隧道异常。
|
||||
- 每个“告警类型 + 对象类型 + 对象 ID”只有一条记录；同一源版本重复刷新不增加发现次数，也不产生第二条活动告警。恢复后再次异常复用原记录、递增处理周期并保留全部历史。
|
||||
- 状态为 `unacknowledged`（待确认）、`acknowledged`（已确认）、`recovering`（恢复观察）、`recovered`（已恢复）。人工确认只表示已接手，不表示故障恢复。
|
||||
- 健康事实恢复后先进入固定 5 分钟观察窗口；只有 `recovering` 且观察窗口结束后才能人工确认恢复。观察期再次异常返回原处理状态并追加恢复失败历史。
|
||||
- 确认和恢复都要求 6–256 字符原因、当前版本和允许的状态；旧版本或错误状态返回冲突。所有动作写入独立流转历史和 GoAdmin 操作审计。
|
||||
- 运维告警永远设置为 Sense 内部运维记录，不创建本地安全事件或 Bell Alert，不进入跨项目 Outbox，也不实现通知升级。
|
||||
<!-- sense-ops-alerts:end -->
|
||||
|
||||
@@ -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: 05435d53528271a866c525655486689afc198762
|
||||
synchronized_at: 2026-08-28T08:02:52Z
|
||||
wiki_revision: e6068ff0e42765d32ff4e0ee0e8e51cf7d79b7da
|
||||
synchronized_at: 2026-08-29T12:37:58Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 本地开发与验证
|
||||
@@ -515,3 +515,112 @@ go test ./cmd/migrate/migration/version -run TestMediaShardMigrationOnPostgres -
|
||||
|
||||
验证应覆盖任意配置容量、稳定重复分配、容量耗尽、分片故障后归属不变、设备/Profile/路径影响范围、只读迁移预检、只读 RBAC、Control API 不出现在响应，以及 Brain/Bell 均不运行。没有专用 PostgreSQL 连接时必须记录真库迁移测试未执行。
|
||||
<!-- sense-media-shards:end -->
|
||||
|
||||
<!-- sense-outbox:start -->
|
||||
## Sense Outbox 本地验证
|
||||
|
||||
从 `Sense/server` 运行完整后端测试：
|
||||
|
||||
```powershell
|
||||
go test ./...
|
||||
```
|
||||
|
||||
PostgreSQL 多 worker 集成测试必须使用专用隔离数据库，不得指向开发或生产库：
|
||||
|
||||
```powershell
|
||||
$env:SENSE_OUTBOX_TEST_DATABASE_URL = '<隔离 PostgreSQL 连接>'
|
||||
go test ./app/sense/outbox -run TestPostgresConcurrentWorkersDoNotClaimSameMessage -count=1 -v
|
||||
```
|
||||
|
||||
前端从 `Sense/ui` 运行：
|
||||
|
||||
```powershell
|
||||
pnpm lint
|
||||
pnpm test:unit -- --runInBand
|
||||
pnpm build:prod
|
||||
```
|
||||
|
||||
验证至少覆盖：领域记录与 outbox 原子回滚、并发 claim/lease、租约恢复、退避与 dead、人工重新排队及操作人、永久幂等收据、production 禁用测试 sink、只读/恢复权限、API 不泄露 payload，以及 Brain/Bell 均不运行时页面可观察。无专用 PostgreSQL 连接时必须明确记录真库并发测试未执行。
|
||||
<!-- sense-outbox:end -->
|
||||
|
||||
<!-- sense-ops-alerts:start -->
|
||||
## Sense 运维告警验证
|
||||
|
||||
从后端目录运行：
|
||||
|
||||
```powershell
|
||||
cd Sense/server
|
||||
go test ./app/sense/ops_alert ./app/admin/router ./cmd/migrate/migration/version
|
||||
go test ./...
|
||||
```
|
||||
|
||||
从前端目录运行：
|
||||
|
||||
```powershell
|
||||
cd Sense/ui
|
||||
pnpm lint
|
||||
pnpm test:unit -- --runInBand
|
||||
pnpm build:prod
|
||||
```
|
||||
|
||||
故障注入至少覆盖六类来源、相同源版本重复刷新、健康恢复、5 分钟观察门槛、观察期复发、恢复后再次发生、旧版本并发冲突、viewer 只读权限和脱敏操作审计。Brain/Bell 不启动。隔离启动 smoke 必须验证 `2026082816000_ops_alert.go` 迁移、菜单和 API 注册；不得把开发或生产数据库当作破坏性故障注入库。
|
||||
<!-- sense-ops-alerts:end -->
|
||||
|
||||
<!-- brain-input-v1:start -->
|
||||
## Brain 合成与本地输入验证
|
||||
|
||||
从仓库根目录使用 Brain 的隔离 CPython 3.11 环境执行：
|
||||
|
||||
```powershell
|
||||
Brain\.venv\Scripts\python.exe -m pytest Brain/tests/input Brain/tests/config -q
|
||||
Brain\.venv\Scripts\python.exe -m pytest Brain/tests -q
|
||||
```
|
||||
|
||||
定向测试覆盖固定种子与时间基准、Profile/分辨率和规则配置、EOF、取消、文件不存在、非法配置、凭据字段拒绝及安全错误文本。测试只使用运行时生成的小型匿名字节文件，不启动 Sense/Bell，不连接摄像头或网络服务。
|
||||
<!-- brain-input-v1:end -->
|
||||
|
||||
<!-- brain-decode-v1:start -->
|
||||
## Brain 视频解码验证
|
||||
|
||||
```powershell
|
||||
Brain\.venv\Scripts\python.exe -m pytest Brain/tests/decode -q
|
||||
Brain\.venv\Scripts\python.exe -m pytest Brain/tests -q
|
||||
```
|
||||
|
||||
定向测试使用运行时生成的匿名 YUV4MPEG2 字节流，覆盖跨输入分块解码、顺序与时间戳、Profile/分辨率、RGB24 尺寸变化、正常 EOF、主动取消、截断帧、不支持格式/色度和配置尺寸不匹配。该结果不证明生产 RTSP、硬件解码、GPU 或多路性能。
|
||||
<!-- brain-decode-v1:end -->
|
||||
|
||||
<!-- brain-vision-v1:start -->
|
||||
## Brain 匿名检测与跟踪验证
|
||||
|
||||
```powershell
|
||||
Brain\.venv\Scripts\python.exe -m pytest Brain/tests/vision -q
|
||||
Brain\.venv\Scripts\python.exe -m pytest Brain/tests -q
|
||||
Brain\.venv\Scripts\python.exe -m yovision_brain --smoke cpu
|
||||
```
|
||||
|
||||
定向测试覆盖空帧、目标出现/移动、短暂遮挡、消失、轨迹结束、会话 ID 边界及 PyTorch CPU 后端。合成几何帧不含人脸或客户数据；结果只证明链路可运行，不是效果评估。
|
||||
<!-- brain-vision-v1:end -->
|
||||
|
||||
<!-- brain-rules-v1:start -->
|
||||
## Brain 区域与方向越线验证
|
||||
|
||||
```powershell
|
||||
Brain\.venv\Scripts\python.exe -m pytest Brain/tests/rules -q
|
||||
Brain\.venv\Scripts\python.exe -m pytest Brain/tests -q
|
||||
```
|
||||
|
||||
定向测试覆盖区域外/进入/内部、边界点、正反方向、贴线 deadband、无效多边形/警戒线、重复 ID 和 Profile/分辨率不匹配；只使用合成归一化几何与匿名轨迹。
|
||||
<!-- brain-rules-v1:end -->
|
||||
|
||||
<!-- brain-local-events-v1:start -->
|
||||
## Brain 独立纵切运行与验证
|
||||
|
||||
```powershell
|
||||
Brain\.venv\Scripts\python.exe -m pytest Brain/tests/events Brain/tests/app -q
|
||||
Brain\.venv\Scripts\python.exe -m pytest Brain/tests -q
|
||||
Brain\.venv\Scripts\python.exe -m yovision_brain.app --config Brain\tests\fixtures\events\area.json --output -
|
||||
```
|
||||
|
||||
CLI 将内部事件 JSON Lines 写入 stdout，并把 completed/cancelled、帧数、检测数和事件数摘要写入 stderr。配置文件必须显式提供，当前使用 JSON；无命中正常返回零事件，读取/配置/模块失败返回非零且不回显机器路径。命令不启动 Sense/Bell、不连接摄像头或网络。
|
||||
<!-- brain-local-events-v1:end -->
|
||||
|
||||
@@ -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: dcbdcf563017a1749fa76ad5f78c74a2c3cc6be1
|
||||
synchronized_at: 2026-08-28T06:16:00Z
|
||||
wiki_revision: eac307b5aa55ff770ff034c53a65b70dc01cb00d
|
||||
synchronized_at: 2026-08-29T12:39:32Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 产品需求
|
||||
@@ -232,3 +232,43 @@ Sense 为网管和非技术运维人员提供只读的“边缘节点”页面
|
||||
|
||||
本能力只管理 Sense 自有投影，不建立 Brain/Bell 共享身份、控制协议或跨项目回填执行；Brain、Bell 未运行时仍可独立查看。合成节点仅供显式开发和测试，不由生产启动或迁移自动写入。
|
||||
<!-- sense-edge-nodes:end -->
|
||||
|
||||
<!-- brain-input-delivery:start -->
|
||||
## BRN-001 独立输入适配交付边界
|
||||
|
||||
BRN-001 的首个独立实现已通过工单 #11 验收。Brain 可在 Sense、Bell 均未启动时使用固定种子和时间基准生成可重复的 RGB 合成帧，也可从显式本地路径读取容器字节供后续解码层消费；两种输入都携带 Brain 内部逻辑设备、Profile 和分辨率信息，并支持 EOF、协作取消及安全可定位错误。
|
||||
|
||||
项目内配置版本为 `brain.internal.input/v1`，可承载测试用区域和方向线，但它不是 Sense→Brain 共享契约。正式 RTSP、Sense 源/区域配置和跨项目机器身份仍须由协调工单在版本化 `contracts/` 中冻结；不得让 Sense 或 Bell 直接依赖此内部模型。配置和测试不得包含摄像头凭据、客户视频、个人数据或机器绝对路径。
|
||||
<!-- brain-input-delivery:end -->
|
||||
|
||||
<!-- brain-decode-delivery:start -->
|
||||
## BRN-002 独立解码交付边界
|
||||
|
||||
BRN-002 的首个解码阶段已通过工单 #13 验收。Brain 通过可替换 `DecoderBackend` 把内部输入转换为顺序、纳秒时间戳、逻辑设备、Profile、分辨率和像素格式明确的帧；当前独立路径支持确定性 RGB24 与匿名本地 YUV4MPEG2 C444。正常 EOF、主动取消、损坏或不支持格式、尺寸变化/不匹配均有明确结果。
|
||||
|
||||
该验收不包括生产 RTSP、FFmpeg/PyAV、NVIDIA 硬件解码、多路性能或客户视频，不得据此声明 GPU/生产编解码能力。
|
||||
<!-- brain-decode-delivery:end -->
|
||||
|
||||
<!-- brain-vision-delivery:start -->
|
||||
## BRN-002 匿名检测与跟踪交付边界
|
||||
|
||||
工单 #14 已验收匿名目标检测和会话内单路跟踪。输出只包含匿名类别、置信度、边界框、帧时间和当前进程内轨迹 ID；不包含姓名、人脸模板、生物特征、摄像头凭据或跨摄像头身份。
|
||||
|
||||
当前版本化基线是无外部权重的 first-party 亮度目标算法及 PyTorch 2.12.1 张量后端，只证明匿名检测/跟踪接口与链路可运行。真实人员检测效果、GPU、召回率、误报率和 ReID 均未验证或启用。
|
||||
<!-- brain-vision-delivery:end -->
|
||||
|
||||
<!-- brain-rules-delivery:start -->
|
||||
## BRN-003/BRN-004 区域与方向规则交付边界
|
||||
|
||||
工单 #15 已验收 Brain 内部危险区域与方向越线判定。轨迹框底边中心为归一化锚点；多边形边界视为区域内，状态区分 outside、entered、inside；有向线按起点→终点区分左右方向，并使用 deadband 抑制贴线抖动。
|
||||
|
||||
每个结果绑定规则配置版本、Profile、分辨率和解释原因。结果仍是 Brain 内部候选，不是 Bell Alert 或正式共享事件；聚集、完整时段/持续/冷却和正式 Sense 配置契约仍是后续范围。
|
||||
<!-- brain-rules-delivery:end -->
|
||||
|
||||
<!-- brain-local-events-delivery:start -->
|
||||
## BRN-005 独立内部事件候选交付边界
|
||||
|
||||
工单 #16 已验收 Brain 首个独立纵切：合成/本地输入经过解码、匿名检测/单路跟踪和区域/方向规则后，可输出 `brain.internal.event-candidate/v1` JSON Lines 候选。事件 ID 基于规范化输入事实与版本生成稳定 SHA-256；相同输入、配置和版本重复运行不制造不同 ID。
|
||||
|
||||
内部候选只含逻辑输入引用、规则/模型版本、发生时间、匿名观测和解释原因，不含摄像头凭据、客户隐私、人脸、生物特征、机器绝对路径或伪造证据。该格式不是正式 Brain→Bell 契约；证据、机器身份、Outbox/可靠投递和跨项目 E2E 仍须协调工单实现。
|
||||
<!-- brain-local-events-delivery:end -->
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
generated: true (请先修改 Gitea Wiki，禁止直接编辑本文件)
|
||||
wiki_page: Product-Roadmap
|
||||
wiki_url: https://git.ilapage.cn/ila/yovision/wiki/Product-Roadmap.-
|
||||
wiki_revision: 2d5b8550109a8ff0795ad46dd0f96c85929fb506
|
||||
synchronized_at: 2026-08-11T10:31:04Z
|
||||
wiki_revision: 5142de162b4665bd7c9ff201168cb0d4a7552f35
|
||||
synchronized_at: 2026-08-29T12:40:13Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# 产品路线图
|
||||
@@ -84,3 +84,40 @@ Sense/Brain Event → 持久 Outbox/可靠投递
|
||||
- 契约未冻结却尝试共享数据库、用户会话或内部文件；
|
||||
- 新纵切尚未验收却删除或覆盖旧仓库；
|
||||
- 许可证、隐私或客户/法务门禁未满足却进入生产试点。
|
||||
|
||||
<!-- brain-input-delivery:start -->
|
||||
## Brain 独立纵切进度
|
||||
|
||||
- 工单 #11 已验收：确定性合成输入、本地文件输入和 Brain 内部版本化配置已合入 `dev`。
|
||||
- 下一项按真实依赖进入 #13 视频解码流水线；#14 检测/跟踪、#15 区域/越线和 #16 项目内匿名事件仍需依次完成。
|
||||
- 当前输入模型只用于 Brain 独立纵切，不代替阶段 2 的 Sense→Brain 正式契约。
|
||||
<!-- brain-input-delivery:end -->
|
||||
|
||||
<!-- brain-decode-delivery:start -->
|
||||
## Brain 解码进度
|
||||
|
||||
- 工单 #13 已验收：可替换解码端口、RGB24 和匿名本地 YUV4MPEG2 路径已合入 `dev`。
|
||||
- 下一项进入 #14 匿名检测与单路跟踪；#15、#16 仍按依赖顺序推进。
|
||||
<!-- brain-decode-delivery:end -->
|
||||
|
||||
<!-- brain-vision-delivery:start -->
|
||||
## Brain 匿名视觉进度
|
||||
|
||||
- 工单 #14 已验收并合入 `dev`；下一项进入 #15 区域与方向越线规则。
|
||||
- 当前基线不代表生产模型效果，#16 项目内事件仍未完成。
|
||||
<!-- brain-vision-delivery:end -->
|
||||
|
||||
<!-- brain-rules-delivery:start -->
|
||||
## Brain 规则进度
|
||||
|
||||
- 工单 #15 已验收并合入 `dev`；下一项进入 #16 独立纵切与内部匿名事件。
|
||||
- #16 完成前，Brain 首个独立纵切仍未闭环。
|
||||
<!-- brain-rules-delivery:end -->
|
||||
|
||||
<!-- brain-local-events-delivery:start -->
|
||||
## Brain 首个独立纵切完成状态
|
||||
|
||||
- #10、#11、#13、#14、#15、#16 已全部通过用户验收。
|
||||
- Brain 可在 Sense/Bell 未启动时，以合成输入产生稳定的项目内匿名区域事件。
|
||||
- 下一步是 MVP #8 三项目独立纵切集成验收；正式跨项目契约与投递不属于该 MVP。
|
||||
<!-- brain-local-events-delivery:end -->
|
||||
|
||||
@@ -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: ce246054849b5b797dc4da0a55116238a4c00d7e
|
||||
synchronized_at: 2026-08-28T08:04:52Z
|
||||
wiki_revision: b21bbc64f323f465b78b557537c38e334de31f45
|
||||
synchronized_at: 2026-08-29T12:41:01Z
|
||||
<!-- gitea-wiki-mirror:end -->
|
||||
|
||||
# YoVision 部署与运维
|
||||
@@ -112,3 +112,25 @@ Sense\start_sense.bat
|
||||
|
||||
页面“运行异常”表示最近一次 Control API 探测失败；“状态已陈旧”表示运行循环已超过 30 秒没有更新探测结果。故障时先在详情定位设备/Profile/路径，不要手工改数据库归属。迁移预检不会执行迁移；任何实际跨分片迁移都必须另建高风险工单和回退方案。
|
||||
<!-- sense-media-shards:end -->
|
||||
|
||||
<!-- sense-outbox:start -->
|
||||
## Sense 可靠投递运维与排错
|
||||
|
||||
升级后应执行包含 `2026082815000_outbox.go` 的数据库迁移。看不到“可靠投递”菜单时，先确认迁移成功，再重新登录或刷新动态菜单。页面提供等待投递、重试、处理中/租约和死信数量；未配置正式 connector 时队列保留，不影响 Sense 设备接入、实时监看和其他核心能力。
|
||||
|
||||
积压时先查看状态、可用时间、租约、尝试次数和最近脱敏错误。processing 长时间不恢复时检查 worker 是否仍运行、数据库时间与租约是否过期；不要手工清空租约或删除消息。dead 只能由 implementation_operator 或 site_admin 在排除根因后填写恢复原因重新排队，原业务记录、幂等键和失败历史必须保留。
|
||||
|
||||
日志、页面和 API 不得输出内部 payload、外部凭据或机器身份。production 配置不得启用测试 sink。正式 Brain/Bell connector、机器身份、共享 schema 和跨项目 E2E 必须通过后续协调工单交付；停用 relay 可以作为回退，但不得删除未投递记录或永久幂等收据。
|
||||
<!-- sense-outbox:end -->
|
||||
|
||||
<!-- sense-ops-alerts:start -->
|
||||
## Sense 运维告警运行与排错
|
||||
|
||||
升级后必须执行包含 `2026082816000_ops_alert.go` 的数据库迁移。看不到“运维告警”菜单时，先确认迁移成功，再重新登录或刷新动态菜单。viewer 只能查看列表和详情；implementation_operator、site_admin 可使用“刷新状态”、确认和恢复。
|
||||
|
||||
“刷新状态”只读取 Sense 数据库中已有的设备接入、媒体路由、媒体分片和边缘节点健康投影。没有对应健康投影时不会伪造演示告警；先检查上游模块是否已完成探测或心跳入库。分片超过 30 秒没有探测、节点超过 90 秒没有心跳会被判定异常。
|
||||
|
||||
确认后仍显示活动告警是正常行为：确认只代表有人处理。源状态健康后进入“恢复观察”，稳定满 5 分钟才能确认恢复；期间复发会返回待确认或已确认。恢复操作被拒绝时先刷新列表，检查健康状态、观察起始时间和页面版本，不要手工改表或删除历史。
|
||||
|
||||
运维告警排错不得粘贴设备地址、Stream URI、摄像头凭据、JWT、Cookie 或数据库连接。需要回退时可停止使用刷新/处置入口，但不得删除 `sense_ops_alerts` 或 `sense_ops_alert_transitions` 历史；规则语义变化必须另建工单。
|
||||
<!-- sense-ops-alerts:end -->
|
||||
|
||||
Reference in New Issue
Block a user