api

type APIDoc struct {
	Name        string      // API名称
	Description string      // API描述
	Parameters  []Parameter // 参数
	Returns     []Parameter // 返回值
	Errors      []Error     // 错误
}

type Configurable interface {
	// UpdateConfig 更新插件配置
	// ctx: 上下文
	// config: 新的配置
	// 返回: 更新过程中的错误
	UpdateConfig(ctx context.Context, config map[string]interface{}) error

	// GetConfig 获取当前配置
	// 返回: 当前配置
	GetConfig() map[string]interface{}

	// ValidateConfig 验证配置
	// config: 待验证的配置
	// 返回: 验证结果和错误信息
	ValidateConfig(config map[string]interface{}) (bool, error)
}

type DataProcessorPlugin interface {
	Plugin // 继承基础插件接口

	// ProcessData 处理数据
	// ctx: 上下文
	// data: 输入数据
	// 返回: 处理后的数据和错误
	ProcessData(ctx context.Context, data interface{}) (interface{}, error)

	// GetSupportedDataTypes 返回支持的数据类型
	// 返回: 支持的数据类型列表
	GetSupportedDataTypes() []string
}

type Debuggable interface {
	// EnableDebug 启用调试
	// level: 调试级别
	// 返回: 错误
	EnableDebug(level int) error

	// DisableDebug 禁用调试
	// 返回: 错误
	DisableDebug() error

	// GetDebugInfo 获取调试信息
	// 返回: 调试信息
	GetDebugInfo() map[string]interface{}
}

type Documentable interface {
	// GetDocumentation 获取文档
	// 返回: 文档内容
	GetDocumentation() Documentation
}

type Documentation struct {
	Overview   string            // 概述
	Usage      string            // 使用说明
	API        map[string]APIDoc // API文档
	Examples   []Example         // 示例
	References []Reference       // 参考资料
}

type Error struct {
	Code        string // 错误码
	Description string // 错误描述
	Resolution  string // 解决方案
}

type ErrorSeverity string

type ErrorType string

type Event struct {
	Type      string                 // 事件类型
	Source    string                 // 事件源
	ID        string                 // 事件ID
	Timestamp time.Time              // 时间戳
	Data      map[string]interface{} // 事件数据
}

type EventHandlerPlugin interface {
	Plugin // 继承基础插件接口

	// HandleEvent 处理事件
	// ctx: 上下文
	// event: 事件
	// 返回: 处理结果和错误
	HandleEvent(ctx context.Context, event Event) (interface{}, error)

	// GetSupportedEventTypes 返回支持的事件类型
	// 返回: 支持的事件类型列表
	GetSupportedEventTypes() []string
}

type Example struct {
	Title       string // 示例标题
	Description string // 示例描述
	Code        string // 示例代码
	Output      string // 示例输出
}

type HTTPHandlerPlugin interface {
	Plugin // 继承基础插件接口

	// GetHTTPHandler 返回HTTP处理器
	// 返回: HTTP处理器和错误
	GetHTTPHandler() (http.Handler, error)

	// GetBasePath 返回基础路径
	// 返回: 处理器的基础路径
	GetBasePath() string
}

type HealthStatus struct {
	Status      string                 // 状态: healthy, degraded, unhealthy
	Details     map[string]interface{} // 详细信息
	LastChecked time.Time              // 最后检查时间
}

type IsolationConfig struct {
	Level       string            // 隔离级别: none, basic, strict, complete
	Resources   map[string]int64  // 资源限制: memory, cpu, etc.
	Timeout     time.Duration     // 操作超时时间
	WorkingDir  string            // 工作目录
	Environment map[string]string // 环境变量
}

type Loggable interface {
	// Log 记录日志
	// level: 日志级别
	// msg: 日志消息
	// fields: 日志字段
	Log(level string, msg string, fields map[string]interface{})

	// SetLogLevel 设置日志级别
	// level: 日志级别
	SetLogLevel(level string)

	// GetLogLevel 获取日志级别
	// 返回: 当前日志级别
	GetLogLevel() string
}

