yovision/docs/tasks/T-003.md

id, title, phase, deps, status, created, issue, context_ref, claim_branch, work_branch, write_paths

id	title	phase	deps	status	created	issue	context_ref	claim_branch	work_branch	write_paths
T-003	建立 Sense M1 无实机接入骨架	1	T-002	DONE	2026-08-03	3	e28070dd03	claims/T-003	agent/codex/T-003	docs/tasks/T-003.md Sense/ docs/00-ai-start-here.md docs/03-tech-stack.md docs/api.md docs/06-tasks.md docs/current-state.md init.ps1 init.sh

问题 / 背景

当前 Sense/ 只有占位文件。M1 需要在不继承完整 MiBeeNvr 架构的前提下建立可持续演进的 Go 生产骨架，并正式引入 MediaMTX 数据面。T-001 的真实摄像头兼容性验证已由项目负责人暂缓，因此本任务只建立可由 fake ONVIF、MediaMTX 假服务和合成 RTSP 源验证的无实机骨架；不得据此宣称摄像头兼容、5 路实机验收、M0 出口或完整 M1 出口已经完成。

关联需求与交互（如适用）

• 用户故事：US-001、US-002。
• 交互清单：本任务以 API/脚本为主，不实现正式 Web UI。
• 架构：docs/04-architecture.md；详细目录见 docs/raw/08-三系统职责划分.md。

方案

1. 冻结 Go、SQLite driver、MediaMTX 和 oapi-codegen 的精确版本，记录许可证、校验来源、升级策略与退出路线。
2. 建立 cmd/sense-api 与 internal/onvif、store、mtx、reconcile、probe 的最小目录、配置边界和测试；入口只绑定可信网络，日志不得泄露凭据或完整流地址。
3. 从锁定版本的 MediaMTX 官方 OpenAPI 可重复生成客户端，生成代码与手写薄封装分离；使用假 HTTP 服务验证创建、读取和删除 path 的请求/响应映射。
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 路独立实机集成验收。

不可变约束

• 阈值 / 数值边界：本任务不验收真实 5 路；site.max_video_channels 默认 16、最大 128，必须测试 17/128/129 边界，不能把 fake 数量、5 或 16 写成架构上限。
• 判定式 / 状态转换：数据库是期望态真相源；对账幂等、只收敛不跨系统回滚；配额不可用不影响已有流。
• 安全边界：不提交摄像头凭据；调试/MediaMTX 管理端口不暴露到非可信网络；孤儿删除暂不实现或必须有 10% 安全闸。
• 既有契约：M1 只动 Sense，不创建 Brain/Bell 业务代码；完整 MiBeeNvr 不进入依赖；MediaMTX 独立二进制。

验收要点

• 任务相关验证：go test ./...、go vet ./...、SQLite migration/配额边界、ONVIF fake、MediaMTX 假服务、对账幂等与重启恢复测试，以及三条 harness 治理命令。
• 完整门禁：公共 API、schema 或生成客户端变化时运行全部 Sense 测试和契约/迁移检查。
• 人工 / 设备验收：设备验收不适用且不得用模拟结果替代；维护者必须人工核对生成命令、版本/许可证与本地启动说明。真实摄像头和 5 路验收由 T-006 承担。
• 构建产物：冻结 Sense 二进制路径、MediaMTX 获取/校验方式、生成命令和版本信息；是否交付镜像若未在技术评审确定则不得自行扩展。

边界（不改什么）

不开发 Brain、Bell、正式管理端、规则引擎、人脸识别、真实摄像头兼容性、5 路实机验收或 64/128 路容量实现；不修改 _reference/，不把 MiBeeNvr 引入生产依赖。

协作约束

• 责任 Agent：由 dispatcher 分配。
• 唯一写入者：同责任 Agent。
• 委派：默认不启用；需要只读调研时结论先回填本文。
• Gitea：主 Issue 为 #3；本次重构合入默认分支并读回后才加入 status/todo。领取时再记录 context_ref、claim 和工作分支。

任何新增写路径先由 dispatcher 与活跃任务做前缀冲突检查。

执行记录

2026-08-04 领取与基线

