---
id: T-003
title: 建立 Sense M1 接入骨架
phase: 1
deps: [T-001, T-002]
status: TODO
created: 2026-08-03
issue: null
context_ref: null
claim_branch: null
work_branch: null
write_paths:
  - docs/tasks/T-003.md
  - Sense/
  - docs/03-tech-stack.md
  - docs/api.md
  - docs/current-state.md
  - init.ps1
  - init.sh
---

## 问题 / 背景

当前 `Sense/` 只有占位文件。M1 需要在不继承完整 MiBeeNvr 架构的前提下建立可持续演进的 Go 生产骨架，并正式引入 MediaMTX 数据面。

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

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

## 方案

1. 冻结 Go、SQLite 和 MediaMTX 的精确版本，记录许可证与升级策略。
2. 建立 `cmd/sense-api` 与 `internal/onvif`、`store`、`mtx`、`reconcile`、`probe` 的最小目录和测试。
3. 从 MediaMTX 官方 OpenAPI 生成客户端，手写代码只放薄封装。
4. 设备台账先使用 SQLite，但 schema 语义与生产 PostgreSQL `sense` schema 保持一致。
5. 跑通 5 路自动建 path、探活和断线重建的可重复集成测试。
6. 将真实安装、验证和启动命令同步到标准入口与文档。

## 不可变约束

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

## 验收要点

- 任务相关验证：`go test ./...`、`go vet ./...`、5 路集成 smoke、断线恢复测试，以及三条 harness 治理命令。
- 完整门禁：公共 API、schema 或生成客户端变化时运行全部 Sense 测试和契约/迁移检查。
- 人工 / 设备验收：必需；使用 T-001 白名单中至少一款设备验证 5 路流程，记录 MediaMTX 与探活证据。
- 构建产物：Sense 二进制/镜像路径、生成命令和哈希在实施任务中冻结；本任务开工前补齐。

## 边界（不改什么）

不开发 Brain、Bell、正式管理端、规则引擎、人脸识别、64/128 路容量实现；不修改 `_reference/`。

## 协作约束

- 责任 Agent：由 dispatcher 分配。
- 唯一写入者：同责任 Agent。
- 委派：默认不启用；需要只读调研时结论先回填本文。
- Gitea：已预建候选 Issue #3，但依赖 T-001/T-002 均 DONE 前不回填映射、不加 `status/todo`、不得领取；进入可领取队列时再记录 Issue、`context_ref`、claim 和工作分支。

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

## 执行记录

尚未领取，依赖未完成。