data

type BinaryCache interface {
	// Get reads a cached []byte value by key.
	//
	// Get 按 key 读取缓存 []byte 值。
	Get(ctx context.Context, key string) ([]byte, error)

	// Set writes a []byte value into cache with a TTL.
	//
	// Set 按 TTL 将 []byte 值写入缓存。
	Set(ctx context.Context, key string, value []byte, ttl time.Duration) error

	// Del deletes a cached value by key.
	//
	// Del 按 key 删除缓存值。
	Del(ctx context.Context, key string) error

	// MGet reads multiple cached values in one call.
	//
	// MGet 一次调用读取多个缓存值。
	MGet(ctx context.Context, keys ...string) (map[string][]byte, error)

	// MSet writes multiple key-value pairs in one call.
	//
	// MSet 一次调用写入多个键值对。
	MSet(ctx context.Context, kvs map[string][]byte, ttl time.Duration) error

	// Remember loads from cache first and computes the value on miss.
	//
	// Remember 先查缓存，未命中时再计算并回填结果。
	Remember(ctx context.Context, key string, ttl time.Duration, fn func(context.Context) ([]byte, error)) ([]byte, error)
}

type Cache interface {
	// Get reads a cached string value by key.
	//
	// Get 按 key 读取缓存字符串值。
	Get(ctx context.Context, key string) (string, error)

	// Set writes a string value into cache with a TTL.
	//
	// Set 按 TTL 将字符串值写入缓存。
	Set(ctx context.Context, key, value string, ttl time.Duration) error

	// Del deletes a cached value by key.
	//
	// Del 按 key 删除缓存值。
	Del(ctx context.Context, key string) error

	// MGet reads multiple cached values in one call.
	//
	// MGet 一次调用读取多个缓存值。
	MGet(ctx context.Context, keys ...string) (map[string]string, error)

	// MSet writes multiple key-value pairs in one call.
	//
	// MSet 一次调用写入多个键值对。
	MSet(ctx context.Context, kvs map[string]string, ttl time.Duration) error

	// Remember loads from cache first and computes the value on miss.
	//
	// Remember 先查缓存，未命中时再计算并回填结果。
	Remember(ctx context.Context, key string, ttl time.Duration, fn func(context.Context) (string, error)) (string, error)
}

type Column struct {
	Name       string
	Type       string
	NotNull    bool
	PrimaryKey bool
	DefaultVal *string
	Comment    string // Column comment from database schema.

}

type Config interface {
	// Env returns the current application environment name.
	//
	// Env 返回当前应用环境名。
	Env() string

	// Get reads a raw config value by key.
	//
	// Get 按 key 读取原始配置值。
	Get(key string) any

	// GetString reads a config value as string.
	//
	// GetString 以字符串形式读取配置值。
	GetString(key string) string

	// GetInt reads a config value as int.
	//
	// GetInt 以整数形式读取配置值。
	GetInt(key string) int

	// GetBool reads a config value as bool.
	//
	// GetBool 以布尔形式读取配置值。
	GetBool(key string) bool

	// GetFloat reads a config value as float64.
	//
	// GetFloat 以 float64 形式读取配置值。
	GetFloat(key string) float64

	// Unmarshal decodes a config subtree into the target object.
	//
	// Unmarshal 将配置子树解码到目标对象。
	Unmarshal(key string, out any) error

	// Watch subscribes to changes of a given config key.
	//
	// Watch 订阅指定配置 key 的变更事件。
	Watch(ctx context.Context, key string) (ConfigWatcher, error)

	// Reload forces a config refresh from the underlying source.
	//
	// Reload 强制从底层配置源刷新配置。
	Reload(ctx context.Context) error
}

type ConfigSource interface {
	// Load loads the full config snapshot.
	//
	// Load 加载完整配置快照。
	Load(ctx context.Context) (map[string]any, error)

	// Get reads a single config value from the source.
	//
	// Get 从配置源读取单个配置值。
	Get(ctx context.Context, key string) (any, error)

	// Set writes a config value back to the source when supported.
	//
	// Set 在配置源支持时回写配置值。
	Set(ctx context.Context, key string, value any) error

	// Watch subscribes to source-side changes of a config key.
	//
	// Watch 订阅配置源侧的指定 key 变更。
	Watch(ctx context.Context, key string) (ConfigWatcher, error)

	// Close releases resources held by the source.
	//
	// Close 释放配置源持有的资源。
	Close() error
}

