model

type AgentCallLog struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// TokenID 鉴权成功后的 agent token 主键。
	TokenID uint `gorm:"not null;index:idx_agent_call_token_created,priority:1;index" json:"tokenId"`
	// TokenName 冗余快照（吊销后仍可读）。
	TokenName string `gorm:"type:varchar(128);not null" json:"tokenName"`
	// Action 与 service.AgentAction* 或 MCP 事件对齐（如 agent.whoami）。
	Action string `gorm:"type:varchar(64);not null;index:idx_agent_call_action_created,priority:1" json:"action"`
	// Capability 本次授权实际使用的能力标签（V2 capability 或 V1 legacy.*）；会话事件可空。
	Capability string `gorm:"type:varchar(64)" json:"capability,omitempty"`
	// Client 调用方：mcp | jmagent | curl | unknown（优先 X-JM-Agent-Client）。
	Client string `gorm:"type:varchar(32);not null;default:unknown" json:"client"`
	// Transport 可选：streamable_http | sse | http | 空。
	Transport string `gorm:"type:varchar(32)" json:"transport,omitempty"`
	// TargetType 目标类型（instance/node 等，可空）。
	TargetType string `gorm:"type:varchar(32)" json:"targetType,omitempty"`
	// TargetID 目标 ID 字符串（可空）。
	TargetID string `gorm:"type:varchar(64)" json:"targetId,omitempty"`
	// Success 是否成功（策略 403 记 false；业务失败亦 false）。
	Success bool `json:"success"`
	// Error 失败时截断短文（禁 Token 明文）。
	Error string `gorm:"type:varchar(512)" json:"error,omitempty"`
	// LatencyMs 处理耗时毫秒。
	LatencyMs uint `json:"latencyMs"`
	// IP 客户端 IP。
	IP string `gorm:"type:varchar(64)" json:"ip"`
	// CreatedAt 写入时间；复合索引供按 token/时间、action/时间查询。
	CreatedAt time.Time `gorm:"index:idx_agent_call_token_created,priority:2;index:idx_agent_call_action_created,priority:2;index" json:"createdAt"`
}

type AgentToken struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// Name 运营可见名称。
	Name string `gorm:"type:varchar(128);not null" json:"name"`
	// TokenHash 明文的 SHA-256 十六进制小写。库内不存明文。
	TokenHash string `gorm:"column:token_hash;type:char(64);uniqueIndex;not null" json:"-"`
	// TokenPrefix 明文前缀（如 jmat_ab12），仅供列表识别。
	TokenPrefix string `gorm:"column:token_prefix;type:varchar(16);not null" json:"tokenPrefix"`
	// ScopedInstanceIDs 可访问实例 ID 列表（JSON 数组）。空表示「未授权任何实例读/写」——默认从严。
	ScopedInstanceIDs string `gorm:"column:scoped_instance_ids;type:text" json:"scopedInstanceIds"`
	// ScopedNodeIDs 可访问节点 ID 列表（JSON 数组）。空表示未授权任何节点。
	ScopedNodeIDs string `gorm:"column:scoped_node_ids;type:text" json:"scopedNodeIds"`
	// WriteAllowlist 写操作白名单（JSON 字符串数组），如 ["instance.life","node.maintenance"]。
	// 仅 V1 策略使用；V2 保持空并改用 Capabilities。
	WriteAllowlist string `gorm:"column:write_allowlist;type:text" json:"writeAllowlist"`
	// PolicyVersion 策略版本：1=V1 写白名单；2=V2 capability。既有记录默认 1。
	PolicyVersion int `gorm:"column:policy_version;not null;default:1" json:"policyVersion"`
	// Capabilities V2 能力分组（JSON 字符串数组）。仅 policy_version=2 使用。
	Capabilities string `gorm:"column:capabilities;type:text" json:"capabilities,omitempty"`
	// ExpiresAt 过期时间；到期即校验失败。
	ExpiresAt time.Time `gorm:"not null;index" json:"expiresAt"`
	// Revoked 吊销标记；true 即立即失效。
	Revoked bool `gorm:"default:false;not null;index" json:"revoked"`
	// LastUsedAt 最近一次成功鉴权时间（可选更新）。
	LastUsedAt *time.Time `json:"lastUsedAt"`
	CreatedAt  time.Time  `json:"createdAt"`
	// CreatedBy 签发该 token 的平台管理员用户 ID。
	CreatedBy uint `json:"createdBy"`
}

type AgentTransferTicket struct {
	Digest     string     `gorm:"primaryKey;type:char(64)"`
	ExpiresAt  time.Time  `gorm:"not null;index"`
	ConsumedAt *time.Time `gorm:"index"`
	CreatedAt  time.Time
}

type AlertChannel struct {
	ID      uint   `gorm:"primaryKey" json:"id"`
	UUID    string `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	Name    string `gorm:"type:varchar(128);not null" json:"name"`
	Type    string `gorm:"type:varchar(32);not null" json:"type"`
	Enabled bool   `gorm:"default:true" json:"enabled"`
	// Config 通道连接配置的 JSON 串。各类型字段不同（见 service/channel_notifier.go ChannelConfig）：
	//   webhook/dingtalk/wecom/feishu/discord: {"url":"${ENV}"}（URL 含 access_token/secret，强制 ${ENV} 引用）
	//   telegram: {"token":"${ENV}","chatId":"..."}
	//   email:    {"host","port","username","password":"${ENV}","from","to"}
	//   inapp:    {}（无外部配置）
	// 凭证子字段（URL/token/password）强制经 ${ENV_VAR} 引用，CreateChannel/UpdateChannel 时校验、发送时解析。
	Config    string         `gorm:"type:text" json:"config"`
	CreatedAt time.Time      `json:"createdAt"`
	UpdatedAt time.Time      `json:"updatedAt"`
	DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`
}

type AlertEvent struct {
	ID       uint `gorm:"primaryKey" json:"id"`
	RuleID   uint `gorm:"not null;index" json:"ruleId"`
	TargetID uint `json:"targetId"`
	// Level/TriggerType 冗余快照规则当时的级别与类型，便于历史筛选（规则可能被改/删）。
	Level       string `gorm:"type:varchar(16);default:warn" json:"level"`
	TriggerType string `gorm:"type:varchar(32);default:metric" json:"triggerType"`
	// DedupKey 去抖键（rule + target + 触发标识）。聚合窗口内复发更新同一活跃事件而非新建。
	DedupKey string  `gorm:"type:varchar(256);index" json:"-"`
	Value    float64 `json:"value"`
	Message  string  `gorm:"type:varchar(512)" json:"message"`
	// Count 聚合计数：去抖窗口内该告警被触发的次数（≥1）。
	Count    int       `gorm:"default:1" json:"count"`
	Resolved bool      `gorm:"default:false" json:"resolved"`
	FiredAt  time.Time `json:"firedAt"`
	// LastFiredAt 最近一次复发时间（聚合时更新）。
	LastFiredAt *time.Time `json:"lastFiredAt"`
	ResolvedAt  *time.Time `json:"resolvedAt"`

	// ── 确认 / 已读（FR-085）──
	Acknowledged   bool       `gorm:"default:false" json:"acknowledged"`
	AcknowledgedBy *uint      `json:"acknowledgedBy"`
	AcknowledgedAt *time.Time `json:"acknowledgedAt"`
	// Read 站内已读状态（仅影响未读角标，不影响确认）。
	Read bool `gorm:"default:false" json:"read"`

	Rule AlertRule `gorm:"foreignKey:RuleID" json:"rule,omitempty"`
}

type AlertRule struct {
	ID   uint   `gorm:"primaryKey" json:"id"`
	UUID string `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	Name string `gorm:"type:varchar(128);not null" json:"name"`
	// TriggerType 触发类型（FR-085）：metric|instance_crash|node_offline|log_keyword|player_event|backup_failed。
	// 为兼容 FR-011 存量规则，空值按 metric 处理。
	TriggerType string `gorm:"type:varchar(32);default:metric" json:"triggerType"`
	// Level 告警级别（FR-085）：info|warn|critical。空值按 warn 处理。
	Level      string `gorm:"type:varchar(16);default:warn" json:"level"`
	TargetType string `gorm:"type:varchar(32);not null" json:"targetType"` // node, instance
	TargetID   *uint  `json:"targetId"`                                    // nil 表示全局

	// ── metric 触发专用（FR-011）──
	Metric      string  `gorm:"type:varchar(64)" json:"metric"`  // cpu, memory, disk
	Operator    string  `gorm:"type:varchar(4)" json:"operator"` // >, <, >=, <=, ==
	Threshold   float64 `json:"threshold"`
	DurationSec int     `gorm:"default:0" json:"durationSec"`

	// ── 非指标触发专用（FR-085）──
	// Keyword 日志关键字触发的匹配子串（log_keyword）。
	Keyword string `gorm:"type:varchar(256)" json:"keyword"`
	// EventMatch 玩家事件触发的子类型（player_event）：join|quit|chat|cross_server，空=任意。
	EventMatch string `gorm:"type:varchar(64)" json:"eventMatch"`

	// ── 聚合 / 静默 / 路由（FR-085）──
	// ChannelIDs 路由目标通道 ID 列表的 JSON 串（如 "[1,2]"）。空=不发外部通知（仍入事件库 + 站内）。
	ChannelIDs string `gorm:"type:varchar(256)" json:"channelIds"`
	// DedupWindowSec 去抖聚合窗口（秒）。同一告警键在窗口内重复触发只通知一次、累计计数。0=不去抖。
	DedupWindowSec int `gorm:"default:0" json:"dedupWindowSec"`
	// SilenceStart/SilenceEnd 静默窗口（"HH:MM" 24h，本地时区）。落在窗口内触发的告警不发外部通知（仍入库）。
	// 支持跨午夜（start > end，如 23:00→07:00）。两者皆空=不静默。
	SilenceStart string `gorm:"type:varchar(8)" json:"silenceStart"`
	SilenceEnd   string `gorm:"type:varchar(8)" json:"silenceEnd"`
	// NotifyRecover 恢复时是否发送恢复通知（仅对可恢复的触发类型：metric/instance_crash/node_offline）。
	NotifyRecover bool `json:"notifyRecover"`

	// NotifyType/NotifyTarget 兼容 FR-011 的单 webhook 直发（未配置 ChannelIDs 时回退）。
	NotifyType   string `gorm:"type:varchar(32)" json:"notifyType"`
	NotifyTarget string `gorm:"type:varchar(512)" json:"-"`

	Enabled   bool           `gorm:"default:true" json:"enabled"`
	CreatedAt time.Time      `json:"createdAt"`
	UpdatedAt time.Time      `json:"updatedAt"`
	DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`
}

