通道数据模型（core/repositories/models/channels）
本文说明 通道（目录节点与摄像头通道） core/repositories/models/channels 包中的职责、与项目各层的对接方式，以及字段含义与 API/库形态对应关系。
姊妹篇：7.1 设备数据模型（devices）、7.0 组织部门数据模型（departments，与本文 depIds 对应）。
1. 在项目中承担的作用
该模型描述 国标/接入侧通道与目录 的核心实体：数据落在表 sk-channels，通过统一 ORM 接入 db 服务；通道与 设备 通过 deviceUniqueId 逻辑关联（与 sk-devices.deviceUniqueId 对应）；与 部门 通过 depIds 多选关联。通道还承担 在线/拉流/录制/地理位置/级联编号 等运行时状态与业务字段的持久化。
| 层级 | 作用 |
|---|---|
| 数据层 | core/app/sev/db/internal/svc/init_database.go 对 channels.Channels 执行 AutoMigrate；ServiceContext 注入 ChannelsModel。 |
| RPC / db 服务 | core/app/sev/db/internal/logic/deviceservice/ 下 channel_* 系列逻辑（列表、创建、更新、删除、Upsert、按条件删通道等）操作 ChannelsModel 与 channels.Item。 |
| HTTP / backend | core/app/sev/backend/internal/handler/device/channels 与路由中的 /device/channel 等接口，经 RPC 访问 db 服务。 |
| 配置 / 编号 | MaxIdLogic 在 type == "cascadeChannel" 时，基于 cascadeChannelUniqueId 生成下一级联通道编号（条件构建复用 ChannelsModel.CaseNumberCondition）。 |
| 与其它模型 | deviceUniqueId 归属某台设备；depIds 为部门 id 数组（库内 JSON 字符串）；初始化/同步逻辑（如 svc/proc.go）会按通道的 depIds 聚合回写设备的部门归属。 |
通道是 设备之下的监控资源单元：parental / parentID 表达国标目录树中的父子关系；uniqueId 与 deviceUniqueId 组成业务唯一约束（索引 device_channel_UniqueId）。
2. 表与字段：数据库列 ↔ Go ↔ JSON
实体 Channels 映射表 sk-channels（TableName() 返回值）。下列「说明」中概括库类型与典型 JSON 形态。
| 字段 | 含义 | 说明 |
|---|---|---|
id | 主键 | 自增。 |
deviceUniqueId | 所属设备 ID | CHAR(70)，与设备表 deviceUniqueId 对应；与 uniqueId 组成复合唯一索引。 |
uniqueId | 通道业务 ID | CHAR(70)；同一设备下通道/目录唯一。 |
originalChannelUniqueId | 平台原始通道 ID | varchar，对接设备/国标侧原始编码。 |
name | 通道名称 | 展示名。 |
label | 自定义标签 | varchar。 |
cascadeChannelUniqueId | 级联通道编号 | 可空、唯一；MaxId 的 cascadeChannel 类型用于生成。 |
cascadeDepUniqueId | 级联父级编号 | 分组/设备/平台侧父级标识（注释语义）。 |
isCascade | 是否本机级联设备 | 1 表示是。 |
ptzType | 云台类型 | 与 variables.PTXTypes 注释一致（球机/枪机等）。 |
streamUrl | 接入码流地址 | ONVIF/流媒体源等场景。 |
cdnState / cdnUrl | CDN 开关与地址 | 开关 + URL。 |
longitude / latitude | 经纬度 | decimal 映射为 float64。 |
onDemandLiveState | 按需直播 | 0/1。 |
audioState | 是否开启音频 | 0/1。 |
transCodedState | 是否转码 | 0/1。 |
onlineAt | 上线时间 | 毫秒时间戳。 |
online | 在线状态 | 0 不在线，1 在线。 |
streamState | 流状态 | 是否在推/拉流等（见字段注释）。 |
recordingState | 是否录制中 | 见字段注释。 |
streamMSId | 当前媒体服务 ID | 关联流媒体实例。 |
parentID | 父目录 ID | 国标目录树上级的 uniqueId 类标识（CHAR(70)）。 |
parental | 是否有子节点 | 1 目录/组织节点，0 叶子通道。 |
original | 原始 Catalog 数据 | 库内 JSON 字符串；Item.Original 为 map[string]interface{}。 |
videos | 已保存录像信息 | 库内 JSON 数组字符串；Item.Videos 为 []*VideoItem（含 date 区间与 path）。CorrectionMap 会校验 path 与 date。 |
screenshots | 截图路径列表 | 库内 JSON 数组字符串；Item 为 []string。 |
snapshot | 快照 | 单 URL 或路径字符串。 |
depIds | 部门 ID 集合 | 库内 JSON 数组字符串；Item.DepIds 为 []uint64，与 departments.id 对应。 |
createdAt / updatedAt | 创建 / 更新时间 | 毫秒时间戳；Correction / CorrectionMap 维护 updatedAt。 |
3. Item 与 Channels 的字段对应
Item 在 data.go 中定义：
- 内嵌
*Channels：标量字段的 JSON 与Channels一致。 Original：API 为对象；落库为original字符串。Videos：API 为[]*VideoItem；落库为videos字符串。Screenshots：API 为[]string；落库为screenshots字符串。DepIds：API 为[]uint64；落库为depIdsJSON 字符串。UseDBCache：json:"-"。
更新场景下，CheckMap 校验列名属于 variables.Columns，并对 original / videos / screenshots / depIds 做类型转换后序列化为字符串写入 map。
4. 列名常量（variables.go）
| 常量 | 数据库列 |
|---|---|
ColumnID | id |
ColumnUniqueId | uniqueId |
ColumnDeviceUniqueId | deviceUniqueId |
ColumnOriginalChannelUniqueId | originalChannelUniqueId |
ColumnCascadeChannelUniqueId | cascadeChannelUniqueId |
ColumnCascadeDepUniqueId | cascadeDepUniqueId |
ColumnIsCascade | isCascade |
ColumnName | name |
ColumnLabel | label |
ColumnPtzType | ptzType |
ColumnStreamUrl | streamUrl |
ColumnCdnState | cdnState |
ColumnCdnUrl | cdnUrl |
ColumnLongitude | longitude |
ColumnLatitude | latitude |
ColumnOnDemandLiveState | onDemandLiveState |
ColumnAudioState | audioState |
ColumnTransCodedState | transCodedState |
ColumnRecordingState | recordingState |
ColumnOnline | online |
ColumnOnlineAt | onlineAt |
ColumnStreamState | streamState |
ColumnStreamMSId | streamMSId |
ColumnOriginal | original |
ColumnVideos | videos |
ColumnScreenshots | screenshots |
ColumnSnapshot | snapshot |
ColumnDepIds | depIds |
ColumnParental | parental |
ColumnParentID | parentID |
ColumnCreatedAt | createdAt |
ColumnUpdatedAt | updatedAt |
PrimaryId 为 "id"。
5. 行为与联调注意点
- 缓存：
Channels.UseCache()开启内存缓存（前缀为表名，约 60 秒），且包含UpdateDelete等选项；排障时注意缓存滞后。 - 唯一性：业务上以
deviceUniqueId+uniqueId唯一定位一条通道记录（与前端/国标目录同步约定一致）。 - 精简列表：
DB.XList仅 SELECT 部分列并单独解析depIds，用于高性能列表或关联场景。 - 与设备、部门：删除设备时往往联动删除通道；部门与通道、设备的
depIds在部分初始化流程中会保持一致性处理。
6. 相关代码路径
- 模型包：
core/repositories/models/channels/ - DB 迁移与模型注入：
core/app/sev/db/internal/svc/init_database.go、service_context.go - 通道 RPC 逻辑：
core/app/sev/db/internal/logic/deviceservice/channel_*.go - HTTP 处理器：
core/app/sev/backend/internal/handler/device/channels/ - 级联通道编号：
core/app/sev/db/internal/logic/configservice/max_id_logic.go（cascadeChannel） - 与设备部门同步：
core/app/sev/db/internal/svc/proc.go
