engine

type ChangedRow struct {
	Key   map[string]any `json:"key"`   // 主键列取值
	Diffs []ValueDiff    `json:"diffs"` // 取值不一致的列
}

type ColumnDiff struct {
	Matched    bool             `json:"matched"`
	SourceOnly []ColumnItem     `json:"sourceOnly"` // 源有目标无的列
	TargetOnly []ColumnItem     `json:"targetOnly"` // 目标有源无的列
	Different  []ColumnItemDiff `json:"different"`  // 类型/可空/主键不一致的列
}

type ColumnFilter struct {
	Column string   `json:"column"`
	Op     FilterOp `json:"op"`
	Value  any      `json:"value,omitempty"`
}

type ColumnItem struct {
	Name           string `json:"name"`
	DataType       string `json:"dataType"`                 // 原始类型（GetOrginalDataType），用于展示
	NormalizedType string `json:"normalizedType,omitempty"` // 按方言归一后的类型（写入时固化，diff 优先用此比对）
	Nullable       bool   `json:"nullable"`
	PrimaryKey     bool   `json:"primaryKey"`
}

type ColumnItemDiff struct {
	Name   string     `json:"name"`
	Source ColumnItem `json:"source"`
	Target ColumnItem `json:"target"`
}

type CompareDBPair struct {
	SourceDB string `json:"sourceDB" yaml:"sourceDB"` // 源库名（oracle 为 schema）
	TargetDB string `json:"targetDB" yaml:"targetDB"` // 目标库名
}

type CompareDatabaseResult struct {
	SourceDB string               `json:"sourceDB"` // 源库名（oracle 为 schema）
	TargetDB string               `json:"targetDB"` // 目标库名
	Tables   []CompareTableResult `json:"tables"`   // 该库内表级结果
	Summary  CompareSummary       `json:"summary"`  // 该库汇总统计
}

type CompareOptions struct {
	SourceConn    string            `json:"sourceConn" yaml:"sourceConn"`
	TargetConn    string            `json:"targetConn" yaml:"targetConn"`
	Source        *DBConnInfo       `json:"source,omitempty" yaml:"source,omitempty"`
	Target        *DBConnInfo       `json:"target,omitempty" yaml:"target,omitempty"`
	Databases     []CompareDBPair   `json:"databases,omitempty" yaml:"databases,omitempty"` // 库对（源库↔目标库），按索引配对
	DBMapping     map[string]string `json:"dbMapping,omitempty" yaml:"dbMapping,omitempty"` // 源库名→目标库名覆盖映射
	Tables        []string          `json:"tables,omitempty" yaml:"tables,omitempty"`
	Aliases       []TableAlias      `json:"aliases,omitempty" yaml:"aliases,omitempty"`
	StructureOnly bool              `json:"structureOnly" yaml:"structureOnly"` // 仅比结构
	DataOnly      bool              `json:"dataOnly" yaml:"dataOnly"`           // 仅比数据
	Threshold     int               `json:"threshold" yaml:"threshold"`         // 数据逐行比较阈值，默认 1000
	IgnoreColumns []string          `json:"ignoreColumns,omitempty" yaml:"ignoreColumns,omitempty"`
	ForceData     bool              `json:"forceData,omitempty" yaml:"forceData,omitempty"`
	// Lang 任务日志语言（zh/en），默认 zh
	Lang string `json:"lang,omitempty" yaml:"lang,omitempty"`
	// User 任务发起人标识（宿主注入）：随 OnTaskStart 透传宿主。运行时注入不入任务配置
	User string `json:"-" yaml:"-"`
}

type CompareResult struct {
	Source    string                  `json:"source"`           // 源连接标签
	Target    string                  `json:"target"`           // 目标连接标签
	Databases []CompareDatabaseResult `json:"databases"`        // 每个库对的结果（多库分组）
	Tables    []CompareTableResult    `json:"tables,omitempty"` // 兼容字段：所有库表的扁平汇总（旧数据可读，新写入不再依赖）
	Summary   CompareSummary          `json:"summary"`          // 汇总统计（所有库合计）
}

type CompareSummary struct {
	Total         int `json:"total"`         // 配对总数
	Matched       int `json:"matched"`       // 完全一致
	SourceOnly    int `json:"sourceOnly"`    // 仅源有
	TargetOnly    int `json:"targetOnly"`    // 仅目标有
	StructureDiff int `json:"structureDiff"` // 结构差异
	DataDiff      int `json:"dataDiff"`      // 数据差异（含仅计数不一致）
}

