Merge pull request '[T-008] 冻结 Sense 设备管理 API 与 Bell 配额只读投影契约' (#29) from agent/codex/T-008 into main

docs/04-architecture.md

@@ -45,7 +45,7 @@ Sense ── 视频流/触发信号 ──> Brain
 
 主流程：
 
-1. Bell 持有站点、Area、配额与 `capture_policy`；Sense 在新增/启用设备时通过版本化内部 API 或只读投影校验，并记录所用投影版本。
+1. Bell 持有站点、Area、配额与 `capture_policy`；首期在同一 PostgreSQL 实例内发布版本化只读视图 `bell.site_quota_v1`，Sense 在新增/启用设备的同一写路径校验并记录所用 `source_version`。未来分库必须发布新版本契约，不能静默改变 v1 语义。
 2. Sense 维护设备期望态，通过 MediaMTX API 和对账器收敛实际态。
 3. Brain 消费视频与触发信号，产生符合 v0.1 的事件。
 4. Bell 做 schema 与代码级断言，生成平台 ULID，保存不可变事件。
@@ -63,11 +63,11 @@ Sense ── 视频流/触发信号 ──> Brain
 4. 平台事件 ULID 由 Bell 生成；Brain 只填 `source_event_id`。
 5. 一个 PostgreSQL 实例，`sense`/`bell` schema 分离；Brain 无业务 schema。
 6. 16/128 都不是单机保证；媒体与推理按独立分片横向扩展。
-7. Bell 拥有 `site.max_video_channels`，Sense 在设备写路径执行；不跨 schema 直接写。
+7. Bell 拥有 `site.max_video_channels` 并拥有 `bell.site_quota_v1`；Sense 角色只获得视图 `SELECT`，在设备写路径执行准入，不能写 Bell schema 或读取 Bell 源表。
 8. 事件片段写入客户侧 MinIO/S3，常态录像留在客户 NVR；元数据/审计、人脸和训练样本使用独立生命周期。
 9. 投递状态机只依赖 Bell provider 接口，不直接依赖某家短信或语音 SDK；生产前至少两条独立路径并能故障切换。
 10. 设备领域模型使用 `modality + capabilities`，页面不以摄像头作为唯一根实体；未实现协议适配器明确为 `adapter_not_ready`，不得用模拟遥测伪装交付。
-11. Tenant/Site/Area/RBAC、配额、`capture_policy` 与全局审计属于 Bell；Sense 只读消费版本化投影并在设备写路径执行，投影不可用时只阻断相关新变更，不静默切断已有链路。
+11. Tenant/Site/Area/RBAC、配额、`capture_policy` 与全局审计属于 Bell；Sense Control API v1 只管理 Device 期望态与收敛查询，Sense 只读消费版本化投影并在设备写路径执行，投影不可用时只阻断相关新变更，不静默切断已有链路。
 12. Sense 的设备操作审计先写本地持久化 outbox，再由幂等 relay 异步送入 Bell 全局审计；不得使用“先执行高风险操作、再尽力入队”的顺序。具体字段、签名、重放与留存契约必须由独立 API/契约任务冻结后实现。
 
 ## 6. 容量架构
@@ -84,7 +84,7 @@ Sense ── 视频流/触发信号 ──> Brain
 - PostgreSQL 是期望态真相源；MediaMTX、推理 worker 和对象存储是可对账的实际态。
 - 对账器水平触发、幂等、指数退避、限制并发；部分失败不做跨系统回滚，只持续收敛。
 - 孤儿删除必须有 10% 安全闸和人工可观察指标。
-- 配额读取失败只阻止新增/启用，不中断已有流。
+- `bell.site_quota_v1` 行缺失、数值越界、版本回退或读取失败只阻止视频设备新增/启用，不中断已有流；降低配额导致超限时不自动停用，后续准入返回稳定错误并产生运维信号。
 - Area 策略投影读取失败只阻止相关设备新增/启用；已有设备保持原状态并产生运维告警。策略变更与已有成像设备冲突时由 Bell 管理端显式处置。
 - 高风险设备操作在本地事务内同时写期望态与审计 outbox；异步 relay 可重试、幂等投递到 Bell。T-004 只验证交互归属，不定义或实现接口契约。
 - Brain 投递失败落本地队列重试，不阻塞实时推理主链路。
@@ -94,7 +94,8 @@ Sense ── 视频流/触发信号 ──> Brain
 
 ## 8. 数据与契约
 
-- Bell 核心实体：Tenant → Site → Area（含 `capture_policy`）以及 Role/Binding/Quota/Audit；Sense 核心实体：Device（含 `modality + capabilities`）→ StreamBinding/Zone，以及带 `source_version`/`synced_at` 的 SiteQuota/AreaPolicyProjection。两个 schema 以稳定逻辑 ID 关联，不跨 schema 写入。
+- Bell 核心实体：Tenant → Site → Area（含 `capture_policy`）以及 Role/Binding/Quota/Audit；Sense 核心实体：Device（含 `modality + capabilities`）→ StreamBinding/Zone，以及带 `source_version`/`synced_at` 的 SiteQuota/AreaPolicyProjection。两个 schema 以稳定逻辑 ID 关联，不跨 schema 写入；配额 v1 的跨 schema 列签名限定为 `tenant_id/site_id/max_video_channels/source_version/source_updated_at`。
+- Sense Control API v1 使用站点作用域路径、认证上下文 tenant、cursor 分页、幂等键与 ETag；敏感连接引用只写不读。正式签名和兼容规则以 [`contracts/`](contracts/) 为准，当前契约冻结不等于 handler 或 PostgreSQL migration 已实现。
 - 业务实体：Rule → Event → Alert → DeliveryAttempt/Ack；Event 与 Alert 不合并。
 - Bell 通知域分为三个聚合：Contact/Team 保存身份、成员关系和已验证通道；OnCallSchedule/ScheduleVersion/ShiftException 保存时区、轮换与例外；EscalationPolicy/Step 通过 `person / team / on_call_schedule` 类型化 `target_ref` 引用目标。三者共享逻辑 ID，不复制手机号、班次或轮换字段。
 - 每个 DeliveryAttempt 创建时解析当时生效的排班版本，并保存实际收件人、通道、`schedule_version` 和解析时间快照；之后联系人或排班修改不得回写既有投递事实。

docs/06-tasks.md

@@ -22,8 +22,9 @@
 
 出口：10 个站点试点，至少一个站点完成 16 路开通/停用；`unconverged = 0` 稳定。
 
+- T-008：冻结 Sense Control API v1 与 Bell `site_quota_v1` 只读投影契约；只建立接口和测试门禁，不等于 handler、Bell 表或 migration 已实现。
+- 按 T-008 契约实现认证 tenant 上下文、设备管理 handler、PostgreSQL repository、Bell 配额源表/migration 与只读投影。
 - 对账器幂等/退避/并发/10% 安全闸。
-- Bell 站点配额投影到 Sense 的版本化读取契约。
 - WireGuard 边缘隧道与断网恢复。
 - 16 路批量开通、停用和容量基准。
 

docs/api.md

@@ -1,6 +1,6 @@
 # API 与契约
 
-> 事件契约 v0.1 已冻结；其他 API 仍在设计阶段。不得把本文的“待定”自行具体化为公共契约。
+> Brain → Bell 事件契约 v0.1、Sense Control API v1 与 Bell 站点配额只读投影 v1 已冻结；其他 API 仍在设计阶段。不得把本文的“待定”自行具体化为公共契约。
 
 ## 1. 已冻结：Brain → Bell 事件契约
 
@@ -17,17 +17,35 @@
 - 证据文件名只含事件 ID 与日期目录，不含 IP、端口、凭据或客户名。
 - `sensors` 中恰有一个 primary，且其 `device_id` 与顶层一致。
 
-## 2. 待冻结的内部接口
+## 2. 跨系统接口状态
 
 | 调用方 → 提供方 | 用途 | 当前约束 | 状态 |
 | --- | --- | --- | --- |
-| Sense → Bell | 读取站点视频配额 | 版本化；默认 16、最大 128；失败时拒绝新增/启用但不影响已有流 | 待 M2 设计 |
+| Sense → Bell | 读取站点视频配额 | 同一 PostgreSQL 实例内只读 `bell.site_quota_v1`；默认 16、最大 128；失败时拒绝新增/启用但不影响已有流 | T-008 已冻结 |
 | Bell → Sense | 请求事件证据/pre-roll 切片 | 幂等、按租户授权、异步结果、不得暴露原始凭据 | 待 M3 设计 |
 | Bell → Brain | outcome/误报反馈 | 原事件不可变；反馈可重试、去重、审计 | 待 M3 设计 |
 | Sense → Brain | 流绑定与设备型触发 | 分片可路由，触发入口与流控制解耦 | 待 M2/M3 设计 |
 | Worker → 控制面 | 注册、心跳、容量 | `max_sources` 来自 profile/压测，不固定为 16 | 待 M3 设计 |
 
-## 3. 待冻结的 Bell 公共 API
+冻结签名和失败语义见 [`contracts/README.md`](contracts/README.md) 与 [`contracts/site-quota-v1.sql`](contracts/site-quota-v1.sql)。Bell 拥有源数据和视图，Sense 数据库角色只有 `SELECT`；未来分库必须发布新版本，不能在 v1 下把本地视图静默替换为网络调用。
+
+## 3. 已冻结：Sense Control API v1
+
+- OpenAPI：[`contracts/sense-control-v1.openapi.json`](contracts/sense-control-v1.openapi.json)
+- 语义、资源所有权、幂等、并发与兼容规则：[`contracts/README.md`](contracts/README.md)
+- 范围：设备分页查询、创建、读取、修改、单项启停、最多 128 项的批量启停和批量操作查询。
+
+关键规则：
+
+- 所有业务路径使用 `/api/v1` 和 Bearer 认证；tenant 只来自认证上下文，跨租户访问与不存在统一为 `404 not_found`。
+- Site、Area、RBAC、配额和全局审计仍由 Bell 持有；Sense 只管理 Device 期望态和收敛状态，不提供这些 Bell 资源的 CRUD。
+- 列表使用稳定顺序和不透明 cursor，默认 50、最大 100；创建与批量写要求 `Idempotency-Key`，资源修改与单项期望态写要求 `If-Match`。
+- `endpoint_ref`、`credential_ref`、`profile_token` 只写不读；设备 ID 由服务端生成。普通响应和错误不得包含凭据、完整流 URI、token 或 MediaMTX 内部配置。
+- v1 不提供删除设备；停用设备保留历史。写入受理只表示期望态已持久化，不能表示实际态已收敛。
+
+T-008 只冻结契约和仓库门禁，尚未实现 Sense HTTP handler、认证中间件、Bell 表或 PostgreSQL migration。
+
+## 4. 待冻结的 Bell 公共 API
 
 资源范围预计包括：租户、站点、设备只读投影、规则、事件、预警、ack、处置、误报反馈、审计和报表。设计时必须满足：
 
@@ -38,11 +56,11 @@
 - 错误体包含稳定错误码、可读消息和 trace ID，不返回内部堆栈或凭据。
 - 人脸功能未授权时表现为能力不存在，而非仅按钮置灰。
 
-## 4. MediaMTX 接口边界
+## 5. MediaMTX 接口边界
 
 Sense 使用 MediaMTX 官方 OpenAPI 生成客户端并加薄封装。业务代码不得散落硬编码 path API；生成代码不可手改。MediaMTX path 不是租户/站点/设备的业务真相源。
 
-### 4.1 T-003 已实现的内部适配契约
+### 5.1 T-003 已实现的内部适配契约
 
 以下是 Sense 内部 Go port，不是 Bell 或第三方可依赖的公共 HTTP API：
 
@@ -54,22 +72,22 @@ Sense 使用 MediaMTX 官方 OpenAPI 生成客户端并加薄封装。业务代
 
 MediaMTX 薄封装调用同版官方 OpenAPI 的 `/v3/config/paths/get|add|patch|delete/{name}` 与 `/v3/paths/get/{name}`。生成源、版本和 SHA-256 见 `docs/03-tech-stack.md`；业务包不得直接 import 生成包。
 
-### 4.2 设备台账语义
+### 5.2 设备台账语义
 
 - 设备类型由 `modality` 表达物理类别，由多值 `capabilities` 表达视频采集、音频、空间规则或遥测能力，避免把“摄像头”固化为唯一设备模型。
 - 视频配额只统计 `desired_state=enabled` 且具有 `video_capture` capability 的设备；站点默认 16、可配置 1～128。禁用设备和非视频传感器不占视频路数。
 - SQLite 表使用 `sense_` 前缀对应未来 PostgreSQL `sense` schema：`sense_sites`、`sense_devices`、`sense_device_capabilities`、`sense_reconcile_state`。标识、唯一性、状态与时间字段语义保持一致；本地表名前缀不是跨系统公共契约。
 - 摄像头密码不进入设备普通字段。`credential_ref` 只保存外部密钥引用；ONVIF 返回的 stream URI 只在内存中传给 MediaMTX，不写入设备台账或日志。
 
-### 4.3 Sense 进程 HTTP 面
+### 5.3 Sense 进程 HTTP 面
 
-T-003 只提供运维探针：`GET /healthz` 表示进程存活，`GET /readyz` 表示配置、SQLite 打开及 migration 已完成。两者返回 JSON，均不等价于摄像头、MediaMTX path 或 M1 里程碑健康。设备管理、认证、分页、幂等键与并发控制尚未冻结，因此本任务不暴露 `/api/v1/devices` 等临时接口。
+T-003 只实现了运维探针：`GET /healthz` 表示进程存活，`GET /readyz` 表示配置、SQLite 打开及 migration 已完成。两者返回 JSON，均不等价于摄像头、MediaMTX path 或 M1 里程碑健康。T-008 已冻结站点作用域的 `/api/v1/sites/{site_id}/devices` 等设备管理契约，但尚未实现对应 handler；当前可运行进程仍只暴露探针，后续实现不得发布 `/api/v1/devices` 等无站点边界的临时接口。
 
-## 5. 变更流程
+## 6. 变更流程
 
 1. 在对应任务文件写清调用方、提供方、数据所有者、失败语义、幂等与兼容策略。
 2. 更新本文和 schema/OpenAPI。
 3. 同步生产者、消费者、契约测试和示例。
 4. 记录迁移、回滚与版本废弃策略。
 
-事件 v0.1 的破坏性变化必须发布新版本，不能原地修改已被 M3 生产者/消费者使用的契约。
+事件 v0.1、Sense Control API v1 或站点配额投影 v1 的破坏性变化必须发布新版本，不能原地修改已被生产者/消费者使用的契约。

docs/contracts/README.md

@@ -0,0 +1,69 @@
+# Sense 控制面与站点配额契约 v1
+
+> 冻结日期：2026-08-07。契约版本：`1.0.0`。Sense 是设备期望态的提供方；Bell 是 Tenant、Site、Area、RBAC 与配额的所有者。本文冻结接口，不表示 HTTP handler、Bell 表或 PostgreSQL migration 已实现。
+
+## 契约文件
+
+| 文件 | 生产者 / 所有者 | 消费者 | 用途 |
+| --- | --- | --- | --- |
+| [`sense-control-v1.openapi.json`](sense-control-v1.openapi.json) | Sense | Bell 管理面、受控集成方 | 设备查询、创建、修改、启停与批量操作 |
+| [`site-quota-v1.sql`](site-quota-v1.sql) | Bell | Sense | 单 PostgreSQL 实例内的站点视频配额只读投影 |
+
+OpenAPI 的 `/api/v1` 路径是公共控制面边界；`/healthz`、`/readyz` 仍是非业务运维探针。v1 不提供设备删除：停用设备使用期望态接口，保留设备、操作和审计历史。Site、Area、配额、RBAC 和审计聚合不由 Sense 提供 CRUD。
+
+## HTTP 资源与操作
+
+| 操作 | 路径 | 关键约束 |
+| --- | --- | --- |
+| 列出 / 创建设备 | `GET/POST /api/v1/sites/{site_id}/devices` | 列表使用不透明 cursor，默认 50、最大 100；创建要求 `Idempotency-Key`，设备 ID 由服务端生成 |
+| 读取 / 修改设备 | `GET/PATCH /api/v1/sites/{site_id}/devices/{device_id}` | 修改要求 `If-Match`，版本不匹配返回 `412 etag_mismatch` |
+| 修改期望态 | `PUT /api/v1/sites/{site_id}/devices/{device_id}/desired-state` | 要求 `If-Match`；受理不表示实际态已经收敛 |
+| 批量修改期望态 | `POST /api/v1/sites/{site_id}/devices:batchDesiredState` | 要求 `Idempotency-Key`，最多 128 项，异步返回逐项结果 |
+| 查询批量操作 | `GET /api/v1/operations/{operation_id}` | 只返回当前租户和站点可见的操作 |
+
+列表按 `created_at ASC, id ASC` 稳定排序，cursor 是服务端生成的不透明位置标记。客户端不得解析或拼接 cursor；服务端可以在兼容范围内改变编码。批量不是跨设备全有或全无事务：每项独立接受或拒绝，成功项继续收敛，失败项带稳定错误码。请求内重复 `device_id` 视为对应项 `invalid_request`，不得用“最后一项覆盖”。重试失败项应使用新幂等键；原样重放整个请求必须返回原收据。
+
+## 身份、租户与敏感信息
+
+- 所有 `/api/v1` 操作都需要 Bearer 认证；具体 token 格式由认证任务冻结。`tenant_id` 只从认证上下文取得，body、query 和 path 均不能自报 tenant。
+- 跨租户访问与资源不存在都返回 `404 not_found`，不得用状态码、消息或耗时泄露资源是否存在。授权范围不足但不涉及资源枚举时返回 `403 forbidden`。
+- `endpoint_ref`、`credential_ref` 和 `profile_token` 是 write-only 输入。不允许 userinfo 形式的完整 RTSP URI；响应、错误、日志与示例不得包含这些引用、密码、token、完整连接串或 MediaMTX 内部配置。
+- 创建设备显式提交 `modality + capabilities`；`video` 模态必须包含 `video_capture`，任何请求了 `video_capture` 的设备都必须同时提供 endpoint 与 credential 引用。服务端仍须由适配器验证能力，不能把客户端声明当作探测成功。
+- `ETag` 表示设备资源版本；`If-Match` 缺失返回 `428 precondition_required`，过期版本返回 `412 etag_mismatch`。相同期望态重复提交不增加 generation，但每次受理仍可产生审计记录。
+
+`Idempotency-Key` 的作用域是“认证主体 + tenant + site + operation + key”，服务端至少保存 24 小时。同作用域、同请求体重放返回首次状态码和响应；同 key 不同请求体返回 `409 idempotency_conflict`。幂等收据不等价于实际态完成。
+
+## 配额投影与准入
+
+Bell migration 最终创建 `bell.site_quota_v1`，列顺序和含义固定如下：
+
+| 列 | 含义 |
+| --- | --- |
+| `tenant_id`、`site_id` | 与两个 schema 共享的稳定逻辑 ID |
+| `max_video_channels` | 默认 16，有效范围 1～128 |
+| `source_version` | 站点投影每次变更后单调递增的版本 |
+| `source_updated_at` | Bell 源记录的更新时间 |
+
+视图由 `bell_app` 拥有；`sense_app` 只有 Bell schema 的 `USAGE` 和该视图的 `SELECT`，没有 `INSERT`、`UPDATE`、`DELETE` 或 Bell 源表权限。Sense 不得通过任何旁路写 Bell schema。首期使用同一 PostgreSQL 实例及 `sense`/`bell` schema；如果未来分库，必须发布新版本的网络契约，不能在 v1 下静默改变一致性和失败语义。
+
+配额只统计 `desired_state=enabled` 且 capabilities 含 `video_capture` 的设备。创建已启用视频设备或把视频设备启用时，Sense 必须在同一设备写路径读取并记录所用 `source_version`，同时验证 Area 策略投影。降低配额不会自动停用已有设备；若当前占用已超限，后续创建/启用返回 `409 quota_exceeded`。配额行缺失、越界、版本回退或投影不可读时返回 `503 quota_projection_unavailable`，只阻止相关创建/启用，读取、非准入属性修改和停用仍允许，已有流保持运行。
+
+Area/capture policy 的投影形态不在 T-008 中冻结；Sense v1 仍保留 `area_policy_unavailable` 与 `area_policy_denied` 稳定错误语义，后续契约不得放宽同写路径校验要求。
+
+## 兼容与废弃
+
+- v1 可增加不改变已有语义的可选响应字段和新错误细节；客户端必须忽略未知响应字段。
+- 删除/重命名字段、收紧已接受输入、改变状态码/幂等作用域/配额计数或把只读视图改为远程调用，均属于破坏性变化，必须发布新版本。
+- 废弃版本应先在 OpenAPI 标记并公告迁移窗口；服务端在所有已声明消费者完成迁移前继续提供旧版本。
+- OpenAPI 中的稳定错误码用于程序判断，`message` 只用于人读，不得依赖其字面内容。
+
+## 验证
+
+从仓库根目录执行：
+
+```powershell
+python -m json.tool docs/contracts/sense-control-v1.openapi.json | Out-Null
+python -m unittest discover -s tests -p "test_sense_control_contract.py"
+```
+
+测试校验本仓库依赖的 OpenAPI 结构与安全不变量，并不替代后续实现任务对完整 OpenAPI 标准验证器、HTTP handler 和 PostgreSQL migration 的验证。

docs/contracts/sense-control-v1.openapi.json

@@ -0,0 +1,691 @@
+{
+  "openapi": "3.1.0",
+  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
+  "info": {
+    "title": "YoVision Sense Control API",
+    "version": "1.0.0",
+    "description": "受控的设备期望态与收敛查询契约。Tenant 只从认证上下文确定；Site、Area、RBAC 和配额真相仍由 Bell 持有。"
+  },
+  "servers": [
+    {
+      "url": "/",
+      "description": "由部署入口提供 scheme、host 和认证终止"
+    }
+  ],
+  "security": [
+    {
+      "bearerAuth": []
+    }
+  ],
+  "tags": [
+    {
+      "name": "Devices",
+      "description": "设备台账、期望态和收敛状态"
+    },
+    {
+      "name": "Operations",
+      "description": "批量写入的逐项结果"
+    }
+  ],
+  "paths": {
+    "/api/v1/sites/{site_id}/devices": {
+      "get": {
+        "tags": ["Devices"],
+        "operationId": "listDevices",
+        "summary": "分页查询当前认证租户下的站点设备",
+        "parameters": [
+          {"$ref": "#/components/parameters/SiteID"},
+          {"$ref": "#/components/parameters/Cursor"},
+          {"$ref": "#/components/parameters/Limit"},
+          {"$ref": "#/components/parameters/ModalityFilter"},
+          {"$ref": "#/components/parameters/CapabilityFilter"},
+          {"$ref": "#/components/parameters/DesiredStateFilter"},
+          {"$ref": "#/components/parameters/ActualStateFilter"}
+        ],
+        "responses": {
+          "200": {
+            "description": "按 created_at、id 稳定升序返回的一页设备",
+            "headers": {"X-Trace-ID": {"$ref": "#/components/headers/TraceID"}},
+            "content": {
+              "application/json": {"schema": {"$ref": "#/components/schemas/DevicePage"}}
+            }
+          },
+          "401": {"$ref": "#/components/responses/ErrorResponse"},
+          "404": {"$ref": "#/components/responses/ErrorResponse"},
+          "500": {"$ref": "#/components/responses/ErrorResponse"}
+        }
+      },
+      "post": {
+        "tags": ["Devices"],
+        "operationId": "createDevice",
+        "summary": "创建待探测设备",
+        "parameters": [
+          {"$ref": "#/components/parameters/SiteID"},
+          {"$ref": "#/components/parameters/IdempotencyKey"}
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {"schema": {"$ref": "#/components/schemas/DeviceCreate"}}
+          }
+        },
+        "responses": {
+          "201": {"$ref": "#/components/responses/CreatedDevice"},
+          "400": {"$ref": "#/components/responses/ErrorResponse"},
+          "401": {"$ref": "#/components/responses/ErrorResponse"},
+          "404": {"$ref": "#/components/responses/ErrorResponse"},
+          "409": {"$ref": "#/components/responses/ErrorResponse"},
+          "422": {"$ref": "#/components/responses/ErrorResponse"},
+          "503": {"$ref": "#/components/responses/ErrorResponse"}
+        }
+      }
+    },
+    "/api/v1/sites/{site_id}/devices/{device_id}": {
+      "get": {
+        "tags": ["Devices"],
+        "operationId": "getDevice",
+        "summary": "读取设备期望态、实际态和收敛进度",
+        "parameters": [
+          {"$ref": "#/components/parameters/SiteID"},
+          {"$ref": "#/components/parameters/DeviceID"}
+        ],
+        "responses": {
+          "200": {"$ref": "#/components/responses/CurrentDevice"},
+          "401": {"$ref": "#/components/responses/ErrorResponse"},
+          "404": {"$ref": "#/components/responses/ErrorResponse"},
+          "500": {"$ref": "#/components/responses/ErrorResponse"}
+        }
+      },
+      "patch": {
+        "tags": ["Devices"],
+        "operationId": "updateDevice",
+        "summary": "按 ETag 修改设备可编辑配置",
+        "parameters": [
+          {"$ref": "#/components/parameters/SiteID"},
+          {"$ref": "#/components/parameters/DeviceID"},
+          {"$ref": "#/components/parameters/IfMatch"}
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/merge-patch+json": {"schema": {"$ref": "#/components/schemas/DevicePatch"}}
+          }
+        },
+        "responses": {
+          "202": {"$ref": "#/components/responses/AcceptedMutation"},
+          "400": {"$ref": "#/components/responses/ErrorResponse"},
+          "401": {"$ref": "#/components/responses/ErrorResponse"},
+          "404": {"$ref": "#/components/responses/ErrorResponse"},
+          "409": {"$ref": "#/components/responses/ErrorResponse"},
+          "412": {"$ref": "#/components/responses/ErrorResponse"},
+          "422": {"$ref": "#/components/responses/ErrorResponse"},
+          "428": {"$ref": "#/components/responses/ErrorResponse"},
+          "503": {"$ref": "#/components/responses/ErrorResponse"}
+        }
+      }
+    },
+    "/api/v1/sites/{site_id}/devices/{device_id}/desired-state": {
+      "put": {
+        "tags": ["Devices"],
+        "operationId": "setDeviceDesiredState",
+        "summary": "启用或停用设备接入期望态",
+        "description": "成功只表示期望态已持久化并进入对账，不表示实际态已经收敛。重复提交不会重复改变 generation，但每次请求均可产生审计事实。",
+        "parameters": [
+          {"$ref": "#/components/parameters/SiteID"},
+          {"$ref": "#/components/parameters/DeviceID"},
+          {"$ref": "#/components/parameters/IfMatch"}
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {"schema": {"$ref": "#/components/schemas/DesiredStateChange"}}
+          }
+        },
+        "responses": {
+          "202": {"$ref": "#/components/responses/AcceptedMutation"},
+          "400": {"$ref": "#/components/responses/ErrorResponse"},
+          "401": {"$ref": "#/components/responses/ErrorResponse"},
+          "404": {"$ref": "#/components/responses/ErrorResponse"},
+          "412": {"$ref": "#/components/responses/ErrorResponse"},
+          "422": {"$ref": "#/components/responses/ErrorResponse"},
+          "428": {"$ref": "#/components/responses/ErrorResponse"},
+          "503": {"$ref": "#/components/responses/ErrorResponse"}
+        }
+      }
+    },
+    "/api/v1/sites/{site_id}/devices:batchDesiredState": {
+      "post": {
+        "tags": ["Devices"],
+        "operationId": "batchSetDeviceDesiredState",
+        "summary": "批量提交最多 128 个设备期望态变更",
+        "parameters": [
+          {"$ref": "#/components/parameters/SiteID"},
+          {"$ref": "#/components/parameters/IdempotencyKey"}
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {"schema": {"$ref": "#/components/schemas/BatchDesiredStateRequest"}}
+          }
+        },
+        "responses": {
+          "202": {
+            "description": "请求已接收；响应包含已知的逐项接受/拒绝结果，后续状态从 operation 读取",
+            "headers": {
+              "Location": {"$ref": "#/components/headers/OperationLocation"},
+              "X-Trace-ID": {"$ref": "#/components/headers/TraceID"}
+            },
+            "content": {
+              "application/json": {"schema": {"$ref": "#/components/schemas/BatchOperation"}}
+            }
+          },
+          "400": {"$ref": "#/components/responses/ErrorResponse"},
+          "401": {"$ref": "#/components/responses/ErrorResponse"},
+          "404": {"$ref": "#/components/responses/ErrorResponse"},
+          "409": {"$ref": "#/components/responses/ErrorResponse"},
+          "422": {"$ref": "#/components/responses/ErrorResponse"},
+          "503": {"$ref": "#/components/responses/ErrorResponse"}
+        }
+      }
+    },
+    "/api/v1/operations/{operation_id}": {
+      "get": {
+        "tags": ["Operations"],
+        "operationId": "getOperation",
+        "summary": "查询批量写入和逐项结果",
+        "parameters": [
+          {"$ref": "#/components/parameters/OperationID"}
+        ],
+        "responses": {
+          "200": {
+            "description": "批量操作状态",
+            "headers": {"X-Trace-ID": {"$ref": "#/components/headers/TraceID"}},
+            "content": {
+              "application/json": {"schema": {"$ref": "#/components/schemas/BatchOperation"}}
+            }
+          },
+          "401": {"$ref": "#/components/responses/ErrorResponse"},
+          "404": {"$ref": "#/components/responses/ErrorResponse"},
+          "500": {"$ref": "#/components/responses/ErrorResponse"}
+        }
+      }
+    }
+  },
+  "components": {
+    "securitySchemes": {
+      "bearerAuth": {
+        "type": "http",
+        "scheme": "bearer",
+        "bearerFormat": "opaque",
+        "description": "认证实现与 claim 格式不属于 v1 契约；服务端必须从已验证主体确定 tenant 与权限。"
+      }
+    },
+    "parameters": {
+      "SiteID": {
+        "name": "site_id",
+        "in": "path",
+        "required": true,
+        "schema": {"$ref": "#/components/schemas/LogicalID"},
+        "description": "当前认证租户中的稳定站点 ID"
+      },
+      "DeviceID": {
+        "name": "device_id",
+        "in": "path",
+        "required": true,
+        "schema": {"$ref": "#/components/schemas/LogicalID"}
+      },
+      "OperationID": {
+        "name": "operation_id",
+        "in": "path",
+        "required": true,
+        "schema": {"type": "string", "pattern": "^op_[0-9A-HJKMNP-TV-Z]{26}$"}
+      },
+      "Cursor": {
+        "name": "cursor",
+        "in": "query",
+        "required": false,
+        "schema": {"type": "string", "minLength": 16, "maxLength": 512},
+        "description": "不透明游标；客户端不得解析或构造"
+      },
+      "Limit": {
+        "name": "limit",
+        "in": "query",
+        "required": false,
+        "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}
+      },
+      "ModalityFilter": {
+        "name": "modality",
+        "in": "query",
+        "required": false,
+        "schema": {"$ref": "#/components/schemas/Modality"}
+      },
+      "CapabilityFilter": {
+        "name": "capability",
+        "in": "query",
+        "required": false,
+        "schema": {"$ref": "#/components/schemas/Capability"}
+      },
+      "DesiredStateFilter": {
+        "name": "desired_state",
+        "in": "query",
+        "required": false,
+        "schema": {"$ref": "#/components/schemas/DesiredState"}
+      },
+      "ActualStateFilter": {
+        "name": "actual_state",
+        "in": "query",
+        "required": false,
+        "schema": {"$ref": "#/components/schemas/ActualState"}
+      },
+      "IdempotencyKey": {
+        "name": "Idempotency-Key",
+        "in": "header",
+        "required": true,
+        "schema": {
+          "type": "string",
+          "minLength": 16,
+          "maxLength": 128,
+          "pattern": "^[A-Za-z0-9._:-]+$"
+        },
+        "description": "同一认证主体、站点、operationId、key 和规范化 body 在 24 小时内返回同一结果；key 相同而 body 不同返回 idempotency_conflict。"
+      },
+      "IfMatch": {
+        "name": "If-Match",
+        "in": "header",
+        "required": true,
+        "schema": {"type": "string", "minLength": 3, "maxLength": 128},
+        "description": "使用最近一次 GET/写响应的 opaque ETag；不匹配返回 412 etag_mismatch。"
+      }
+    },
+    "headers": {
+      "ETag": {
+        "description": "设备资源的不透明并发版本",
+        "schema": {"type": "string"}
+      },
+      "TraceID": {
+        "description": "不含租户、主机或凭据的排查 ID",
+        "schema": {"type": "string", "minLength": 8, "maxLength": 128}
+      },
+      "DeviceLocation": {
+        "description": "新建设备资源的相对路径",
+        "schema": {"type": "string", "pattern": "^/api/v1/sites/[^/]+/devices/[^/]+$"}
+      },
+      "OperationLocation": {
+        "description": "批量操作资源的相对路径",
+        "schema": {"type": "string", "pattern": "^/api/v1/operations/op_[0-9A-HJKMNP-TV-Z]{26}$"}
+      }
+    },
+    "responses": {
+      "CurrentDevice": {
+        "description": "设备当前表示；endpoint 与 credential ref 永不回显",
+        "headers": {
+          "ETag": {"$ref": "#/components/headers/ETag"},
+          "X-Trace-ID": {"$ref": "#/components/headers/TraceID"}
+        },
+        "content": {
+          "application/json": {"schema": {"$ref": "#/components/schemas/Device"}}
+        }
+      },
+      "CreatedDevice": {
+        "description": "设备已创建；启用设备仍需等待对账收敛",
+        "headers": {
+          "ETag": {"$ref": "#/components/headers/ETag"},
+          "Location": {"$ref": "#/components/headers/DeviceLocation"},
+          "X-Trace-ID": {"$ref": "#/components/headers/TraceID"}
+        },
+        "content": {
+          "application/json": {"schema": {"$ref": "#/components/schemas/Device"}}
+        }
+      },
+      "AcceptedMutation": {
+        "description": "期望态/配置写入已接受，实际态异步收敛",
+        "headers": {
+          "ETag": {"$ref": "#/components/headers/ETag"},
+          "X-Trace-ID": {"$ref": "#/components/headers/TraceID"}
+        },
+        "content": {
+          "application/json": {"schema": {"$ref": "#/components/schemas/MutationReceipt"}}
+        }
+      },
+      "ErrorResponse": {
+        "description": "稳定错误；不返回内部堆栈、资源存在性或连接秘密",
+        "headers": {"X-Trace-ID": {"$ref": "#/components/headers/TraceID"}},
+        "content": {
+          "application/problem+json": {"schema": {"$ref": "#/components/schemas/Problem"}}
+        }
+      }
+    },
+    "schemas": {
+      "LogicalID": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 64,
+        "pattern": "^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$"
+      },
+      "Modality": {
+        "type": "string",
+        "enum": ["video", "radar", "contact", "button", "wearable", "other"]
+      },
+      "Capability": {
+        "type": "string",
+        "enum": ["video_capture", "audio_capture", "spatial_rule", "telemetry"]
+      },
+      "DesiredState": {
+        "type": "string",
+        "enum": ["disabled", "enabled"]
+      },
+      "ActualState": {
+        "type": "string",
+        "enum": ["pending", "online", "offline", "failed"]
+      },
+      "AdapterStatus": {
+        "type": "string",
+        "enum": ["pending", "ready", "adapter_not_ready", "authentication_failed", "unavailable"]
+      },
+      "ErrorCode": {
+        "type": "string",
+        "enum": [
+          "invalid_request",
+          "unauthenticated",
+          "forbidden",
+          "not_found",
+          "conflict",
+          "precondition_required",
+          "etag_mismatch",
+          "idempotency_conflict",
+          "duplicate_serial_number",
+          "quota_exceeded",
+          "quota_projection_unavailable",
+          "quota_projection_invalid",
+          "area_policy_denied",
+          "area_policy_unavailable",
+          "adapter_not_ready",
+          "authentication_failed",
+          "endpoint_credentials_forbidden",
+          "batch_too_large",
+          "service_unavailable",
+          "internal_error"
+        ]
+      },
+      "DeviceCreate": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["serial_number", "name", "modality", "capabilities", "area_id"],
+        "properties": {
+          "serial_number": {"type": "string", "minLength": 1, "maxLength": 128},
+          "name": {"type": "string", "minLength": 1, "maxLength": 200},
+          "modality": {"$ref": "#/components/schemas/Modality"},
+          "capabilities": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 16,
+            "uniqueItems": true,
+            "items": {"$ref": "#/components/schemas/Capability"},
+            "description": "请求接入的能力集合；适配器探测不支持时以稳定错误拒绝或标记 adapter_not_ready。"
+          },
+          "area_id": {"$ref": "#/components/schemas/LogicalID"},
+          "endpoint_ref": {
+            "type": "string",
+            "format": "uri",
+            "minLength": 1,
+            "maxLength": 2048,
+            "writeOnly": true,
+            "description": "绝对 URI，禁止 userinfo；只在受控写路径使用。"
+          },
+          "credential_ref": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "writeOnly": true,
+            "description": "不透明密钥引用，不是用户名、密码或 token。"
+          },
+          "profile_token": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "writeOnly": true
+          },
+          "desired_state": {
+            "allOf": [{"$ref": "#/components/schemas/DesiredState"}],
+            "default": "disabled"
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "required": ["modality"],
+              "properties": {"modality": {"const": "video"}}
+            },
+            "then": {
+              "properties": {
+                "capabilities": {"contains": {"const": "video_capture"}, "minContains": 1}
+              }
+            }
+          },
+          {
+            "if": {
+              "required": ["capabilities"],
+              "properties": {
+                "capabilities": {"contains": {"const": "video_capture"}, "minContains": 1}
+              }
+            },
+            "then": {"required": ["endpoint_ref", "credential_ref"]}
+          }
+        ]
+      },
+      "DevicePatch": {
+        "type": "object",
+        "additionalProperties": false,
+        "minProperties": 1,
+        "properties": {
+          "name": {"type": "string", "minLength": 1, "maxLength": 200},
+          "area_id": {"$ref": "#/components/schemas/LogicalID"},
+          "endpoint_ref": {
+            "type": "string",
+            "format": "uri",
+            "minLength": 1,
+            "maxLength": 2048,
+            "writeOnly": true,
+            "description": "绝对 URI，禁止 userinfo。"
+          },
+          "credential_ref": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 512,
+            "writeOnly": true
+          },
+          "profile_token": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 256,
+            "writeOnly": true
+          }
+        }
+      },
+      "DesiredStateChange": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["desired_state", "reason"],
+        "properties": {
+          "desired_state": {"$ref": "#/components/schemas/DesiredState"},
+          "reason": {"type": "string", "minLength": 1, "maxLength": 500}
+        }
+      },
+      "Device": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id", "tenant_id", "site_id", "serial_number", "name", "modality",
+          "capabilities", "area_id", "desired_state", "actual_state", "adapter_status",
+          "endpoint_configured", "credential_configured", "generation", "observed_generation",
+          "converged", "failure_count", "projection_versions", "created_at", "updated_at"
+        ],
+        "properties": {
+          "id": {"$ref": "#/components/schemas/LogicalID"},
+          "tenant_id": {
+            "allOf": [{"$ref": "#/components/schemas/LogicalID"}],
+            "readOnly": true,
+            "description": "只用于回显已授权上下文，不得由客户端写入。"
+          },
+          "site_id": {"$ref": "#/components/schemas/LogicalID"},
+          "serial_number": {"type": "string", "minLength": 1, "maxLength": 128},
+          "name": {"type": "string", "minLength": 1, "maxLength": 200},
+          "modality": {"$ref": "#/components/schemas/Modality"},
+          "capabilities": {
+            "type": "array",
+            "items": {"$ref": "#/components/schemas/Capability"},
+            "uniqueItems": true,
+            "maxItems": 16,
+            "readOnly": true
+          },
+          "area_id": {"$ref": "#/components/schemas/LogicalID"},
+          "desired_state": {"$ref": "#/components/schemas/DesiredState"},
+          "actual_state": {"$ref": "#/components/schemas/ActualState"},
+          "adapter_status": {"$ref": "#/components/schemas/AdapterStatus"},
+          "endpoint_configured": {"type": "boolean", "readOnly": true},
+          "credential_configured": {"type": "boolean", "readOnly": true},
+          "generation": {"type": "integer", "format": "int64", "minimum": 1, "readOnly": true},
+          "observed_generation": {"type": "integer", "format": "int64", "minimum": 0, "readOnly": true},
+          "converged": {
+            "type": "boolean",
+            "readOnly": true,
+            "description": "期望代已被观察且当前无待重试；不等价于所有外部系统健康。"
+          },
+          "failure_count": {"type": "integer", "minimum": 0, "readOnly": true},
+          "next_attempt_at": {"type": ["string", "null"], "format": "date-time", "readOnly": true},
+          "last_error_code": {"type": ["string", "null"], "maxLength": 128, "readOnly": true},
+          "projection_versions": {"$ref": "#/components/schemas/ProjectionVersions"},
+          "created_at": {"type": "string", "format": "date-time", "readOnly": true},
+          "updated_at": {"type": "string", "format": "date-time", "readOnly": true}
+        }
+      },
+      "ProjectionVersions": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["quota_source_version", "area_policy_source_version", "synced_at"],
+        "properties": {
+          "quota_source_version": {"type": ["integer", "null"], "format": "int64", "minimum": 1, "readOnly": true},
+          "area_policy_source_version": {"type": ["integer", "null"], "format": "int64", "minimum": 1, "readOnly": true},
+          "synced_at": {"type": ["string", "null"], "format": "date-time", "readOnly": true}
+        }
+      },
+      "SiteQuotaStatus": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["status", "used_video_channels", "max_video_channels", "available_video_channels", "over_limit", "source_version", "synced_at"],
+        "properties": {
+          "status": {"type": "string", "enum": ["current", "unavailable", "invalid"]},
+          "used_video_channels": {"type": "integer", "minimum": 0, "maximum": 128},
+          "max_video_channels": {"type": ["integer", "null"], "minimum": 1, "maximum": 128},
+          "available_video_channels": {"type": ["integer", "null"], "minimum": 0, "maximum": 128},
+          "over_limit": {"type": "boolean"},
+          "source_version": {"type": ["integer", "null"], "format": "int64", "minimum": 1},
+          "synced_at": {"type": ["string", "null"], "format": "date-time"}
+        }
+      },
+      "PageInfo": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["limit", "has_more", "next_cursor"],
+        "properties": {
+          "limit": {"type": "integer", "minimum": 1, "maximum": 100},
+          "has_more": {"type": "boolean"},
+          "next_cursor": {"type": ["string", "null"], "maxLength": 512}
+        }
+      },
+      "DevicePage": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["items", "page", "quota"],
+        "properties": {
+          "items": {"type": "array", "maxItems": 100, "items": {"$ref": "#/components/schemas/Device"}},
+          "page": {"$ref": "#/components/schemas/PageInfo"},
+          "quota": {"$ref": "#/components/schemas/SiteQuotaStatus"}
+        }
+      },
+      "MutationReceipt": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["device", "accepted_at", "trace_id"],
+        "properties": {
+          "device": {"$ref": "#/components/schemas/Device"},
+          "accepted_at": {"type": "string", "format": "date-time"},
+          "trace_id": {"type": "string", "minLength": 8, "maxLength": 128}
+        }
+      },
+      "BatchDesiredStateItem": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["device_id", "etag", "desired_state"],
+        "properties": {
+          "device_id": {"$ref": "#/components/schemas/LogicalID"},
+          "etag": {"type": "string", "minLength": 3, "maxLength": 128},
+          "desired_state": {"$ref": "#/components/schemas/DesiredState"}
+        }
+      },
+      "BatchDesiredStateRequest": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["items", "reason"],
+        "properties": {
+          "items": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 128,
+            "items": {"$ref": "#/components/schemas/BatchDesiredStateItem"}
+          },
+          "reason": {"type": "string", "minLength": 1, "maxLength": 500}
+        }
+      },
+      "BatchItemResult": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["device_id", "status", "error_code", "message", "generation"],
+        "properties": {
+          "device_id": {"$ref": "#/components/schemas/LogicalID"},
+          "status": {"type": "string", "enum": ["accepted", "rejected", "succeeded", "failed"]},
+          "error_code": {"oneOf": [{"$ref": "#/components/schemas/ErrorCode"}, {"type": "null"}]},
+          "message": {"type": ["string", "null"], "maxLength": 500},
+          "generation": {"type": ["integer", "null"], "format": "int64", "minimum": 1}
+        }
+      },
+      "BatchOperation": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "status", "submitted_at", "completed_at", "results", "trace_id"],
+        "properties": {
+          "id": {"type": "string", "pattern": "^op_[0-9A-HJKMNP-TV-Z]{26}$"},
+          "status": {"type": "string", "enum": ["queued", "running", "succeeded", "partially_succeeded", "failed"]},
+          "submitted_at": {"type": "string", "format": "date-time"},
+          "completed_at": {"type": ["string", "null"], "format": "date-time"},
+          "results": {"type": "array", "maxItems": 128, "items": {"$ref": "#/components/schemas/BatchItemResult"}},
+          "trace_id": {"type": "string", "minLength": 8, "maxLength": 128}
+        }
+      },
+      "FieldError": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["field", "code", "message"],
+        "properties": {
+          "field": {"type": "string", "maxLength": 256},
+          "code": {"type": "string", "maxLength": 128},
+          "message": {"type": "string", "maxLength": 500}
+        }
+      },
+      "Problem": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["type", "title", "status", "code", "message", "trace_id", "field_errors"],
+        "properties": {
+          "type": {"type": "string", "format": "uri-reference"},
+          "title": {"type": "string", "maxLength": 200},
+          "status": {"type": "integer", "minimum": 400, "maximum": 599},
+          "code": {"$ref": "#/components/schemas/ErrorCode"},
+          "message": {"type": "string", "maxLength": 1000},
+          "trace_id": {"type": "string", "minLength": 8, "maxLength": 128},
+          "field_errors": {"type": "array", "maxItems": 100, "items": {"$ref": "#/components/schemas/FieldError"}}
+        }
+      }
+    }
+  }
+}

