From fd16f77b95201e4437df966c19c8eabc1d32a51e Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Tue, 4 Aug 2026 17:25:33 +0800 Subject: [PATCH] docs(requirements): adopt single-camera development strategy --- docs/00-ai-start-here.md | 4 +-- docs/02-requirements.md | 2 ++ docs/03-tech-stack.md | 3 +- docs/04-architecture.md | 2 +- docs/06-tasks.md | 7 ++-- docs/current-state.md | 6 ++-- docs/quality-document.md | 2 +- docs/tasks/T-001.md | 7 +++- docs/tasks/T-003.md | 8 ++--- docs/tasks/T-006.md | 37 ++++++++++++--------- docs/tasks/T-007.md | 69 ++++++++++++++++++++++++++++++++++++++++ 11 files changed, 117 insertions(+), 30 deletions(-) create mode 100644 docs/tasks/T-007.md diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md index b1de4b4..908982d 100644 --- a/docs/00-ai-start-here.md +++ b/docs/00-ai-start-here.md @@ -40,12 +40,12 @@ MVP 以默认 16 路跑通一个场景的端到端闭环；架构、数据和 UI ## 当前阶段 -当前为 **M0 指定型号实机准入待执行，M1 Sense 无实机骨架已建立**。一台指定型号样机可以完成 M0 准入，但不能替代 M1 五路独立实机出口。 +当前为 **M0 指定型号实机准入待执行，M1 Sense 无实机骨架已建立**。后续本地开发统一使用现有一台海康样机，多路软件闭环使用独立合成 RTSP 源补足；真实多设备证据延后到客户/借用/租赁条件具备时执行。 优先路径： 1. M0：一台真实样机完成首期指定“型号 + 硬件版本 + 固件”ONVIF/RTSP 准入；结论不外推为多品牌兼容。 -2. M1：只在 `Sense/` 建立 MediaMTX 生产接入骨架，5 路自动建 path、探活、断线重建。 +2. M1：只在 `Sense/` 建立 MediaMTX 生产接入骨架，以 1 路准入实机 + 至少 4 路独立合成源完成五路自动建 path、探活和断线重建。 3. M2：对账、多租户、隧道和至少一个站点的 16 路全流程。 4. M3：Brain + Bell 起步，默认 16 路端到端事件、预警、ack 与误报反馈。 5. M4–M5：64/128 路分片、管理端和第二/第三场景包。 diff --git a/docs/02-requirements.md b/docs/02-requirements.md index 66b407f..b31a000 100644 --- a/docs/02-requirements.md +++ b/docs/02-requirements.md @@ -23,6 +23,8 @@ - 执行 `raw/01-需求收集.md` §8 已批准的决策台账；只将明确记录的下游法务、客户、硬件和供应商门禁留到对应里程碑。 - M0 代码与临时配置可丢弃，不作为生产基线；可借鉴范围严格遵循 NVR 白名单。 +本地硬件开发基线为现有一台 Hikvision IP Camera，精确型号/硬件/固件由 T-001 冻结；生产代码仍只依赖标准 ONVIF/RTSP adapter，不得写死海康品牌或私有地址。M1 实验室使用该 1 路实机和至少 4 条可独立启停的合成 RTSP 上游完成五路软件闭环。合成源可用于功能、配额和容量测试，但不能证明多台真实设备故障隔离、批次一致性或生产 SLA；这些结论由客户授权、借用或租赁设备的 T-007 现场门禁提供。 + ## 3. P0 功能要求 ### 3.1 接入与设备 diff --git a/docs/03-tech-stack.md b/docs/03-tech-stack.md index 2ac8ab8..6967021 100644 --- a/docs/03-tech-stack.md +++ b/docs/03-tech-stack.md @@ -8,6 +8,7 @@ | --- | --- | --- | | 首期部署 | 客户侧私有化实例 | 保留 `tenant_id`、RBAC、schema 和 API 的 SaaS-ready 隔离边界 | | M1–M3 视频接入 | ONVIF / RTSP | 售前盘点存量 NVR；GB/T 28181-2022 不进当前 MVP，按需另建适配任务 | +| 本地摄像头基线 | 1 台 Hikvision IP Camera + 独立合成 RTSP 源 | 海康精确型号/固件由 T-001 冻结；T-006 冻结合成 publisher 及版本。仅为开发策略，不在业务代码写死品牌，也不替代 T-007 真实多路现场验收 | | Sense | Go | 设备、ONVIF、MediaMTX 控制与对账 | | 媒体数据面 | MediaMTX 独立二进制 | MIT；M1 正式生产基线 | | MediaMTX API | 从官方 OpenAPI 用 `oapi-codegen` 生成 + 薄封装 | 不依赖第三方非官方 SDK | @@ -97,7 +98,7 @@ python scripts/validate_harness_governance.py | --- | --- | --- | --- | | Harness 文档/任务/Gitea 模板 | 上述三条 Python 命令 | 任一治理协议、清单或任务 schema 变化 | 不适用 | | `docs/raw/contracts/` | JSON Schema 校验 + 契约代码断言（实现后补命令） | schema/示例/mapper 任一变化 | 生产者与消费者联合评审 | -| Sense Go | `go -C Sense generate ./internal/mtx`、`go -C Sense test ./...`、`go -C Sense vet ./...`、`go -C Sense build ./...` | ONVIF、存储、MediaMTX、对账或公共 API 变化 | T-003 为无实机；命中 T-006 等设备任务时使用指定摄像头矩阵 | +| Sense Go | `go -C Sense generate ./internal/mtx`、`go -C Sense test ./...`、`go -C Sense vet ./...`、`go -C Sense build ./...` | ONVIF、存储、MediaMTX、对账或公共 API 变化 | T-006 使用 1 路指定实机 + 4 路独立合成源；T-007 才要求客户/借用/租赁的真实多路矩阵 | | Brain Python | 单元测试、类型/格式检查（命令待项目脚手架冻结） | mapper、判定状态机、模型接口变化 | 命中模型任务时用冻结数据集和目标硬件 | | Bell Go/Web | 后端测试 + 前端 lint/test/build（命令待脚手架冻结） | schema、RBAC、预警状态机或公共 UI 变化 | P0 流程由产品/值班角色验收 | | 容量/分片 | 任务内基准脚本 | 16/64/128 路里程碑 | 目标网络、媒体和 GPU 硬件必需 | diff --git a/docs/04-architecture.md b/docs/04-architecture.md index 48e2946..3c80696 100644 --- a/docs/04-architecture.md +++ b/docs/04-architecture.md @@ -117,7 +117,7 @@ Bell/{web,packs,contracts} ## 10. 开发顺序 - M0 不写生产代码。 -- M1 只动 Sense，5 路视频接入骨架与 MediaMTX；设备模型从此时起保持模态/能力可扩展，但不提前实现非视频适配器。 +- M1 只动 Sense，以 1 路 T-001 准入实机 + 至少 4 路独立合成 RTSP 源完成五路接入骨架与 MediaMTX；设备模型从此时起保持模态/能力可扩展，但不提前实现非视频适配器。真实多设备现场门禁移到 T-007，阻塞生产试点但不阻塞本地开发。 - M2 仍以 Sense 为主，完成 16 路开通/停用、对账、多租户投影与隧道。 - M3 Brain 与 Bell 同时起步，事件契约首次被真实使用。 - M4/M5 再做 64/128 路分片、完整管理端和多个场景包；M6 接入雷达、门磁、按钮和可穿戴等非视频适配器。 diff --git a/docs/06-tasks.md b/docs/06-tasks.md index 884c991..40abd24 100644 --- a/docs/06-tasks.md +++ b/docs/06-tasks.md @@ -11,12 +11,12 @@ ## M1：Sense 接入骨架 + MediaMTX -出口：5 路自动建 path、探活、断线重建；使用 MediaMTX 生产数据面，完整 MiBeeNvr 不替代生产基线。 +出口：1 路 T-001 准入实机 + 至少 4 路独立合成 RTSP 源完成五路自动建 path、探活、断线重建；使用 MediaMTX 生产数据面，完整 MiBeeNvr 不替代生产基线。该出口是实验室软件闭环，不代表真实五机或生产 SLA。 - T-003：建立无需真实摄像头即可验证的 Sense Go 脚手架、设备台账、ONVIF port/fake、MediaMTX 生成客户端与薄封装；完成不代表 M0/M1 出口。 - T-003 只冻结 `/healthz`、`/readyz` 运维探针，设备管理公共 API 留给后续契约任务；真实 ONVIF adapter 不用 fake 冒充。 -- T-006：在 T-001 指定准入基线与 T-003 骨架之上，使用该型号建立 5 条独立真实上游，完成自动建 path、探活、断线恢复和 MediaMTX 集成验收；复制同一 RTSP 上游不计为多路。 -- T-003 已完成；T-006 和 M1 出口继续等待 T-001 指定型号实机证据及 5 条独立上游硬件条件。 +- T-006：在 T-001 指定准入基线与 T-003 骨架之上，以 1 路海康实机 + 至少 4 路可独立启停的合成 RTSP 源完成五路自动建 path、探活、恢复和 MediaMTX 实验室集成验收。 +- T-003 已完成；T-006 只等待 T-001 指定实机证据及合成源准备，不要求当前购买更多摄像头。 ## M2：对账、多租户投影与 16 路全流程 @@ -36,6 +36,7 @@ - 规则引擎、场景包加载、预警状态机与双路径投递。 - 最小 Web/App 处置流程、RBAC 与审计。 - 现场误报基线和反馈队列。 +- T-007：客户试点、借用或租赁设备条件具备后完成至少 5 条独立真实上游的现场验收；不阻塞本地开发，但阻塞生产试点启用和真实多路 SLA。 ## M4：64 路分片与完整管理系统 diff --git a/docs/current-state.md b/docs/current-state.md index c9b3db7..377067c 100644 --- a/docs/current-state.md +++ b/docs/current-state.md @@ -5,7 +5,7 @@ ## 当前阶段 - 阶段：M0 已收敛为首期指定摄像头型号准入，实机验证尚未执行；M1 Sense 无实机软件骨架已完成，但不得提前宣称 M0/M1 出口完成。 -- 生产代码：Sense M1 无实机骨架已建立，包含可构建进程、SQLite 台账、ONVIF port/fake、MediaMTX 生成客户端、最小对账与探活；真实 ONVIF adapter 和五路设备验收仍未开始。 +- 生产代码：Sense M1 无实机骨架已建立，包含可构建进程、SQLite 台账、ONVIF port/fake、MediaMTX 生成客户端、最小对账与探活；真实 ONVIF adapter 和单实机混合源验收仍未开始。 - 默认容量：16 路；单站点本阶段上限 128 路，必须横向分片。 ## 仓库现实 @@ -49,6 +49,8 @@ Sense 默认监听 `127.0.0.1:8080`，提供 `/healthz` 与 `/readyz` 运维探 ## 当前 blocker / 待确认 - 项目负责人已将 T-001 重构为一个指定型号/固件基线、至少一台真实样机的 ONVIF/RTSP 准入；数量条件已满足，但实物身份、隔离网络、ONVIF 账号和原始证据仍须在领取后核验。单样机结论不代表批次或多品牌兼容。 +- 后续本地开发统一使用现有一台 Hikvision IP Camera；T-006 以该实机 + 至少 4 条独立合成 RTSP 源完成五路软件闭环，不要求当前购买更多摄像头。合成 publisher 的具体工具和版本在 T-006 领取后冻结。 +- T-007 保留至少 5 条独立真实上游的客户现场门禁，可使用客户授权、借用或租赁设备；它不阻塞本地开发/M1 实验室出口，但继续阻塞生产试点和真实多路 SLA。 - S2 真实生产试点的未成年人影像、公共安全视频法规适用性和最终留存政策仍需客户/法务确认，阻塞 M3 上线但不阻塞 M1 实验室骨架。 - 人脸方向已延后至 M5 的 S4 成人园区候选试点；必要性/PIP 影响评估、单独同意与替代方式、合法底库来源和删除流程未完成，阻塞人脸能力上线。 - 短信/语音具体供应商未选；生产前必须选定两条独立投递路径并验证故障切换。 @@ -57,7 +59,7 @@ Sense 默认监听 `127.0.0.1:8080`，提供 `/healthz` 与 `/readyz` 运维探 ## 下一步 -先领取并完成 T-001 指定型号准入；随后为 T-006 准备该准入基线的 5 条独立真实视频上游，完成自动建 path、探活、断线恢复和 MediaMTX 证据。同一摄像头/同一 RTSP 上游重复连接不能冒充五路。实时领取状态仍以 Gitea 为准。 +先领取并完成 T-001 海康指定型号准入；随后 T-006 使用该一台实机和至少 4 条独立合成 RTSP 上游完成五路软件闭环，无需采购额外摄像头。客户/借用/租赁条件具备后再执行 T-007 真实多路现场门禁。实时领取状态仍以 Gitea 为准。 ## 已知风险 diff --git a/docs/quality-document.md b/docs/quality-document.md index 3d1b8c4..28cac26 100644 --- a/docs/quality-document.md +++ b/docs/quality-document.md @@ -25,7 +25,7 @@ | 领域 | 评级 | 验证状态 | Agent 可读性 | 测试稳定性 | 关键缺口 | 上次更新 | |------|------|---------|-------------|-----------|---------|---------| | Harness 文档与任务治理 | A | 三条治理命令通过 | A | A | 需观察真实多轮任务是否顺畅 | 2026-08-03 | -| 摄像头接入与媒体 | N/A | M0/M1 未完成 | B（设计清楚） | N/A | 实机兼容矩阵、Sense 代码与 5 路 smoke | 2026-08-03 | +| 摄像头接入与媒体 | N/A | M0/M1 未完成 | B（设计清楚） | N/A | T-001 单海康准入、Sense 代码、T-006 单实机混合五路 smoke；生产前补 T-007 真实多路现场证据 | 2026-08-04 | | 推理与事件契约 | C | 契约已冻结，生产者未实现 | A | N/A | Brain mapper、契约测试和硬件基准 | 2026-08-03 | | 规则、预警与处置 | N/A | M3 未开始 | B（设计清楚） | N/A | Bell、ack/升级、投递与 UI | 2026-08-03 | | 多租户、RBAC 与审计 | N/A | M3 未开始 | B（设计清楚） | N/A | schema、鉴权和隔离测试 | 2026-08-03 | diff --git a/docs/tasks/T-001.md b/docs/tasks/T-001.md index 0ee1cb6..31e0f13 100644 --- a/docs/tasks/T-001.md +++ b/docs/tasks/T-001.md @@ -72,4 +72,9 @@ YoVision 尚未用真实摄像头验证 ONVIF/RTSP 接入。项目负责人决 - 项目负责人确认首期只有一台摄像头，并决定统一采购一个指定型号；T-001 从“3–5 款兼容性矩阵”收敛为“一个精确型号/固件基线、至少一台真实样机”的准入验证。 - 数量门槛降低不等于降低必过项：保留三个 ONVIF 核心操作、主/子码流、认证失败、校时/漂移和掉线恢复，增加主/子码流各 10 分钟及 3 次断线恢复的最低证据要求。 -- 准入结论不得外推到其他型号、硬件版本、固件、生产批次或多品牌兼容。后续 T-006 仍要求 5 条独立真实视频通道，不能把同一台摄像头的同一 RTSP 上游复制为五路。 +- 准入结论不得外推到其他型号、硬件版本、固件、生产批次或多品牌兼容。后续 T-006 使用该一台实机 + 至少 4 条独立合成 RTSP 源完成五路软件闭环；真实多设备证据由 T-007 在客户/借用/租赁条件具备后完成。 + +### 2026-08-04 单海康样机开发基线 + +- 项目负责人确认当前唯一实机为 Hikvision IP Camera，后续本地硬件开发均使用该样机；领取 T-001 后仍须从实物读取并冻结精确型号、硬件版本和固件，不能只记录品牌。 +- 多路功能、配额和容量验证允许使用无人物合成 RTSP 源；合成结果不扩展 T-001 的准入范围，也不证明多台真实设备兼容或故障隔离。 diff --git a/docs/tasks/T-003.md b/docs/tasks/T-003.md index 2583332..761141f 100644 --- a/docs/tasks/T-003.md +++ b/docs/tasks/T-003.md @@ -39,7 +39,7 @@ write_paths: 4. 以 port/adapter 隔离 ONVIF，提供确定性的 fake adapter 和脱敏 fixture，验证 profile、stream URI、校时、认证失败和超时的领域映射，但不伪造厂商兼容结论。 5. 设备台账先使用 SQLite migration，schema 语义与生产 PostgreSQL `sense` schema 保持一致；建模使用 `modality + capabilities`，配额默认 16、最大 128，并覆盖 17/128/129 边界。 6. 建立数据库期望态驱动的最小对账/探活循环，使用 fake ONVIF、MediaMTX 假服务和可选合成 RTSP 源验证幂等、退避、取消与重启恢复；本任务不接真实摄像头，也不实现孤儿删除。 -7. 将真实安装、生成、验证、构建和启动命令同步到标准入口与文档；后续 T-006 再使用 T-001 指定准入基线设备完成 5 路独立实机集成验收。 +7. 将真实安装、生成、验证、构建和启动命令同步到标准入口与文档；后续 T-006 使用 T-001 指定实机 + 独立合成 RTSP 源完成五路实验室集成，T-007 再补真实多路现场证据。 ## 不可变约束 @@ -52,7 +52,7 @@ write_paths: - 任务相关验证：`go test ./...`、`go vet ./...`、SQLite migration/配额边界、ONVIF fake、MediaMTX 假服务、对账幂等与重启恢复测试，以及三条 harness 治理命令。 - 完整门禁：公共 API、schema 或生成客户端变化时运行全部 Sense 测试和契约/迁移检查。 -- 人工 / 设备验收：设备验收不适用且不得用模拟结果替代；维护者必须人工核对生成命令、版本/许可证与本地启动说明。真实摄像头和 5 路验收由 T-006 承担。 +- 人工 / 设备验收：设备验收不适用且不得用模拟结果替代；维护者必须人工核对生成命令、版本/许可证与本地启动说明。单实机五路混合源验收由 T-006 承担，真实多设备现场验收由 T-007 承担。 - 构建产物：冻结 Sense 二进制路径、MediaMTX 获取/校验方式、生成命令和版本信息；是否交付镜像若未在技术评审确定则不得自行扩展。 ## 边界（不改什么） @@ -80,7 +80,7 @@ write_paths: - 项目负责人决定暂缓 T-001，并批准继续推进 Sense 离线软件骨架。T-003 的开工依赖调整为仅依赖已完成的 T-002，但真实摄像头验证仍是后续集成门禁。 - 本任务收敛为 fake ONVIF、MediaMTX 假服务、SQLite 和可选合成 RTSP 可验证的生产骨架；不得用 mock 测试宣称 M0 或 M1 里程碑完成。 -- 真实设备、5 路自动建 path、探活、断线恢复和 MediaMTX 证据拆到 T-006，依赖 T-001 与 T-003。 +- 指定实机 + 合成源的五路自动建 path、探活、断线恢复和 MediaMTX 实验室证据拆到 T-006；真实多设备现场证据后续拆到 T-007。 - 任务尚未领取；Issue #3 在本次规格合入默认分支前不进入 `status/todo`。 ### 2026-08-04 版本与实现决策 @@ -101,4 +101,4 @@ write_paths: - 对账测试覆盖成功收敛后不重复、指数退避、取消不消耗重试预算和关闭/重开 SQLite 后恢复；探活测试覆盖 online/offline 映射。对账器不调用 `DeletePath`，没有孤儿删除旁路。 - `go test -race ./...` 全部通过；`go test ./... -count=2` 连续两轮通过；`go vet ./...`、`go build ./...` 通过。实际构建 `sense-api` 后在随机回环端口用绕过系统代理的 curl 验证 `health=ok`、`ready=ready`，临时 EXE、SQLite 和日志随后逐项删除。 - 根标准入口 `./init.ps1` 通过：agent-context 校验、18 项治理测试、harness 治理校验、生成漂移检查、Sense 全量测试、vet 与 build 均成功。人工核对生成头为 `oapi-codegen v2.8.0`、OpenAPI/二进制下载使用固定 `v1.19.3` URL 和 SHA-256、MediaMTX/Sense 管理端默认只绑定回环地址。 -- 设备人工验收不适用：未连接摄像头，未宣称 T-001 白名单、真实 5 路或 M0/M1 出口完成；这些证据仍由 T-006 在 T-001 恢复后提供。 +- 设备人工验收不适用：未连接摄像头，未宣称 T-001 准入、五路混合源或 M0/M1 出口完成；这些证据由 T-001/T-006 提供，真实多设备现场证据由 T-007 提供。 diff --git a/docs/tasks/T-006.md b/docs/tasks/T-006.md index 3f00252..8e2b465 100644 --- a/docs/tasks/T-006.md +++ b/docs/tasks/T-006.md @@ -1,6 +1,6 @@ --- id: T-006 -title: 完成 Sense 五路真实摄像头集成验收 +title: 完成 Sense 单实机与五路混合源集成验收 phase: 1 deps: [T-001, T-003] status: TODO @@ -18,7 +18,7 @@ write_paths: ## 问题 / 背景 -T-003 只用 fake ONVIF、MediaMTX 假服务和合成 RTSP 建立无实机骨架，不能证明指定实机基线可用、真实媒体路径稳定或断线后能自动收敛。M1 出口仍要求使用 T-001 已批准“型号 + 硬件版本 + 固件”基线的真实摄像头完成 5 路自动建 path、探活和断线恢复，并留下可重复、脱敏的证据。 +T-003 只用 fake ONVIF 和 MediaMTX 假服务建立无实机骨架，不能证明指定海康实机基线可用或真实媒体路径能自动收敛。受当前硬件预算限制，M1 实验室出口改为使用 T-001 已批准的 1 台 Hikvision IP Camera 作为真实 ONVIF/RTSP 上游，再用至少 4 条可独立启停的合成 RTSP 上游补足 5 路，验证控制面、多路调和、探活和恢复。该结果是开发集成 smoke，不是五台真实设备或生产 SLA 证据。 ## 关联需求与交互（如适用） @@ -28,29 +28,30 @@ T-003 只用 fake ONVIF、MediaMTX 假服务和合成 RTSP 建立无实机骨架 ## 方案 -1. 使用 T-001 指定准入基线，在隔离实验室建立至少 5 条彼此独立的真实视频上游，原则上使用 5 台该型号设备；只有能证明传感器、编码会话和故障域独立的多通道硬件才可折算多路。重复连接同一 RTSP URI、同一编码上游或 MediaMTX fan-out 只算 1 路。记录型号、硬件版本、固件、网络拓扑和主/子码流，但不记录密码或含凭据的完整 URI。 -2. 通过 Sense 设备台账写入期望态，验证 ONVIF profile/stream URI 映射、MediaMTX path 自动创建和健康状态，不允许人工修改 MediaMTX 配置冒充自动化成功。 -3. 验证三类恢复：摄像头/网络短时离线、Sense 进程重启、MediaMTX 进程重启。每类都记录配置的探活/退避期限、实际恢复时间、对账结果和失败证据。 -4. 验证 5 路并行运行期间 path、reader/upstream、探活和数据库期望态一致；连续观察窗口至少 30 分钟，只作为 M1 集成 smoke，不外推 16/64/128 路容量或生产 SLA。 -5. 将可重复步骤、版本、命令、脱敏结果、已知厂商差异和结论写入 `docs/research/sense-5-stream-integration.md`；失败通道保留记录，不通过删除样本美化结果。 +1. 使用 T-001 指定准入基线的 1 台真实海康摄像头，记录型号、硬件版本、固件、网络拓扑和主/子码流，但不记录密码或含凭据的完整 URI。 +2. 使用 FFmpeg、GStreamer 或等价离线工具建立至少 4 条合成 RTSP 上游；每条必须有不同 source/path，并可单独启动、停止和注入故障。同一真实 RTSP URI 的重复连接、同一编码上游的 fan-out 或同一合成 publisher 的重复映射不增加独立源计数。 +3. 通过 Sense 设备台账写入期望态，验证真实设备的 ONVIF profile/stream URI 映射，以及全部 5 路的 MediaMTX path 自动创建和健康状态；不允许人工修改 MediaMTX 配置冒充自动化成功。 +4. 验证四类恢复：真实摄像头/网络短时离线、单条合成 publisher 停止/恢复、Sense 进程重启、MediaMTX 进程重启。每类都记录探活/退避期限、实际恢复时间、对账结果和失败证据。 +5. 验证 5 路并行运行期间 path、reader/upstream、探活和数据库期望态一致；连续观察窗口至少 30 分钟，只作为 M1 实验室集成 smoke，不外推真实多设备故障隔离、16/64/128 路容量或生产 SLA。 +6. 将可重复步骤、版本、合成源生成命令、脱敏结果、限制和结论写入 `docs/research/sense-5-stream-integration.md`；失败通道保留记录，不通过删除样本美化结果。 ## 不可变约束 -- 阈值 / 数值边界：至少 5 条同时在线且上游独立的真实视频通道，连续观察至少 30 分钟；同一上游的重复拉流不增加计数。默认 16、最大 128 的配额语义不得改变。本任务不验收 16/64/128 路容量。 -- 判定式 / 状态转换：数据库仍是期望态真相源；三类恢复均须在 T-003 冻结的探活/退避配置内自动重新收敛，`unconverged = 0`，不得靠人工改配置或重建数据库通过。 -- 安全边界：只使用自购设备和隔离网络；证据中不得出现密码、完整 RTSP/ONVIF 凭据、可复用 token、真实客户地址或人物画面。 +- 阈值 / 数值边界：至少 5 条同时在线的开发上游，其中 1 条来自 T-001 真实准入样机、至少 4 条为可独立故障注入的合成 RTSP 源，连续观察至少 30 分钟；重复上游不增加计数。默认 16、最大 128 的配额语义不得改变。本任务不验收真实 5 机或 16/64/128 路容量。 +- 判定式 / 状态转换：数据库仍是期望态真相源；四类恢复均须在 T-003 冻结的探活/退避配置内自动重新收敛，`unconverged = 0`，不得靠人工改配置或重建数据库通过。 +- 安全边界：只使用自购样机、无人物测试图案和隔离网络；证据中不得出现密码、完整 RTSP/ONVIF 凭据、可复用 token、真实客户地址或人物画面。 - 既有契约：MediaMTX 保持独立二进制，MiBeeNvr 不进入生产依赖；不得为通过某一厂商测试把 5、16 或厂商名称写死在业务逻辑中。 ## 验收要点 -- 任务相关验证：执行 T-003 冻结的全部 Sense 单测、vet、migration/契约检查；完成 5 路自动 path、健康、30 分钟观察和三类恢复矩阵；运行三条 harness 治理命令。 -- 完整门禁：若为实机差异修改 ONVIF、MediaMTX、store、reconcile、probe 或公共 API，必须重跑全部 Sense 测试和全部 5 路实机矩阵。 -- 人工 / 设备验收：必需。实施/硬件负责人核对 5 路设备身份、固件、网络条件、原始时间线与脱敏证据；任何一条未通过则任务不得标记 `DONE`。 +- 任务相关验证：执行 T-003 冻结的全部 Sense 单测、vet、migration/契约检查；完成 1 实机 + 4 合成源的 5 路自动 path、健康、30 分钟观察和四类恢复矩阵；运行三条 harness 治理命令。 +- 完整门禁：若为实机差异修改 ONVIF、MediaMTX、store、reconcile、probe 或公共 API，必须重跑全部 Sense 测试和完整五路混合源矩阵。 +- 人工 / 设备验收：必需。实施/硬件负责人核对真实设备身份/固件、4 条合成源的独立启停命令、网络条件、原始时间线与脱敏证据；任何一条未通过则任务不得标记 `DONE`。 - 构建产物：记录实际 Sense 与 MediaMTX 二进制版本/哈希、配置模板、启动命令和证据文档；不提交摄像头配置秘密或媒体样本。 ## 边界（不改什么） -不修改 Brain、Bell、规则/告警业务、正式管理 UI，不做 16/64/128 路容量验收，不重新裁决 T-001 指定型号准入基线，不把失败设备从证据中删除。 +不修改 Brain、Bell、规则/告警业务、正式管理 UI，不做真实 5 机或 16/64/128 路容量验收，不重新裁决 T-001 指定型号准入基线，不把失败源从证据中删除。 ## 协作约束 @@ -68,7 +69,13 @@ T-003 只用 fake ONVIF、MediaMTX 假服务和合成 RTSP 建立无实机骨架 - 项目负责人批准将 T-003 拆成无实机软件骨架，并由本任务保留真实摄像头和 5 路 M1 集成门禁。 - 当前 T-001 暂缓、T-003 尚未领取，因此 T-006 仅建立规格，不进入可领取队列。 -### 2026-08-04 上游准入范围更新 +### 2026-08-04 上游准入范围更新（已由下一节替代） - T-001 已按项目负责人决定收敛为一个指定型号/固件基线的一台样机准入；T-006 可以使用同一准入型号的设备，不再要求多个品牌。 - T-006 的 5 路门禁不随之降低：必须是 5 条独立真实上游，通常需要 5 台设备；同一摄像头或同一 RTSP URI 的复制连接不能计数。 + +### 2026-08-04 单实机开发策略 + +- 项目负责人确认无预算购买更多摄像头，后续本地开发统一使用现有 1 台 Hikvision IP Camera；精确型号/硬件/固件仍由 T-001 冻结，代码不得写死品牌或私有地址。 +- T-006 改为 1 路真实准入样机 + 至少 4 路可独立启停的合成 RTSP 源，验证五路软件闭环；原“五条独立真实上游”现场证据移交 T-007，不再阻塞日常开发或 M1 实验室出口。 +- 该变更替代上一节“需要五台真实设备”的约束，但不允许把同一摄像头/同一 RTSP URI 重复拉流冒充多个独立源。 diff --git a/docs/tasks/T-007.md b/docs/tasks/T-007.md new file mode 100644 index 0000000..6fa561d --- /dev/null +++ b/docs/tasks/T-007.md @@ -0,0 +1,69 @@ +--- +id: T-007 +title: 完成客户试点真实多路摄像头现场验收 +phase: 3 +deps: [T-001, T-006] +status: TODO +created: 2026-08-04 +issue: 22 +context_ref: null +claim_branch: null +work_branch: null +write_paths: + - docs/tasks/T-007.md + - docs/research/pilot-real-camera-integration.md + - Sense/ + - docs/current-state.md +--- + +## 问题 / 背景 + +受硬件预算限制，T-006 只用 1 台真实海康摄像头和至少 4 条合成 RTSP 源完成实验室软件闭环，不能证明多台真实设备的并发接入、网络故障隔离、批次一致性或现场恢复。项目无需为日常开发提前采购设备，但在客户试点、借用或租赁条件具备后，生产上线和真实多路 SLA 声明仍需要现场证据。 + +## 关联需求与交互（如适用） + +- 用户故事：US-001、US-002、US-007。 +- 交互清单：无正式 UI；使用 Sense API、日志、指标和版本化现场记录验收。 +- 前置产物：T-001 指定准入基线、T-006 五路混合源实验室证据。 + +## 方案 + +1. 使用客户授权、借用或租赁设备，在隔离的试点测试窗口建立至少 5 条来自不同真实编码上游的视频通道；优先使用 T-001 准入型号。若型号/硬件/固件不在准入基线，先按 T-001 全矩阵完成独立准入变更，不能在本任务中默许。 +2. 通过 Sense 自动完成设备发现/台账期望态、MediaMTX path、探活和对账；不得人工修改 MediaMTX 配置或复制同一 RTSP URI 凑数。 +3. 对至少一条上游执行摄像头/网络断开恢复，并验证 Sense 与 MediaMTX 分别重启后的全量自动收敛；记录配置期限、实际恢复时间和 `unconverged`。 +4. 全部真实上游同时在线连续观察至少 2 小时；记录码率、分辨率、FPS、连接/重连、path/reader/upstream 一致性和失败时间线。 +5. 将步骤、授权来源、设备身份/固件的脱敏摘要、网络拓扑、命令、结果、限制和签字结论写入 `docs/research/pilot-real-camera-integration.md`，不提交视频样本或秘密。 + +## 不可变约束 + +- 阈值 / 数值边界：至少 5 条独立真实编码上游，同时在线至少 2 小时；同一摄像头/编码会话/RTSP URI 的重复连接和 MediaMTX fan-out 只算 1 路。本任务不替代 16/64/128 路容量验收。 +- 判定式 / 状态转换：数据库仍是期望态真相源；摄像头/网络、Sense、MediaMTX 三类恢复后必须自动达到 `unconverged = 0`，不得人工改配置或重建数据库通过。 +- 安全边界：设备必须自购、借用、租赁或由客户书面授权；在测试窗口使用无敏感人物画面或遮挡画面，证据不含密码、完整 URI、token、客户地址或媒体样本。 +- 上线边界：本任务不阻塞本地开发和 M1 实验室出口，但阻塞客户生产试点启用、真实多路稳定性结论和相关 SLA。 + +## 验收要点 + +- 任务相关验证：执行全部 Sense 单测、vet、migration/契约检查；完成至少 5 路真实上游、2 小时观察和三类恢复；运行三条 harness 治理命令。 +- 完整门禁：若修改 ONVIF、MediaMTX、store、reconcile、probe 或公共 API，重跑全部 Sense 测试和全部现场矩阵。 +- 人工 / 设备验收：必需。客户/实施/硬件负责人核对设备来源、身份、固件、网络、原始时间线、脱敏证据与限制，并签署结论。 +- 构建产物：记录 Sense/MediaMTX 版本与哈希、配置模板、启动/恢复命令和证据文档；不提交摄像头秘密或媒体。 + +## 边界（不改什么） + +不开发 Brain/Bell 功能，不评估 AI 检出率，不宣称多品牌兼容，不做 16/64/128 路容量验收，不要求项目在客户/借用/租赁条件出现前自行购买额外摄像头。 + +## 协作约束 + +- 责任 Agent：由 dispatcher 分配。 +- 唯一写入者：同责任 Agent。 +- 委派：默认不启用；现场人员可执行设备操作，但任务所有者必须核验并版本化脱敏证据。 +- Gitea：主 Issue 为 #22；T-001、T-006 均为 `DONE` 且外部设备条件具备前保持 `status/waiting`。 + +任何新增写路径先由 dispatcher 与活跃任务做前缀冲突检查。 + +## 执行记录 + +### 2026-08-04 任务定义 + +- 项目负责人批准后续本地开发只使用现有一台海康摄像头，多路由合成 RTSP 补足；真实五路现场证据从 T-006 移入本任务。 +- 设备不要求项目当前采购，可使用客户授权、借用或租赁设备；本任务只阻塞生产试点，不阻塞软件开发。 -- 2.55.0