type CompareTableResult struct {
	Name       string      `json:"name"`                 // 展示名：同名取表名，别名配对为 "源表 ↔ 目标表"
	SourceName string      `json:"sourceName,omitempty"` // 源侧实际表名
	TargetName string      `json:"targetName,omitempty"` // 目标侧实际表名
	SourceDB   string      `json:"sourceDB,omitempty"`   // 源侧库名（oracle 为 schema），多库展示用
	TargetDB   string      `json:"targetDB,omitempty"`   // 目标侧库名，多库展示用
	Status     string      `json:"status"`
	Columns    *ColumnDiff `json:"columns,omitempty"` // 结构差异（DataOnly 时为 nil）
	Data       *DataDiff   `json:"data,omitempty"`    // 数据差异（StructureOnly 时为 nil）
}

type Contributor struct {
	// Type 类型标识，同时是 zip 包内目录名（如 flow/panel/rule/datatable），须为安全目录名
	Type string `json:"type" yaml:"type"`
	// Title 展示名（进度/日志用），空则回退 Type
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// Export 导出回调：生成文件写入 req.Dir，返回清单（文件路径相对 req.Dir）；nil 视为非法注册
	Export func(ctx context.Context, req ContributorRequest) (*ContributorResult, error) `json:"-" yaml:"-"`
	// Import 导入回调：从 req.Dir 读回业务对象；nil 表示仅导出（导入包中该目录被跳过）
	Import func(ctx context.Context, req ContributorImportRequest) error `json:"-" yaml:"-"`
	// IDs 本次任务要导出的业务对象 ID（任务配置层携带；Client 注册的模板留空）
	IDs []string `json:"ids,omitempty" yaml:"ids,omitempty"`
}

type ContributorImportRequest struct {
	// Key 任务目标连接 connKey（宿主据此路由到对应环境的业务配置）
	Key string
	// Conn 目标库连接（即本次导入的目标连接）
	Conn *DBConnInfo
	// DB 目标库名（连接配置库）
	DB string
	// Dir 业务对象目录（解压后 <Type>/）
	Dir string
}

type ContributorRequest struct {
	// Key 任务连接 connKey（如 env:prod/db:biz）：业务对象策略是环境级的，
	// 宿主据此路由到对应环境的业务配置（回调无 Key 时宿主无法区分多环境）
	Key string
	// Conn 业务对象所在库连接（即本次导出的源连接；宿主可自行建连或忽略）
	Conn *DBConnInfo
	// DB 业务库名（连接配置库；多库导出时为连接默认库，宿主自定义语义）
	DB string
	// IDs 要导出的业务对象 ID 列表（来自任务配置层）
	IDs []string
	// Dir 写入目录（任务目录下 <Type>/，已存在）
	Dir string
}

type ContributorResult struct {
	// Files 生成的文件清单（相对 Dir）
	Files []string
	// Count 导出的业务对象数（进度/日志展示用）
	Count int
}

type CreateSnapshotOptions struct {
	IncludeSamples bool // 是否保存前 N 行采样数据
	SampleLimit    int  // 采样行数上限，默认 10
	// Lang 任务日志语言（zh/en），默认 zh
	Lang string
}

type DBConnInfo struct {
	def.DBConnection `json:",inline" yaml:",inline"`
}

type DBSchema struct {
	Name    string              `json:"name"`
	Tables  []string            `json:"tables"`
	Objects map[string][]string `json:"objects,omitempty"`
}

type DBSelection struct {
	DB      string   `json:"db" yaml:"db"`
	Tables  []string `json:"tables,omitempty" yaml:"tables,omitempty"`
	Objects []string `json:"objects,omitempty" yaml:"objects,omitempty"`
}

type DBTables struct {
	Name   string   `json:"name"`
	Tables []string `json:"tables"`
	// Schemas 库内 schema 清单（PG 系按 schema 分层时填充；MySQL/Oracle 为空）
	Schemas []DBSchema `json:"schemas,omitempty"`
	// Objects 库内对象：_views/_functions/_procedures → 对象名（枚举失败的类型不返回）
	Objects map[string][]string `json:"objects,omitempty"`
}