docs/contracts/site-quota-v1.sql

@@ -0,0 +1,32 @@
+-- YoVision Bell -> Sense site quota projection contract v1.
+--
+-- This file freezes the PostgreSQL object signature and privileges. It is not a
+-- migration: Bell must create the source table and install this view in a later
+-- implementation task. The source table must enforce a default of 16 and a
+-- CHECK constraint that keeps max_video_channels between 1 and 128 inclusive.
+-- source_version must increase monotonically for each logical site whenever a
+-- projected value changes.
+
+CREATE VIEW bell.site_quota_v1 (
+    tenant_id,
+    site_id,
+    max_video_channels,
+    source_version,
+    source_updated_at
+) AS
+SELECT
+    site.tenant_id,
+    site.id,
+    site.max_video_channels,
+    site.version,
+    site.updated_at
+FROM bell.sites AS site
+WHERE site.deleted_at IS NULL;
+
+COMMENT ON VIEW bell.site_quota_v1 IS
+    'v1 read-only site video quota projection owned by Bell and consumed by Sense';
+
+ALTER VIEW bell.site_quota_v1 OWNER TO bell_app;
+REVOKE ALL PRIVILEGES ON TABLE bell.site_quota_v1 FROM PUBLIC;
+GRANT USAGE ON SCHEMA bell TO sense_app;
+GRANT SELECT ON TABLE bell.site_quota_v1 TO sense_app;

