From 951508b8b45e66cafc963faf5079db7e5adf2662 Mon Sep 17 00:00:00 2001
From: QiuSW <105186638@qq.com>
Date: Sat, 8 Aug 2026 08:52:59 +0800
Subject: [PATCH] docs(task): define T-014 capacity baseline

---
 docs/06-tasks.md    |  4 +--
 docs/tasks/T-014.md | 81 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+), 2 deletions(-)
 create mode 100644 docs/tasks/T-014.md

diff --git a/docs/06-tasks.md b/docs/06-tasks.md
index fd1fb17..6cbcf3f 100644
--- a/docs/06-tasks.md
+++ b/docs/06-tasks.md
@@ -27,8 +27,8 @@
 - T-010：建立 Bell Area/`capture_policy` 只读投影、Sense 成像准入与设备操作审计 Outbox 原子写入；relay 传输协议留给后续任务。
 - T-011：按 T-008 契约实现认证 tenant 上下文、7 个设备/operation handler、PostgreSQL 幂等收据、ETag/HMAC cursor、最多 128 项批量操作和停用精确 path 收敛；公共控制 API 默认关闭且只在 PostgreSQL 路径启用。
 - T-012：以 PostgreSQL 数据库时钟租约和 fencing token 防止多实例重复调和；增加可证明的 Path 历史归属、默认只读孤儿报告、15 分钟二次确认、10% 不可绕过安全闸和低基数 `/metrics`。
-- WireGuard 边缘隧道与断网恢复。
-- 16 路批量开通、停用和容量基准。
+- T-013（后置，尚未创建）：WireGuard 边缘隧道与断网恢复；等待客户网络拓扑、地址规划和部署权限，不阻塞本地软件开发。
+- T-014：使用隔离 PostgreSQL、真实 Control API 和 16 个独立本地合成 publisher，完成批量开通/停用、局部故障恢复和资源观测；只形成实验室软件基线，不替代 T-007/T-013 或生产 SLA。
 
 ## M3：首个 16 路端到端 MVP
 