type DataApplyResult struct {
	Stmts         int64    // 执行的语句数（DDL/REPLACE/成对 SQL）
	RollbackSQL   []string // 回滚 SQL（按执行顺序排列，整体回放即恢复到应用前状态）
	SkippedTables []string // 跳过的表（无主键等无法精确回滚的场景，宿主侧告警）
	Unrollback    []string // 执行了但无法生成精确回滚的语句（宿主侧告警；见 tryColumnRollback）
}

type DataDiff struct {
	Mode           string           `json:"mode"`
	SourceRows     int64            `json:"sourceRows"`
	TargetRows     int64            `json:"targetRows"`
	Equal          bool             `json:"equal"`                // count 模式：行数相等；rows 模式：无差异
	KeyColumns     []string         `json:"keyColumns,omitempty"` // 有无判断依据的主键列（PK 模式）；空=无主键整行比较
	Missing        int              `json:"missing,omitempty"`    // 源有目标无的行数（rows 模式）
	Extra          int              `json:"extra,omitempty"`      // 目标有源无的行数（rows 模式）
	Changed        int              `json:"changed,omitempty"`    // 主键匹配但内容不同的行数（PK 模式）
	MissingSamples []map[string]any `json:"missingSamples,omitempty"`
	ExtraSamples   []map[string]any `json:"extraSamples,omitempty"`
	ChangedSamples []ChangedRow     `json:"changedSamples,omitempty"` // 变化行样例（主键值 + 差异列双侧取值）
	SampleColumns  []string         `json:"sampleColumns,omitempty"`  // 采样行列序（按源表列定义顺序），供前端按序渲染
	SkippedReason  string           `json:"skippedReason,omitempty"`  // 未逐行比较的原因说明
}

type DataEntry struct {
	Type        int                      `json:"type"`
	Table       string                   `json:"table,omitempty"`
	PK          []string                 `json:"pk,omitempty"`
	SQL         string                   `json:"sql,omitempty"`
	RollbackSQL string                   `json:"rollback_sql,omitempty"`
	Data        []map[string]interface{} `json:"data,omitempty"`
}

type DataPackage struct {
	DB       string         `json:"db"`
	Entries  []*DataEntry   `json:"datas"`
	MapIndex map[string]int `json:"index"`
	// contains filtered or unexported fields
}

type DataPrepareRequest struct {
	// Key 目标连接 connKey（宿主据此路由 env 级业务上下文）
	Key string
	// DB 目标库名（注册键相同）
	DB string
	// Package 待应用的数据包（宿主可原地修改）
	Package *DataPackage
}

type DataPreparer func(ctx context.Context, req DataPrepareRequest) (context.Context, *DataPackage, error)

type DeleteRowParams struct {
	Table     string   // 表名（不含库前缀）
	PKColumns []string // 主键列名（可复合主键）
	PKValues  []any    // 主键值，与 PKColumns 顺序一致
}

type DictionaryOptions struct {
	SourceConn string        `json:"sourceConn" yaml:"sourceConn"` // 已保存连接名（与 Source 二选一）
	Source     *DBConnInfo   `json:"source,omitempty" yaml:"source,omitempty"`
	OutputDir  string        `json:"outputDir" yaml:"outputDir"`                       // 导出根目录，默认数据目录下 exports/
	TaskName   string        `json:"taskName" yaml:"taskName"`                         // 用于生成产物文件名
	Databases  []string      `json:"databases" yaml:"databases"`                       // 指定库（空=连接配置的库）
	Tables     []string      `json:"tables" yaml:"tables"`                             // 指定表（nil=全部，空数组=不导出）
	Selections []DBSelection `json:"selections,omitempty" yaml:"selections,omitempty"` // 结构化库→表选择（优先于 Databases/Tables）
	Compress   bool          `json:"compress" yaml:"compress"`                         // 是否打包 zip，默认 true
	Lang       string        `json:"lang,omitempty" yaml:"lang,omitempty"`             // 产物文案语言（zh/en），默认 zh
	// User 任务发起人标识（宿主注入）：随 OnTaskStart 透传宿主。运行时注入不入任务配置
	User string `json:"-" yaml:"-"`
}