docs/current-state.md

@@ -4,7 +4,7 @@
 
 ## 当前阶段
 
-- 阶段：M0 指定摄像头型号准入已完成；M1 的“一实机 + 四合成源”实验室软件闭环已通过，但五条独立真实上游和生产 SLA 尚未验收。
+- 阶段：M0 指定摄像头型号准入已完成；M1 的“一实机 + 四合成源”实验室软件闭环已通过；M2 已完成首个控制面/配额契约门禁，但五条独立真实上游和生产 SLA 尚未验收。
 - 生产代码：Sense 已包含可构建进程、SQLite 台账、标准 ONVIF SOAP/WS-Security adapter、凭据引用、MediaMTX 生成客户端、对账、探活和 MediaMTX 重启重建；公共设备管理 API 与生产部署能力仍未实现。
 - 默认容量：16 路；单站点本阶段上限 128 路，必须横向分片。
 
@@ -17,6 +17,7 @@
 - T-006 正式使用 1 台准入实机和 4 个独立合成 publisher 连续观察 `1806.6 s` / 180 次采样，四类恢复均通过，最大与最终 `unconverged` 均为 0；详细证据见 `docs/research/sense-5-stream-integration.md`。
 - `docs/raw/01`～`08` 已记录需求、分析、方案、客户场景、事件比对和三系统职责。
 - `docs/raw/contracts/event-v0.1.schema.json` 已冻结，并有多份示例与语义说明。