type MetricsCollector interface {
	// CollectMetric 收集指标
	// name: 指标名称
	// value: 指标值
	// labels: 标签
	CollectMetric(name string, value float64, labels map[string]string) error
}

type Monitorable interface {
	// GetMetrics 获取指标
	// 返回: 指标数据
	GetMetrics() map[string]interface{}

	// RegisterMetricsCollector 注册指标收集器
	// collector: 指标收集器
	// 返回: 错误
	RegisterMetricsCollector(collector MetricsCollector) error
}

type Parameter struct {
	Name        string      // 参数名称
	Type        string      // 参数类型
	Description string      // 参数描述
	Required    bool        // 是否必需
	Default     interface{} // 默认值
}

type Plugin interface {
	// GetInfo 返回插件的基本信息
	GetInfo() PluginInfo

	// Init 初始化插件
	// ctx: 上下文，可用于超时控制和取消操作
	// config: 插件配置
	// 返回: 初始化过程中的错误
	Init(ctx context.Context, config PluginConfig) error

	// Start 启动插件
	// ctx: 上下文，可用于超时控制和取消操作
	// 返回: 启动过程中的错误
	Start(ctx context.Context) error

	// Stop 停止插件
	// ctx: 上下文，可用于超时控制和取消操作
	// 返回: 停止过程中的错误
	Stop(ctx context.Context) error

	// HealthCheck 执行健康检查
	// ctx: 上下文，可用于超时控制和取消操作
	// 返回: 健康状态和检查过程中的错误
	HealthCheck(ctx context.Context) (HealthStatus, error)
}

type PluginConfig struct {
	// 基本配置
	ID       string // 插件ID
	Enabled  bool   // 是否启用
	LogLevel string // 日志级别

	// 运行时配置
	AutoStart   bool // 是否自动启动
	AutoRestart bool // 是否自动重启

	// 隔离配置
	Isolation IsolationConfig // 隔离配置

	// 自定义配置
	Settings map[string]interface{} // 自定义设置，插件特定的配置项
}

type PluginDependency struct {
	ID       string // 依赖的插件ID
	Version  string // 依赖的插件版本要求（语义化版本表达式）
	Optional bool   // 是否为可选依赖
}

type PluginError struct {
	Type     ErrorType              // 错误类型
	Severity ErrorSeverity          // 错误严重程度
	Code     string                 // 错误代码
	Message  string                 // 错误消息
	PluginID string                 // 插件ID
	Details  map[string]interface{} // 错误详情
	Cause    error                  // 原因
}

type PluginEvent struct {
	Type      string                 // 事件类型: loaded, unloaded, started, stopped, error
	PluginID  string                 // 插件ID
	Timestamp time.Time              // 时间戳
	Data      map[string]interface{} // 事件数据
}

type PluginInfo struct {
	ID           string             // 插件唯一标识符
	Name         string             // 插件名称
	Version      string             // 插件版本
	Description  string             // 插件描述
	Author       string             // 插件作者
	License      string             // 插件许可证
	Tags         []string           // 插件标签，用于分类和筛选
	Capabilities map[string]bool    // 插件能力，表示插件支持的功能
	Dependencies []PluginDependency // 插件依赖，表示插件依赖的其他插件
}

type PluginLocation struct {
	// 位置类型: local, remote, registry
	Type string

	// 路径
	Path string

	// URL
	URL string

	// 版本
	Version string
}

type PluginMetadata struct {
	// 插件ID
	ID string

	// 插件名称
	Name string

	// 插件版本
	Version string

	// 插件描述
	Description string

	// 插件作者
	Author string

	// 插件许可证
	License string

	// 插件标签
	Tags []string

	// 插件能力
	Capabilities map[string]bool

	// 插件依赖
	Dependencies []PluginDependency

	// 插件位置
	Location PluginLocation

	// 插件签名
	Signature string

	// 注册时间
	Timestamp time.Time
}

type PluginState string