type ExportDesc struct {
	Database   string              `json:"database"`          // 数据库名
	ExportTime string              `json:"exportTime"`        // 导出时间
	DBType     string              `json:"dbType"`            // 数据库类型（mysql/postgresql/oracle）
	Mode       string              `json:"mode"`              // 导出模式：schema+data / schemaOnly / dataOnly
	Tables     []ExportDescTable   `json:"tables,omitempty"`  // 表列表（含行数、条件）
	Objects    map[string][]string `json:"objects,omitempty"` // 对象：_views/_functions/_procedures → 名称列表
}

type ExportDescTable struct {
	Name    string   `json:"name"`
	Rows    int64    `json:"rows"`
	Query   string   `json:"query,omitempty"`   // 完整 SELECT（按条件导出时记录）
	Where   string   `json:"where,omitempty"`   // Deprecated: 旧版导出文件的 WHERE 条件
	Columns []string `json:"columns,omitempty"` // Deprecated: 旧版导出文件的导出列
}

type ExportDetail struct {
	Database string            // 库名（引擎枚举的库名；Oracle 为 schema(user)）
	Kind     string            // 明细类型：DetailKindTable/View/Function/Procedure
	Name     string            // 引擎实际表/对象名（PG 系表名可能为 "schema.table" 限定形式）
	Rows     int64             // 导出行数（仅 table；对象恒为 0）
	Query    string            // 条件取数归一化后的完整 SELECT（仅 table 条件导出时非空）
	Ddl      string            // 建表/对象 DDL（DataOnly 或获取失败时为空）
	Comment  string            // 表注释（仅 table；元数据不可得时为空）
	Columns  []TableColumnInfo // 列明细（仅 table，名称/类型/可空/主键/默认值/注释等；DataOnly 或元数据不可得时为空）
}

type ExportFormat string

type ExportOptions struct {
	SourceConn string           `json:"sourceConn" yaml:"sourceConn"` // 已保存连接名（与 Source 二选一）
	Source     *DBConnInfo      `json:"source,omitempty" yaml:"source,omitempty"`
	OutputDir  string           `json:"outputDir" yaml:"outputDir"`                       // 导出根目录，默认数据目录下 exports/
	TaskName   string           `json:"taskName" yaml:"taskName"`                         // 用于生成 zip 文件名
	Databases  []string         `json:"databases" yaml:"databases"`                       // 指定库（空=连接配置的库）
	Tables     []string         `json:"tables" yaml:"tables"`                             // 指定表（nil=全部，空数组=不导出）
	Objects    []string         `json:"objects" yaml:"objects"`                           // 指定对象，格式 _views/名称（nil=全部，空数组=不导出）
	Selections []DBSelection    `json:"selections,omitempty" yaml:"selections,omitempty"` // 结构化库→表/对象选择（优先于 Databases/Tables/Objects）
	Conditions []TableCondition `json:"conditions" yaml:"conditions"`
	SchemaOnly bool             `json:"schemaOnly" yaml:"schemaOnly"` // 仅导出结构
	DataOnly   bool             `json:"dataOnly" yaml:"dataOnly"`     // 仅导出数据
	BatchSize  int              `json:"batchSize" yaml:"batchSize"`
	Compress   bool             `json:"compress" yaml:"compress"` // 是否打包 zip，默认 true
	// SingleTransaction 一致性快照导出（等同 mysqldump --single-transaction）：
	// 全程在同一事务内读取，跨表数据处于同一时间点，避免运行中库导出出不一致状态
	SingleTransaction bool `json:"singleTransaction" yaml:"singleTransaction"`
	// Gzip 将 SQL 文件 gzip 压缩为 .sql.gz（导入侧透明解压；与 Compress 同时开启时 zip 内为 .sql.gz）
	Gzip bool `json:"gzip" yaml:"gzip"`
	// CompatCollation 兼容排序规则：将 MySQL 8.0 特有排序规则（如 utf8mb4_0900_ai_ci）
	// 替换为 MySQL 5.7 兼容的 utf8mb4_unicode_ci，使导出 SQL 可在低版本 MySQL 上执行。
	// 仅对 MySQL 导出的建表 DDL 生效（表级和列级 COLLATE）。
	CompatCollation bool `json:"compatCollation" yaml:"compatCollation"`
	// Lang 任务日志/产物文案语言（zh/en），默认 zh
	Lang string `json:"lang,omitempty" yaml:"lang,omitempty"`
	// User 任务发起人标识（宿主注入，如 X-DQEX-User 登录名）：随 OnTaskStart 透传宿主。
	// 运行时注入不入任务配置。
	User string `json:"-" yaml:"-"`
	// Contributors 业务对象贡献者（代理层）：宿主注册回调，编排由 dqex 负责。
	// 仅需 Type + IDs（配置层可序列化），Export/Import 回调为空时由服务层按 Type
	// 匹配 Client 注册的模板补齐（未注册报错）。
	Contributors []Contributor `json:"contributors,omitempty" yaml:"contributors,omitempty"`
	// Format 产物格式：FormatSQL（默认，SQL 文本）或 FormatJSON（DataPackage 数据包，
	// 每库一个 <db>.json，支持精确回滚导入）。json 格式适用于业务配置类中小表数据。
	Format ExportFormat `json:"format,omitempty" yaml:"format,omitempty"`
	// OnDetail 导出明细回调（可选）：每张表/每个对象导出完成时同步调用，fire-and-forget——
	// 无返回值，回调行为（panic/耗时）由宿主自负，不影响导出主流程。
	// 导出循环为单 goroutine 顺序调用，宿主侧无需加锁；每表恰好回调一次
	// （skip/无数据表 Rows=0），对象在 DDL 写入成功后回调。
	OnDetail func(ExportDetail) `json:"-" yaml:"-"`
}

