平台级联数据模型（core/repositories/models/cascade）
本文说明 GB28181 平台级联（GBC：下级平台向上级注册/保活/目录关系） 配置实体 core/repositories/models/cascade 的职责、字段含义，及与 VSS 运行时结构的关系。
1. 在项目中承担的作用
该模型描述 一条「上级联平台」连接配置：数据落在表 sk-cascade。字段覆盖 对端 SIP 国标编码、域、IP/端口、认证、本地出口 IP、注册/心跳周期、relations 中允许参与级联的目录或通道节点 等。VSS 进程内 types.ServiceContext 持有 CascadeRecords []*cascade.Item，在 录像目录应答、报警 等逻辑中按 relations 与通道的 CascadeChannelUniqueId 匹配，决定是否向 上行 GBC 发送或转发（实现细节见 gbs_sip/video_records.go、alarm.go）。GBCKeepaliveChan、CascadeRegister* 等 map 与通道配合维护 GBC 注册与保活状态。
| 层级 | 作用 |
|---|---|
| 数据层 | core/app/sev/db/internal/svc/init_database.go 对 cascade.Cascade 执行 AutoMigrate；ServiceContext 注入 CascadeModel（core/app/sev/db/internal/svc/service_context.go）。 |
| 运行时 | VSS core/app/sev/vss/internal/types.ServiceContext 使用 cascade.Item（含运行时 XSipRegisterState / XSipAuth 等 非持久化 字段）及 CascadeRecords 列表。 |
| 信令 | GBC 注册、保活、Invite/转发等逻辑与 Item 上 MakeGBCRegisterExecutingKey、DelayRegisterTimeout 等辅助方法配合。 |
UseCache() 返回 nil，本表 不启用 ORM 模型级内存缓存。
2. 表与字段：数据库列 ↔ Go ↔ JSON
实体 Cascade 映射表 sk-cascade。
| 字段 | 含义 | 说明 |
|---|---|---|
id | 主键 | 自增。 |
name | 名称 | 展示名（通道名称/级联配置名称，以代码为准）。 |
uniqueId | 业务 UID | CHAR(70)，唯一索引 Cascade_UniqueId。 |
protocol | 信令传输协议 | 1 UDP、2 TCP（见 ProtocolMaps；与常量 Protocol_UDP/Protocol_TCP 对应，注意常量名与数值约定）。 |
sipId | 对端 SIP 国标编码 | 文本。 |
sipDomain | 对端 SIP 域 | 文本。 |
sipIp / sipPort | 对端 SIP 地址端口 | |
username | SIP 认证用户 | 唯一索引，注意安全存储。 |
password | SIP 认证密码 | 注意安全存储。 |
localIp | 本机级联出口 IP | 与对端可达性相关。 |
keepaliveInterval | 心跳间隔 | 秒。 |
registerInterval | 注册间隔 | 秒。 |
registerTimeout | 注册有效期 | 秒；Item.DelayRegisterTimeout()会在过短时下限 30s 并略提前续约。 |
commandTransport | 命令传输方式 | 信令 TCP/UDP，数值含义同 protocol 一类约定。 |
state | 是否启用 | 0 未启用，1 启用。 |
online | 是否在线 | 0 不在线，1 在线（由信令/任务刷新，具体见 VSS GBC 逻辑）。 |
relations | 分组/通道集合 | 库内 JSON 数组字符串；元素为 RelationItem（parental + uniqueId），可与通道级联编号或目录节点 id 对齐。 |
catalogGroupSize | 目录分组大小 | 默认 4，用于 Catalog 分包等行为（与国标目录同步相关）。 |
createdAt / updatedAt | 创建 / 更新时间 | 毫秒时间戳；Correction / CorrectionMap 维护。 |
3. Item 与 Cascade 的字段对应
- 内嵌
*Cascade：标量与Cascade的json一致。 Relations：API 为[]RelationItem；落库为relations字符串。UseDBCache、XSipRegisterState、XSipAuth：gorm:"column:-"，不落库；供 GBC 连接过程使用。
4. 列名常量（variables.go）
| 常量 | 数据库列 |
|---|---|
ColumnId | id |
ColumnUniqueId | uniqueId |
ColumnName | name |
ColumnProtocol | protocol |
ColumnSipId | sipId |
ColumnSipDomain | sipDomain |
ColumnSipIp | sipIp |
ColumnSipPort | sipPort |
ColumnUsername | username |
ColumnPassword | password |
ColumnLocalIp | localIp |
ColumnKeepaliveInterval | keepaliveInterval |
ColumnRegisterInterval | registerInterval |
ColumnRegisterTimeout | registerTimeout |
ColumnCommandTransport | commandTransport |
ColumnState | state |
ColumnOnline | online |
ColumnCatalogGroupSize | catalogGroupSize |
ColumnRelations | relations |
ColumnCreatedAt | createdAt |
ColumnUpdatedAt | updatedAt |
PrimaryId 为 "id"。
5. 行为与联调注意点
CascadeModel与 VSS：DB 服务已注册CascadeModel；VSS 侧主要通过 RPC + 内存中的CascadeRecords消费配置，二者由数据同步/拉取逻辑衔接（以实际FetchData或配置下发为准）。relations匹配：转发时常 跳过parental==true的目录项，只对 叶子uniqueId与通道CascadeChannelUniqueId相等性做匹配（见video_records.go、alarm.go）。
6. 相关代码路径
- 模型包：
core/repositories/models/cascade/ - DB：
core/app/sev/db/internal/svc/init_database.go、service_context.go（CascadeModel） - VSS 类型与通道：
core/app/sev/vss/internal/types/types.go、internal/svc/service_context.go - 级联匹配与转发：
core/app/sev/vss/internal/logic/gbs_sip/alarm.go、video_records.go - SSE 中的级联数量展示：
core/app/sev/vss/internal/logic/sse/sev_state.go
