db_view/service/internal/common/databases/interfaces.go

package databases

import (
	"context"
	_ "dbview/service/internal/common/databases/drivers/mysql"
	"dbview/service/internal/common/databases/meta"
)

// Connection 基础连接接口
type Connection interface {
	Close() error
}

// MetadataReader 新一代元数据读取接口
//
// 说明：
// MetadataReader 使用“基于路径的通用导航模型”（ObjectPath）来定位数据库对象，
// 将对象标识从不透明字符串 id 替换为结构化路径，便于驱动实现与前端 UI 的统一。
//
// 设计要点与约定：
// - ListNodes 用于轻量级的树/列表分页查询（尽量快、传输小）；GetNodeDetails 用于获取指定节点的重量级详情（例如表的列/索引）。
// - 所有方法接收 context.Context，用于超时与取消控制；实现方应尊重上下文取消。
// - 返回值中的 meta.Node / meta.NodeDetails 应尽量只包含前端需要的字段，避免携带大量未压缩数据。
// - 错误处理：实现方应返回可读的 error（用于上层日志/提示），但不要泄露敏感信息（如密码）。
//
// 方法说明：
// GetStructureDefinition(ctx)：
//
//	返回数据库类型的层级定义（NodeTypeDefinition 列表），用于前端在构建树时决定每个层级的显示和可展开的子类型。
//	实现该方法时应避免做重量级 IO，可以返回静态或缓存的描述信息。
//
// ListNodes(ctx, path, req)：
//
//	列出指定父路径下的子节点（轻量级），返回节点数组和满足条件的总数（用于分页）。
//	- path: 结构化父路径，空路径表示根（例如列出数据库）。
//	- req: 支持分页、类型过滤和名称过滤等。实现应在 DB 层尽量做过滤/分页以节省网络带宽。
//
// GetNodeDetails(ctx, path)：
//
//	获取指定节点的完整详情，Driver 可在 NodeDetails.RawMetadata 中附加任意驱动特有信息（例如列定义、DDL、权限等）。
//
// SearchNodes(ctx, keyword, scope)：
//
//	在给定作用域内搜索节点（全局搜索时 scope 为空）。实现应限制返回结果数量并尽量使用索引以提高性能。
type MetadataReader interface {
	GetStructureDefinition(ctx context.Context) ([]meta.NodeTypeDefinition, error)

	ListNodes(ctx context.Context, path meta.ObjectPath, req meta.ListNodesRequest) ([]meta.Node, int64, error)

	GetNodeDetails(ctx context.Context, path meta.ObjectPath) (meta.NodeDetails, error)

	SearchNodes(ctx context.Context, keyword string, scope meta.ObjectPath) ([]meta.Node, error)
}

// ObjectManager 统一管理对象的生命周期（创建、修改、删除）
//
// 设计理念：采用“意图驱动 + 预览优先”的工作流。
// 前端通过 GetObjectProperties 获取要渲染的属性定义和当前值，生成表单；用户提交后通过 ApplyChanges
// 提交变更（支持 DryRun 预览与实际执行）。
//
// 约定与语义：
// - GetObjectProperties：当 path 的最后一段没有 Name 时，表示创建场景（返回创建模板/字段）；当有 Name 时，表示修改场景（返回字段定义+当前值）。
// - PropertyDefinitions 描述每个字段的 label/type/required/options 等，PropertyValues 为 key->value 的当前值映射。
// - ApplyChanges：通过 action 指定 create/update/delete。options.DryRun=true 表示仅生成预览（返回生成 SQL/脚本等），不进行实际变更。
// - ApplyResult 应包含生成的脚本、受影响行数及可供前端显示的简短消息。
// - 实现方在执行真实修改时应注意事务一致性（并在无法回滚的 DDL 场景下明确告知前端）。
//
// 错误处理：驱动实现应返回明确的 error 用于上层展示或日志，验证类错误（参数缺失/格式错误）建议返回易于前端处理的错误信息。
type ObjectManager interface {
	GetObjectProperties(ctx context.Context, path meta.ObjectPath) (meta.PropertyDefinitions, meta.PropertyValues, error)

	ApplyChanges(ctx context.Context, action meta.ObjectAction, path meta.ObjectPath, changes meta.PropertyValues, options meta.ApplyOptions) (meta.ApplyResult, error)
}