type PluginStatus struct {
	ID         string                 // 插件ID
	State      PluginState            // 状态
	Health     HealthStatus           // 健康状态
	StartTime  time.Time              // 启动时间
	StopTime   time.Time              // 停止时间
	Error      string                 // 错误信息
	Statistics map[string]interface{} // 统计信息
}

type Reference struct {
	Title       string // 标题
	URL         string // URL
	Description string // 描述
}

type SecurityPlugin interface {
	Plugin // 继承基础插件接口

	// ValidateRequest 验证请求
	// ctx: 上下文
	// request: 请求对象
	// 返回: 验证结果和错误
	ValidateRequest(ctx context.Context, request interface{}) (bool, error)

	// EncryptData 加密数据
	// ctx: 上下文
	// data: 待加密数据
	// 返回: 加密后的数据和错误
	EncryptData(ctx context.Context, data []byte) ([]byte, error)

	// DecryptData 解密数据
	// ctx: 上下文
	// data: 待解密数据
	// 返回: 解密后的数据和错误
	DecryptData(ctx context.Context, data []byte) ([]byte, error)
}

type ServicePlugin interface {
	Plugin // 继承基础插件接口

	// GetService 返回插件提供的服务实例
	// 返回值是一个通用接口，调用方需要根据插件类型进行类型断言
	GetService() (interface{}, error)

	// RegisterHandler 注册服务处理器
	// path: 服务路径
	// handler: 处理器实例
	RegisterHandler(path string, handler interface{}) error
}

type StoragePlugin interface {
	Plugin // 继承基础插件接口

	// Store 存储数据
	// ctx: 上下文
	// key: 键
	// value: 值
	// 返回: 错误
	Store(ctx context.Context, key string, value []byte) error

	// Retrieve 检索数据
	// ctx: 上下文
	// key: 键
	// 返回: 值和错误
	Retrieve(ctx context.Context, key string) ([]byte, error)

	// Delete 删除数据
	// ctx: 上下文
	// key: 键
	// 返回: 错误
	Delete(ctx context.Context, key string) error

	// List 列出键
	// ctx: 上下文
	// prefix: 前缀
	// 返回: 键列表和错误
	List(ctx context.Context, prefix string) ([]string, error)
}

type Traceable interface {
	// StartSpan 开始一个追踪span
	// ctx: 上下文
	// operationName: 操作名称
	// 返回: 新的上下文和span
	StartSpan(ctx context.Context, operationName string) (context.Context, interface{})

	// FinishSpan 结束一个追踪span
	// span: 要结束的span
	FinishSpan(span interface{})

	// AddSpanTag 添加span标签
	// span: 目标span
	// key: 标签键
	// value: 标签值
	AddSpanTag(span interface{}, key string, value interface{})
}

type UIPlugin interface {
	Plugin // 继承基础插件接口

	// GetUIResources 返回插件提供的UI资源
	// 如CSS、JavaScript、图片等静态资源
	GetUIResources() ([]UIResource, error)

	// GetUIRoutes 返回插件提供的UI路由
	// 定义了插件UI组件如何集成到主应用的路由系统
	GetUIRoutes() ([]UIRoute, error)
}

type UIResource struct {
	Path        string // 资源路径
	ContentType string // 内容类型
	Data        []byte // 资源数据
}

type UIRoute struct {
	Path        string    // 路由路径
	Component   string    // 组件名称
	Title       string    // 页面标题
	Icon        string    // 图标
	Permissions []string  // 所需权限
	Children    []UIRoute // 子路由
}

type VersionInfo struct {
	Version     string   // 版本号
	BuildTime   string   // 构建时间
	GitCommit   string   // Git提交哈希
	APIVersions []string // 支持的API版本
}

type Versionable interface {
	// GetVersion 获取版本信息
	// 返回: 版本信息
	GetVersion() VersionInfo

	// CheckCompatibility 检查兼容性
	// requiredVersion: 所需版本
	// 返回: 是否兼容
	CheckCompatibility(requiredVersion string) bool
}

type Watcher interface {
	// Stop 停止观察
	Stop() error
}