type ArtifactMigration struct {
	ID     uint   `gorm:"primaryKey" json:"id"`
	TaskID string `gorm:"type:varchar(64);uniqueIndex;not null" json:"taskId"`
	// TargetChannelID 目标渠道（重试 = 对同目标重新发起的解析源）。
	TargetChannelID uint `gorm:"not null;index" json:"targetChannelId"`
	// Total 快照内全部 client-file 存量数。
	Total int `gorm:"not null;default:0" json:"total"`
	// Migrated 本次任务实际搬运成功数。
	Migrated int `gorm:"not null;default:0" json:"migrated"`
	// Failed 本次任务失败条数（明细见 ArtifactMigrationFailure）。
	Failed int `gorm:"not null;default:0" json:"failed"`
	// Skipped 发起时已在目标渠道数（续跑时「上轮已迁」体现于此）。
	Skipped   int       `gorm:"not null;default:0" json:"skipped"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type ArtifactMigrationFailure struct {
	ID      uint   `gorm:"primaryKey" json:"id"`
	TaskID  string `gorm:"type:varchar(64);not null;index" json:"taskId"`
	AssetID uint   `json:"assetId"`
	// SHA256 制品内容寻址键（定位失败制品）。
	SHA256    string    `gorm:"type:char(64);not null" json:"sha256"`
	Filename  string    `gorm:"type:varchar(255)" json:"filename"`
	Size      int64     `json:"size"`
	Reason    string    `gorm:"type:text" json:"reason"`
	CreatedAt time.Time `json:"createdAt"`
}

type ArtifactPackage struct {
	ID               uint      `gorm:"primaryKey" json:"id"`
	Key              string    `gorm:"type:varchar(128);not null;uniqueIndex" json:"key"`
	Name             string    `gorm:"type:varchar(255);not null" json:"name"`
	AssetType        AssetType `gorm:"type:varchar(32);not null" json:"assetType"`
	DefaultVersionID uint      `gorm:"default:0;index" json:"defaultVersionId"`
	CreatedAt        time.Time `json:"createdAt"`
	UpdatedAt        time.Time `json:"updatedAt"`
}

type ArtifactReconcileDiff struct {
	ID        uint `gorm:"primaryKey" json:"id"`
	RunID     uint `gorm:"not null;index" json:"runId"`
	ChannelID uint `gorm:"not null;index" json:"channelId"`
	// Kind missing | orphan。
	Kind string `gorm:"type:varchar(16);not null;index" json:"kind"`
	// AssetID missing：资产 ID；orphan：0（对象不在索引，无资产可指）。
	AssetID uint `json:"assetId"`
	// SHA256 missing：资产内容寻址键；orphan 空。
	SHA256 string `gorm:"type:char(64)" json:"sha256"`
	// ObjectKey CAS 相对键（missing=Asset.RelPath；orphan=剥渠道前缀后的对象键）。
	ObjectKey string `gorm:"type:varchar(512);not null" json:"objectKey"`
	Size      int64  `json:"size"`
	// LastModified orphan：S3 对象 Last-Modified；missing nil。
	LastModified *time.Time `json:"lastModified"`
	// Status open | resolved。
	Status     string     `gorm:"type:varchar(16);not null;default:open" json:"status"`
	ResolvedAt *time.Time `json:"resolvedAt"`
	// ResolvedAction marked_lost | cleaned | stale。
	ResolvedAction string `gorm:"type:varchar(32)" json:"resolvedAction"`
	// ResolveError 清理失败原因（保持 open 供重试）。
	ResolveError string    `gorm:"type:varchar(512)" json:"resolveError"`
	CreatedAt    time.Time `json:"createdAt"`
}

type ArtifactReconcileRun struct {
	ID        uint `gorm:"primaryKey" json:"id"`
	ChannelID uint `gorm:"not null;index" json:"channelId"`
	// ChannelName 渠道名快照：渠道后续改名/删除不影响历史报告可读。
	ChannelName string `gorm:"type:varchar(128)" json:"channelName"`
	// Status running | succeeded | failed。
	Status string `gorm:"type:varchar(16);not null" json:"status"`
	// TriggeredBy manual | scheduled。
	TriggeredBy string     `gorm:"type:varchar(16);not null" json:"triggeredBy"`
	StartedAt   time.Time  `json:"startedAt"`
	FinishedAt  *time.Time `json:"finishedAt"`
	// IndexCount 索引侧扫描条数（该渠道 s3 资产数，含已 lost）。
	IndexCount int `json:"indexCount"`
	// ObjectCount 对象侧扫描条数（渠道 prefix 下 CAS client-file 命名空间内）。
	ObjectCount int `json:"objectCount"`
	// MatchedCount 两侧一致数（仅计数不落明细）。
	MatchedCount int `json:"matchedCount"`
	MissingCount int `json:"missingCount"`
	OrphanCount  int `json:"orphanCount"`
	// ErrorMessage failed 时的原因（截断 512）。
	ErrorMessage string    `gorm:"type:varchar(512)" json:"errorMessage"`
	CreatedAt    time.Time `json:"createdAt"`
}

type ArtifactReconcileSetting struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// Enabled 定期对账开关，默认开。
	Enabled bool `gorm:"not null;default:true" json:"enabled"`
	// IntervalHours 周期小时数，默认 24（每日），钳制 [1,720]。
	IntervalHours int `gorm:"not null;default:24" json:"intervalHours"`
	// NextRunAt 下次定期触发时间；禁用时 nil。首个周期从启用/启动时刻起算（不在启动瞬间扫存储）。
	NextRunAt *time.Time `json:"nextRunAt"`
	UpdatedAt time.Time  `json:"updatedAt"`
}

type ArtifactSource struct {
	ID           uint       `gorm:"primaryKey" json:"id"`
	PackageID    uint       `gorm:"not null;index;uniqueIndex:idx_artifact_sources_package_name" json:"packageId"`
	Provider     string     `gorm:"type:varchar(64);not null;index" json:"provider"`
	Name         string     `gorm:"type:varchar(255);not null;uniqueIndex:idx_artifact_sources_package_name" json:"name"`
	Config       string     `gorm:"type:text;not null" json:"config"`
	Enabled      bool       `gorm:"default:true;not null" json:"enabled"`
	LastSyncedAt *time.Time `json:"lastSyncedAt"`
	LastError    string     `gorm:"type:varchar(512)" json:"lastError"`
	CreatedAt    time.Time  `json:"createdAt"`
	UpdatedAt    time.Time  `json:"updatedAt"`
}

type ArtifactStorageChannel struct {
	ID   uint                       `gorm:"primaryKey" json:"id"`
	Name string                     `gorm:"type:varchar(128);not null;uniqueIndex" json:"name"`
	Type ArtifactStorageChannelType `gorm:"type:varchar(16);not null" json:"type"`
	// Endpoint S3 主机[:端口]，容带 scheme（适配器剥离）。
	Endpoint string `gorm:"type:varchar(512)" json:"endpoint"`
	// Bucket S3 桶名。
	Bucket string `gorm:"type:varchar(255)" json:"bucket"`
	// Region SigV4 region，缺省 us-east-1。
	Region string `gorm:"type:varchar(64)" json:"region"`
	// Prefix 对象键前缀；真实对象键 = <Prefix>/<CAS 相对路径>。
	Prefix string `gorm:"type:varchar(255)" json:"prefix"`
	// AccessKeyEnc/SecretKeyEnc AES-256-GCM 可逆加密密文（base64）。
	// json:"-"：任何 API 响应不回明文也不回密文，列表以 Has* 布尔示意。
	AccessKeyEnc string `gorm:"type:text" json:"-"`
	SecretKeyEnc string `gorm:"type:text" json:"-"`
	// UseSSL S3 走 https；false 走 http（rustfs/MinIO 内网常态）。
	// 不用 gorm default:true，否则 GORM 会把显式 false（零值）覆盖回 true（同 BackupStorage 先例）。
	UseSSL bool `json:"useSsl"`
	// PresignTTLSeconds 预签名 URL 有效期秒数，默认 600（10 分钟），service 钳制 [60, 3600]。
	PresignTTLSeconds int `gorm:"default:600;not null" json:"presignTtlSeconds"`
	// Active 活跃渠道标记：写路径唯一路由开关（全表恰一条，service 事务保证）。
	Active bool `gorm:"default:false;not null" json:"active"`
	// Builtin 内置「本机存储」渠道：不可删、不可编辑，兜底活跃。
	Builtin bool `gorm:"default:false;not null" json:"builtin"`
	// LastTest* 最近一次已存渠道连通性测试结果；表单临时测试不写入。
	LastTestAt      *time.Time `json:"lastTestAt,omitempty"`
	LastTestOk      bool       `json:"lastTestOk"`
	LastTestMessage string     `gorm:"type:varchar(255)" json:"lastTestMessage"`
	// HasAccessKey/HasSecretKey 列表标示凭证已配（不回明文/密文），service 填充。
	HasAccessKey bool      `gorm:"-" json:"hasAccessKey"`
	HasSecretKey bool      `gorm:"-" json:"hasSecretKey"`
	CreatedAt    time.Time `json:"createdAt"`
	UpdatedAt    time.Time `json:"updatedAt"`
}

type ArtifactStorageChannelType string

type ArtifactVersion struct {
	ID             uint       `gorm:"primaryKey" json:"id"`
	PackageID      uint       `gorm:"not null;index" json:"packageId"`
	SourceID       uint       `gorm:"not null;index;uniqueIndex:idx_artifact_versions_source_version" json:"sourceId"`
	Version        string     `gorm:"type:varchar(128);not null;uniqueIndex:idx_artifact_versions_source_version" json:"version"`
	ReleaseRef     string     `gorm:"type:varchar(255);not null" json:"releaseRef"`
	AssetName      string     `gorm:"type:varchar(255);not null" json:"assetName"`
	ExpectedSHA256 string     `gorm:"type:char(64);not null" json:"expectedSha256"`
	SourceURL      string     `gorm:"type:varchar(1024);not null" json:"sourceUrl"`
	AssetID        uint       `gorm:"default:0;index" json:"assetId"`
	CachedAt       *time.Time `json:"cachedAt"`
	LastError      string     `gorm:"type:varchar(512)" json:"lastError"`
	CreatedAt      time.Time  `json:"createdAt"`
	UpdatedAt      time.Time  `json:"updatedAt"`

	Asset *Asset `gorm:"foreignKey:AssetID" json:"asset,omitempty"`
}

type Asset struct {
	ID   uint      `gorm:"primaryKey" json:"id"`
	Type AssetType `gorm:"type:varchar(32);not null;index;uniqueIndex:idx_assets_type_sha256" json:"type"`
	// Name 人类可读名称（如 "paper-1.20.4"），非寻址键。
	Name string `gorm:"type:varchar(255);index" json:"name"`
	// Version 版本标记（如 "1.20.4-435"），可空。
	Version string `gorm:"type:varchar(128)" json:"version"`
	// Filename 入库时的原始文件名，决定存储扩展名与下载名。
	Filename string `gorm:"type:varchar(255)" json:"filename"`
	// SHA256 内容寻址 + 去重键（十六进制小写）。
	SHA256 string `gorm:"type:char(64);not null;index;uniqueIndex:idx_assets_type_sha256" json:"sha256"`
	// MD5 辅助完整性校验（十六进制小写）。
	MD5 string `gorm:"type:char(32)" json:"md5"`
	// Size 字节数。
	Size int64 `gorm:"not null" json:"size"`
	// ContentType MIME 类型。
	ContentType string `gorm:"type:varchar(128)" json:"contentType"`
	// SourceURL 来源地址（下载入库时记录），可空。
	SourceURL string `gorm:"type:varchar(1024)" json:"sourceUrl"`
	// Metadata 类型相关的扩展元数据（JSON 字符串）。
	Metadata string `gorm:"type:text" json:"metadata"`
	// StorageState 冷热/外置状态，默认 hot。
	StorageState AssetStorageState `gorm:"type:varchar(32);default:hot;not null" json:"storageState"`
	// StorageBackend 存储后端标识，默认 local。
	StorageBackend string `gorm:"type:varchar(64);default:local;not null" json:"storageBackend"`
	// StorageChannelID 外置存储渠道引用（FR-347，见 ADR-073）：0=本地/无渠道（历史行为），
	// >0 时指向 artifact_storage_channels.id——位置由记录自述，不由全局活跃状态推断。
	StorageChannelID uint `gorm:"default:0;not null;index" json:"storageChannelId"`
	// RefCount 引用计数，>0 时禁止删除（被模板/实例占用）。
	RefCount int `gorm:"default:0;not null" json:"refCount"`
	// RelPath 物理文件相对数据根的路径（var/artifacts/<type>/<ab>/<sha256><ext>），便携登记。
	RelPath    string     `gorm:"type:varchar(512)" json:"relPath"`
	CreatedAt  time.Time  `json:"createdAt"`
	LastUsedAt *time.Time `json:"lastUsedAt"`
}

type AssetStorageState string

type AssetType string

type AuditLog struct {
	ID         uint   `gorm:"primaryKey" json:"id"`
	UUID       string `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	UserID     uint   `gorm:"not null;index" json:"userId"`
	Action     string `gorm:"type:varchar(64);not null" json:"action"` // instance.start, user.create, etc.
	TargetType string `gorm:"type:varchar(32)" json:"targetType"`      // instance, user, group
	TargetID   string `gorm:"type:varchar(64)" json:"targetId"`
	Detail     string `gorm:"type:text" json:"detail"` // JSON
	IP         string `gorm:"type:varchar(64)" json:"ip"`
	// Failed 操作是否失败（FR-321：失败操作也留痕并带错误内容）。语义取「失败」而非「成功」：
	// 失败是非零值 true，规避 GORM 零值列不进 INSERT 的坑（存 success 时 false 会被 default 吃掉），
	// 且历史行零值天然=未失败，无需迁移回填。
	Failed bool `json:"failed"`
	// Error 失败时的错误内容（响应 error body 截断，FR-321）。
	Error     string    `gorm:"type:varchar(512)" json:"error"`
	CreatedAt time.Time `json:"createdAt"`
	User      User      `gorm:"foreignKey:UserID" json:"user,omitempty"`
}

type AuthSetupLock struct {
	Key       string    `gorm:"type:varchar(64);primaryKey"`
	CreatedAt time.Time `json:"not null"`
}

type Backup struct {
	ID         uint         `gorm:"primaryKey" json:"id"`
	UUID       string       `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	InstanceID uint         `gorm:"not null;index" json:"instanceId"`
	Name       string       `gorm:"type:varchar(128);not null" json:"name"`
	FilePath   string       `gorm:"type:varchar(512)" json:"filePath"`
	FileSizeMB float64      `gorm:"default:0" json:"fileSizeMb"`
	Type       BackupType   `gorm:"default:0" json:"type"`
	Mode       BackupMode   `gorm:"default:0" json:"mode"`
	Status     BackupStatus `gorm:"default:0" json:"status"`
	// ParentID 增量备份的父备份 ID，串成备份链；全量备份为 nil（FR-056）。
	ParentID *uint `gorm:"index" json:"parentId,omitempty"`
	// Manifest 本次备份完成后工作目录的完整文件清单（JSON 序列化的 manifest 数组）。
	// 作为下一次增量的基准与链式恢复的依据，由 Worker 返回、CP 持久化。
	Manifest string `gorm:"type:text" json:"-"`
	// StorageID 远程存储后端 ID；nil 表示存于节点本地数据根（FR-057）。
	StorageID *uint `gorm:"index" json:"storageId,omitempty"`
	// StorageKey 上传到远程后端的对象键；本地备份为空（FR-057）。
	StorageKey string `gorm:"type:varchar(512)" json:"storageKey,omitempty"`
	// Checksum 归档 tar.gz 的 SHA-256，用于恢复前完整性校验（FR-171）。
	Checksum string `gorm:"type:char(64)" json:"checksum,omitempty"`
	// ChecksumAlgo 校验算法，当前固定 sha256（FR-171）。
	ChecksumAlgo string         `gorm:"type:varchar(16)" json:"checksumAlgo,omitempty"`
	CreatedAt    time.Time      `json:"createdAt"`
	DeletedAt    gorm.DeletedAt `gorm:"index" json:"-"`
}

type BackupMode int

type BackupStatus int

type BackupStorage struct {
	ID   uint   `gorm:"primaryKey" json:"id"`
	Name string `gorm:"type:varchar(128);not null" json:"name"`
	// ActiveNameKey 仅活跃记录保存名称，软删时置 NULL；SQLite/MySQL 均允许唯一索引中的多个 NULL。
	ActiveNameKey *string           `gorm:"type:varchar(128);uniqueIndex:uniq_backup_storage_active_name_key" json:"-"`
	Type          BackupStorageType `gorm:"type:varchar(32);not null" json:"type"`
	// Endpoint S3 endpoint / WebDAV 基地址 / SFTP host[:port]。
	Endpoint string `gorm:"type:varchar(512)" json:"endpoint"`
	// Bucket S3 bucket（其余类型忽略）。
	Bucket string `gorm:"type:varchar(255)" json:"bucket"`
	// Region S3 region（SigV4 用，缺省 us-east-1）。
	Region string `gorm:"type:varchar(64)" json:"region"`
	// Prefix 对象键/远程目录前缀，便于多实例/多平台共用一个后端。
	Prefix string `gorm:"type:varchar(255)" json:"prefix"`
	// AccessKeyEnv 访问密钥的环境变量引用（如 ${JIANMANAGER_BACKUP_S3_AK}）。
	AccessKeyEnv string `gorm:"type:varchar(255)" json:"accessKeyEnv"`
	// SecretKeyEnv 密钥的环境变量引用（如 ${JIANMANAGER_BACKUP_S3_SK}）。
	SecretKeyEnv string `gorm:"type:varchar(255)" json:"secretKeyEnv"`
	// UseSSL S3 是否启用 TLS。默认由应用层（router/service）设为 true；
	// 不用 gorm default:true，否则 GORM 会把显式 false（零值）覆盖回 true。
	UseSSL bool `json:"useSsl"`
	// LastTest* 保存已落库后端最近一次连通性测试结果；表单临时测试不写入。
	LastTestAt      *time.Time `json:"lastTestAt,omitempty"`
	LastTestOk      bool       `json:"lastTestOk"`
	LastTestMessage string     `gorm:"type:varchar(255)" json:"lastTestMessage"`
	// BackupCount/UsedBytes 为 FR-152 列表聚合展示字段，不落库。
	BackupCount int64          `gorm:"-" json:"backupCount"`
	UsedBytes   int64          `gorm:"-" json:"usedBytes"`
	CreatedAt   time.Time      `json:"createdAt"`
	UpdatedAt   time.Time      `json:"updatedAt"`
	DeletedAt   gorm.DeletedAt `gorm:"index" json:"-"`
}

type BackupStorageType string

type BackupType int

type BanRecord struct {
	ID   uint   `gorm:"primaryKey" json:"id"`
	UUID string `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	// PlayerName 被封禁玩家名（大小写按客户端原样存储）。
	PlayerName string `gorm:"type:varchar(64);not null;index" json:"playerName"`
	// Reason 封禁原因（下发给 RCON ban 命令并入库留档）。
	Reason string `gorm:"type:varchar(512)" json:"reason"`
	// Scope 封禁范围：network / instance / global。
	Scope BanScope `gorm:"type:varchar(16);not null;default:global" json:"scope"`
	// ScopeID 范围目标 ID：network 时为 NetworkID，instance 时为 InstanceID，global 时为 0。
	ScopeID uint `gorm:"default:0" json:"scopeId"`
	// OperatorID 执行封禁的用户 ID（关联审计）。
	OperatorID uint `gorm:"not null;index" json:"operatorId"`
	// Active 是否仍被本平台视为生效；解封置 false，保留记录用于追溯。
	Active bool `gorm:"default:true;index" json:"active"`
	// CreatedAt 封禁时间。
	CreatedAt time.Time `json:"createdAt"`
	// UnbannedAt 解封时间；未解封为 nil。
	UnbannedAt *time.Time `json:"unbannedAt"`
	// Operator 关联用户，便于列表展示操作者用户名。
	Operator User `gorm:"foreignKey:OperatorID" json:"operator,omitempty"`
}