// MetadataRefresher 提供按对象刷新元数据的能力（例如在驱动层重新加载某对象缓存）
//
// 使用场景：当外部操作（如通过 SQL 执行变更）导致驱动内部缓存失效时，可调用该方法通知驱动刷新指定对象的元数据。
// objectID 的语义由上层约定（通常为连接/对象唯一标识），实现方需记录其预期格式并在文档中说明。
type MetadataRefresher interface {
	RefreshObject(ctx context.Context, objectID string) error
}

// MetadataInfo 提供数据库级别的额外元信息查询
//
// 返回值用于驱动能力探测（如支持的数据类型、关键字、函数等），前端或管理组件可以据此调整 UI/校验逻辑。
type MetadataInfo interface {
	GetMetadataInfo(ctx context.Context) (meta.MetadataCapabilities, error)
}

// DataReader 数据读取接口：对路径指向的对象（通常为 table / view）执行数据查询
//
// 说明：该接口用于实现表数据的分页/过滤/排序查询。path 应指向包含表信息的 ObjectPath。
// 实现时请注意 SQL 注入风险，优先使用参数化查询。返回的 meta.QueryResult 包含列元信息与行数据。
type DataReader interface {
	// QueryData 执行数据查询。
	// 新增参数 includeLarge：当为 true 时，驱动应尽量返回大型字段（BLOB/CLOB）的完整内容；
	// 当为 false 时，驱动可按策略省略大型字段并在返回的 meta.QueryResult 的 DataMeta 中设置 `omitted:true`。
	QueryData(ctx context.Context, path meta.ObjectPath, req meta.DataQueryRequest, includeLarge bool) (meta.QueryResult, error)
}

// DataExecutor 统一的执行接口
//
// 说明：用于执行任意 SQL（包括 DDL/DML）。path 提供可选的上下文（例如当前数据库/表）。
// 实现应尽量返回结构化的 meta.ExecuteResult，包含执行成功与否、受影响行数和错误信息。
type DataExecutor interface {
	// ExecuteSQL 执行任意SQL并返回执行结果。
	// 新增参数 includeLarge：当为 true 时，驱动应尽量返回大对象字段的完整值；
	// 当为 false 时，驱动可按策略省略大型 LOB 字段并在 meta.ExecuteResult.Data 中标记为 Omitted。
	ExecuteSQL(ctx context.Context, path meta.ObjectPath, sql string, params []interface{}, includeLarge bool) (meta.ExecuteResult, error)
}

// 以下为向后兼容的旧接口定义（保留，便于逐步迁移）
type MetadataDeleter interface {
	DescribeDeleteTemplate(ctx context.Context, path meta.ObjectPath) (meta.ObjectTemplate, error)
	DeleteRootObjects(ctx context.Context, req meta.ObjectOperationRequest) (meta.ObjectOperationResponse, error)
	DeleteChildObjects(ctx context.Context, req meta.ObjectOperationRequest) (meta.ObjectOperationResponse, error)
}

type MetadataCreater interface {
	DescribeCreateTemplate(ctx context.Context, path meta.ObjectPath) (meta.ObjectTemplate, error)
	CreateObject(ctx context.Context, req meta.CreateObjectRequest) (meta.CreateObjectResponse, error)
}

type MetadataUpdater interface {
	DescribeUpdateTemplate(ctx context.Context, path meta.ObjectPath) (meta.ObjectTemplate, error)
	UpdateObject(ctx context.Context, req meta.UpdateObjectRequest) (meta.UpdateObjectResponse, error)
}