• dispatcher ila 已将 Issue #3 分配给 codex；claim 与工作分支均从 e28070dd035cef3ff3e4a2dad879a482c41dac3a 创建并读回一致。
• 在独立工作树 D:\OPC\yovision-T-003 开工，唯一写入范围为本任务声明的 Sense/、任务/技术/API/路线图/当前状态文档和根初始化脚本。
• 开工基线 ./init.ps1 通过，18 项治理测试成功；仓库尚无 Sense 生产代码，代码知识图谱工具未提供，本轮按仓库规则降级到文件检查。

2026-08-04 无实机拆分

• 项目负责人决定暂缓 T-001，并批准继续推进 Sense 离线软件骨架。T-003 的开工依赖调整为仅依赖已完成的 T-002，但真实摄像头验证仍是后续集成门禁。
• 本任务收敛为 fake ONVIF、MediaMTX 假服务、SQLite 和可选合成 RTSP 可验证的生产骨架；不得用 mock 测试宣称 M0 或 M1 里程碑完成。
• 真实设备、5 路自动建 path、探活、断线恢复和 MediaMTX 证据拆到 T-006，依赖 T-001 与 T-003。
• 任务尚未领取；Issue #3 在本次规格合入默认分支前不进入 status/todo。

2026-08-04 版本与实现决策

• 冻结 Go 1.26.5、MediaMTX v1.19.3、oapi-codegen v2.8.0 与 modernc.org/sqlite v1.54.0；许可证、module sum、MediaMTX 二进制 SHA-256、OpenAPI SHA-256、升级策略与退出路线已写入 docs/03-tech-stack.md。
• SQLite driver 使用无 CGO 的 modernc.org/sqlite，但业务代码只依赖 database/sql repository；migration 避免 SQLite 专有业务语义，后续映射到 PostgreSQL sense schema。
• 设备模型使用 modality + capabilities；视频配额只统计期望启用且具备视频采集能力的设备。站点默认 16、配置允许 1～128，超出时拒绝新增/启用，已有流不受影响。
• 数据库持有期望态；ONVIF、MediaMTX 均由 port/adapter 隔离。T-003 实现确定性 fake 与假 HTTP 契约测试，不提供真实厂商兼容结论；对账只创建/修正应有 path，不做孤儿删除。
• MediaMTX 官方 OpenAPI 按 tag vendoring，生成代码不可手改；薄封装负责状态码、幂等与领域错误映射。服务默认只监听 127.0.0.1，非回环监听必须显式开启。
• 实现中发现标准 AI 入口仍会宣称“没有生产代码”。dispatcher 串行读回 Gitea 后确认只有 T-003 处于活跃状态、无路径冲突，并以完整 CLAIM RENEWAL 将 docs/00-ai-start-here.md 加入写入范围；worker 已同步本文件后才修改该入口。

2026-08-04 实现与验证证据

• 建立 Sense/go.mod、cmd/sense-api、SQLite v1 migration 与 device/store/onvif/mtx/reconcile/probe 包。进程默认回环监听，只提供 /healthz、/readyz；真实 ONVIF adapter 显式返回 unavailable，避免把 fake 冒充生产兼容实现。
• vendoring MediaMTX v1.19.3 官方 OpenAPI，输入 SHA-256 为 a2b58195f1ec76541e124b5de4ee54645e5a3e25f70c4a73acc4a44d6f2b9c52；go generate ./internal/mtx 生成文件 SHA-256 在重复生成前后均为 9e10d96eac1b332783d7cbfaba5872fede62a16ef6ccc1062cdb246607db7dac。
• SQLite 测试覆盖默认第 17 路拒绝、配置 128 路成功、第 129 路拒绝、禁用第 17 路重新启用拒绝、非视频设备不占额度，以及下调配额不关闭已有流。migration、唯一性、期望态 generation 和持久化退避由同一 repository 测试链路执行。
• ONVIF fixture 覆盖 profile、脱敏 stream URI、校时、认证失败和取消/超时；MediaMTX 假 HTTP 服务覆盖官方生成客户端的 create/read/delete、ensure 幂等/patch、runtime path 探活和错误脱敏。
• 对账测试覆盖成功收敛后不重复、指数退避、取消不消耗重试预算和关闭/重开 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 恢复后提供。