type ConfigSourceConfig struct {
	Type ConfigSourceType `mapstructure:"type"`

	ConsulAddr  string `mapstructure:"consul_addr"`
	ConsulPath  string `mapstructure:"consul_path"`
	ConsulToken string `mapstructure:"consul_token"`

	EtcdEndpoints []string `mapstructure:"etcd_endpoints"`
	EtcdPath      string   `mapstructure:"etcd_path"`
	EtcdUsername  string   `mapstructure:"etcd_username"`
	EtcdPassword  string   `mapstructure:"etcd_password"`

	NacosAddr      string `mapstructure:"nacos_addr"`
	NacosNamespace string `mapstructure:"nacos_namespace"`
	NacosGroup     string `mapstructure:"nacos_group"`
	NacosDataID    string `mapstructure:"nacos_data_id"`

	ApolloAddr      string `mapstructure:"apollo_addr"`
	ApolloNamespace string `mapstructure:"apollo_namespace"`
	ApolloAppID     string `mapstructure:"apollo_app_id"`
}

type ConfigSourceType string

type ConfigWatcher interface {
	// OnChange registers a callback for key changes.
	//
	// OnChange 为 key 变更注册回调。
	OnChange(key string, callback func(value any))

	// Stop stops the watcher and releases related resources.
	//
	// Stop 停止监听并释放相关资源。
	Stop() error
}

type CustomRuleConfig struct {
	Name    string
	Message string
	Fn      CustomValidateFunc
}

type CustomValidateFunc func(ctx context.Context, field any) bool

type DBConfig struct {
	Driver  string `mapstructure:"driver"`
	Backend string `mapstructure:"backend"`
	DSN     string `mapstructure:"dsn"`

	MaxOpenConns int `mapstructure:"max_open_conns"`
	MaxIdleConns int `mapstructure:"max_idle_conns"`

	// ConnMaxLifetime is the maximum amount of time a connection may be reused.
	// Stored as string (e.g. "30s", "5m") for mapstructure compatibility;
	// use ParseConnMaxLifetime() to convert to time.Duration.
	//
	// ConnMaxLifetime 是连接可复用的最长时间。
	// 以字符串存储（如 "30s"、"5m"）以兼容 mapstructure；
	// 使用 ParseConnMaxLifetime() 转换为 time.Duration。
	ConnMaxLifetime string `mapstructure:"conn_max_lifetime"`
	// ConnMaxIdleTime is the maximum amount of time a connection may be idle.
	// Stored as string; use ParseConnMaxIdleTime() to convert to time.Duration.
	//
	// ConnMaxIdleTime 是连接可空闲的最长时间。
	// 以字符串存储；使用 ParseConnMaxIdleTime() 转换为 time.Duration。
	ConnMaxIdleTime string `mapstructure:"conn_max_idletime"`
}

type DBInspector interface {
	// Ping checks whether the database connection is available.
	//
	// Ping 检查数据库连接是否可用。
	Ping(ctx context.Context) error

	// Tables lists visible tables in the current database.
	//
	// Tables 列出当前数据库中可见的表。
	Tables(ctx context.Context) ([]Table, error)

	// Columns lists visible columns of a given table.
	//
	// Columns 列出指定表中可见的列。
	Columns(ctx context.Context, table string) ([]Column, error)
}

type DistributedLock interface {
	// Lock blocks until the lock is acquired or the context is canceled.
	//
	// Lock 会阻塞直到成功获取锁或 context 被取消。
	Lock(ctx context.Context, key string, ttl time.Duration) error

	// TryLock attempts to acquire the lock immediately.
	//
	// TryLock 尝试立即获取锁。
	TryLock(ctx context.Context, key string, ttl time.Duration) (bool, error)

	// Unlock releases the lock identified by key.
	//
	// Unlock 释放指定 key 对应的锁。
	Unlock(ctx context.Context, key string) error

	// Renew extends the TTL of the lock.
	//
	// Renew 延长锁的 TTL。
	Renew(ctx context.Context, key string, ttl time.Duration) error

	// IsLocked reports whether the target key is currently locked.
	//
	// IsLocked 返回目标 key 当前是否处于加锁状态。
	IsLocked(ctx context.Context, key string) (bool, error)

	// WithLock executes the callback while holding the lock.
	// Guarantees that the lock is released after fn returns (even on panic),
	// using deferred unlock semantics.
	//
	// WithLock 在持有锁期间执行回调。
	// 保证在 fn 返回后（即使 panic）自动释放锁，使用 defer unlock 语义。
	WithLock(ctx context.Context, key string, ttl time.Duration, fn func() error) error
}