type BanScope string

type Bot struct {
	ID              uint      `gorm:"primaryKey" json:"id"`
	UUID            string    `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	InstanceID      uint      `gorm:"not null;index" json:"instanceId"`
	StressSessionID *uint     `gorm:"index" json:"stressSessionId,omitempty"`
	ExecutorNodeID  *uint     `gorm:"index;index:idx_bots_executor_generation,priority:1" json:"executorNodeId,omitempty"`
	LoadBatchID     *uint     `gorm:"index" json:"loadBatchId,omitempty"`
	Name            string    `gorm:"type:varchar(128);not null" json:"name"`
	Status          BotStatus `gorm:"type:varchar(32);default:pending" json:"status"`
	// DesiredState 是 CP 对 Bot 的期望运行态（running/stopped），与 runtime Status 分离（FR-365）。
	DesiredState           BotDesiredState `gorm:"type:varchar(16);not null;default:stopped;index" json:"desiredState"`
	WorkerEpoch            string          `gorm:"type:varchar(36);not null;default:''" json:"workerEpoch"`
	WorkerEpochGeneration  int64           `gorm:"not null;default:0" json:"workerEpochGeneration"`
	LastEventSeq           int64           `gorm:"not null;default:0" json:"lastEventSeq"`
	LastSeenAt             *time.Time      `json:"lastSeenAt,omitempty"`
	ConnectedAt            *time.Time      `json:"connectedAt,omitempty"`
	DesiredStateGeneration int64           `gorm:"not null;default:1;index:idx_bots_executor_generation,priority:2" json:"desiredStateGeneration"`
	ConfigHash             string          `gorm:"type:char(64);not null;default:''" json:"configHash"`
	// ReconnectCount 累计成功触发的自动重连次数，服务端恢复后不清零（FR-365）。
	ReconnectCount int    `gorm:"not null;default:0" json:"reconnectCount"`
	CohortKey      string `gorm:"type:varchar(64);not null;default:''" json:"cohortKey"`
	// LastError 最近一次委托 Worker 失败的原因（如 bot-worker 依赖未装、节点未连）。
	// 委托成功即清空；status=error 时前端据此显示可操作指引，杜绝「创建 201 但永远 pending 零反馈」。
	LastError string         `gorm:"type:text" json:"lastError,omitempty"`
	Config    string         `gorm:"type:text" json:"config"` // JSON: server, port, auth
	Behavior  string         `gorm:"type:varchar(64)" json:"behavior"`
	WorkerID  string         `gorm:"type:varchar(128)" json:"workerId"`
	CreatedAt time.Time      `json:"createdAt"`
	UpdatedAt time.Time      `json:"updatedAt"`
	DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`

	// Instance 表示被测目标实例和权限归属，不代表 Bot 实际执行位置。
	Instance Instance `gorm:"foreignKey:InstanceID" json:"-"`
	// ExecutorNode 是实际运行 Bot Worker 的节点；为空时兼容回退 Instance.NodeID。
	ExecutorNode *Node `gorm:"foreignKey:ExecutorNodeID;constraint:OnUpdate:CASCADE,OnDelete:RESTRICT" json:"executorNode,omitempty"`
	// LoadBatch 是分布式运行所属批次；删除批次时保留 Bot 并清空关联。
	LoadBatch *BotLoadBatch `gorm:"foreignKey:LoadBatchID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL" json:"-"`
	// StressSession 所属压测会话；删除会话时保留 Bot，并清空关联。
	StressSession *BotStressSession `gorm:"foreignKey:StressSessionID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL" json:"-"`
}

type BotDesiredState string

type BotLoadActionResult struct {
	ID               uint                      `gorm:"primaryKey" json:"id"`
	StressSessionID  uint                      `gorm:"not null;index" json:"stressSessionId"`
	BotID            uint                      `gorm:"not null;index" json:"botId"`
	CohortKey        string                    `gorm:"type:varchar(64);not null" json:"cohortKey"`
	StepID           string                    `gorm:"type:varchar(64);not null" json:"stepId"`
	ActionRunID      string                    `gorm:"type:char(36);not null;uniqueIndex" json:"actionRunId"`
	Attempt          int                       `gorm:"not null" json:"attempt"`
	Status           BotLoadActionResultStatus `gorm:"type:varchar(16);not null;index" json:"status"`
	ErrorCode        string                    `gorm:"type:varchar(64)" json:"errorCode,omitempty"`
	Message          string                    `gorm:"type:text" json:"message,omitempty"`
	DurationMS       int64                     `gorm:"not null;default:0" json:"durationMs"`
	CorrelationToken string                    `gorm:"type:varchar(128);index" json:"correlationToken,omitempty"`
	StartedAt        time.Time                 `gorm:"not null" json:"startedAt"`
	EndedAt          *time.Time                `json:"endedAt,omitempty"`
	ResultJSON       string                    `gorm:"type:longtext" json:"resultJson,omitempty"`
	CreatedAt        time.Time                 `json:"createdAt"`
	UpdatedAt        time.Time                 `json:"updatedAt"`

	StressSession BotStressSession `gorm:"foreignKey:StressSessionID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE" json:"-"`
	Bot           Bot              `gorm:"foreignKey:BotID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE" json:"-"`
}

type BotLoadActionResultStatus string

type BotLoadBatch struct {
	ID                uint              `gorm:"primaryKey" json:"id"`
	UUID              string            `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	StressSessionID   uint              `gorm:"not null;index;uniqueIndex:uniq_bot_load_batch_ordinal" json:"stressSessionId"`
	ExecutorNodeID    uint              `gorm:"not null;index" json:"executorNodeId"`
	Ordinal           int               `gorm:"not null;uniqueIndex:uniq_bot_load_batch_ordinal" json:"ordinal"`
	PlannedCount      int               `gorm:"not null" json:"plannedCount"`
	AcceptedCount     int               `gorm:"default:0" json:"acceptedCount"`
	ConnectedCount    int               `gorm:"default:0" json:"connectedCount"`
	FailedCount       int               `gorm:"default:0" json:"failedCount"`
	State             BotLoadBatchState `gorm:"type:varchar(16);default:planned;index" json:"state"`
	IdempotencyKey    string            `gorm:"type:varchar(128);uniqueIndex;not null" json:"idempotencyKey"`
	ConnectStartAt    time.Time         `json:"connectStartAt"`
	ConnectIntervalMS int               `gorm:"not null" json:"connectIntervalMs"`
	LastError         string            `gorm:"type:text" json:"lastError,omitempty"`
	StartedAt         *time.Time        `json:"startedAt,omitempty"`
	EndedAt           *time.Time        `json:"endedAt,omitempty"`
	CreatedAt         time.Time         `json:"createdAt"`
	UpdatedAt         time.Time         `json:"updatedAt"`

	StressSession BotStressSession `gorm:"foreignKey:StressSessionID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE" json:"-"`
	ExecutorNode  Node             `gorm:"foreignKey:ExecutorNodeID;constraint:OnUpdate:CASCADE,OnDelete:RESTRICT" json:"executorNode,omitempty"`
}

type BotLoadBatchState string

type BotLoadCommandCheckpoint struct {
	ID              uint                           `gorm:"primaryKey" json:"id"`
	StressSessionID uint                           `gorm:"not null;index" json:"stressSessionId"`
	BotID           *uint                          `gorm:"index" json:"botId,omitempty"`
	RunUUID         string                         `gorm:"type:char(36);not null;uniqueIndex:uniq_bot_load_cmd_ckpt_key" json:"runUuid"`
	BotUUID         string                         `gorm:"type:char(36);not null;uniqueIndex:uniq_bot_load_cmd_ckpt_key" json:"botUuid"`
	StepID          string                         `gorm:"type:varchar(64);not null;uniqueIndex:uniq_bot_load_cmd_ckpt_key" json:"stepId"`
	CommandID       string                         `gorm:"type:varchar(64);not null;uniqueIndex:uniq_bot_load_cmd_ckpt_key" json:"commandId"`
	Occurrence      int                            `gorm:"not null;uniqueIndex:uniq_bot_load_cmd_ckpt_key" json:"occurrence"`
	Generation      int64                          `gorm:"not null" json:"generation"`
	ScheduleRunID   string                         `gorm:"type:char(36);not null;index" json:"scheduleRunId"`
	ActionRunID     string                         `gorm:"type:char(36);not null;index" json:"actionRunId"`
	PlannedAtUnixMs *int64                         `json:"plannedAtUnixMs,omitempty"`
	SentAtUnixMs    *int64                         `json:"sentAtUnixMs,omitempty"`
	Attempt         int                            `gorm:"not null;default:0" json:"attempt"`
	Status          BotLoadCommandCheckpointStatus `gorm:"type:varchar(32);not null;index" json:"status"`
	ErrorCode       string                         `gorm:"type:varchar(64)" json:"errorCode,omitempty"`
	EndedAt         *time.Time                     `json:"endedAt,omitempty"`
	CreatedAt       time.Time                      `json:"createdAt"`
	UpdatedAt       time.Time                      `json:"updatedAt"`

	StressSession BotStressSession `gorm:"foreignKey:StressSessionID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE" json:"-"`
}

type BotLoadCommandCheckpointStatus string

type BotLoadMetricSample struct {
	ID              uint      `gorm:"primaryKey" json:"id"`
	StressSessionID uint      `` /* 132-byte string literal not displayed */
	SampledAt       time.Time `gorm:"not null;uniqueIndex:uniq_bot_load_metric_sample,priority:2" json:"sampledAt"`
	StageIndex      int       `gorm:"not null;index:idx_bot_load_metric_stage,priority:2" json:"stageIndex"`
	CountsJSON      string    `gorm:"type:longtext;not null" json:"countsJson"`
	CommandJSON     string    `gorm:"type:longtext;not null" json:"commandJson"`
	BarrierJSON     string    `gorm:"type:longtext;not null" json:"barrierJson"`
	ExecutorJSON    string    `gorm:"type:longtext;not null" json:"executorJson"`
	LatencyJSON     string    `gorm:"type:longtext;not null" json:"latencyJson"`
	ErrorsJSON      string    `gorm:"type:longtext;not null" json:"errorsJson"`
	// TargetLegacyJSON 可选 legacy 指标；缺失时 null，不写 0。
	TargetLegacyJSON *string   `gorm:"type:longtext" json:"targetLegacyJson,omitempty"`
	CreatedAt        time.Time `json:"createdAt"`

	StressSession BotStressSession `gorm:"foreignKey:StressSessionID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE" json:"-"`
}

type BotLoadRunEvent struct {
	ID              uint                `gorm:"primaryKey" json:"id"`
	StressSessionID uint                `` /* 179-byte string literal not displayed */
	RunUUID         string              `gorm:"type:char(36);not null" json:"runUuid"`
	Type            BotLoadRunEventType `gorm:"type:varchar(32);not null;index:idx_bot_load_run_event_type,priority:2" json:"type"`
	OccurredAt      time.Time           `gorm:"not null;index:idx_bot_load_run_event_time,priority:2" json:"occurredAt"`
	StageIndex      *int                `json:"stageIndex,omitempty"`
	ActionRunID     *string             `gorm:"type:char(36);index:idx_bot_load_run_event_action,priority:2" json:"actionRunId,omitempty"`
	BotUUID         *string             `gorm:"type:char(36);index:idx_bot_load_run_event_bot,priority:2" json:"botUuid,omitempty"`
	ExecutorNodeID  *uint               `gorm:"index:idx_bot_load_run_event_executor,priority:2" json:"executorNodeId,omitempty"`
	StepID          *string             `gorm:"type:varchar(64);index:idx_bot_load_run_event_step,priority:2" json:"stepId,omitempty"`
	PayloadJSON     string              `gorm:"type:longtext;not null" json:"payloadJson"`
	LegacyJSON      *string             `gorm:"type:longtext" json:"legacyJson,omitempty"`
	CreatedAt       time.Time           `json:"createdAt"`

	StressSession BotStressSession `gorm:"foreignKey:StressSessionID;constraint:OnUpdate:CASCADE,OnDelete:CASCADE" json:"-"`
}

type BotLoadRunEventType string

type BotLoadRunState string

type BotLoadTemplate struct {
	ID        uint   `gorm:"primaryKey" json:"id"`
	UUID      string `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	CreatedBy uint   `gorm:"not null;index;uniqueIndex:uniq_bot_load_tpl_active_name,priority:1" json:"createdBy"`
	// ActiveNameKey 为 trim 后名称 UTF-8 的 SHA-256 hex；软删时置 null 以允许复用名称。
	ActiveNameKey   *string        `gorm:"type:char(64);uniqueIndex:uniq_bot_load_tpl_active_name,priority:2" json:"-"`
	Name            string         `gorm:"type:varchar(128);not null" json:"name"`
	Description     string         `gorm:"type:text;not null" json:"description"`
	CommandSchedule string         `gorm:"type:longtext;not null" json:"commandSchedule"`
	LoadProfile     string         `gorm:"type:longtext;not null" json:"loadProfile"`
	Thresholds      string         `gorm:"type:longtext;not null" json:"thresholds"`
	Tags            string         `gorm:"type:longtext;not null" json:"tags"`
	CreatedAt       time.Time      `json:"createdAt"`
	UpdatedAt       time.Time      `json:"updatedAt"`
	DeletedAt       gorm.DeletedAt `gorm:"index" json:"-"`

	Creator User `gorm:"foreignKey:CreatedBy;constraint:OnUpdate:CASCADE,OnDelete:RESTRICT" json:"-"`
}

type BotLoadVerdict string

type BotStatus string