type ExportResult struct {
	OutputPath  string // 最终产物路径（zip 或目录）
	OutputDir   string // 导出明细目录
	TotalTables int
	TotalRows   int64
}

type FilterOp string

type GenSQLKind string

type GenSQLParams struct {
	Table       string         `json:"table"`       // 表名（不含库前缀）
	Kind        GenSQLKind     `json:"kind"`        // 生成类型
	Columns     []string       `json:"columns"`     // 列清单（与 Rows 列序一致；whereCell 时仅 1 个 = 条件列名）
	Rows        [][]any        `json:"rows"`        // 行数据（insert 支持多行；其余取首行；whereCell 时 [[值]]）
	PKColumns   []string       `json:"pkColumns"`   // 主键列名（update/delete/selectByPk）
	SkipColumns []string       `json:"skipColumns"` // 跳过的列（insert 的自增列）
	Filters     []ColumnFilter `json:"filters"`     // 过滤条件（selectByFilter）
	SortSpecs   []SortSpec     `json:"sortSpecs"`   // 排序（selectByFilter）
}

type ImportFileInfo struct {
	Type      string                 `json:"type"` // sql / json / zip
	Size      int64                  `json:"size"`
	Databases []string               `json:"databases"`
	Descs     map[string]*ExportDesc `json:"descs,omitempty"`   // 库名 → 导出描述（如有）
	Entries   int                    `json:"entries,omitempty"` // 条目数（json 数据包格式）
}

type ImportOptions struct {
	TargetConn string      `json:"targetConn" yaml:"targetConn"`
	Target     *DBConnInfo `json:"target,omitempty" yaml:"target,omitempty"`
	InputPath  string      `json:"inputPath" yaml:"inputPath"` // 支持 .sql 单文件 或 .zip 包
	ResetMode  ResetMode   `json:"resetMode" yaml:"resetMode"` // 重置模式: "" / "truncate" / "drop"
	Backup     bool        `json:"backup" yaml:"backup"`       // 重置前在目标库创建备份表（默认 true，仅 reset != none 时生效）
	BatchSize  int         `json:"batchSize" yaml:"batchSize"`
	TempDir    string      `json:"-" yaml:"-"` // 任务处理临时目录（zip 解压），空=系统临时目录；运行时注入不入任务配置
	// CompatCollation 兼容排序规则：将 SQL 文件中的 MySQL 8.0 特有排序规则（如 utf8mb4_0900_ai_ci）
	// 替换为 MySQL 5.7 兼容的 utf8mb4_unicode_ci。仅对 MySQL 目标的导入生效。
	CompatCollation bool `json:"compatCollation" yaml:"compatCollation"`
	// Lang 任务日志语言（zh/en），默认 zh
	Lang string `json:"lang,omitempty" yaml:"lang,omitempty"`
	// User 任务发起人标识（宿主注入）：随 OnTaskStart 透传宿主。运行时注入不入任务配置
	User string `json:"-" yaml:"-"`
	// Contributors 业务对象贡献者（代理层）：zip 包内含 <Type>/ 目录时回调 Import 读回。
	// 仅需 Type（+可选 IDs），回调为空时由服务层按 Type 匹配注册模板补齐。
	Contributors []Contributor `json:"contributors,omitempty" yaml:"contributors,omitempty"`
	// Rollback 生成精确回滚 SQL 产物（.json 数据导入按旧行快照生成；.sql 导入无行级
	// 语义仅失败自动回滚，不生成产物）。产物写入输入文件同目录 <名称>.rollback.sql。
	Rollback bool `json:"rollback" yaml:"rollback"`
	// DataPreparers 数据前置处理器（代理层，按目标库名注册）：导入 .json 数据包前
	// 回调宿主做版本合并等业务策略（对应 tl-env PreProcess 语义），可修改包内容。
	// 运行时注入不入任务配置。
	DataPreparers map[string]DataPreparer `json:"-" yaml:"-"`
}