+- `docs/contracts/sense-control-v1.openapi.json` 已冻结站点作用域的设备查询、创建、修改、启停与最多 128 项批量操作；`site-quota-v1.sql` 已冻结 Bell 所有、Sense 只读的配额视图签名。两者当前只有契约测试，HTTP handler、认证、Bell 表和 migration 尚未实现。
 - harness coding 文档、上下文清单、Gitea Issue/PR 模板和治理脚本已接入。
 - Gitea 已初始化 12 个协作标签；`status/waiting` 用于依赖或外部条件未满足的未领取任务，实时可领取状态必须从 Gitea 查询，不在本文复制。
 - T-002 已关闭架构影响型问题：首期 S2 民办寄宿学校、客户侧私有部署、ONVIF/RTSP、NVIDIA 主路径、自研 Bell、Web/H5 与客户侧证据存储等边界已批准。
@@ -60,7 +61,7 @@ Sense 默认监听 `127.0.0.1:8080`，提供 `/healthz` 与 `/readyz` 运维探
 
 ## 下一步
 
-下一步按 Gitea 依赖关系选择后续 M1 任务；客户授权、借用或租赁条件具备后执行 T-007 五条独立真实上游现场门禁。T-006 的合成结果不解除 T-007，也不形成容量或生产 SLA 承诺。实时领取状态仍以 Gitea 为准。
+下一步先按 Gitea 流程建立并领取 T-008 的实现后续任务：实现认证 tenant 上下文、Sense 设备管理 handler/PostgreSQL repository，以及 Bell 配额源表、migration 和 `bell.site_quota_v1`。客户授权、借用或租赁条件具备后再执行 T-007 五条独立真实上游现场门禁。T-006 的合成结果不解除 T-007，也不形成容量或生产 SLA 承诺。实时领取状态仍以 Gitea 为准。
 
 ## 已知风险
 