type BotStressSession struct {
	ID                   uint                   `gorm:"primaryKey" json:"id"`
	UUID                 string                 `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	InstanceID           uint                   `gorm:"not null;index" json:"instanceId"`
	Name                 string                 `gorm:"type:varchar(128);not null" json:"name"`
	NamePrefix           string                 `gorm:"type:varchar(64);not null" json:"namePrefix"`
	Status               BotStressSessionStatus `gorm:"type:varchar(32);default:pending;index" json:"status"`
	BotCount             int                    `gorm:"not null" json:"botCount"`
	Behavior             string                 `gorm:"type:varchar(64)" json:"behavior"`
	Config               string                 `gorm:"type:text" json:"config"`
	OrchestrationYAML    string                 `gorm:"type:text" json:"orchestrationYaml,omitempty"`
	OrchestrationSummary string                 `gorm:"type:text" json:"orchestrationSummary,omitempty"`
	ScenarioSnapshot     string                 `gorm:"type:longtext" json:"scenarioSnapshot,omitempty"`
	CommandScheduleSnap  string                 `gorm:"type:longtext" json:"commandScheduleSnapshot,omitempty"`
	AllocationPlan       string                 `gorm:"type:text" json:"allocationPlan,omitempty"`
	SchemaVersion        int                    `gorm:"type:smallint;not null;default:1;index" json:"schemaVersion"`
	// FR-370 V2 专属列：schemaVersion=1 历史行允许 null，schemaVersion=2 由 service 强制完整。
	TemplateID     *uint            `gorm:"index" json:"templateId,omitempty"`
	LoadProfile    string           `gorm:"type:longtext" json:"loadProfile,omitempty"`
	Thresholds     string           `gorm:"type:longtext" json:"thresholds,omitempty"`
	RunState       *BotLoadRunState `gorm:"type:varchar(32);index" json:"runState,omitempty"`
	CurrentStage   *int             `json:"currentStage,omitempty"`
	Verdict        *BotLoadVerdict  `gorm:"type:varchar(16);index" json:"verdict,omitempty"`
	MaxStableBots  *int             `json:"maxStableBots,omitempty"`
	FailureSummary string           `gorm:"type:longtext" json:"failureSummary,omitempty"`
	ReportSummary  string           `gorm:"type:longtext" json:"reportSummary,omitempty"`
	Succeeded      int              `gorm:"default:0" json:"succeeded"`
	Failed         int              `gorm:"default:0" json:"failed"`
	LastError      string           `gorm:"type:text" json:"lastError,omitempty"`
	StartedAt      *time.Time       `json:"startedAt,omitempty"`
	EndedAt        *time.Time       `json:"endedAt,omitempty"`
	CreatedAt      time.Time        `json:"createdAt"`
	UpdatedAt      time.Time        `json:"updatedAt"`
	DeletedAt      gorm.DeletedAt   `gorm:"index" json:"-"`

	Instance Instance         `gorm:"foreignKey:InstanceID" json:"instance,omitempty"`
	Template *BotLoadTemplate `gorm:"foreignKey:TemplateID;constraint:OnUpdate:CASCADE,OnDelete:SET NULL" json:"-"`
}

type BotStressSessionStatus string

type BusinessEvent struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// Domain 业务域命名空间（economy/inventory…）；与来源 scope、DedupKey 组成唯一去重键。
	Domain string `gorm:"type:varchar(32);not null;uniqueIndex:idx_be_scope_dedup,priority:1;index:idx_be_domain_time,priority:1" json:"domain"`
	// DedupKey 业务事件去重锚点（经济域为 mce ledgerId，只有 node→zone 内唯一）。
	DedupKey string `gorm:"column:dedup_key;type:varchar(128);not null;uniqueIndex:idx_be_scope_dedup,priority:4" json:"dedupKey"`
	// Action 业务事件子类型（economy_change…），供下游分流/展示。
	Action string `gorm:"type:varchar(64);not null" json:"action"`
	// NodeUUID 事件来源节点（经济多区/多节点聚合的 node→zone 维度起点）。
	NodeUUID string `gorm:"column:node_uuid;type:varchar(64);not null;uniqueIndex:idx_be_scope_dedup,priority:2;index:idx_be_node" json:"nodeUuid"`
	// ZoneID 经济事件的 mce 区；其它业务域为空串。账本 ID 只在 node→zone 内去重。
	ZoneID string `gorm:"column:zone_id;type:varchar(64);not null;default:'';uniqueIndex:idx_be_scope_dedup,priority:3" json:"zoneId,omitempty"`
	// InstanceUUID 事件来源实例（探针所在子服实例）。
	InstanceUUID string `gorm:"column:instance_uuid;type:varchar(64);index:idx_be_instance" json:"instanceUuid"`
	// Operator 操作者身份透传位（FR-121 业务写横切硬化时回填"哪个管理员/为什么"；自发事件为空）。
	Operator string `gorm:"type:varchar(128)" json:"operator,omitempty"`
	// PayloadJSON 业务信封原始载荷 JSON（CP 不解析语义，原样留存供下游/审计；经济域同时落结构化专表）。
	PayloadJSON string `gorm:"column:payload_json;type:text" json:"payloadJson"`
	// OccurredAt 业务侧事件发生时间（epoch 毫秒，来自探针信封；0 表示未携带）。
	OccurredAt int64 `gorm:"column:occurred_at;index:idx_be_domain_time,priority:2" json:"occurredAt"`
	// CreatedAt CP 落库时间。
	CreatedAt time.Time `json:"createdAt"`
}

type ClientChannel struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// ChannelID 频道 slug：对外标识与端点路径段，全局唯一。约束 `^[a-z0-9][a-z0-9-]{1,63}$`。
	ChannelID string `gorm:"column:channel_id;type:varchar(64);uniqueIndex;not null" json:"channelId"`
	// Name 展示名。
	Name string `gorm:"type:varchar(128);not null" json:"name"`
	// Description 描述，可空。
	Description string `gorm:"type:varchar(512)" json:"description"`
	// CurrentVersion 当前 latest 版本指针占位；0=未发布。本 FR 仅建字段，编排见 FR-088。
	CurrentVersion int `gorm:"default:0;not null" json:"currentVersion"`
	// Deprecated: PinnedCoreVersion 原为频道 pin 的 updater-core 版本号（FR-193 初版，已随反转废弃，见 ADR-045 改写）。
	// updater-core 现由 CP 内嵌默认版本自动驱动 manifest agent.core，运营不再 pin/管理。保留此列（加性、默认 0）
	// 仅为兼容存量库、避免无谓迁移；不再被任何运营端点写入、不参与 manifest 生成。
	PinnedCoreVersion int `gorm:"default:0;not null" json:"-"`
	// SelectedCoreSHA256 频道选定的 updater-core 归档制品 sha256（FR-259，见 updater-arch-simplification spec §D）。
	// 指向 type=client-updater-core 的 Asset.SHA256；空=未选定（coreEndpoint 回退最新归档版本）。
	// 运营经 PUT /client-channels/:id/updater-core/selected 切换，客户端下次启动查 coreEndpoint 即用选定版本。
	SelectedCoreSHA256 string `gorm:"column:selected_core_sha256;type:char(64)" json:"-"`
	// SelectedCoreVersion 是频道级 core 分发版本号，每次切换选定 SHA 时递增。
	// 楔子只按 version 递增决定是否下载，所以选回旧 SHA 回滚时不能返回旧 Asset.Version。
	SelectedCoreVersion  int            `gorm:"column:selected_core_version;default:0;not null" json:"-"`
	ProtectionMode       string         `gorm:"column:protection_mode;type:varchar(32);default:normal;not null" json:"protectionMode"`
	ProtectionPolicyJSON string         `gorm:"column:protection_policy_json;type:text" json:"-"`
	ProtectionUpdatedAt  *time.Time     `gorm:"column:protection_updated_at" json:"protectionUpdatedAt"`
	CreatedAt            time.Time      `json:"createdAt"`
	UpdatedAt            time.Time      `json:"updatedAt"`
	DeletedAt            gorm.DeletedAt `gorm:"index" json:"-"`
}

type ClientDistDaily struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// Day UTC 日期 YYYY-MM-DD。与 channel/version/kind 组成唯一键。
	Day string `gorm:"type:char(10);not null;uniqueIndex:idx_cdd_day_chan_ver_kind" json:"day"`
	// ChannelID 频道 slug。
	ChannelID string `gorm:"column:channel_id;type:varchar(64);not null;uniqueIndex:idx_cdd_day_chan_ver_kind" json:"channelId"`
	// Version manifest 版本（artifact 聚合为 0）。
	Version int `gorm:"not null;uniqueIndex:idx_cdd_day_chan_ver_kind" json:"version"`
	// Kind manifest | artifact。
	Kind string `gorm:"type:varchar(16);not null;uniqueIndex:idx_cdd_day_chan_ver_kind" json:"kind"`
	// Requests 当日该维度请求数。
	Requests int64 `gorm:"default:0;not null" json:"requests"`
	// Bytes 当日该维度总字节数。
	Bytes int64 `gorm:"default:0;not null" json:"bytes"`
}

type ClientDistEvent struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// ChannelID 频道 slug。
	ChannelID string `gorm:"column:channel_id;type:varchar(64);not null;index:idx_cde_channel_time" json:"channelId"`
	// MachineID 客户端机器码（不可信）。
	MachineID string `gorm:"column:machine_id;type:varchar(128);index" json:"machineId"`
	// IP 来源 IP（限流/分布主维度）。
	IP string `gorm:"type:varchar(64);index" json:"ip"`
	// Kind 事件类型：manifest | artifact。
	Kind string `gorm:"type:varchar(16);not null" json:"kind"`
	// Version manifest 拉取的版本号（artifact 事件为 0，制品跨版本共享）。
	Version int `gorm:"default:0;not null" json:"version"`
	// ArtifactSHA 制品 sha256（仅 artifact 事件）。
	ArtifactSHA string `gorm:"column:artifact_sha;type:char(64)" json:"artifactSha"`
	// Bytes 响应字节数。
	Bytes int64 `gorm:"default:0;not null" json:"bytes"`
	// Status HTTP 状态码（200/206/304/404…）。
	Status int `gorm:"default:0;not null" json:"status"`
	// ErrCode 语义错误码（FR-249）。成功事件为空；失败事件填与响应 error 字段一致的码
	// （INVALID_CLIENT_KEY/NO_LATEST_VERSION/ARTIFACT_NOT_FOUND/SIGN_KEY_NOT_CONFIGURED/CHANNEL_NOT_FOUND/INTERNAL_ERROR）。
	ErrCode string `gorm:"column:err_code;type:varchar(48);index" json:"errCode"`
	// ErrReason 可读错误原因（FR-265）。
	ErrReason string `gorm:"column:err_reason;type:varchar(255)" json:"errReason"`
	// Method HTTP 方法（FR-265 日志详情）。
	Method string `gorm:"type:varchar(8)" json:"method"`
	// Path 请求路径（含 query，FR-265 日志详情）。
	Path string `gorm:"type:varchar(1024)" json:"path"`
	// RequestBody 请求体预览（FR-265 排障详情，最多保存短文本；凭证类字段不写入）。
	RequestBody string `gorm:"column:request_body;type:text" json:"-"`
	// ResponseBody 响应体预览（FR-265 排障详情，最多保存短文本；二进制响应不写入）。
	ResponseBody string `gorm:"column:response_body;type:text" json:"-"`
	// RequestHeadersJSON 请求头 JSON（FR-265）。凭证类头不落库。
	RequestHeadersJSON string `gorm:"column:request_headers_json;type:text" json:"-"`
	// ResponseHeadersJSON 响应头 JSON（FR-265）。凭证类头不落库。
	ResponseHeadersJSON string `gorm:"column:response_headers_json;type:text" json:"-"`
	// ETag 响应 ETag 快捷列（FR-265）。
	ETag string `gorm:"column:etag;type:varchar(128)" json:"etag"`
	// DurationMs 处理耗时（毫秒）。
	DurationMs int64 `gorm:"column:duration_ms;default:0;not null" json:"durationMs"`
	// CreatedAt 事件时间（清理基准）。
	CreatedAt time.Time `gorm:"index:idx_cde_channel_time" json:"createdAt"`
}

type ClientDistSnapshot struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// ChannelID 频道 slug；与 BucketTS 组成唯一键。空串=跨频道/制品共享桶。
	ChannelID string `gorm:"column:channel_id;type:varchar(64);not null;default:'';uniqueIndex:idx_cds_channel_bucket,priority:1" json:"channelId"`
	// BucketTS 小时桶起点（UTC，整小时对齐）。与 ChannelID 唯一；单列索引供区间扫描/TTL 清理。
	BucketTS time.Time `gorm:"not null;uniqueIndex:idx_cds_channel_bucket,priority:2;index:idx_cds_bucket" json:"bucketTs"`

	// 拉取侧（源 client_dist_event）。
	ManifestPulls int64 `gorm:"default:0;not null" json:"manifestPulls"` // 桶内 manifest 拉取次数
	ArtifactPulls int64 `gorm:"default:0;not null" json:"artifactPulls"` // 桶内制品拉取次数
	DownloadBytes int64 `gorm:"default:0;not null" json:"downloadBytes"` // 桶内总响应字节
	// ActiveMachines 桶内 machineId 精确去重计数（排空串）。machineId 不可信（ADR-023），仅统计近似；
	// 跨桶不可简单求和（同客户端跨小时会重复），跨区间去重口径见 ADR-049 §4。
	ActiveMachines int64 `gorm:"default:0;not null" json:"activeMachines"`
	// VersionDist 版本分布 JSON map[version]count（manifest 拉取按 version 计数）。
	VersionDist string `gorm:"column:version_dist;type:text" json:"-"`
	// PlatformDist 平台分布 JSON map[os]count（来源遥测 os 字段）。
	PlatformDist string `gorm:"column:platform_dist;type:text" json:"-"`

	// 更新侧（源 client_telemetry，按 result 分桶计数）。
	UpdateTotal      int64 `gorm:"default:0;not null" json:"updateTotal"`
	UpdateSuccess    int64 `gorm:"default:0;not null" json:"updateSuccess"`
	UpdateFailStatic int64 `gorm:"column:update_fail_static;default:0;not null" json:"updateFailStatic"` // 断网兜底启动
	UpdateRolledBack int64 `gorm:"column:update_rolled_back;default:0;not null" json:"updateRolledBack"`
	UpdateError      int64 `gorm:"default:0;not null" json:"updateError"`
	// LagDist 版本滞后分布 JSON map[lag]count（current_version - toVersion，下界 0；遥测 toVersion>0 时计）。
	LagDist string `gorm:"column:lag_dist;type:text" json:"-"`

	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type ClientIPRule struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// CIDR IP 或 CIDR（单 IP 视作 /32、/128）。
	CIDR string `gorm:"column:cidr;type:varchar(64);not null" json:"cidr"`
	// Mode deny | allow。
	Mode string `gorm:"type:varchar(8);not null" json:"mode"`
	// Note 规则备注。
	Note string `gorm:"type:varchar(255)" json:"note"`
	// CreatedBy 创建者用户 ID（审计辅助）。
	CreatedBy uint      `gorm:"default:0;not null" json:"createdBy"`
	CreatedAt time.Time `json:"createdAt"`
}

type ClientMachine struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// ChannelID 所属频道 slug。与 MachineID 组成唯一键。
	ChannelID string `gorm:"column:channel_id;type:varchar(64);not null;uniqueIndex:idx_client_machines_channel_machine" json:"channelId"`
	// MachineID 客户端机器码（SHA-256 十六进制，不可逆）。库内仅存哈希。
	MachineID string `gorm:"column:machine_id;type:varchar(128);not null;uniqueIndex:idx_client_machines_channel_machine" json:"machineId"`
	// HitCount 该机器码在本频道的累计拉取命中次数（弱一致统计）。
	HitCount int64 `gorm:"default:0;not null" json:"hitCount"`
	// FirstSeen 首次登记时间。
	FirstSeen time.Time `json:"firstSeen"`
	// LastSeen 最近一次登记时间。
	LastSeen time.Time `json:"lastSeen"`
}

type ClientProtectionAction struct {
	ID          uint       `gorm:"primaryKey" json:"id"`
	TargetType  string     `gorm:"type:varchar(32);not null;index" json:"targetType"`
	TargetValue string     `gorm:"column:target_value;type:varchar(128);default:'';not null;index" json:"targetValue"`
	ChannelID   string     `gorm:"column:channel_id;type:varchar(64);index" json:"channelId"`
	Action      string     `gorm:"type:varchar(64);not null;index" json:"action"`
	Status      string     `gorm:"type:varchar(16);default:active;not null;index" json:"status"`
	PolicyJSON  string     `gorm:"column:policy_json;type:text" json:"-"`
	Reason      string     `gorm:"type:varchar(512)" json:"reason"`
	Auto        bool       `gorm:"default:false;not null" json:"auto"`
	ExpiresAt   *time.Time `gorm:"index" json:"expiresAt"`
	CreatedBy   uint       `gorm:"default:0;not null" json:"createdBy"`
	CreatedAt   time.Time  `json:"createdAt"`
	UpdatedAt   time.Time  `json:"updatedAt"`
	CanceledAt  *time.Time `json:"canceledAt"`
}

type ClientPullKey struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// ChannelID 所属频道 slug（随频道删除级联清理）。
	ChannelID string `gorm:"column:channel_id;type:varchar(64);index;not null" json:"channelId"`
	// Name 密钥名（识别用途，如「正式包」「灰度」）。
	Name string `gorm:"type:varchar(128);not null" json:"name"`
	// KeyHash 拉取密钥明文的 SHA-256 十六进制小写。**鉴权依据**，库内不存明文。
	KeyHash string `gorm:"column:key_hash;type:char(64);uniqueIndex;not null" json:"-"`
	// KeyEnc 拉取密钥明文的 AES-256-GCM 可逆加密副本（base64(nonce‖密文)；FR-192，见 ADR-044）。
	// 仅供平台管理员经 reveal 端点查看明文，不参与鉴权、绝不序列化给客户端。空=不可查看
	// （存量老密钥 / 创建时未配 JIANMANAGER_CLIENT_KEY_ENC_SECRET 的密钥）。加性列、默认空。
	// 密钥发出后永久使用；管理员可经编辑端点改值（重算 KeyHash + 重写 KeyEnc），不再提供轮换。
	KeyEnc string `gorm:"column:key_enc;type:text" json:"-"`
	// KeyPrefix 明文前缀（如 jmck_ab12），仅供列表识别，不足以重建密钥。
	KeyPrefix string `gorm:"column:key_prefix;type:varchar(16);not null" json:"keyPrefix"`
	// Revealable 是否可查看明文（派生字段，不落库；= KeyEnc 非空，FR-192）。
	// 供前端对存量「只有哈希」的老密钥禁用「查看」并提示；不泄露密文本身。
	Revealable bool `gorm:"-" json:"revealable"`
	// Revoked 吊销标记；true 即鉴权失败。
	Revoked bool `gorm:"default:false;index;not null" json:"revoked"`
	// ExpiresAt 可选过期时间；到期即鉴权失败。
	ExpiresAt *time.Time `json:"expiresAt"`
	// LastUsedAt 最近一次鉴权命中时间（统计用，弱一致）。
	LastUsedAt         *time.Time `json:"lastUsedAt"`
	SecurityState      string     `gorm:"column:security_state;type:varchar(32);default:normal;not null" json:"securityState"`
	ThrottlePolicyJSON string     `gorm:"column:throttle_policy_json;type:text" json:"-"`
	SecurityNote       string     `gorm:"column:security_note;type:varchar(512)" json:"securityNote"`
	SecurityUpdatedAt  *time.Time `gorm:"column:security_updated_at" json:"securityUpdatedAt"`
	CreatedAt          time.Time  `json:"createdAt"`
	// RevokedAt 吊销时间。
	RevokedAt *time.Time `json:"revokedAt"`
}

type ClientRuntimeState struct {
	ID               uint       `gorm:"primaryKey" json:"id"`
	ChannelID        string     `gorm:"column:channel_id;type:varchar(64);not null;uniqueIndex:idx_client_runtime_identity;index" json:"channelId"`
	MachineID        string     `gorm:"column:machine_id;type:varchar(128);not null;uniqueIndex:idx_client_runtime_identity;index" json:"machineId"`
	PlayerName       string     `gorm:"column:player_name;type:varchar(32);index" json:"playerName"`
	IP               string     `gorm:"type:varchar(64);index" json:"ip"`
	Platform         string     `gorm:"type:varchar(32);index" json:"platform"`
	JavaVersion      string     `gorm:"column:java_version;type:varchar(32)" json:"javaVersion"`
	Launcher         string     `gorm:"type:varchar(32);index" json:"launcher"`
	CoreVersion      string     `gorm:"column:core_version;type:varchar(64);index" json:"coreVersion"`
	LocalVersion     int        `gorm:"column:local_version;default:0;not null;index" json:"localVersion"`
	FirstSeenAt      time.Time  `gorm:"column:first_seen_at;index" json:"firstSeenAt"`
	LastHeartbeatAt  time.Time  `gorm:"column:last_heartbeat_at;index" json:"lastHeartbeatAt"`
	LastUpdateResult string     `gorm:"column:last_update_result;type:varchar(16);index" json:"lastUpdateResult"`
	LastUpdateAt     *time.Time `gorm:"column:last_update_at;index" json:"lastUpdateAt"`
	CreatedAt        time.Time  `json:"createdAt"`
	UpdatedAt        time.Time  `json:"updatedAt"`
}

type ClientSecurityCounter struct {
	ID        uint      `gorm:"primaryKey" json:"id"`
	Scope     string    `gorm:"type:varchar(32);not null;uniqueIndex:idx_client_security_counter_bucket" json:"scope"`
	Key       string    `gorm:"type:varchar(128);not null;uniqueIndex:idx_client_security_counter_bucket" json:"key"`
	Bucket    string    `gorm:"type:varchar(32);not null;uniqueIndex:idx_client_security_counter_bucket" json:"bucket"`
	Value     int64     `gorm:"default:0;not null" json:"value"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type ClientSecurityGroup struct {
	ID               uint      `gorm:"primaryKey" json:"id"`
	Name             string    `gorm:"type:varchar(128);not null;uniqueIndex" json:"name"`
	Kind             string    `gorm:"type:varchar(16);default:manual;not null" json:"kind"`
	TargetType       string    `gorm:"column:target_type;type:varchar(32);default:'';not null" json:"targetType"`
	RuleJSON         string    `gorm:"column:rule_json;type:text" json:"-"`
	ActionPolicyJSON string    `gorm:"column:action_policy_json;type:text" json:"-"`
	Enabled          bool      `gorm:"default:true;not null" json:"enabled"`
	CreatedBy        uint      `gorm:"default:0;not null" json:"createdBy"`
	CreatedAt        time.Time `json:"createdAt"`
	UpdatedAt        time.Time `json:"updatedAt"`
}

type ClientSecurityHello struct {
	ID          uint      `gorm:"primaryKey" json:"id"`
	ChannelID   string    `gorm:"column:channel_id;type:varchar(64);index" json:"channelId"`
	MachineID   string    `gorm:"column:machine_id;type:varchar(128);index" json:"machineId"`
	InstallID   string    `gorm:"column:install_id;type:varchar(128);index" json:"installId"`
	PlayerName  string    `gorm:"type:varchar(64);index" json:"playerName"`
	Accepted    bool      `gorm:"default:false;not null" json:"accepted"`
	ErrCode     string    `gorm:"column:err_code;type:varchar(64);index" json:"errCode"`
	IP          string    `gorm:"type:varchar(64);index" json:"ip"`
	KeyID       uint      `gorm:"column:key_id;index" json:"keyId"`
	KeyPrefix   string    `gorm:"column:key_prefix;type:varchar(16)" json:"keyPrefix"`
	UserAgent   string    `gorm:"type:varchar(255)" json:"userAgent"`
	PayloadJSON string    `gorm:"column:payload_json;type:text" json:"-"`
	CreatedAt   time.Time `gorm:"index" json:"createdAt"`
}

type ClientSecurityProfile struct {
	ID              uint      `gorm:"primaryKey" json:"id"`
	ChannelID       string    `gorm:"column:channel_id;type:varchar(64);not null;uniqueIndex:idx_client_security_profile_identity" json:"channelId"`
	MachineID       string    `gorm:"column:machine_id;type:varchar(128);not null;uniqueIndex:idx_client_security_profile_identity" json:"machineId"`
	InstallID       string    `gorm:"column:install_id;type:varchar(128);not null;uniqueIndex:idx_client_security_profile_identity" json:"installId"`
	PlayerName      string    `gorm:"type:varchar(64)" json:"playerName"`
	PlayerNameNorm  string    `gorm:"type:varchar(64);index" json:"playerNameNorm"`
	KeyID           uint      `gorm:"column:key_id;index" json:"keyId"`
	KeyPrefix       string    `gorm:"column:key_prefix;type:varchar(16)" json:"keyPrefix"`
	FirstSeen       time.Time `gorm:"column:first_seen;index" json:"firstSeen"`
	LastSeen        time.Time `gorm:"column:last_seen;index" json:"lastSeen"`
	LastIP          string    `gorm:"column:last_ip;type:varchar(64);index" json:"lastIp"`
	UserAgent       string    `gorm:"type:varchar(255)" json:"userAgent"`
	CoreVersion     string    `gorm:"type:varchar(64)" json:"coreVersion"`
	WedgeVersion    string    `gorm:"type:varchar(64)" json:"wedgeVersion"`
	ManifestVersion string    `gorm:"type:varchar(64)" json:"manifestVersion"`
	OS              string    `gorm:"type:varchar(64)" json:"os"`
	OSVersion       string    `gorm:"type:varchar(64)" json:"osVersion"`
	Arch            string    `gorm:"type:varchar(32)" json:"arch"`
	JavaVendor      string    `gorm:"type:varchar(128)" json:"javaVendor"`
	JavaVersion     string    `gorm:"type:varchar(64)" json:"javaVersion"`
	JavaArch        string    `gorm:"type:varchar(32)" json:"javaArch"`
	Launcher        string    `gorm:"type:varchar(128)" json:"launcher"`
	Locale          string    `gorm:"type:varchar(32)" json:"locale"`
	Timezone        string    `gorm:"type:varchar(64)" json:"timezone"`
	MemoryTier      string    `gorm:"type:varchar(32)" json:"memoryTier"`
	RiskScore       int       `gorm:"default:0;not null" json:"riskScore"`
	RiskLevel       string    `gorm:"type:varchar(32);default:normal;not null" json:"riskLevel"`
	ProtectionState string    `gorm:"type:varchar(32);default:normal;not null" json:"protectionState"`
	LabelsJSON      string    `gorm:"column:labels_json;type:text" json:"-"`
	CreatedAt       time.Time `json:"createdAt"`
	UpdatedAt       time.Time `json:"updatedAt"`
}

type ClientSecurityRiskEvent struct {
	ID           uint      `gorm:"primaryKey" json:"id"`
	SubjectType  string    `gorm:"column:subject_type;type:varchar(32);index" json:"subjectType"`
	SubjectValue string    `gorm:"column:subject_value;type:varchar(128);index" json:"subjectValue"`
	ChannelID    string    `gorm:"column:channel_id;type:varchar(64);index" json:"channelId"`
	MachineID    string    `gorm:"column:machine_id;type:varchar(128);index" json:"machineId"`
	InstallID    string    `gorm:"column:install_id;type:varchar(128);index" json:"installId"`
	PlayerName   string    `gorm:"type:varchar(64);index" json:"playerName"`
	IP           string    `gorm:"type:varchar(64);index" json:"ip"`
	KeyID        uint      `gorm:"column:key_id;index" json:"keyId"`
	KeyPrefix    string    `gorm:"column:key_prefix;type:varchar(16)" json:"keyPrefix"`
	RuleCode     string    `gorm:"column:rule_code;type:varchar(64);default:'';not null;index" json:"ruleCode"`
	Severity     string    `gorm:"type:varchar(32);default:info;not null" json:"severity"`
	ScoreDelta   int       `gorm:"column:score_delta;default:0;not null" json:"scoreDelta"`
	Action       string    `gorm:"type:varchar(32)" json:"action"`
	Reason       string    `gorm:"type:varchar(512)" json:"reason"`
	DetailJSON   string    `gorm:"column:detail_json;type:text" json:"-"`
	CreatedAt    time.Time `gorm:"index" json:"createdAt"`
}

type ClientTelemetry struct {
	ID          uint      `gorm:"primaryKey" json:"id"`
	ChannelID   string    `gorm:"column:channel_id;type:varchar(64);index:idx_ct_channel_time" json:"channelId"`
	MachineID   string    `gorm:"column:machine_id;type:varchar(128);index" json:"machineId"`
	PlayerName  string    `gorm:"column:player_name;type:varchar(32);index" json:"playerName"`
	IP          string    `gorm:"type:varchar(64)" json:"ip"`
	Result      string    `gorm:"type:varchar(16);not null" json:"result"` // success|fail-static|rolled-back|error
	FromVersion int       `gorm:"default:0;not null" json:"fromVersion"`
	ToVersion   int       `gorm:"default:0;not null" json:"toVersion"`
	CoreVersion string    `gorm:"column:core_version;type:varchar(64)" json:"coreVersion"`
	OS          string    `gorm:"column:os;type:varchar(32)" json:"os"`
	Arch        string    `gorm:"column:arch;type:varchar(16)" json:"arch"`
	JavaVersion string    `gorm:"column:java_version;type:varchar(32)" json:"javaVersion"`
	JavaVendor  string    `gorm:"column:java_vendor;type:varchar(64)" json:"javaVendor"`
	Launcher    string    `gorm:"type:varchar(32)" json:"launcher"`
	Locale      string    `gorm:"column:locale;type:varchar(32)" json:"locale"`
	Timezone    string    `gorm:"column:timezone;type:varchar(64)" json:"timezone"`
	MemoryTier  string    `gorm:"column:memory_tier;type:varchar(16)" json:"memoryTier"`
	DurationMs  int64     `gorm:"column:duration_ms;default:0;not null" json:"durationMs"`
	BootSuccess bool      `gorm:"column:boot_success;default:false;not null" json:"bootSuccess"`
	Error       string    `gorm:"type:varchar(512)" json:"error"`
	CreatedAt   time.Time `gorm:"index:idx_ct_channel_time" json:"createdAt"`
}

type ClientTelemetryDaily struct {
	ID        uint   `gorm:"primaryKey" json:"id"`
	Day       string `gorm:"type:char(10);not null;uniqueIndex:idx_ctd_day_chan_result" json:"day"`
	ChannelID string `gorm:"column:channel_id;type:varchar(64);not null;uniqueIndex:idx_ctd_day_chan_result" json:"channelId"`
	Result    string `gorm:"type:varchar(16);not null;uniqueIndex:idx_ctd_day_chan_result" json:"result"`
	Count     int64  `gorm:"default:0;not null" json:"count"`
}

type ClientVersion struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// ChannelID 所属频道 slug（随频道删除级联清理）。
	ChannelID string `gorm:"column:channel_id;type:varchar(64);index:idx_client_versions_channel_version,unique;not null" json:"channelId"`
	// Version 单调递增整数（同频道内唯一）；防降级基准（contract §3）。
	Version int `gorm:"index:idx_client_versions_channel_version,unique;not null" json:"version"`
	// FilesJSON 文件清单快照（[]ManifestFile 的 JSON）：path/sha256/md5/size/sync/platform/artifact。
	FilesJSON string `gorm:"column:files_json;type:text;not null" json:"-"`
	// ManagedDirsJSON 托管目录快照（[]string 的 JSON）：仅这些目录可增删（减量）。
	// FR-255：可含 "*" 哨兵表「整个 gameDir」（clean-all）。
	ManagedDirsJSON string `gorm:"column:managed_dirs_json;type:text;not null" json:"-"`
	// CleanExcludeJSON 运营自定义排除快照（[]string 的 JSON，FR-255）：命中前缀永不删。
	// 空串=未声明（向后兼容，老版本无此列）。
	CleanExcludeJSON string `gorm:"column:clean_exclude_json;type:text" json:"-"`
	// AgentJSON 楔子 + updater-core 自更新段快照（ManifestAgent 的 JSON），可空（未声明自更新段）。
	AgentJSON string `gorm:"column:agent_json;type:text" json:"-"`
	// Note 发布备注（运营可读，信息性）。
	Note string `gorm:"type:varchar(512)" json:"note"`
	// CreatedBy 发布者用户 ID（审计辅助，0=未知）。
	CreatedBy uint      `gorm:"default:0;not null" json:"createdBy"`
	CreatedAt time.Time `json:"createdAt"`
}