type ImportResult struct {
	TotalDatabases int
	TotalStmts     int64    // 执行的 SQL 语句数
	RollbackPath   string   // 精确回滚 SQL 产物路径（仅 .json 数据导入且 Rollback=true 时非空；多库 zip 按库分文件，此为首个产物路径，其余经任务日志输出）
	SkippedTables  []string // 跳过的表（无主键，无法精确导入/回滚）
	Unrollback     []string // 执行了但无法生成精确回滚的语句（宿主侧告警）
}

type InsertRowParams struct {
	Table   string   // 表名（不含库前缀）
	Columns []string // 要写入的列名（与 Values 顺序一致）
	Values  []any    // 对应列的值（nil 表示 NULL）
}

type MigrateOptions struct {
	SourceConn string      `json:"sourceConn" yaml:"sourceConn"`
	TargetConn string      `json:"targetConn" yaml:"targetConn"`
	Source     *DBConnInfo `json:"source,omitempty" yaml:"source,omitempty"`
	Target     *DBConnInfo `json:"target,omitempty" yaml:"target,omitempty"`
	Tables     []string    `json:"tables" yaml:"tables"`   // 指定表（nil=全部，空数组=不迁移）
	Objects    []string    `json:"objects" yaml:"objects"` // 指定对象，格式 _views/名称（nil=全部，空数组=不迁移；仅同类型生效）
	// Selections 结构化源库→表/对象选择（与 Tables/Objects 二选一，非空时优先）。
	// 多库迁移逐库执行：目标库为连接配置库（未配置时与源库同名）
	Selections []DBSelection    `json:"selections,omitempty" yaml:"selections,omitempty"`
	Conditions []TableCondition `json:"conditions" yaml:"conditions"`
	SchemaOnly bool             `json:"schemaOnly" yaml:"schemaOnly"`
	DataOnly   bool             `json:"dataOnly" yaml:"dataOnly"`
	ResetMode  ResetMode        `json:"resetMode" yaml:"resetMode"` // 重置模式: "" / "truncate" / "drop"
	Backup     bool             `json:"backup" yaml:"backup"`       // 重置前在目标库创建备份表（默认 true）
	BatchSize  int              `json:"batchSize" yaml:"batchSize"`
	// CompatCollation 兼容排序规则：将 MySQL 8.0 特有排序规则（如 utf8mb4_0900_ai_ci）
	// 替换为 MySQL 5.7 兼容的 utf8mb4_unicode_ci。
	// 仅对 MySQL 同类型迁移的建表 DDL 生效（表级和列级 COLLATE）。
	CompatCollation bool `json:"compatCollation" yaml:"compatCollation"`
	// Lang 任务日志/产物文案语言（zh/en），默认 zh
	Lang string `json:"lang,omitempty" yaml:"lang,omitempty"`
	// User 任务发起人标识（宿主注入）：随 OnTaskStart 透传宿主。运行时注入不入任务配置
	User string `json:"-" yaml:"-"`
}

type MigrateResult struct {
	TotalTables int
	TotalRows   int64
}

type MsgError struct {
	Key   string // 错误注册表模板 key
	Args  []any  // 模板参数
	Cause error  // 底层原因（原 ": %w" 包装），可为 nil
}