docs/tasks/T-008.md

@@ -3,12 +3,12 @@ id: T-008
 title: 冻结 Sense 设备管理 API 与 Bell 配额只读投影契约
 phase: 2
 deps: [T-006]
-status: TODO
+status: DONE
 created: 2026-08-07
 issue: 27
-context_ref: null
-claim_branch: null
-work_branch: null
+context_ref: cc47e1463849151bee3c349cc53971181e262043
+claim_branch: claims/T-008
+work_branch: agent/codex/T-008
 write_paths:
   - docs/tasks/T-008.md
   - docs/contracts/
@@ -50,7 +50,7 @@ T-006 已证明 Sense 能用 SQLite 期望态驱动 1 路真实摄像头与 4
 
 ## 验收要点
 
-- 任务相关验证：OpenAPI/SQL/说明互相引用且无悬空路径；运行 `python -m unittest tests.test_sense_control_contract`，正例全通过，关键约束负例均产生预期错误；JSON 可由标准库解析。
+- 任务相关验证：OpenAPI/SQL/说明互相引用且无悬空路径；运行 `python -m unittest discover -s tests -p "test_sense_control_contract.py"`，正例全通过，关键约束负例均产生预期错误；JSON 可由标准库解析。
 - 完整门禁：运行 `./init.ps1`、`python scripts/validate_agent_context.py`、`python -m unittest discover -s tests -p "test_*.py"`、`python scripts/validate_harness_governance.py` 和 `git diff --check`，全部通过。
 - 人工 / 设备验收：不需要摄像头或 UI 人工验收；由架构/后端负责人核对资源所有权、失败语义、幂等/并发、隐私和未来分库退出路线。
 - 构建产物：`docs/contracts/sense-control-v1.openapi.json`、`docs/contracts/site-quota-v1.sql`、`docs/contracts/README.md`；本任务不生成部署二进制或数据库 migration。
