ila/yovision
1
0
Fork 0
Code Issues 14 Pull Requests 14 Actions Packages Projects Releases Wiki Activity

[CTR] 冻结 Sense→Brain 媒体源与区域规则配置契约 v1 #148

New Issue
Closed
opened 2026-08-29 21:04:53 +08:00 by ila · 5 comments
ila commented 2026-08-29 21:04:53 +08:00
Owner
Copy Link
Copy Source

状态

已完成（2026-08-31，用户验收通过）

基本信息

  • 类型：共享契约 / 跨项目协调
  • 主项目：YoVision contracts
  • 主 agent：单一 coordination agent
  • 所属 Epic：#7
  • 所属 MVP：#156
  • 来源：#124 对 #69、#72–#77、Brain #11/#15/#16 的去重汇总；用户于 2026-08-29 指令“执行工单 #124”
  • 生产者：Sense
  • 消费者：Brain
  • 前置：#8 已验收；实施前确认本工单技术设计
  • 契约事实源：contracts/source-config/v1/**

目标

冻结 Sense 向 Brain 发布的媒体源、逻辑设备/Profile 和版本化区域/方向线配置契约 v1，使 Brain 不读取 Sense 数据库，也不依赖 brain.internal.input/v1 作为共享协议。

已确认边界与拟议设计

  • 共享快照只携带 schema 版本、配置 ID/revision、站点与逻辑设备引用、Profile 引用及规格、无凭据媒体引用、区域/方向线及规则版本、生效时间和完整性摘要。
  • 坐标统一为 0–1 归一化值并绑定 Profile/分辨率；Profile 变化必须形成新 revision 或显式重校准状态。
  • 媒体引用不得包含账号、密码、query token、客户内部文件路径或 Sense 数据库主键语义；实际解析由后续 connector 完成。
  • v1 只允许向后兼容的可选字段扩展；字段删除、类型或语义变化发布新主版本。未知主版本必须安全拒绝，旧版本兼容周期和回退样例写入契约。
  • Sense 内部 Device/Profile/Area 模型和 Brain brain.internal.input/v1 继续是各自内部实现，只通过 mapper 对接。

非目标

不实现 Sense/Brain adapter、机器身份、RTSP 凭据交换、Brain 运行状态、标准事件、部署或 E2E；不修改任何产品数据库模型。

精确 write_paths

  • contracts/source-config/v1/**
  • contracts/tests/source-config-v1/**

禁止写入：Sense/**、Brain/**、Bell/**、其他 contracts/**、根级部署和 docs/**。

验收标准

  • JSON Schema/OpenAPI、兼容说明、有效/无效示例和 mapper 字段表完整
  • 生产者/消费者对逻辑 ID、Profile、坐标、revision、生效与重校准语义一致
  • 示例和错误路径证明不携带摄像头凭据、query token、内部路径或数据库模型
  • Sense 生产者契约测试与 Brain 消费者契约测试责任写明
  • 破坏性变化、兼容周期和回退到上一主版本的方法明确

验证

Schema 校验、有效/无效/未知版本样例、兼容性测试、秘密字段拒绝测试和 git diff --check。

风险与回退

错误坐标/Profile 绑定会产生错误规则判定。协议未冻结前不得实施 adapter；回退保留上一冻结主版本并停用新 revision，不原地改写已发布语义。

设计与文档影响

非 UI 任务，以本工单的 API/数据/版本设计为确认门禁；协议冻结后更新 Architecture、Product-Requirements、Business-Rules 和本地验证 Wiki，再同步核心镜像。

## 状态 已完成（2026-08-31，用户验收通过） ## 基本信息 - 类型：共享契约 / 跨项目协调 - 主项目：YoVision contracts - 主 agent：单一 coordination agent - 所属 Epic：#7 - 所属 MVP：#156 - 来源：#124 对 #69、#72–#77、Brain #11/#15/#16 的去重汇总；用户于 2026-08-29 指令“执行工单 #124” - 生产者：Sense - 消费者：Brain - 前置：#8 已验收；实施前确认本工单技术设计 - 契约事实源：`contracts/source-config/v1/**` ## 目标 冻结 Sense 向 Brain 发布的媒体源、逻辑设备/Profile 和版本化区域/方向线配置契约 v1，使 Brain 不读取 Sense 数据库，也不依赖 `brain.internal.input/v1` 作为共享协议。 ## 已确认边界与拟议设计 - 共享快照只携带 schema 版本、配置 ID/revision、站点与逻辑设备引用、Profile 引用及规格、无凭据媒体引用、区域/方向线及规则版本、生效时间和完整性摘要。 - 坐标统一为 0–1 归一化值并绑定 Profile/分辨率；Profile 变化必须形成新 revision 或显式重校准状态。 - 媒体引用不得包含账号、密码、query token、客户内部文件路径或 Sense 数据库主键语义；实际解析由后续 connector 完成。 - v1 只允许向后兼容的可选字段扩展；字段删除、类型或语义变化发布新主版本。未知主版本必须安全拒绝，旧版本兼容周期和回退样例写入契约。 - Sense 内部 Device/Profile/Area 模型和 Brain `brain.internal.input/v1` 继续是各自内部实现，只通过 mapper 对接。 ## 非目标 不实现 Sense/Brain adapter、机器身份、RTSP 凭据交换、Brain 运行状态、标准事件、部署或 E2E；不修改任何产品数据库模型。 ## 精确 write_paths - `contracts/source-config/v1/**` - `contracts/tests/source-config-v1/**` 禁止写入：`Sense/**`、`Brain/**`、`Bell/**`、其他 `contracts/**`、根级部署和 `docs/**`。 ## 验收标准 - [ ] JSON Schema/OpenAPI、兼容说明、有效/无效示例和 mapper 字段表完整 - [ ] 生产者/消费者对逻辑 ID、Profile、坐标、revision、生效与重校准语义一致 - [ ] 示例和错误路径证明不携带摄像头凭据、query token、内部路径或数据库模型 - [ ] Sense 生产者契约测试与 Brain 消费者契约测试责任写明 - [ ] 破坏性变化、兼容周期和回退到上一主版本的方法明确 ## 验证 Schema 校验、有效/无效/未知版本样例、兼容性测试、秘密字段拒绝测试和 `git diff --check`。 ## 风险与回退 错误坐标/Profile 绑定会产生错误规则判定。协议未冻结前不得实施 adapter；回退保留上一冻结主版本并停用新 revision，不原地改写已发布语义。 ## 设计与文档影响 非 UI 任务，以本工单的 API/数据/版本设计为确认门禁；协议冻结后更新 Architecture、Product-Requirements、Business-Rules 和本地验证 Wiki，再同步核心镜像。
ila added the kind/taskproject/senseproject/brainpriority/p0scope/coordination labels 2026-08-29 21:04:53 +08:00
ila commented 2026-08-29 21:21:12 +08:00
Author
Owner
Copy Link
Copy Source

设计确认（2026-08-29）

用户在 #124 验收闭环后的下一步中明确回复“已确认”。按上一条明确建议，本次确认覆盖 #148、#149、#150 的协议/状态设计与兼容、回退边界；工单进入“待实施”。

本次只放行后续实施，不代表功能验收，不关闭工单，也不扩展为对高风险 #151 机器身份认证、轮换和吊销方案的确认。

## 设计确认（2026-08-29） 用户在 #124 验收闭环后的下一步中明确回复“已确认”。按上一条明确建议，本次确认覆盖 #148、#149、#150 的协议/状态设计与兼容、回退边界；工单进入“待实施”。 本次只放行后续实施，不代表功能验收，不关闭工单，也不扩展为对高风险 #151 机器身份认证、轮换和吊销方案的确认。
ila commented 2026-08-31 08:40:12 +08:00
Author
Owner
Copy Link
Copy Source

开始实施（2026-08-31）

  • 分支：feature/148-source-config-contract
  • 写路径：contracts/source-config/v1/**、contracts/tests/source-config-v1/**
  • 前置：#8 已验收，#148 技术设计已于 2026-08-29 确认。
  • 并行安全：本工单仅写上述独占路径，不触碰 #149/#150 或产品目录。
  • Gitea 访问说明：当前 agent 会话未暴露项目 Gitea MCP 工具，按仓库规则回退使用由项目环境提供凭据的 Gitea API。
## 开始实施（2026-08-31） - 分支：`feature/148-source-config-contract` - 写路径：`contracts/source-config/v1/**`、`contracts/tests/source-config-v1/**` - 前置：#8 已验收，#148 技术设计已于 2026-08-29 确认。 - 并行安全：本工单仅写上述独占路径，不触碰 #149/#150 或产品目录。 - Gitea 访问说明：当前 agent 会话未暴露项目 Gitea MCP 工具，按仓库规则回退使用由项目环境提供凭据的 Gitea API。
ila commented 2026-08-31 08:54:00 +08:00
Author
Owner
Copy Link
Copy Source

实施完成，待验收（2026-08-31）

最终差异

  • 新增 Draft 2020-12 JSON Schema：contracts/source-config/v1/source-config.schema.json；因本工单不定义 HTTP 端点，选择 payload JSON Schema 而非 OpenAPI。
  • 冻结媒体无凭据引用、逻辑站点/设备/Profile、0–1 坐标、revision/生效时间、规则状态及 SHA-256/JCS 完整性语义。
  • 三协议公共命名已统一为 snake_case，顶层版本字段为 schema_version: yovision.source-config/v1。
  • 新增 active/待重校准有效样例，以及未知主版本、秘密字段、query token、内部路径、坐标越界和 Profile 绑定错误样例。
  • 新增兼容周期（新主版本后至少一个正式发布周期且不少于 90 天）、破坏性变化、迁移/回退说明及 Sense/Brain mapper 字段与测试责任表。
  • 新增隔离可复制测试入口 contracts/tests/source-config-v1/run.ps1，覆盖 Schema、跨字段语义、revision 转换、秘密拒绝和摘要篡改。

验证证据

  • contracts\tests\source-config-v1\run.ps1：11 项通过（命名统一后重跑）。
  • python dev_scripts/harness.py check --strict：通过。
  • python -m unittest discover -s tests -v：48 项通过。
  • git diff --check：通过；16 个变更文件全部位于工单授权路径。

Git / PR

  • 初始实现提交：67391acb16f83f66e48233ac65b13cd2dba54839
  • 命名统一提交：2e61167500459666f5d2339a0d06a12c335a24b1
  • PR：#159（feature/148-source-config-contract → dev），保持开放，未合并。

未验证与文档影响

  • 未实现或验证 Sense/Brain adapter、真实媒体解析、机器身份、凭据交换和跨项目 E2E；这些属于后续 connector/安全/E2E 工单。
  • 本契约形成长期架构、产品规则和本地验证事实，需更新 Architecture、Product-Requirements、Business-Rules 和本地验证 Wiki。按并行协调安排，本 agent 未修改 Wiki/docs/**，由根协调 agent 在 #148/#149/#150 汇合后串行更新并同步镜像。
  • 未创建任务归档，未修改任何产品目录或其他 contracts 路径。
## 实施完成，待验收（2026-08-31） ### 最终差异 - 新增 Draft 2020-12 JSON Schema：`contracts/source-config/v1/source-config.schema.json`；因本工单不定义 HTTP 端点，选择 payload JSON Schema 而非 OpenAPI。 - 冻结媒体无凭据引用、逻辑站点/设备/Profile、0–1 坐标、revision/生效时间、规则状态及 SHA-256/JCS 完整性语义。 - 三协议公共命名已统一为 snake_case，顶层版本字段为 `schema_version: yovision.source-config/v1`。 - 新增 active/待重校准有效样例，以及未知主版本、秘密字段、query token、内部路径、坐标越界和 Profile 绑定错误样例。 - 新增兼容周期（新主版本后至少一个正式发布周期且不少于 90 天）、破坏性变化、迁移/回退说明及 Sense/Brain mapper 字段与测试责任表。 - 新增隔离可复制测试入口 `contracts/tests/source-config-v1/run.ps1`，覆盖 Schema、跨字段语义、revision 转换、秘密拒绝和摘要篡改。 ### 验证证据 - `contracts\tests\source-config-v1\run.ps1`：11 项通过（命名统一后重跑）。 - `python dev_scripts/harness.py check --strict`：通过。 - `python -m unittest discover -s tests -v`：48 项通过。 - `git diff --check`：通过；16 个变更文件全部位于工单授权路径。 ### Git / PR - 初始实现提交：`67391acb16f83f66e48233ac65b13cd2dba54839` - 命名统一提交：`2e61167500459666f5d2339a0d06a12c335a24b1` - PR：#159（`feature/148-source-config-contract` → `dev`），保持开放，未合并。 ### 未验证与文档影响 - 未实现或验证 Sense/Brain adapter、真实媒体解析、机器身份、凭据交换和跨项目 E2E；这些属于后续 connector/安全/E2E 工单。 - 本契约形成长期架构、产品规则和本地验证事实，需更新 Architecture、Product-Requirements、Business-Rules 和本地验证 Wiki。按并行协调安排，本 agent 未修改 Wiki/`docs/**`，由根协调 agent 在 #148/#149/#150 汇合后串行更新并同步镜像。 - 未创建任务归档，未修改任何产品目录或其他 contracts 路径。
ila commented 2026-08-31 09:01:49 +08:00
Author
Owner
Copy Link
Copy Source

根协调联合复核（2026-08-31）

将 #148、#149、#150 的最终提交按完整提交链临时叠加到同一隔离 review worktree 后复核，未合并或推送 review 分支。

  • 公共命名统一为 snake_case，版本标识分别为 yovision.source-config/v1、yovision.runtime-status/v1、yovision.event/v1、yovision.evidence-reference/v1。
  • #149 已按 #148 的 config_id + integer revision 改为多配置流 configurations[]，不存在单一 revision 歧义。
  • #150 证据成功态已与确认设计统一为 success，保留 processing 中间态；旧 available 被测试拒绝。
  • 联合测试：#148 11/11、#149 14/14、events 7/7、evidence 4/4、仓库 48/48 全部通过。
  • 全部 42 个 JSON 文件可解析；DevHarness strict、git diff --check 通过；旧命名标记扫描为 0。
  • 三个 PR 均 open、mergeable、目标为 dev，尚未合并。
  • 长期 Wiki/核心镜像将在用户验收并确定协议冻结提交后由单一协调写入者串行处理，避免三个并行工单争用共享文档；当前未创建任务归档。

#148 最终 PR：#159，head 2e61167500459666f5d2339a0d06a12c335a24b1。

## 根协调联合复核（2026-08-31） 将 #148、#149、#150 的最终提交按完整提交链临时叠加到同一隔离 review worktree 后复核，未合并或推送 review 分支。 - 公共命名统一为 snake_case，版本标识分别为 `yovision.source-config/v1`、`yovision.runtime-status/v1`、`yovision.event/v1`、`yovision.evidence-reference/v1`。 - #149 已按 #148 的 `config_id + integer revision` 改为多配置流 `configurations[]`，不存在单一 revision 歧义。 - #150 证据成功态已与确认设计统一为 `success`，保留 `processing` 中间态；旧 `available` 被测试拒绝。 - 联合测试：#148 11/11、#149 14/14、events 7/7、evidence 4/4、仓库 48/48 全部通过。 - 全部 42 个 JSON 文件可解析；DevHarness strict、`git diff --check` 通过；旧命名标记扫描为 0。 - 三个 PR 均 open、mergeable、目标为 `dev`，尚未合并。 - 长期 Wiki/核心镜像将在用户验收并确定协议冻结提交后由单一协调写入者串行处理，避免三个并行工单争用共享文档；当前未创建任务归档。 #148 最终 PR：#159，head `2e61167500459666f5d2339a0d06a12c335a24b1`。
ila commented 2026-08-31 09:42:19 +08:00
Author
Owner
Copy Link
Copy Source

用户验收结论（2026-08-31）

用户明确回复“#148；#148、#149通过验收”。按本次明确范围，#148 验收通过。

  • 实现 head：2e61167500459666f5d2339a0d06a12c335a24b1
  • PR #159 已合入 dev：30c43aa8d72443fd65e5b575cb2a97ebe381bc0b
  • 合并后验证：源配置契约 11/11、仓库 48/48、DevHarness strict、git diff --check 通过
  • 与另一份已验收契约联合验证通过；公共命名、config_id + integer revision 语义一致
  • Wiki 已在线更新并回读；核心镜像经 PR #160 合入 dev@96777a948f176bd890ab2a81bc4ae9af939c7a15
  • 文档 revision：Product Requirements 28dce0d89804013411f8111ba421c93e9a1dfa2c，Architecture 3327861dbd77ae63fd10246533b87e0b99a69220，Business Rules feca453cd0873c3ad4cef243acfada08ef3f1e33，Local Verification 43eb0f69fbb4d573a5cd1c61b97dbc9fc9d2a49b，Deployment 0a772b0511044d98430ebd93304faa3dee57183d

结论：工单完成并关闭。#152 connector 尚未实现；本次不创建任务归档。

## 用户验收结论（2026-08-31） 用户明确回复“#148；#148、#149通过验收”。按本次明确范围，#148 验收通过。 - 实现 head：`2e61167500459666f5d2339a0d06a12c335a24b1` - PR #159 已合入 `dev`：`30c43aa8d72443fd65e5b575cb2a97ebe381bc0b` - 合并后验证：源配置契约 11/11、仓库 48/48、DevHarness strict、`git diff --check` 通过 - 与另一份已验收契约联合验证通过；公共命名、`config_id + integer revision` 语义一致 - Wiki 已在线更新并回读；核心镜像经 PR #160 合入 `dev@96777a948f176bd890ab2a81bc4ae9af939c7a15` - 文档 revision：Product Requirements `28dce0d89804013411f8111ba421c93e9a1dfa2c`，Architecture `3327861dbd77ae63fd10246533b87e0b99a69220`，Business Rules `feca453cd0873c3ad4cef243acfada08ef3f1e33`，Local Verification `43eb0f69fbb4d573a5cd1c61b97dbc9fc9d2a49b`，Deployment `0a772b0511044d98430ebd93304faa3dee57183d` 结论：工单完成并关闭。#152 connector 尚未实现；本次不创建任务归档。
ila closed this issue 2026-08-31 09:42:19 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
area/ux
UI/UX 与交互原型
 kind/epic
长期产品目标
 kind/mvp
可独立验收的最小版本
 kind/task
单元实施任务
 priority/p0
首个纵切必需能力
 project/bell
Bell 项目
 project/brain
Brain 项目
 project/sense
Sense 项目
 scope/coordination
跨项目协调任务
 scope/independent
不依赖其他项目在线的项目内任务
No labels kind/task priority/p0 project/brain project/sense scope/coordination
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: ila/yovision#148