type ObjectDDLType string

type Progress struct {
	State        string   `json:"state"` // idle/running/done/error/cancelled
	TaskID       string   `json:"taskID"`
	TotalUnits   int      `json:"totalUnits"` // 工作单元总数（表 + 视图/函数/存储过程等对象）
	CurrentTable string   `json:"currentTable"`
	Phase        string   `json:"phase,omitempty"` // 当前表所处阶段：schema=结构（DDL）/ data=数据（行导出）；空=未细分（对象/收尾等）
	DoneUnits    int      `json:"doneUnits"`
	TotalRows    int64    `json:"totalRows"`
	DoneRows     int64    `json:"doneRows"`
	Percent      float64  `json:"percent"`
	Message      string   `json:"message"`
	MsgSeq       int      `json:"msgSeq"`               // 事件序号：每次 log() 追加新事件时递增；节流快照不变。宿主据此区分"新事件"与"快照刷新"，无需比对消息文本
	OutputPath   string   `json:"outputPath,omitempty"` // 导出完成后的文件路径
	DurationMs   int64    `json:"durationMs,omitempty"` // 任务总耗时（仅终态回放时由执行历史填充，实时推送时前端自行计时）
	Logs         []string `json:"logs"`
}

type ProgressFunc func(Progress)

type QueryHooks struct {
	// OnQuery 语句执行完成回调：stmt 为语句文本（超长截断至 4096 字节，截断点回退至
	// UTF-8 字符边界；宿主自行做摘要/脱敏）；
	// costMs 为执行耗时（毫秒）；rowsAffected 写操作为受影响行数，查询为返回行数。
	// 失败语句同样回调（rowsAffected = -1），宿主可据此记录失败审计。
	OnQuery func(ctx context.Context, connKey, stmt string, costMs int64, rowsAffected int64)
}

type ResetMode string

type SQLQueryResult struct {
	Columns      []string `json:"columns"`
	Rows         [][]any  `json:"rows"`
	RowCount     int      `json:"rowCount"`
	AffectedRows int64    `json:"affectedRows"`
	Elapsed      int64    `json:"elapsedMs"` // 毫秒
	SQL          string   `json:"sql"`
	IsWrite      bool     `json:"isWrite"`
	Warnings     []string `json:"warnings"`
	Error        string   `json:"error,omitempty"`   // 执行失败原因（非空时视为失败结果，正常返回给前端展示）
	Skipped      bool     `json:"skipped,omitempty"` // 未执行：因前面语句失败而跳过的语句（仅占位，无结果）
}

type SchemaSummary struct {
	Name       string `json:"name"`
	TableCount int    `json:"tableCount"` // 表数量（视图/函数等不计入，展开后见明细）
}

type Snapshot struct {
	ID          string             `json:"id"`
	Name        string             `json:"name"`
	Description string             `json:"description,omitempty"`
	ConnID      string             `json:"connId"`    // 来源连接 ID（允许连接被删除后快照仍可读）
	ConnLabel   string             `json:"connLabel"` // 冗余连接名称
	DBType      string             `json:"dbType"`
	CreatedAt   int64              `json:"createdAt"` // unix 秒
	TableCount  int                `json:"tableCount"`
	TotalRows   int64              `json:"totalRows"`
	Databases   []SnapshotDatabase `json:"databases"`        // 多库快照
	DBName      string             `json:"dbName,omitempty"` // 兼容字段（单库旧快照），新写入不再使用
	Tables      []SnapshotTable    `json:"tables,omitempty"` // 兼容字段（单库旧快照）
}

type SnapshotColumn struct {
	Name           string `json:"name"`
	DataType       string `json:"dataType"`                 // 原始类型
	NormalizedType string `json:"normalizedType,omitempty"` // 按快照库方言归一后的类型（写入时固化）
	Nullable       bool   `json:"nullable"`
	PrimaryKey     bool   `json:"primaryKey"`
	Position       int    `json:"position"`
}