@@ -70,6 +70,19 @@ T-006 已证明 Sense 能用 SQLite 期望态驱动 1 路真实摄像头与 4
 
 ## 执行记录
 
+### 2026-08-07 完成契约冻结
+
+- 冻结 OpenAPI 3.1 `1.0.0`：7 个站点作用域/批量操作 endpoint，tenant 来自认证上下文，列表默认 50/最大 100，批量最大 128，并明确 Bearer、幂等键、ETag、逐项结果和稳定错误码。
+- 设备创建使用 `modality + capabilities` 且 ID 由服务端生成；连接和凭据引用只写不读，v1 不暴露删除或 Site/Area/RBAC/配额 CRUD，也不把期望态受理误报为实际态收敛。
+- 冻结 `bell.site_quota_v1` 的 5 列签名、`bell_app` 所有权及 `sense_app` 的最小 `USAGE + SELECT` 权限；配额默认 16、范围 1～128，投影失败只阻断相关新增/启用，已有链路保持不变。
+- 增加 8 个标准库契约测试，正例覆盖 OpenAPI/SQL/说明一致性，负例证明缺失认证、客户端自报 tenant、101 页上限、129 项批量、敏感字段回显和 Bell 写权限都会被拒绝。
+- `./init.ps1` 通过；`python -m unittest discover -s tests -p "test_*.py"` 共 26 项通过；JSON 标准库解析、上下文校验、治理校验和 `git diff --check` 均通过。本任务不需要摄像头或 UI 人工验收。
+
+### 2026-08-07 领取任务
+
+- dispatcher `ila` 将任务分配给 `codex`；`context_ref` 为 `cc47e1463849151bee3c349cc53971181e262043`，claim 为 `claims/T-008`，工作分支为 `agent/codex/T-008`。
+- 接受既有写路径：`docs/tasks/T-008.md`、`docs/contracts/`、`docs/api.md`、`docs/04-architecture.md`、`docs/06-tasks.md`、`docs/current-state.md`、`tests/test_sense_control_contract.py`。
+
 ### 2026-08-07 任务定义
 
 - 项目负责人要求落成并立即实施 T-008；任务按 M2 第一项契约门禁建立，依赖已完成的 T-006。