diff --git a/docs/tasks/T-014.md b/docs/tasks/T-014.md
new file mode 100644
index 0000000..2b59a3d
--- /dev/null
+++ b/docs/tasks/T-014.md
@@ -0,0 +1,81 @@
+---
+id: T-014
+title: 建立 Sense 本地 16 路批量收敛与容量基线
+phase: 2
+deps: [T-012]
+status: TODO
+created: 2026-08-08
+issue: null
+context_ref: null
+claim_branch: null
+work_branch: null
+write_paths:
+  - docs/tasks/T-014.md
+  - Sense/README.md
+  - Sense/scripts/t014-capacity.ps1
+  - docs/00-ai-start-here.md
+  - docs/03-tech-stack.md
+  - docs/04-architecture.md
+  - docs/06-tasks.md
+  - docs/current-state.md
+  - docs/research/sense-16-stream-capacity.md
+  - tests/test_sense_capacity_contract.py
+---
+
+## 问题 / 背景
+
+T-006 已证明一台准入实机与四条独立合成源可以完成五路实验室闭环，T-011/T-012 已实现 PostgreSQL Control API、最多 128 项批量期望态、多实例 fencing、孤儿安全闸和低基数指标；但 M2 的默认 16 路仍只有产品配额和单元测试，没有通过真实 HTTP 控制面完成 16 路创建、批量启停、MediaMTX 收敛、局部故障恢复和资源观测。项目当前没有客户网络环境，WireGuard T-013 暂缓，不能让该外部依赖阻塞本地软件容量基线。
+
+本任务建立可重复的 Windows 本地 16 路实验室基准。它验证当前机器、固定软件版本和低码率无人物合成负载下的 Sense/PostgreSQL/MediaMTX 控制面与媒体拉流能力，不代表 16 台真实摄像头、客户网络、存储、AI/GPU 或生产 SLA。
+
+## 关联需求与交互（如适用）
+
+- 用户故事：US-001、US-002、US-008、US-009；验证默认 16 路站点的批量接入与运维收敛基础。
+- 交互清单：IX-003、IX-004、IX-015、IX-016 的后端容量证据；不修改已确认 HTML 原型。
+- 相关页面 / 路由：复用冻结的 7 个 `/api/v1` Control API endpoint、`/metrics`、MediaMTX v3 API；不增加公共接口。
+
+## 方案
+
+1. 新增 `Sense/scripts/t014-capacity.ps1` 一键基准：校验冻结的 PostgreSQL 17.10、MediaMTX v1.19.3、FFmpeg 与 Go，使用随机回环端口和系统临时目录启动隔离 PostgreSQL、源 MediaMTX、生产 MediaMTX 与 Sense。migration 只读取并重放现有 `001`～`011`，不修改或连接本机已有 `D:\pgsql17\data`/5432。
+2. 先用 FFmpeg 生成 640×360、10 fps、H.264、无音频、无人物的短循环媒体夹具，再启动 16 个独立 FFmpeg `-c copy` RTSP publisher，每路有独立进程与 Path，可单独停止/恢复。预编码发布避免把 16 路软件编码开销计入 Sense/MediaMTX 基线；不把同一 publisher fan-out 冒充独立源。
+3. 在临时 PostgreSQL 中建立固定实验室 Tenant/Site/Area，Site 配额精确为 16；运行时生成 Control API opaque token、SHA-256 注册表和 cursor key，文件只存在于临时目录。通过真实 HTTP API 创建 16 个 disabled 视频设备，并验证第 17 个同站点设备稳定返回 `quota_exceeded` 且不写入台账。
+4. 使用真实 `devices:batchDesiredState` 和每台设备最新 ETag 执行 16 路批量启用、批量停用、再次启用；每次要求 operation 的 16 个结果全部成功。分别验证生产 MediaMTX 配置/运行 Path 为 16、0、16，设备最终状态与 generation/observed generation 收敛，`unconverged=0`。
+5. 在再次启用后同时停止固定四个 publisher，要求能观察到局部离线/未收敛且其余路径继续在线；恢复四个独立进程后自动回到 16 路在线和 `unconverged=0`。不得通过改数据库、人工编辑 MediaMTX 配置或重建进程集合掩盖失败。
+6. 正式稳定观察默认 30 分钟、每 10 秒采样。记录 Sense 与生产 MediaMTX 的归一化 CPU、working set、private bytes、handle 峰值，PostgreSQL连接峰值，以及 MediaMTX aggregate inbound bytes/吞吐、在线 Path、Sense 低基数指标和未收敛数。功能正确性有硬门禁；机器相关资源值只记录，不设置伪通用阈值。
+7. 脚本输出不含 token、DSN、端口清单、Path/source URI 或客户信息的 JSON 摘要；支持显式输出到仓库外路径。失败不输出成功结论，finally 停止全部叶子进程、停止临时 PostgreSQL并校验清理路径；可选调试短窗口必须标记 `formal_eligible=false`，不得作为正式验收。
+8. 将正式运行的硬件/软件版本、命令、功能时间、观察样本、资源统计、失败记录、限制和结论写入 `docs/research/sense-16-stream-capacity.md`，同步 README、架构、路线图和当前状态。增加静态契约测试，锁定 16/17/128/129 语义、无秘密输出、临时目录防护、真实批量 API、独立 publisher 和正式窗口规则。
+
+## 不可变约束
+
+- 阈值 / 数值边界：正式源数精确为 16；Site 默认配额 16、允许范围 1～128，17 路在该 Site 必须拒绝，129 仍非法；批量 API 上限保持 128。正式观察不少于 30 分钟、采样周期 10 秒；局部故障固定 4 路且不得影响其余 12 路。短窗口只能 smoke。
+- 判定式 / 状态转换：16 个设备先 disabled 创建，随后 `16 enabled → 16 disabled → 16 enabled`；每轮批量结果必须全部成功。启用完成必须配置 Path=16、运行在线 Path=16、`unconverged=0`；停用完成必须配置 Path=0、设备 offline 且各自 observed generation 追平。四路故障恢复后必须再次满足 16 路在线和 `unconverged=0`。
+- 安全边界：只绑定随机回环端口；运行时 token/cursor key/DSN/临时路径不进入 Git、普通日志或结果摘要。脚本不得读取 `ip_camera.env`，不得访问客户网络或现有 PostgreSQL data/service；递归清理前必须验证目标位于系统临时目录且名称含 T-014 随机前缀。
+- 既有契约：不修改 Control OpenAPI v1、审计 v1/v2、MediaMTX 生成代码或数据库 migration；不把 16 写入业务数组/协议硬上限。T-001/T-006 的实机结论、T-007 真实五上游门禁与未来 T-013 WireGuard 均保持独立。
+
+## 验收要点
+
+- 任务相关验证：先以短窗口运行脚本 smoke，再执行默认不少于 30 分钟的正式 16 路基准；验证 16 个独立 publisher、17 路配额拒绝、三轮批量状态、16/0/16 Path、四路故障隔离/恢复、最终 `unconverged=0` 和资源摘要。`python -m unittest tests.test_sense_capacity_contract` 锁定脚本安全/语义。
+- 完整门禁：`./init.ps1`、三条 Python 治理命令、`go -C Sense test ./...`、`go -C Sense vet ./...`、`go -C Sense build ./...`、`./scripts/test_postgres.ps1 -PgRoot D:\pgsql17` 和 `git diff --check` 全部通过；本任务不修改 Go 业务代码，但仍回归全部 Sense 包和 PostgreSQL v5。
+- 人工 / 设备验收：不需要摄像头、GPU、客户网络或客户数据。任务所有者核对 30 分钟原始 JSON 摘要、进程独立性和报告；真实摄像头/网络验收仍由 T-007/T-013 完成。
+- 构建产物：`Sense/scripts/t014-capacity.ps1`、`docs/research/sense-16-stream-capacity.md`、静态契约测试与同步文档；临时二进制、媒体、数据库、凭据和日志运行后删除，不提交。
+
+## 边界（不改什么）
+
+不实现或验证 WireGuard/T-013、客户网络、真实 16 摄像头、录像、下游 reader、AI 解码/推理、GPU、Bell UI/服务、Outbox relay、告警规则、跨 MediaMTX 分片或 64/128 路容量；不把本机资源样本转换为最低硬件规格或 SLA。本任务不解除 T-007，失败样本不得从报告中删除。
+
+## 协作约束
+
+- 责任 Agent：由 dispatcher 分配。
+- 唯一写入者：同责任 Agent。
+- 委派：默认不启用。
+- Gitea：任务规格先进入默认分支，再创建唯一 Issue 并回填编号；领取时记录 `context_ref`、claim / 工作分支和全部允许写路径。
+
+任何新增写路径先检查与其他活跃任务是否重叠；同一时刻只有一个 Agent 修改本任务的 `write_paths`。T-007 虽为 waiting，但写路径包含 `Sense/`；T-014 活跃期间不得恢复 T-007。
+
+## 执行记录
+
+### 2026-08-08 任务定义
+
+- 项目负责人确认客户尚未提供网络环境，WireGuard T-013 后置；本任务先建立不依赖客户网络的本地 16 路软件基线。
+- 选择 PostgreSQL v5 + 真实 Control API，而不是沿用 SQLite 直接播种，确保实际覆盖 M2 的认证、配额、ETag、批量 operation、调和与 MediaMTX 路径。
+- 选择 16 个独立、预编码 `-c copy` 合成 publisher 作为正式可重复负载；T-006 已单独覆盖准入实机，本任务不混入公网摄像头波动，也不把合成结果表述为真实 16 机或生产 SLA。