type EconomyBalanceMirror struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// NodeUUID 余额所在节点（聚合 node→zone 维度起点）。
	NodeUUID string `gorm:"column:node_uuid;type:varchar(64);not null;uniqueIndex:idx_ebm_scope,priority:1" json:"nodeUuid"`
	// InstanceUUID 余额来源实例，用于业务汇聚读视图按用户组做资源级隔离。
	InstanceUUID string `gorm:"column:instance_uuid;type:varchar(64);index" json:"instanceUuid"`
	// ZoneID mce 区 ID（CoreLib zoneId）；跨区同名玩家独立隔离的关键维度。
	ZoneID string `gorm:"column:zone_id;type:varchar(64);not null;uniqueIndex:idx_ebm_scope,priority:2" json:"zoneId"`
	// PlayerName 玩家名（区分大小写，mce 口径）。
	PlayerName string `` /* 127-byte string literal not displayed */
	// Currency 货币 identifier（全局稳定业务键；探针侧已由 currencyId Int 折算，跨服可聚合）。
	Currency string `gorm:"type:varchar(64);not null;uniqueIndex:idx_ebm_scope,priority:4" json:"currency"`
	// CurrencyID 货币 mce Int 原值（审计回溯用；跨服不保证一致，故不作聚合键）。
	CurrencyID int `gorm:"column:currency_id;default:0;not null" json:"currencyId"`
	// Balance 最新余额（字符串承载 BigDecimal，禁浮点，防多币种精度失真）。
	Balance string `gorm:"type:varchar(64);not null" json:"balance"`
	// LastSeq 已应用的最大 mce 区内单调 seq（镜像推进游标，防乱序/重发回退余额）。
	LastSeq int64 `gorm:"column:last_seq;default:0;not null" json:"lastSeq"`
	// LastLedgerID 最近一次应用的总账流水 ID（可追溯到 [EconomyLedgerEntry]）。
	LastLedgerID int64 `gorm:"column:last_ledger_id;default:0;not null" json:"lastLedgerId"`
	// LastEntryType 最近一次变更的入账类型（DEPOSIT/WITHDRAW/…）。
	LastEntryType string `gorm:"column:last_entry_type;type:varchar(32)" json:"lastEntryType"`
	// OccurredAt 最近一次变更的业务发生时间（epoch 毫秒）。
	OccurredAt int64     `gorm:"column:occurred_at;default:0;not null" json:"occurredAt"`
	UpdatedAt  time.Time `json:"updatedAt"`
}