tests/test_sense_control_contract.py

@@ -0,0 +1,302 @@
+"""Repository-local invariants for the frozen Sense control-plane contract."""
+
+from __future__ import annotations
+
+import copy
+import json
+import re
+import unittest
+from pathlib import Path
+from typing import Any
+
+
+ROOT = Path(__file__).resolve().parents[1]
+OPENAPI_PATH = ROOT / "docs" / "contracts" / "sense-control-v1.openapi.json"
+QUOTA_SQL_PATH = ROOT / "docs" / "contracts" / "site-quota-v1.sql"
+CONTRACT_README_PATH = ROOT / "docs" / "contracts" / "README.md"
+
+HTTP_METHODS = {"get", "post", "put", "patch", "delete", "options", "head", "trace"}
+EXPECTED_OPERATIONS = {
+    ("get", "/api/v1/sites/{site_id}/devices"),
+    ("post", "/api/v1/sites/{site_id}/devices"),
+    ("get", "/api/v1/sites/{site_id}/devices/{device_id}"),
+    ("patch", "/api/v1/sites/{site_id}/devices/{device_id}"),
+    ("put", "/api/v1/sites/{site_id}/devices/{device_id}/desired-state"),
+    ("post", "/api/v1/sites/{site_id}/devices:batchDesiredState"),
+    ("get", "/api/v1/operations/{operation_id}"),
+}
+
+EXPECTED_ENUMS = {
+    "Modality": ["video", "radar", "contact", "button", "wearable", "other"],
+    "Capability": ["video_capture", "audio_capture", "spatial_rule", "telemetry"],
+    "DesiredState": ["disabled", "enabled"],
+    "ActualState": ["pending", "online", "offline", "failed"],
+}
+
+REQUIRED_ERROR_CODES = {
+    "invalid_request",
+    "unauthenticated",
+    "forbidden",
+    "not_found",
+    "precondition_required",
+    "etag_mismatch",
+    "idempotency_conflict",
+    "duplicate_serial_number",
+    "quota_exceeded",
+    "quota_projection_unavailable",
+    "quota_projection_invalid",
+    "area_policy_denied",
+    "area_policy_unavailable",
+    "adapter_not_ready",
+    "endpoint_credentials_forbidden",
+    "batch_too_large",
+}
+
+
+def load_openapi() -> dict[str, Any]:
+    return json.loads(OPENAPI_PATH.read_text(encoding="utf-8"))
+
+
+def resolve_local_ref(document: dict[str, Any], value: dict[str, Any]) -> dict[str, Any]:
+    """Resolve one local JSON pointer; the contract only needs direct component refs."""
+    ref = value.get("$ref")
+    if not ref:
+        return value
+    if not ref.startswith("#/"):
+        raise ValueError(f"external ref is not allowed here: {ref}")
+    current: Any = document
+    for token in ref[2:].split("/"):
+        current = current[token.replace("~1", "/").replace("~0", "~")]
+    if not isinstance(current, dict):
+        raise ValueError(f"ref does not resolve to an object: {ref}")
+    return current
+
+
+def operation_parameters(
+    document: dict[str, Any], operation: dict[str, Any]
+) -> dict[str, dict[str, Any]]:
+    result: dict[str, dict[str, Any]] = {}
+    for value in operation.get("parameters", []):
+        parameter = resolve_local_ref(document, value)
+        result[parameter.get("name", "")] = parameter
+    return result
+
+
+def validate_openapi(document: dict[str, Any]) -> list[str]:
+    errors: list[str] = []
+    if document.get("openapi") != "3.1.0":
+        errors.append("OpenAPI version must be 3.1.0")
+    if document.get("info", {}).get("version") != "1.0.0":
+        errors.append("contract version must be 1.0.0")
+
+    top_security = document.get("security")
+    if not top_security or not any("bearerAuth" in item for item in top_security):
+        errors.append("top-level bearerAuth is required")
+
+    operations: dict[tuple[str, str], dict[str, Any]] = {}
+    operation_ids: list[str] = []
+    for path, path_item in document.get("paths", {}).items():
+        if not path.startswith("/api/v1/"):
+            errors.append(f"unversioned path: {path}")
+        for method, operation in path_item.items():
+            if method not in HTTP_METHODS:
+                continue
+            key = (method, path)
+            operations[key] = operation
+            operation_id = operation.get("operationId")
+            if not operation_id:
+                errors.append(f"missing operationId: {method.upper()} {path}")
+            else:
+                operation_ids.append(operation_id)
+            if not operation.get("responses"):
+                errors.append(f"missing responses: {method.upper()} {path}")
+            effective_security = operation.get("security", top_security)
+            if not effective_security or not any(
+                "bearerAuth" in item for item in effective_security
+            ):
+                errors.append(f"bearerAuth required: {method.upper()} {path}")
+
+    missing_operations = EXPECTED_OPERATIONS - set(operations)
+    unexpected_operations = set(operations) - EXPECTED_OPERATIONS
+    if missing_operations:
+        errors.append(f"missing operations: {sorted(missing_operations)}")
+    if unexpected_operations:
+        errors.append(f"unexpected operations: {sorted(unexpected_operations)}")
+    if len(operation_ids) != len(set(operation_ids)):
+        errors.append("operationId values must be unique")
+
+    list_operation = operations.get(("get", "/api/v1/sites/{site_id}/devices"), {})
+    list_parameters = operation_parameters(document, list_operation)
+    if "cursor" not in list_parameters:
+        errors.append("device list requires cursor pagination")
+    limit = list_parameters.get("limit", {}).get("schema", {})
+    if limit.get("default") != 50 or limit.get("maximum") != 100:
+        errors.append("device list limit must default to 50 and have maximum 100")
+
+    header_requirements = {
+        ("post", "/api/v1/sites/{site_id}/devices"): "Idempotency-Key",
+        ("post", "/api/v1/sites/{site_id}/devices:batchDesiredState"): "Idempotency-Key",
+        ("patch", "/api/v1/sites/{site_id}/devices/{device_id}"): "If-Match",
+        ("put", "/api/v1/sites/{site_id}/devices/{device_id}/desired-state"): "If-Match",
+    }
+    for key, header in header_requirements.items():
+        parameters = operation_parameters(document, operations.get(key, {}))
+        parameter = parameters.get(header, {})
+        if parameter.get("in") != "header" or parameter.get("required") is not True:
+            errors.append(f"{key[0].upper()} {key[1]} requires header {header}")
+
+    for key in (
+        ("patch", "/api/v1/sites/{site_id}/devices/{device_id}"),
+        ("put", "/api/v1/sites/{site_id}/devices/{device_id}/desired-state"),
+    ):
+        responses = operations.get(key, {}).get("responses", {})
+        if "412" not in responses or "428" not in responses:
+            errors.append(f"{key[0].upper()} {key[1]} must define 412 and 428")
+
+    schemas = document.get("components", {}).get("schemas", {})
+    batch_items = (
+        schemas.get("BatchDesiredStateRequest", {})
+        .get("properties", {})
+        .get("items", {})
+    )
+    if batch_items.get("maxItems") != 128:
+        errors.append("batch desired-state request must have maximum 128 items")
+
+    client_schemas = ("DeviceCreate", "DevicePatch", "DesiredStateChange", "BatchDesiredStateRequest")
+    for schema_name in client_schemas:
+        if "tenant_id" in schemas.get(schema_name, {}).get("properties", {}):
+            errors.append(f"tenant_id must not be client-controlled in {schema_name}")
+
+    create_properties = schemas.get("DeviceCreate", {}).get("properties", {})
+    if "id" in create_properties:
+        errors.append("device id must be generated by the service")
+    required_create = set(schemas.get("DeviceCreate", {}).get("required", []))
+    if not {"modality", "capabilities"}.issubset(required_create):
+        errors.append("device create requires modality and capabilities")
+
+    for schema_name in ("DeviceCreate", "DevicePatch"):
+        properties = schemas.get(schema_name, {}).get("properties", {})
+        for field in ("endpoint_ref", "credential_ref", "profile_token"):
+            if properties.get(field, {}).get("writeOnly") is not True:
+                errors.append(f"{schema_name}.{field} must be writeOnly")
+
+    output_properties = schemas.get("Device", {}).get("properties", {})
+    tenant = output_properties.get("tenant_id", {})
+    if tenant.get("readOnly") is not True:
+        errors.append("Device.tenant_id must be readOnly")
+    forbidden_output_fields = {
+        "endpoint_ref",
+        "credential_ref",
+        "profile_token",
+        "active_profile",
+        "stream_uri",
+        "password",
+        "token",
+    }
+    leaked_fields = forbidden_output_fields & set(output_properties)
+    if leaked_fields:
+        errors.append(f"Device leaks sensitive fields: {sorted(leaked_fields)}")
+
+    for schema_name, expected in EXPECTED_ENUMS.items():
+        actual = schemas.get(schema_name, {}).get("enum")
+        if actual != expected:
+            errors.append(f"{schema_name} enum drift: {actual!r}")
+
+    error_codes = set(schemas.get("ErrorCode", {}).get("enum", []))
+    missing_error_codes = REQUIRED_ERROR_CODES - error_codes
+    if missing_error_codes:
+        errors.append(f"missing stable error codes: {sorted(missing_error_codes)}")
+    return errors
+
+
+def validate_quota_sql(sql: str) -> list[str]:
+    errors: list[str] = []
+    normalized = re.sub(r"\s+", " ", sql.lower()).strip()
+    expected_signature = (
+        "create view bell.site_quota_v1 ( tenant_id, site_id, "
+        "max_video_channels, source_version, source_updated_at ) as"
+    )
+    if expected_signature not in normalized:
+        errors.append("bell.site_quota_v1 column signature is not frozen as expected")
+    if "alter view bell.site_quota_v1 owner to bell_app" not in normalized:
+        errors.append("Bell role must own the quota view")
+    if "grant usage on schema bell to sense_app" not in normalized:
+        errors.append("Sense role needs schema USAGE")
+    if "grant select on table bell.site_quota_v1 to sense_app" not in normalized:
+        errors.append("Sense role needs SELECT on only the quota view")
+    if "revoke all privileges on table bell.site_quota_v1 from public" not in normalized:
+        errors.append("PUBLIC privileges must be revoked")
+    if re.search(
+        r"grant\s+(?:all(?:\s+privileges)?|insert|update|delete|truncate|references|trigger)\b",
+        normalized,
+    ):
+        errors.append("quota view grants a forbidden write or broad privilege")
+    if re.search(r"grant\s+select\s+on\s+table\s+bell\.sites\b", normalized):
+        errors.append("Sense must not receive SELECT on the Bell source table")
+    return errors
+
+
+class SenseControlContractTests(unittest.TestCase):
+    def setUp(self) -> None:
+        self.document = load_openapi()
+        self.quota_sql = QUOTA_SQL_PATH.read_text(encoding="utf-8")
+
+    def test_frozen_openapi_invariants(self) -> None:
+        self.assertEqual([], validate_openapi(self.document))
+
+    def test_frozen_quota_projection_invariants(self) -> None:
+        self.assertEqual([], validate_quota_sql(self.quota_sql))
+
+    def test_contract_narrative_records_failure_and_compatibility_semantics(self) -> None:
+        text = CONTRACT_README_PATH.read_text(encoding="utf-8")
+        for marker in (
+            "默认 16",
+            "1～128",
+            "至少保存 24 小时",
+            "404 not_found",
+            "已有流保持运行",
+            "必须发布新版本",
+        ):
+            self.assertIn(marker, text)
+
+    def test_validator_rejects_missing_authentication(self) -> None:
+        changed = copy.deepcopy(self.document)
+        changed.pop("security", None)
+        self.assertTrue(any("bearerAuth" in item for item in validate_openapi(changed)))
+
+    def test_validator_rejects_client_controlled_tenant(self) -> None:
+        changed = copy.deepcopy(self.document)
+        changed["components"]["schemas"]["DeviceCreate"]["properties"]["tenant_id"] = {
+            "type": "string"
+        }
+        self.assertTrue(any("tenant_id" in item for item in validate_openapi(changed)))
+
+    def test_validator_rejects_unbounded_list_or_batch(self) -> None:
+        changed = copy.deepcopy(self.document)
+        changed["components"]["parameters"]["Limit"]["schema"]["maximum"] = 101
+        changed["components"]["schemas"]["BatchDesiredStateRequest"]["properties"][
+            "items"
+        ]["maxItems"] = 129
+        errors = validate_openapi(changed)
+        self.assertTrue(any("maximum 100" in item for item in errors))
+        self.assertTrue(any("maximum 128" in item for item in errors))
+
+    def test_validator_rejects_sensitive_output_or_writable_credential_ref(self) -> None:
+        changed = copy.deepcopy(self.document)
+        changed["components"]["schemas"]["DevicePatch"]["properties"]["credential_ref"][
+            "writeOnly"
+        ] = False
+        changed["components"]["schemas"]["Device"]["properties"]["stream_uri"] = {
+            "type": "string"
+        }
+        errors = validate_openapi(changed)
+        self.assertTrue(any("credential_ref" in item for item in errors))
+        self.assertTrue(any("sensitive fields" in item for item in errors))
+
+    def test_validator_rejects_write_privilege(self) -> None:
+        changed = self.quota_sql + "\nGRANT ALL PRIVILEGES ON bell.site_quota_v1 TO sense_app;\n"
+        self.assertTrue(any("forbidden" in item for item in validate_quota_sql(changed)))
+
+
+if __name__ == "__main__":
+    unittest.main()