yovision/contracts/source-config/v1/mapper-fields.md

生产者与消费者 mapper 字段表

mapper 必须创建新的契约 DTO，不得直接序列化 Sense GORM 实体，也不得让 Brain 把共享快照当作 brain.internal.input/v1。

契约字段	Sense 生产来源/规则	Brain 消费目标/规则
schema_version	常量 yovision.source-config/v1	在任何映射前精确校验；未知主版本拒绝
config_id	新的稳定配置聚合 ID；不是数据库行 ID 语义	作为配置流逻辑 ID，不解释为 Brain 内部对象 ID
revision	聚合配置变更时严格递增；不可复用	与 config_id 共同做幂等、顺序和陈旧检查
published_at / effective_at	发布时写 UTC RFC 3339；生效不得早于发布	完整校验后按生效时间原子切换
site.id	对外稳定站点引用；不得映射客户名或数据库主键语义	仅作租户隔离后的逻辑关联；v1 不提供用户身份
logical_device.id	area.Definition.DeviceID / media.Route.DeviceID 经稳定外部 ID mapper	映射到 BrainInputConfig.logical_device_id
profile.id	area.Definition.ProfileToken 与 media.Route.ProfileToken 经稳定 Profile ID mapper	映射到 BrainInputConfig.profile.profile_id
profile.width/height/encoding	area.Definition.ProfileWidth/ProfileHeight/ProfileEncoding；必须与当前媒体 Profile 一致	映射到规则 RuleSet 的 Profile 绑定；不一致拒绝
profile.frame_rate	Sense 已验证 Profile 的帧率快照	映射到 BrainInputConfig.profile.fps
media.ref	由 media.Route.ID/Path 生成 media:<opaque-resource>；禁止读取或拼入 admissionProfile.StreamURI 及凭据	交给后续 connector 解析；不得当作 RTSP URL 或本地路径
media.transport	当前固定 rtsp，仅描述媒体传输类别	选择后续 connector/decode adapter；不含认证信息
rule_set.version	由一组 area.Version 聚合成稳定规则集版本	映射到 Brain RuleSet.version
rule_set.state	NeedsRecalibration=true → recalibration_required；整体禁用 → disabled；否则 active	只有 active 可构建并启用规则引擎
rule_set.profile_binding	与本快照 profile.id/width/height 同源复制并交叉校验	必须精确等于 profile；之后才接受归一化几何
rule_set.areas[].id/version	area.Version.DefinitionID/Version 经稳定规则 ID mapper	映射到 AreaRule.rule_id；version 用于可追溯性
rule_set.areas[].kind	Sense polygon 映射为 danger_area	只映射到 Brain 危险区域规则，不透传 Sense 枚举
rule_set.areas[].points	area.Version.GeometryJSON 中 {x,y}；保持 0–1	映射到 Brain Point(x,y)；至少三点且非退化
rule_set.directional_lines[].id/version	area.Version.DefinitionID/Version 经稳定规则 ID mapper	映射到 DirectionalLineRule.rule_id
rule_set.directional_lines[].start/end	direction_line 几何的两个归一化点	映射到 Brain Point；相同点拒绝
rule_set.directional_lines[].trigger_direction	Sense forward/reverse 必须由 mapper 根据已确认的起终点方向转换为 left_to_right/right_to_left	映射到 DirectionalLineRule.trigger_direction；不得直接猜测枚举
integrity	对移除 integrity 的 JCS 快照计算 SHA-256	映射前重算并常量时间比较；失败保留上一有效 revision

测试责任

• Sense 生产者契约测试：从设备、媒体 Route、Profile 与区域版本 fixture 生成快照；断言字段映射、revision 递增、Profile 变化触发新 revision/待重校准、无秘密媒体引用、Schema/语义/摘要通过。
• Brain 消费者契约测试：加载本目录有效与无效样例；断言版本拒绝、幂等/陈旧处理、Profile 绑定、坐标、规则 ID、状态门禁和摘要；再映射为 Brain 内部配置，证明共享 schema_version 不等于 brain.internal.input/v1。
• 协调契约测试（本工单）：校验所有样例、秘密字段/URL/本地路径拒绝、跨字段语义和摘要。产品 adapter 测试在后续 connector 工单实施。

Sense 与 Brain 各自可增加内部字段，但不得将数据库主键、用户表、JWT、Cookie、摄像头凭据、客户内部路径或内部模型直接扩展进本契约。