type SnapshotCompareOptions struct {
	SnapshotID string            `json:"snapshotId"`
	TargetConn string            `json:"targetConn"`
	Target     *DBConnInfo       `json:"target,omitempty"`
	DBMapping  map[string]string `json:"dbMapping,omitempty"` // 快照库名→目标库名映射（默认同名）
	Tables     []string          `json:"tables,omitempty"`    // 限定对比的表，nil=全部（"库.表" 或裸名）
	// Lang 任务日志语言（zh/en），默认 zh
	Lang string `json:"lang,omitempty"`
	// User 任务发起人标识（宿主注入）：随 OnTaskStart 透传宿主。运行时注入不入任务配置
	User string `json:"-"`
}

type SnapshotDatabase struct {
	DBName     string          `json:"dbName"`
	TableCount int             `json:"tableCount"`
	TotalRows  int64           `json:"totalRows"`
	Tables     []SnapshotTable `json:"tables"`
}

type SnapshotInfo struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Description string   `json:"description,omitempty"`
	ConnID      string   `json:"connId"`
	ConnLabel   string   `json:"connLabel"`
	DBNames     []string `json:"dbNames"`
	DBName      string   `json:"dbName,omitempty"` // 兼容字段
	DBType      string   `json:"dbType"`
	TableCount  int      `json:"tableCount"`
	TotalRows   int64    `json:"totalRows"`
	CreatedAt   int64    `json:"createdAt"` // unix 秒
}

type SnapshotTable struct {
	Name       string           `json:"name"`
	RowCount   int64            `json:"rowCount"`
	Columns    []SnapshotColumn `json:"columns"`
	PrimaryKey []string         `json:"primaryKey,omitempty"`
	RowSamples []map[string]any `json:"rowSamples,omitempty"` // 前 N 行采样（创建时可选）
}

type SortSpec struct {
	Column string `json:"column"`
	Order  string `json:"order"` // "asc" | "desc"
}

type TableAlias struct {
	Source        string   `json:"source" yaml:"source"`
	Target        string   `json:"target" yaml:"target"`
	IgnoreColumns []string `json:"ignoreColumns,omitempty" yaml:"ignoreColumns,omitempty"` // 表级忽略列（列名大小写不敏感）
}

type TableColumnInfo struct {
	Name          string `json:"name"`
	DataType      string `json:"dataType"`             // 原始数据类型（如 varchar(255), int, timestamp）
	Nullable      bool   `json:"nullable"`             // 是否允许 NULL
	PrimaryKey    bool   `json:"primaryKey,omitempty"` // 是否主键
	Default       string `json:"default,omitempty"`    // 默认值
	AutoIncrement bool   `json:"autoIncrement,omitempty"`
	Unique        bool   `json:"unique,omitempty"`  // 是否唯一约束（非主键）
	Indexed       bool   `json:"indexed,omitempty"` // 是否有普通索引（非主键/非唯一）
	Comment       string `json:"comment,omitempty"` // 列注释（可能为空）
}

type TableCondition struct {
	TableName string        `json:"tableName" yaml:"tableName"`
	DataMode  TableDataMode `json:"dataMode,omitempty" yaml:"dataMode,omitempty"` // 数据导出模式
	Query     string        `json:"query,omitempty" yaml:"query,omitempty"`       // 完整 SELECT 语句（仅 dataMode=condition 时生效）
	Where     string        `json:"where,omitempty" yaml:"where,omitempty"`       // Deprecated: 旧版 WHERE 条件，仅读取兼容
	Columns   []string      `json:"columns,omitempty" yaml:"columns,omitempty"`   // Deprecated: 旧版导出列，仅读取兼容
}

type TableDataMode string

type TableMeta struct {
	Comment string            // 表注释（可能为空）
	Columns []TableColumnInfo // 列信息（含列注释）
}

type TablePageResult struct {
	Columns        []string `json:"columns"`
	Rows           [][]any  `json:"rows"`
	Total          int64    `json:"total"`
	Page           int      `json:"page"`
	PageSize       int      `json:"pageSize"`
	ExcludeColumns []string `json:"excludeColumns,omitempty"` // 被省略的大字段列名（值为 NULL，前端渲染占位）
}

type UpdateCellParams struct {
	Table     string   // 表名（不含库前缀）
	SetColumn string   // 目标列名
	SetValue  any      // 目标列新值（nil 表示 SET NULL）
	PKColumns []string // 主键列名（可复合主键）
	PKValues  []any    // 主键值，与 PKColumns 顺序一致
}

type ValueDiff struct {
	Column string `json:"column"`
	Source any    `json:"source"`
	Target any    `json:"target"`
}