package meta

type DataMeta struct {
	Name      string            `json:"name"`                // 名称（列名、行标识等）
	Type      string            `json:"type"`                // 类型（"column"、"row"、"value"等）
	FieldType FieldType         `json:"fieldType,omitempty"` // 表单类型（保留）
	DBType    string            `json:"dbType,omitempty"`    // 数据库类型（如 "VARCHAR(255)"、"INT"）
	Nullable  bool              `json:"nullable,omitempty"`  // 是否可空
	Value     interface{}       `json:"value,omitempty"`     // 值（原生 Go 类型：string/int/float/bool/[]byte/nil）
	ValueType FieldType         `json:"valueType,omitempty"` // 值类型（用于前端说明：string/int/bool等）
	RowID     string            `json:"rowId,omitempty"`     // 行ID（仅对Type="row"有效，用于唯一标识数据行）
	Attrs     map[string]string `json:"attrs,omitempty"`     // 额外属性
	Meta      map[string]string `json:"meta,omitempty"`      // 元数据
	Children  []DataMeta        `json:"children,omitempty"`  // 子项（用于行内的列值等）
}

type QueryResult struct {
	Columns   []DataMeta        `json:"columns"`         // 列元信息：每项代表一列（Type 通常为 "column"）
	Rows      []DataMeta        `json:"rows,omitempty"`  // 行数据：每行用 DataMeta 表示（Type="row"），Children 为列值（Type="value"）
	Total     *int64            `json:"total,omitempty"` // 结果总条数；仅当请求 IncludeTotal=true 时返回
	Returned  int               `json:"returned"`        // 本次实际返回的行数（Rows 的长度）
	Truncated bool              `json:"truncated"`       // 是否因 Limit/驱动限制而截断
	Stats     map[string]string `json:"stats,omitempty"` // 执行统计/诊断信息（字符串键值对），如耗时、命中索引等
}

// ExecuteResult SQL执行结果
type ExecuteResult struct {
	Success       bool         `json:"success"`                // 执行是否成功
	SQLType       string       `json:"sqlType"`                // SQL类型（SELECT/INSERT/UPDATE/DELETE/CREATE/DROP等）
	AffectedRows  int64        `json:"affectedRows,omitempty"` // 影响行数（INSERT/UPDATE/DELETE）
	LastInsertID  interface{}  `json:"lastInsertId,omitempty"` // 最后插入ID（INSERT）
	Data          *QueryResult `json:"data,omitempty"`         // 查询结果（SELECT语句）
	ErrorMessage  string       `json:"errorMessage,omitempty"` // 错误信息
	ExecutionTime int64        `json:"executionTime"`          // 执行时间（毫秒）
	RowsReturned  int          `json:"rowsReturned,omitempty"` // 返回的行数（SELECT语句）
}

// SortField 排序字段描述
// Desc: 是否降序；未设置或 false 表示升序
type SortField struct {
	Column string `json:"column"`         // 列名（与 Columns 中的 Name 对应）
	Desc   bool   `json:"desc,omitempty"` // 是否降序
}

// DataQueryRequest 数据查询请求参数（与 DataReader.QueryData 搭配）
// 设计目标：80% 场景只需少量字段；其他可后续扩展（例如复杂表达式、函数、分片信息等）。
// 可扩展策略：保持字段语义清晰，不嵌套过深；需要复杂 DSL 时新增 Expr/Conditions。
type DataQueryRequest struct {
	// Columns 指定需要返回的列名列表；为空或 nil 表示返回全部列。
	Columns []string `json:"columns,omitempty"`

	// Filters 简单等值过滤（列名 -> 字符串值）。
	// 说明：
	//   - 统一用字符串承载值，驱动层负责必要的类型转换/参数化绑定。
	//   - 复杂条件（范围/like/函数等）可在后续通过新增 Conditions/Expr 等字段扩展。
	Filters map[string]string `json:"filters,omitempty"`

	// Order 排序字段列表（可多列）。
	Order []SortField `json:"order,omitempty"`

	// Offset 起始偏移（与 Limit 组合实现分页）。
	Offset int `json:"offset,omitempty"`

	// Limit 返回最大行数。0 或 <0 表示使用驱动默认/不限制（谨慎）。
	Limit int `json:"limit,omitempty"`

	// IncludeTotal 是否计算总行数（可能触发额外 COUNT 开销）。
	IncludeTotal bool `json:"includeTotal,omitempty"`

	// Stream 是否采用流式读取（true 时可能分批返回；具体协议将来扩展）。
	Stream bool `json:"stream,omitempty"`

	// Args 预编译/参数化查询的占位符参数（全部以字符串表示，驱动负责转换与绑定）。
	Args []string `json:"args,omitempty"`

	// QueryID 调用方生成的查询唯一标识（用于幂等/重试跟踪）。
	QueryID string `json:"queryId,omitempty"`

	// TimeoutMs 单次查询的超时时间（毫秒）；0 表示使用 ctx 或驱动默认。
	TimeoutMs int `json:"timeoutMs,omitempty"`

	// Fetch 是否执行查询并返回数据；false 时仅返回生成的 SQL 语句（预览模式），不实际执行查询。
	Fetch bool `json:"fetch,omitempty"`
}