type DistributedLockConfig struct {
	Type string

	RedisAddr     string
	RedisPassword string
	RedisDB       int

	EtcdEndpoints []string
	EtcdUsername  string
	EtcdPassword  string

	DefaultTTL    time.Duration
	RetryInterval time.Duration
	MaxRetry      int
	KeyPrefix     string
}

type EntClientFactory interface {
	// CreateEntClient creates an Ent client from the current container.
	//
	// CreateEntClient 从当前容器创建 Ent client。
	CreateEntClient(c runtimecontract.Container) (any, error)
}

type GormDB interface {
	// WithContext returns a context-bound Gorm handle.
	//
	// WithContext 返回绑定 context 的 Gorm 句柄。
	WithContext(ctx context.Context) any
}

type Migrator interface {
	// AutoMigrate executes schema auto migration for the given models.
	//
	// AutoMigrate 对给定模型执行自动迁移。
	//
	// ⚠ 适用范围：仅限开发/测试环境。生产环境请使用版本化迁移工具（如 golang-migrate）。
	// 原因：AutoMigrate 直接 ALTER TABLE，存在丢数据、锁表风险，无法回滚，无法追踪历史。
	// 开发期：改 model → 重启服务 → 表结构自动同步，快速迭代。
	// 生产期：用 golang-migrate 管理版本化迁移文件，review SQL，支持 up/down。
	AutoMigrate(dst ...any) error
}

type Redis interface {
	// Ping checks whether the Redis connection is available.
	//
	// Ping 检查 Redis 连接是否可用。
	Ping(ctx context.Context) error

	// Get reads a string value by key.
	//
	// Get 按 key 读取字符串值。
	Get(ctx context.Context, key string) (string, error)

	// Set writes a string value with a TTL.
	//
	// Set 按 TTL 写入字符串值。
	Set(ctx context.Context, key string, value string, ttl time.Duration) error

	// Del deletes a key.
	//
	// Del 删除指定 key。
	Del(ctx context.Context, key string) error

	// MGet reads multiple string values in one call.
	//
	// MGet 一次调用读取多个字符串值。
	MGet(ctx context.Context, keys ...string) (map[string]string, error)

	// MSet writes multiple string values in one call.
	//
	// MSet 一次调用写入多个字符串值。
	MSet(ctx context.Context, kvs map[string]string) error

	// Expire sets a TTL on an existing key.
	//
	// Expire 为已存在的 key 设置 TTL。
	Expire(ctx context.Context, key string, ttl time.Duration) error
}

type RuntimeBackend string

type SQLExecutor interface {
	// ExecContext executes a SQL statement in context.
	//
	// ExecContext 在指定 context 中执行 SQL 语句。
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}

type SQLX interface {
	// SQLXExecContext executes a SQL statement through SQLX.
	// Named SQLXExecContext (not ExecContext) to avoid signature conflict
	// with SQLExecutor.ExecContext which returns (sql.Result, error).
	//
	// SQLXExecContext 通过 SQLX 执行 SQL 语句。
	// 命名为 SQLXExecContext（而非 ExecContext）以避免与
	// SQLExecutor.ExecContext 的返回值签名冲突。
	SQLXExecContext(ctx context.Context, query string, args ...any) (any, error)
}

type Table struct {
	Name string
}

type ValidationError struct {
	Field   string
	Tag     string
	Message string
	Value   any
}

type ValidationErrors []ValidationError

type Validator interface {
	// Validate validates the target object.
	//
	// Validate 校验目标对象。
	Validate(ctx context.Context, obj any) error

	// ValidateVar validates a single value against a validation tag.
	//
	// ValidateVar 使用指定 tag 校验单个值。
	ValidateVar(ctx context.Context, field any, tag string) error

	// RegisterCustom registers a named custom validation rule.
	//
	// RegisterCustom 注册具名自定义校验规则。
	RegisterCustom(name string, fn CustomValidateFunc) error

	// SetLocale switches the active validation locale.
	//
	// SetLocale 切换当前校验语言环境。
	SetLocale(locale string) error

	// TranslateError converts a raw validation error into an app error.
	// Returns an error that can be cast to resiliencecontract.AppError if needed.
	//
	// TranslateError 将原始校验错误转换为应用错误。
	// 返回的 error 可在需要时断言为 resiliencecontract.AppError。
	TranslateError(err error) error
}

type ValidatorConfig struct {
	Enabled         bool
	Locale          string
	TranslateErrors bool // TranslateErrors controls whether to translate validation errors.

	CustomRules map[string]CustomRuleConfig
}