type EconomyLedgerEntry struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// LedgerID mce 总账流水 ID（去重锚点，仅 node→zone 内唯一）。
	LedgerID int64 `gorm:"column:ledger_id;not null;uniqueIndex:idx_ele_scope_ledger,priority:3" json:"ledgerId"`
	// NodeUUID / InstanceUUID 事件来源（node→zone 聚合维度）。
	NodeUUID     string `` /* 128-byte string literal not displayed */
	InstanceUUID string `gorm:"column:instance_uuid;type:varchar(64)" json:"instanceUuid"`
	// ZoneID mce 区 ID。
	ZoneID string `` /* 137-byte string literal not displayed */
	// PlayerName 玩家名。
	PlayerName string `gorm:"column:player_name;type:varchar(64);index:idx_ele_player,priority:2" json:"playerName"`
	// Currency 货币 identifier；CurrencyID 为 mce Int 原值。
	Currency   string `gorm:"type:varchar(64)" json:"currency"`
	CurrencyID int    `gorm:"column:currency_id;default:0;not null" json:"currencyId"`
	// EntryType 入账类型（DEPOSIT/WITHDRAW/CONSUME/REFUND/TRANSFER_IN/TRANSFER_OUT/ADJUST）。
	EntryType string `gorm:"column:entry_type;type:varchar(32)" json:"entryType"`
	// SignedAmount 带符号变更额（字符串承载 BigDecimal，正入负出）。
	SignedAmount string `gorm:"column:signed_amount;type:varchar(64)" json:"signedAmount"`
	// BalanceAfter 变更后余额（字符串承载 BigDecimal）。
	BalanceAfter string `gorm:"column:balance_after;type:varchar(64)" json:"balanceAfter"`
	// Seq mce 区内单调投递序号（排序/回放游标，非幂等键）。
	Seq int64 `gorm:"default:0;not null" json:"seq"`
	// OccurredAt 账务发生时间（epoch 毫秒）。
	OccurredAt int64 `gorm:"column:occurred_at;default:0;not null;index:idx_ele_time" json:"occurredAt"`
	// CreatedAt CP 落库时间。
	CreatedAt time.Time `json:"createdAt"`
}

type FileVersion struct {
	ID                  uint      `gorm:"primaryKey" json:"id"`
	InstanceID          uint      `gorm:"not null;index:idx_file_version_instance_path" json:"instanceId"`
	FilePath            string    `gorm:"type:varchar(512);not null;index:idx_file_version_instance_path" json:"filePath"`
	ContentHash         string    `gorm:"type:char(64);not null;index" json:"contentHash"`
	Content             string    `gorm:"type:longtext;not null" json:"-"`
	Size                int64     `gorm:"not null" json:"size"`
	AuthorID            uint      `gorm:"index" json:"authorId"`
	RollbackOfVersionID *uint     `gorm:"index" json:"rollbackOfVersionId,omitempty"`
	CreatedAt           time.Time `json:"createdAt"`
}

type Group struct {
	ID          uint           `gorm:"primaryKey" json:"id"`
	UUID        string         `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	Name        string         `gorm:"type:varchar(128);not null" json:"name"`
	Description string         `gorm:"type:varchar(512)" json:"description"`
	CreatedAt   time.Time      `json:"createdAt"`
	UpdatedAt   time.Time      `json:"updatedAt"`
	DeletedAt   gorm.DeletedAt `gorm:"index" json:"-"`

	Members []GroupMember `gorm:"foreignKey:GroupID" json:"members,omitempty"`
	Quota   *GroupQuota   `gorm:"foreignKey:GroupID" json:"quota,omitempty"`
}

type GroupInstance struct {
	ID         uint      `gorm:"primaryKey" json:"id"`
	GroupID    uint      `gorm:"not null;index" json:"groupId"`
	InstanceID uint      `gorm:"uniqueIndex;not null" json:"instanceId"`
	CreatedAt  time.Time `json:"createdAt"`
}

type GroupMember struct {
	ID        uint            `gorm:"primaryKey" json:"id"`
	GroupID   uint            `gorm:"not null;uniqueIndex:idx_group_user" json:"groupId"`
	UserID    uint            `gorm:"not null;uniqueIndex:idx_group_user" json:"userId"`
	Role      GroupMemberRole `gorm:"default:0" json:"role"`
	CreatedAt time.Time       `json:"createdAt"`

	Group Group `gorm:"foreignKey:GroupID" json:"-"`
	User  User  `gorm:"foreignKey:UserID" json:"user,omitempty"`
}

type GroupMemberRole int

type GroupQuota struct {
	ID           uint      `gorm:"primaryKey" json:"id"`
	GroupID      uint      `gorm:"uniqueIndex;not null" json:"groupId"`
	MaxInstances int       `gorm:"default:10" json:"maxInstances"`
	MaxBots      int       `gorm:"default:50" json:"maxBots"`
	MaxStorageMB int       `gorm:"default:10240" json:"maxStorageMb"`
	CreatedAt    time.Time `json:"createdAt"`
	UpdatedAt    time.Time `json:"updatedAt"`
}

type Instance struct {
	ID          uint           `gorm:"primaryKey" json:"id"`
	UUID        string         `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	NodeID      uint           `gorm:"not null;index" json:"nodeId"`
	Name        string         `gorm:"type:varchar(128);not null;index" json:"name"`
	Type        InstanceType   `gorm:"type:varchar(64);not null" json:"type"`
	Role        InstanceRole   `gorm:"type:varchar(16);default:universal;index" json:"role"`
	ProcessType ProcessType    `gorm:"type:varchar(32);not null" json:"processType"`
	Status      InstanceStatus `gorm:"type:varchar(32);default:STOPPED;index" json:"status"`
	// StatusReason 记录当前状态的原因，主要用于 CRASHED：异步委托（启动/停止）失败时写入具体错误
	// （如「实例未绑定 JDK…」），供前端显示，不再让用户只见「崩溃」无因。正常状态推进时清空。
	StatusReason     string `gorm:"type:varchar(512)" json:"statusReason"`
	StartCommand     string `gorm:"type:varchar(1024);not null" json:"startCommand"`
	JDKID            uint   `gorm:"index" json:"jdkId"`
	JavaMajorVersion int    `gorm:"index" json:"javaMajorVersion"`
	LaunchSpec       string `gorm:"type:text" json:"launchSpec"`
	// ProvisionSpec 存一键搭建/代理搭建的原始请求（JSON），供损毁后「重建」复用参数重跑搭建（FR-342）。
	// 仅经搭建入口创建的实例有值；手动/导入实例为空、不适用重建。
	ProvisionSpec string `gorm:"type:text" json:"provisionSpec,omitempty"`
	WorkDir       string `gorm:"type:varchar(512)" json:"workDir"`
	// WorkDirInPlace 就地导入标记（FR-302，见 ADR-069）：工作目录为托管区外的原始绝对路径
	// （ADR-007 系统分配原则的唯一合法例外）。删除实例时 CP 据此指示 Worker 跳过目录删除，
	// 原目录永不清理（双保险之一，另一道是 Worker 托管区守卫）。
	WorkDirInPlace bool   `gorm:"default:false" json:"workDirInPlace"`
	EnvVars        string `gorm:"type:text" json:"envVars"` // JSON
	// Image 是 docker 模式的容器镜像引用（如 itzg/minecraft-server:latest），仅 process_type=docker 使用（FR-078，ADR-019）。
	Image string `gorm:"type:varchar(256)" json:"image"`
	// ContainerID 记录 docker 模式实例最近一次运行的容器 ID（排障/展示用，运行态由 Worker 持有）。
	ContainerID string `gorm:"type:varchar(64)" json:"containerId"`
	// CPULimit 是 docker 模式的 CPU 核数上限（如 1.5），启动时注入容器 cgroup；0=不限制（FR-079，ADR-019）。
	CPULimit float64 `gorm:"default:0" json:"cpuLimit"`
	// MemLimitMB 是 docker 模式的内存上限（MiB），启动时注入容器 cgroup；0=不限制（FR-079，ADR-019）。
	MemLimitMB int64 `gorm:"default:0" json:"memLimitMb"`
	// DiskLimitMB 是 docker 模式的磁盘上限（MiB），仅持久化与展示，v1 不注入（依赖存储驱动）（FR-079）。
	DiskLimitMB int64 `gorm:"default:0" json:"diskLimitMb"`
	AutoStart   bool  `gorm:"default:false" json:"autoStart"`
	AutoRestart bool  `gorm:"default:true" json:"autoRestart"`
	// Deprecated: RCON 已退役（FR-067，见 ADR-016）——治理改走 ServerProbe 探针。
	// 列保留仅为迁移安全（不破坏既有库与历史实例数据），新实例不再写入、读取方不再使用。
	RCONPort     int    `gorm:"default:0" json:"rconPort"`
	RCONPassword string `gorm:"type:varchar(128)" json:"-"`
	// ForwardingSecret 是 Velocity modern 转发的 forwarding secret（代理实例 provision 时生成）。
	// 下发到所注册后端 paper 配置 + 跨代理一致校验复用；BungeeCord/Waterfall 不使用。参见 FR-035。
	ForwardingSecret string `gorm:"type:varchar(128)" json:"-"`
	// ProxyOnlineMode 代理是否向 Mojang 校验正版（true=正版网络，false=离线模式群组服）。
	// 仅代理实例使用；持久化以便 SyncProxy 重新生成配置时保留选择（默认 true）。参见 FR-035。
	ProxyOnlineMode bool `gorm:"default:true" json:"proxyOnlineMode"`
	ServerPort      int  `gorm:"default:0" json:"serverPort"`
	QueryPort       int  `gorm:"default:0" json:"queryPort"`
	// ProbePort 是 ServerProbe 监控探针 /metrics 端口（系统分配，FR-010）。0 表示未部署探针。
	ProbePort int `gorm:"default:0" json:"probePort"`
	// ProbeVersionID 是实例显式选择的 ServerProbe 版本；0 表示继承所属 Worker 或全局默认（FR-409）。
	ProbeVersionID uint           `gorm:"default:0;index" json:"probeVersionId"`
	PID            int            `gorm:"default:0" json:"pid"`
	StartedAt      *time.Time     `json:"startedAt"`
	CrashCount     int            `gorm:"default:0" json:"crashCount"`
	Tags           string         `gorm:"type:text" json:"tags"` // JSON
	CreatedAt      time.Time      `json:"createdAt"`
	UpdatedAt      time.Time      `json:"updatedAt"`
	DeletedAt      gorm.DeletedAt `gorm:"index" json:"-"`

	Node Node `gorm:"foreignKey:NodeID" json:"node,omitempty"`
}

type InstanceConfigVersion struct {
	ID                    uint      `gorm:"primaryKey" json:"id"`
	InstanceID            uint      `gorm:"not null;index:idx_cfg_version_instance_file" json:"instanceId"`
	FilePath              string    `gorm:"type:varchar(512);not null;index:idx_cfg_version_instance_file" json:"filePath"`
	ContentHash           string    `gorm:"type:char(64);not null;index" json:"contentHash"`
	Content               string    `gorm:"type:longtext;not null" json:"content"`
	Message               string    `gorm:"type:varchar(255)" json:"message"`
	AuthorID              uint      `gorm:"index" json:"authorId"`
	RollbackOfVersionID   *uint     `gorm:"index" json:"rollbackOfVersionId,omitempty"`
	RollbackedByVersionID *uint     `gorm:"index" json:"rollbackedByVersionId,omitempty"`
	CreatedAt             time.Time `json:"createdAt"`
}

type InstanceCrashSnapshot struct {
	ID         uint `gorm:"primaryKey" json:"id"`
	InstanceID uint `gorm:"not null;index" json:"instanceId"`
	// OccurredAt 崩溃发生时刻（Worker 侧时钟）。
	OccurredAt time.Time `json:"occurredAt"`
	// ExitCode 进程退出码；无法获知（Wait 出错/容器 Wait 错误）时为 -1。
	ExitCode int `json:"exitCode"`
	// Signal 终止信号名（Unix，如 killed/terminated）；Windows / 非信号退出为空。
	Signal string `gorm:"type:varchar(32)" json:"signal"`
	// DurationMs 本次运行时长（毫秒）。
	DurationMs int64 `json:"durationMs"`
	// TailOutput 崩溃前终端尾部输出（Worker 侧截取，≤200 行 / 64KB）。
	TailOutput string    `gorm:"type:text" json:"tailOutput"`
	CreatedAt  time.Time `json:"createdAt"`
}

type InstanceGroupMember struct {
	ID         uint      `gorm:"primaryKey" json:"id"`
	GroupID    uint      `gorm:"not null;index;uniqueIndex:idx_igmember_group_inst" json:"groupId"`
	InstanceID uint      `gorm:"not null;index;uniqueIndex:idx_igmember_group_inst" json:"instanceId"`
	CreatedAt  time.Time `json:"createdAt"`
}

type InstanceGroupNode struct {
	ID   uint   `gorm:"primaryKey" json:"id"`
	UUID string `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	Name string `gorm:"type:varchar(128);not null" json:"name"`
	// ParentID 父节点 ID，NULL 表示根分组；自引用邻接表表达树。建索引便于按父查子。
	ParentID *uint `gorm:"index" json:"parentId,omitempty"`
	// Sort 同级排序权重（升序），由 service 维护；前端可拖拽改序。
	Sort      int            `gorm:"default:0" json:"sort"`
	CreatedAt time.Time      `json:"createdAt"`
	UpdatedAt time.Time      `json:"updatedAt"`
	DeletedAt gorm.DeletedAt `gorm:"index" json:"-"`
}

type InstanceRole string

type InstanceStatus string

type InstanceType string

type LogEntry struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// Source 区分实例日志与平台日志，过滤维度之一。
	Source LogSource `gorm:"type:varchar(16);not null;index:idx_logs_source_time,priority:1" json:"source"`
	// Level 日志级别，过滤维度之一。
	Level LogLevel `gorm:"type:varchar(8);not null;index:idx_logs_level_time,priority:1" json:"level"`
	// InstanceID 实例主键（实例日志非零）；与 Time 组成复合索引承接按实例时间检索。
	InstanceID uint `gorm:"index:idx_logs_instance_time,priority:1" json:"instanceId"`
	// InstanceUUID 实例 UUID 冗余列，采集侧仅持有 UUID 时直接落库。
	InstanceUUID string `gorm:"type:char(36);index" json:"instanceUuid"`
	// NodeID 节点主键（实例/Worker 日志非零）；与 Time 组成复合索引承接按节点时间检索。
	NodeID uint `gorm:"index:idx_logs_node_time,priority:1" json:"nodeId"`
	// Stream 原始流名（stdout/stderr/""），仅实例日志使用，辅助前端区分。
	Stream string `gorm:"type:varchar(8)" json:"stream,omitempty"`
	// Message 日志正文（已去除行尾换行）。关键字检索在此列上做 DB 侧 LIKE。
	Message string `gorm:"type:text;not null" json:"message"`
	// Time 日志产生时间（采集/写入时刻）。所有复合索引的次序列，统一按时间倒序检索。
	Time time.Time `` /* 178-byte string literal not displayed */
}

type LogLevel string

type LogSource string

type MetricRollup1h struct {
	ID       uint      `gorm:"primaryKey" json:"id"`
	SeriesID uint      `gorm:"not null;index:idx_metric_1h_series_bucket,priority:1" json:"seriesId"`
	BucketTS time.Time `gorm:"not null;index:idx_metric_1h_series_bucket,priority:2" json:"bucketTs"`
	Avg      float64   `json:"avg"`
	Min      float64   `json:"min"`
	Max      float64   `json:"max"`
	Last     float64   `json:"last"`
	Count    int       `json:"count"`
}

type MetricRollup5m struct {
	ID       uint      `gorm:"primaryKey" json:"id"`
	SeriesID uint      `gorm:"not null;index:idx_metric_5m_series_bucket,priority:1" json:"seriesId"`
	BucketTS time.Time `gorm:"not null;index:idx_metric_5m_series_bucket,priority:2" json:"bucketTs"`
	Avg      float64   `json:"avg"`
	Min      float64   `json:"min"`
	Max      float64   `json:"max"`
	Last     float64   `json:"last"`
	Count    int       `json:"count"`
}

type MetricSampleRaw struct {
	ID       uint      `gorm:"primaryKey" json:"id"`
	SeriesID uint      `gorm:"not null;index:idx_metric_raw_series_ts,priority:1" json:"seriesId"`
	TS       time.Time `gorm:"not null;index:idx_metric_raw_series_ts,priority:2" json:"ts"`
	Value    *float64  `json:"value"`
}

type MetricScope string

type MetricSeries struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// NodeUUID 所属节点。
	NodeUUID string `gorm:"type:varchar(64);not null;uniqueIndex:idx_metric_series_identity,priority:1" json:"nodeUuid"`
	// InstanceID 实例级/世界级序列才有；节点级为空字符串。
	InstanceID string `gorm:"type:varchar(64);not null;default:'';uniqueIndex:idx_metric_series_identity,priority:2" json:"instanceId"`
	// Scope 作用域：node / instance / world。
	Scope MetricScope `gorm:"type:varchar(16);not null;uniqueIndex:idx_metric_series_identity,priority:3" json:"scope"`
	// MetricKey 指标键，见上方常量。
	MetricKey string `gorm:"type:varchar(48);not null;uniqueIndex:idx_metric_series_identity,priority:4" json:"metricKey"`
	// World scope=world 时的世界名，其余为空字符串。
	World string `gorm:"type:varchar(64);not null;default:'';uniqueIndex:idx_metric_series_identity,priority:5" json:"world"`
	// Unit 单位：pct/bytes/bytes_per_sec/count/ms/tps/seconds。
	Unit       string    `gorm:"type:varchar(16)" json:"unit"`
	CreatedAt  time.Time `json:"createdAt"`
	LastSeenAt time.Time `json:"lastSeenAt"`
}

type Network struct {
	ID   uint   `gorm:"primaryKey" json:"id"`
	UUID string `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	// Name 群组名，唯一性由 service 在未软删记录间校验（不加 DB 唯一索引，便于删除后重用同名）。
	Name        string         `gorm:"type:varchar(128);not null;index" json:"name"`
	Description string         `gorm:"type:varchar(512)" json:"description"`
	CreatedAt   time.Time      `json:"createdAt"`
	UpdatedAt   time.Time      `json:"updatedAt"`
	DeletedAt   gorm.DeletedAt `gorm:"index" json:"-"`
}

type NetworkMember struct {
	ID         uint      `gorm:"primaryKey" json:"id"`
	NetworkID  uint      `gorm:"not null;index;uniqueIndex:idx_netmember_net_inst" json:"networkId"`
	InstanceID uint      `gorm:"not null;index;uniqueIndex:idx_netmember_net_inst" json:"instanceId"`
	CreatedAt  time.Time `json:"createdAt"`
}

type Node struct {
	ID   uint   `gorm:"primaryKey" json:"id"`
	UUID string `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	// Name 节点名（人类可读标签）。身份由 UUID 锚定（见 ADR-039），name 仅为可变标签，
	// 但活跃节点间名字唯一：唯一性由 database.AutoMigrate 建的「部分唯一索引」
	// （仅约束 deleted_at IS NULL 的活跃行）强制，软删除节点可释放其名供新节点复用。
	Name        string     `gorm:"type:varchar(128);not null" json:"name"`
	Host        string     `gorm:"type:varchar(256);not null" json:"host"`
	GRPCPort    int        `gorm:"column:grpc_port;not null" json:"grpcPort"`
	WSPort      int        `gorm:"not null" json:"wsPort"`
	Secret      string     `gorm:"type:varchar(128);not null" json:"-"`
	Status      NodeStatus `gorm:"default:0" json:"status"`
	OS          string     `gorm:"type:varchar(64)" json:"os"`
	Arch        string     `gorm:"type:varchar(32)" json:"arch"`
	CPUCores    int        `json:"cpuCores"`
	MemoryMB    int64      `json:"memoryMb"`
	DiskTotalMB int64      `json:"diskTotalMb"`
	CPUUsage    float32    `gorm:"default:0" json:"cpuUsage"`
	MemoryUsage float32    `gorm:"default:0" json:"memoryUsage"`
	DiskUsage   float32    `gorm:"default:0" json:"diskUsage"`
	// Maintenance 维护模式（cordon）标记。为 true 时禁止新实例调度/分配到本节点，
	// 与 Status（在线/离线，由心跳驱动）正交：节点可同时「在线 + 维护中」。
	// 参见 FR-048。
	Maintenance      bool  `gorm:"default:false" json:"maintenance"`
	MemoryUsedMB     int64 `gorm:"default:0" json:"memoryUsedMb"`
	DiskUsedMB       int64 `gorm:"default:0" json:"diskUsedMb"`
	NetworkBytesSent int64 `gorm:"default:0" json:"networkBytesSent"`
	NetworkBytesRecv int64 `gorm:"default:0" json:"networkBytesRecv"`
	// LoadAvg1 节点 1 分钟 load average（FR-062，心跳驱动）。
	LoadAvg1 float64 `gorm:"default:0" json:"loadAvg1"`
	// ManagedRuntimeObservedAt 是 Worker 随已认证 Heartbeat 上报受管运行时快照的实际观测时间。
	// 运行时不可用或旧 Worker 未上报时，相关字段必须清空，避免陈旧值被当成当前资源。
	ManagedRuntimeObservedAt     *time.Time `json:"managedRuntimeObservedAt"`
	WorkerProcessRSSBytes        *int64     `json:"workerProcessRssBytes"`
	WorkerProcessCPUPct          *float64   `json:"workerProcessCpuPct"`
	BotWorkerRSSBytes            *int64     `json:"botWorkerRssBytes"`
	BotWorkerCPUPct              *float64   `json:"botWorkerCpuPct"`
	BotActiveCount               *int32     `json:"botActiveCount"`
	BotConnectingCount           *int32     `json:"botConnectingCount"`
	BotEventLoopP95MS            *float64   `json:"botEventLoopP95Ms"`
	BotCapacityMax               *int32     `json:"botCapacityMax"`
	BotCapacityUnavailableReason string     `gorm:"type:varchar(256)" json:"botCapacityUnavailableReason"`
	BotAvailable                 bool       `gorm:"default:false" json:"botAvailable"`
	BotUnavailableReason         string     `gorm:"type:varchar(256)" json:"botUnavailableReason"`
	// ProxyMode 节点出站代理模式（FR-185，见 ADR-043）：
	//   inherit（默认）= 用平台全局默认代理（settings DB > control-plane.yml > env）；
	//   custom         = 用本节点自定义 ProxyURL/ProxyNoProxy。
	// CP 据此算每节点期望代理经心跳响应下发，Worker 运行时重建出站 client（免登机器改 worker.yml）。
	ProxyMode string `gorm:"type:varchar(16);default:inherit" json:"proxyMode"`
	// ProxyURL 节点自定义代理地址（仅 ProxyMode=custom 有效；含凭据，API 响应/日志脱敏）。
	ProxyURL string `gorm:"type:varchar(512)" json:"-"`
	// ProxyNoProxy 节点自定义免代理列表（逗号分隔，仅 ProxyMode=custom 有效）。
	ProxyNoProxy  string     `gorm:"type:varchar(1024)" json:"proxyNoProxy"`
	LastHeartbeat *time.Time `json:"lastHeartbeat"`
	// RuntimeSyncedAt 上次运行时库存从 Worker 同步成功的时间（FR-301）。
	// JDKService.syncFromWorker 成功即刷新（含 JDK 面板隐式同步与运行时资产页手动刷新）；
	// nil = 从未同步。运行时资产页据此显示「上次同步 <相对时间>」并识别陈旧节点。
	RuntimeSyncedAt *time.Time `json:"runtimeSyncedAt"`
	// ProbeVersionID 是该 Worker 后续新实例的 ServerProbe 默认版本；0 表示继承全局默认（FR-409）。
	ProbeVersionID uint           `gorm:"default:0;index" json:"probeVersionId"`
	CreatedAt      time.Time      `json:"createdAt"`
	UpdatedAt      time.Time      `json:"updatedAt"`
	DeletedAt      gorm.DeletedAt `gorm:"index" json:"-"`

	// TunnelConnected 该节点当前是否有活跃反向隧道（FR-281，见 ADR-066）。
	// 运行态字段不落库（gorm:"-"），由 NodeService 在响应时据 TunnelRegistry 填充：
	// true=指令经隧道下发（NAT/内网节点可用），false=直拨回退（老 worker/隧道重建窗口）。
	TunnelConnected bool `gorm:"-" json:"tunnelConnected"`
}

type NodeEnrollToken struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// TokenHash enrollment token 明文的 SHA-256 十六进制小写。库内不存明文。
	TokenHash string `gorm:"column:token_hash;type:char(64);uniqueIndex;not null" json:"-"`
	// TokenPrefix 明文前缀（如 jmet_ab12），仅供列表识别，不足以重建 token。
	TokenPrefix string `gorm:"column:token_prefix;type:varchar(16);not null" json:"tokenPrefix"`
	// NodeName 预设节点名；留空则注册时以 Worker 上报名生效。
	NodeName string `gorm:"type:varchar(128)" json:"nodeName"`
	// ExpiresAt 过期时间；到期即校验失败。
	ExpiresAt time.Time `gorm:"not null" json:"expiresAt"`
	// Used 是否已消费（一次性）；true 即不可再用于注册。
	Used bool `gorm:"default:false;index;not null" json:"used"`
	// UsedAt 消费时间。
	UsedAt *time.Time `json:"usedAt"`
	// UsedByNode 消费该 token 注册成功的节点 UUID（审计/追溯用）。
	UsedByNode string `gorm:"type:char(36)" json:"usedByNode"`
	// Revoked 吊销标记（运营主动作废未消费 token）；true 即校验失败。
	Revoked   bool      `gorm:"default:false;not null" json:"revoked"`
	CreatedAt time.Time `json:"createdAt"`
	// CreatedBy 签发该 token 的平台管理员用户 ID（审计用）。
	CreatedBy uint `json:"createdBy"`
}

type NodeJDK struct {
	ID           uint      `gorm:"primaryKey" json:"id"`
	NodeID       uint      `gorm:"not null;index" json:"nodeId"`
	Vendor       string    `gorm:"type:varchar(64);not null" json:"vendor"`
	MajorVersion int       `gorm:"not null;index" json:"majorVersion"`
	Version      string    `gorm:"type:varchar(64);not null" json:"version"`
	Arch         string    `gorm:"type:varchar(32);not null" json:"arch"`
	Path         string    `gorm:"type:varchar(512);not null" json:"path"`
	Managed      bool      `gorm:"default:false" json:"managed"`
	CreatedAt    time.Time `json:"createdAt"`
	UpdatedAt    time.Time `json:"updatedAt"`
}

type NodePMConfig struct {
	ID     uint `gorm:"primaryKey" json:"id"`
	NodeID uint `gorm:"not null;uniqueIndex" json:"nodeId"`
	// PM 包管理器偏好：npm（默认）/ pnpm / yarn。pnpm/yarn 经 corepack enable 激活。
	PM string `gorm:"type:varchar(16);not null;default:npm" json:"pm"`
	// Registries JSON 数组（[]PMRegistry）：默认源用 scope="" 那条，其余为 @scope 域源。
	Registries string    `gorm:"type:text" json:"-"`
	CreatedAt  time.Time `json:"createdAt"`
	UpdatedAt  time.Time `json:"updatedAt"`
}

type NodeRuntime struct {
	ID     uint `gorm:"primaryKey" json:"id"`
	NodeID uint `gorm:"not null;index;uniqueIndex:uniq_node_runtime_type_path" json:"nodeId"`
	// Type 运行时类型（nodejs / python 预留；jdk 不落本表）。
	Type string `gorm:"type:varchar(16);not null;uniqueIndex:uniq_node_runtime_type_path" json:"type"`
	// Name 展示名（如 "Node.js 22"）。
	Name string `gorm:"type:varchar(64);not null" json:"name"`
	// Version 完整版本（如 "22.17.0"）。
	Version string `gorm:"type:varchar(64);not null" json:"version"`
	// Major 主版本（如 22），排序/选择用。
	Major int    `gorm:"not null;index" json:"major"`
	Arch  string `gorm:"type:varchar(32)" json:"arch"`
	Path  string `gorm:"type:varchar(512);not null;uniqueIndex:uniq_node_runtime_type_path" json:"path"`
	// Managed 是否平台托管（波1 登记均为外部发现 false；FR-299 安装器落 true）。
	Managed   bool      `gorm:"default:false" json:"managed"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type NodeStatus int

type Notification struct {
	ID     uint              `gorm:"primaryKey" json:"id"`
	UserID uint              `gorm:"index;not null" json:"userId"` // 收件人
	Level  NotificationLevel `gorm:"type:varchar(16);not null;default:info" json:"level"`
	Title  string            `gorm:"type:varchar(256);not null" json:"title"`
	Body   string            `gorm:"type:text" json:"body"`
	// TaskID 关联任务的业务 ID（可空，非任务类通知留空）。
	TaskID string `gorm:"type:varchar(64);index" json:"taskId,omitempty"`
	// ReadAt 已读时间，nil 表示未读。
	ReadAt    *time.Time `json:"readAt,omitempty"`
	CreatedAt time.Time  `json:"createdAt"`
}

type NotificationLevel string

type OrphanRuntime struct {
	ID           uint   `gorm:"primaryKey" json:"id"`
	UUID         string `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	NodeUUID     string `gorm:"type:char(36);not null;index:idx_orphan_node_inst,priority:1" json:"nodeUuid"`
	InstanceUUID string `gorm:"type:char(36);not null;index:idx_orphan_node_inst,priority:2" json:"instanceUuid"`
	// WorkerState 最近一次心跳上报的状态摘要（RUNNING/STOPPED/…）。
	WorkerState string `gorm:"type:varchar(32)" json:"workerState"`
	// WorkerPID 最近一次心跳上报的进程 PID（0=未知）。
	// 列名显式 worker_pid：避免 GORM 把 PID 缩写蛇形化为 worker_p_id（同 grpc_port 先例）。
	WorkerPID   int                 `gorm:"column:worker_pid;default:0" json:"workerPid"`
	Status      OrphanRuntimeStatus `gorm:"type:varchar(32);not null;index;default:pending" json:"status"`
	FirstSeenAt time.Time           `gorm:"not null;index" json:"firstSeenAt"`
	LastSeenAt  time.Time           `gorm:"not null" json:"lastSeenAt"`
	// DisposedAt 处置完成时刻（自动或手动）。
	DisposedAt *time.Time `json:"disposedAt,omitempty"`
	// DisposeMode auto | manual；未处置为空。
	DisposeMode string `gorm:"type:varchar(16)" json:"disposeMode,omitempty"`
	// LastError 最近一次自动/手动处置失败原因（成功后清空）。
	LastError string    `gorm:"type:varchar(512)" json:"lastError,omitempty"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type OrphanRuntimeStatus string

type PMRegistry struct {
	Name  string `json:"name"`  // 展示名（可选）
	URL   string `json:"url"`   // http(s) registry 地址
	Scope string `json:"scope"` // 空=默认源；非空=@<scope> 域源
	Token string `json:"token"` // 可选凭据（出参脱敏）
}

type PlatformSetting struct {
	// Key 配置键，与 SettingsService 白名单一致（如 log.level、graceful_stop.timeout）。
	Key string `gorm:"type:varchar(128);primaryKey" json:"key"`
	// Value 覆盖值的文本表示（按键各自的语义解析，如 duration 文本、整数文本）。
	Value     string    `gorm:"type:text" json:"value"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type ProcessMetricSnapshot struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// NodeUUID 所属节点。
	NodeUUID string `gorm:"type:varchar(64);not null;index:idx_process_metric_node_sampled,priority:1" json:"nodeUuid"`
	// InstanceUUID 受管实例 UUID。
	InstanceUUID string `gorm:"type:varchar(64);not null;index:idx_process_metric_instance_sampled,priority:1" json:"instanceUuid"`
	// PID 显式列名 pid：避免 GORM 把 PID 缩写蛇形化为 p_id，与 managedProcessHistory 的
	// WHERE pid = ? 查询对齐（真机验收 FR-407 抓到：SQL logic error: no such column: pid）。
	PID              int32     `gorm:"column:pid;not null" json:"pid"`
	Name             string    `gorm:"type:varchar(128)" json:"name"`
	CPUPercent       float64   `json:"cpuPercent"`
	RSSBytes         uint64    `json:"rssBytes"`
	ReadBytesPerSec  uint64    `json:"readBytesPerSec"`
	WriteBytesPerSec uint64    `json:"writeBytesPerSec"`
	User             string    `gorm:"type:varchar(128)" json:"user"`
	CommandSummary   string    `gorm:"type:varchar(160)" json:"commandSummary"`
	SampledAt        time.Time `` /* 134-byte string literal not displayed */
	CreatedAt        time.Time `json:"createdAt"`
}

type ProcessType string

type Schedule struct {
	ID         uint           `gorm:"primaryKey" json:"id"`
	UUID       string         `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	InstanceID uint           `gorm:"not null;index" json:"instanceId"`
	Name       string         `gorm:"type:varchar(128);not null" json:"name"`
	CronExpr   string         `gorm:"type:varchar(64);not null" json:"cronExpr"`
	Action     string         `gorm:"type:varchar(32);not null" json:"action"` // start, stop, restart, command, backup
	Payload    string         `gorm:"type:text" json:"payload"`                // JSON: command text, etc.
	Enabled    bool           `gorm:"default:true" json:"enabled"`
	LastRun    *time.Time     `json:"lastRun"`
	CreatedAt  time.Time      `json:"createdAt"`
	UpdatedAt  time.Time      `json:"updatedAt"`
	DeletedAt  gorm.DeletedAt `gorm:"index" json:"-"`
}

type ScheduleExecutionLog struct {
	ID         uint              `gorm:"primaryKey" json:"id"`
	ScheduleID uint              `gorm:"not null;index" json:"scheduleId"`
	Action     string            `gorm:"type:varchar(32);not null" json:"action"`
	Status     ScheduleLogStatus `gorm:"type:varchar(16);not null" json:"status"`
	Error      string            `gorm:"type:text" json:"error"`
	StartedAt  time.Time         `json:"startedAt"`
	FinishedAt time.Time         `json:"finishedAt"`
	Schedule   Schedule          `gorm:"foreignKey:ScheduleID" json:"schedule,omitempty"`
}

type ScheduleLogStatus string

type SelfUpdateCheckCache struct {
	// ID 固定为 1：本表为单行覆盖式缓存，不按时间累积多行。
	ID uint `gorm:"primaryKey" json:"id"`
	// ResultJSON 是上次成功 CheckResult 的 JSON 序列化（含 latestVersion/source/notes/各组件状态）。
	ResultJSON string `gorm:"type:text" json:"-"`
	// Source 冗余存更新源标识（github:owner/repo@channel | feed），便于诊断不必解 blob。
	Source string `gorm:"type:varchar(255)" json:"source"`
	// CheckedAt 该次成功检查的时刻（UTC），供前端展示「上次检查：<相对时间>」。
	CheckedAt time.Time `json:"checkedAt"`
}

type ServerRegistration struct {
	ID uint `gorm:"primaryKey" json:"id"`
	// ProxyID 代理实例 ID（role=proxy）。
	ProxyID uint `gorm:"not null;index;uniqueIndex:idx_reg_proxy_alias" json:"proxyId"`
	// BackendID 后端实例 ID（role=backend）。
	BackendID uint `gorm:"not null;index" json:"backendId"`
	// Alias 在该代理 servers{} 中的本地名（[a-z0-9_-]{1,64}），同一代理内唯一。
	Alias string `gorm:"type:varchar(64);not null;uniqueIndex:idx_reg_proxy_alias" json:"alias"`
	// Priority try/优先级顺序，小值优先。
	Priority int `gorm:"default:0" json:"priority"`
	// ForcedHost 可选 forced-host 域名 → 该后端。
	ForcedHost string `gorm:"type:varchar(255)" json:"forcedHost"`
	// Restricted Velocity restricted：仅可经 forced-host/命令访问。
	Restricted bool `gorm:"default:false" json:"restricted"`
	// Enabled 是否启用（写入代理配置时跳过 disabled）。
	Enabled   bool      `gorm:"default:true" json:"enabled"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type Task struct {
	ID     uint   `gorm:"primaryKey" json:"id"`
	TaskID string `gorm:"type:varchar(64);uniqueIndex;not null" json:"taskId"`
	NodeID uint   `gorm:"index" json:"nodeId"`
	Kind   string `gorm:"type:varchar(64);not null;index" json:"kind"`
	// InstanceID 关联实例（provision/import/clone 等实例级长操作任务用，FR-319/FR-323）；0=无关联。
	// 启动闸据此拦截「工作目录尚未就绪就点启动」的实例（在途任务未终态即拒启）。
	InstanceID uint `gorm:"index" json:"instanceId"`
	// State 见 TaskState；以字符串存储便于跨进程一致。
	State    TaskState `gorm:"type:varchar(16);not null;default:pending;index" json:"state"`
	Progress int       `gorm:"not null;default:0" json:"progress"` // 0~100
	Title    string    `gorm:"type:varchar(256)" json:"title"`
	Detail   string    `gorm:"type:varchar(1024)" json:"detail"` // 发起参数摘要
	Error    string    `gorm:"type:text" json:"error"`           // 失败原因（仅 failed）
	Result   string    `gorm:"type:text" json:"result"`          // 成功结果 JSON（如安装出的 JDK 信息）
	// CancelRequested 标记用户已请求强制停止（FR-227）：CP 据此每拍经心跳向节点下发 cancel_task_ids，
	// 直到 Worker 确认中断并上报 canceled 终态。pending 未起 / 节点离线时直接置 canceled、不设此标记。
	CancelRequested bool `gorm:"not null;default:false" json:"cancelRequested"`
	// CreatedBy 发起用户 ID，用于归属隔离与完成站内信收件人（0=系统）。
	CreatedBy uint      `gorm:"index" json:"createdBy"`
	CreatedAt time.Time `json:"createdAt"`
	UpdatedAt time.Time `json:"updatedAt"`
}

type TaskLog struct {
	ID     uint      `gorm:"primaryKey" json:"id"`
	TaskID string    `gorm:"type:varchar(64);not null;index:idx_tasklog_task_seq,unique,priority:1" json:"taskId"`
	Seq    int       `gorm:"not null;index:idx_tasklog_task_seq,unique,priority:2" json:"seq"`
	Line   string    `gorm:"type:text" json:"line"`
	TS     time.Time `json:"ts"`
}

type TaskState string

type Template struct {
	ID             uint           `gorm:"primaryKey" json:"id"`
	UUID           string         `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	Name           string         `gorm:"type:varchar(128);not null" json:"name"`
	Type           string         `gorm:"type:varchar(64);not null" json:"type"` // minecraft_java, etc.
	Description    string         `gorm:"type:varchar(512)" json:"description"`
	StartCommand   string         `gorm:"type:varchar(1024)" json:"startCommand"`
	DefaultWorkDir string         `gorm:"type:varchar(512)" json:"defaultWorkDir"`
	DownloadURL    string         `gorm:"type:varchar(512)" json:"downloadUrl"`
	ConfigFiles    string         `gorm:"type:text" json:"configFiles"` // JSON
	CreatedAt      time.Time      `json:"createdAt"`
	UpdatedAt      time.Time      `json:"updatedAt"`
	DeletedAt      gorm.DeletedAt `gorm:"index" json:"-"`
}

type User struct {
	ID       uint       `gorm:"primaryKey" json:"id"`
	UUID     string     `gorm:"type:char(36);uniqueIndex;not null" json:"uuid"`
	Username string     `gorm:"type:varchar(64);uniqueIndex;not null" json:"username"`
	Password string     `gorm:"type:varchar(128);not null" json:"-"`
	Role     UserRole   `gorm:"default:0" json:"role"`
	Status   UserStatus `gorm:"default:0" json:"status"`
	// AuthVersion 在密码、状态或角色发生安全相关变更时递增，用于立即吊销旧会话。
	AuthVersion uint           `gorm:"not null;default:0" json:"-"`
	CreatedAt   time.Time      `json:"createdAt"`
	UpdatedAt   time.Time      `json:"updatedAt"`
	DeletedAt   gorm.DeletedAt `gorm:"index" json:"-"`
}

type UserInvitation struct {
	ID            uint           `gorm:"primaryKey" json:"id"`
	Email         string         `gorm:"type:varchar(254);not null;index" json:"email"`
	TokenHash     []byte         `gorm:"type:binary(32);uniqueIndex;not null" json:"-"`
	TokenPrefix   string         `gorm:"type:varchar(16);not null" json:"-"`
	Role          UserRole       `gorm:"not null;default:0" json:"role"`
	ExpiresAt     time.Time      `gorm:"not null;index" json:"expiresAt"`
	CreatedByID   uint           `gorm:"not null;index" json:"createdBy"`
	UsedAt        *time.Time     `json:"usedAt"`
	RevokedAt     *time.Time     `json:"revokedAt"`
	EmailSentAt   *time.Time     `json:"emailSentAt"`
	EmailDelivery string         `gorm:"type:varchar(32);not null;default:not_configured" json:"emailDelivery"`
	CreatedAt     time.Time      `json:"createdAt"`
	UpdatedAt     time.Time      `json:"-"`
	DeletedAt     gorm.DeletedAt `gorm:"index" json:"-"`
}

type UserRole int

type UserStatus int