model

type BaseModel struct {
	ID        uint       `db:"pk" json:"id"`
	CreatedAt time.Time  `db:"readonly" json:"created_at"`
	UpdatedAt time.Time  `db:"readonly" json:"updated_at"`
	DeletedAt *time.Time `db:"column:deleted_at" json:"-"`
}

type CRUD struct {
	// contains filtered or unexported fields
}

type CRUDOperator interface {
	FindAll(ctx context.Context, opts QueryOpts) (*PaginatedResult, error)
	FindByID(ctx context.Context, id interface{}) (interface{}, error)
	Create(ctx context.Context, entity interface{}) error
	Update(ctx context.Context, id interface{}, updates map[string]interface{}) error
	Delete(ctx context.Context, id interface{}) error
}

type Choice struct {
	Value string `json:"value"`
	Label string `json:"label"`
}

type FieldMeta struct {
	Name          string // Go field name (e.g. "Email")
	Column        string // SQL column name (e.g. "email")
	Label         string // Human-readable label (e.g. "Correo electrónico")
	GoType        string // Go type as string (e.g. "string", "int", "bool")
	HTMLType      string // HTML input type (e.g. "text", "email", "number")
	IsPK          bool   // Is primary key
	IsRequired    bool   // Required field (not null / validate:"required")
	IsReadOnly    bool   // Read-only in admin forms
	IsList        bool   // Shown in list view
	IsSearch      bool   // Included in search queries
	IsFilter      bool   // Shown as filter option
	IsExcluded    bool   // Excluded from admin entirely
	IsForeignKey  bool   // This field is a foreign key reference
	IsTenantField bool   // This field holds the tenant ID for multi-tenant isolation
	ForeignModel  string // Name of the related model (e.g. "User" for UserID)
	ForeignTable  string // Name of the related table (e.g. "users")
	ForeignColumn string // Name of the referenced column (e.g. "id")
	IndexRefs     []IndexRef
	MaxLength     int      // Max length from validate tag
	Choices       []Choice // Enum/select options

	// UnknownDBTokens records `db:` tag directives the parser did not
	// recognize. They change nothing at runtime, but a silently ignored
	// token means the developer believes a constraint exists that was
	// never applied — so App.Run surfaces them as a boot-time WARN.
	UnknownDBTokens []string
}

type FieldMetaUpdate struct {
	IsList     *bool   `json:"is_list,omitempty"`
	IsSearch   *bool   `json:"is_search,omitempty"`
	IsFilter   *bool   `json:"is_filter,omitempty"`
	IsExcluded *bool   `json:"is_excluded,omitempty"`
	IsReadOnly *bool   `json:"is_readonly,omitempty"`
	Label      *string `json:"label,omitempty"`
	HTMLType   *string `json:"html_type,omitempty"`
}

type Filter struct {
	Column string
	Op     FilterOp
	Value  string
	Values []string
}

type FilterOp string

type ForeignKey struct {
	FieldName     string // The FK field (e.g. "UserID")
	Column        string // The FK column (e.g. "user_id")
	ForeignModel  string // The related model name (e.g. "User")
	ForeignTable  string // The related table name (e.g. "users")
	ForeignColumn string // The related column name (e.g. "id")
}

type HookContext struct {
	Context context.Context
	Engine  string
	DB      *sql.DB
	Tx      *sql.Tx
}

type HookFunc func(ctx HookContext, entity interface{}) error

type IndexMeta struct {
	Name    string   // SQL index name
	Columns []string // Ordered indexed columns
	Unique  bool     // Unique index/constraint
}

type IndexRef struct {
	Name   string `json:"name"`
	Unique bool   `json:"unique"`
}

type ModelConfig struct {
	Icon          string            // Emoji or icon identifier for the admin sidebar
	ListFields    []string          // Fields shown in the list view
	SearchFields  []string          // Fields included in search queries
	Filters       []string          // Fields shown as filters
	OrderBy       string            // Default ordering (e.g. "created_at desc")
	PageSize      int               // Default page size (0 = framework default of 25)
	ReadOnly      bool              // If true, no create/update/delete in admin
	ExcludeFields []string          // Fields excluded from admin
	FieldLabels   map[string]string // Custom labels: field name -> label

	// RejectClientPK makes CRUD.Create return ErrClientAssignedPK when the
	// entity arrives with a non-zero primary key, instead of inserting that
	// key. Off by default: a caller-assigned key travels in the INSERT
	// (client-generated UUIDs, natural keys).
	//
	// Turn it on for models whose HTTP handlers decode a request body
	// straight into the entity (BindJSON + Create): with the default, that
	// pattern lets the HTTP client choose the row's key. The check runs at
	// the top of Create, before hooks — a BeforeCreate hook that assigns a
	// server-generated key still works with this enabled.
	RejectClientPK bool

	// Database affinity
	DatabaseAlias string // Optional database alias for this model (default "default")

	// Lifecycle hooks
	BeforeCreate HookFunc
	AfterCreate  HookFunc
	BeforeUpdate HookFunc
	AfterUpdate  HookFunc
	BeforeDelete HookFunc
}

type ModelMeta struct {
	Name          string       // Go struct name (e.g. "User")
	Plural        string       // Plural name (e.g. "Users")
	Table         string       // SQL table name (e.g. "users")
	Fields        []FieldMeta  // Extracted field metadata
	PrimaryKey    string       // Name of the PK field (e.g. "ID")
	ForeignKeys   []ForeignKey // Detected foreign key relationships
	Indexes       []IndexMeta  // Declared simple/composite indexes
	Config        ModelConfig  // User-provided configuration
	DatabaseAlias string       // Database alias affinity
	Type          reflect.Type // The reflect.Type of the struct
}

type PaginatedResult struct {
	Items       interface{} `json:"items"`
	Total       int64       `json:"total"`
	Page        int         `json:"page"`
	PageSize    int         `json:"page_size"`
	TotalPages  int         `json:"total_pages"`
	IsEstimated bool        `json:"is_estimated"` // Whether the Total count is an estimate
	HasMore     bool        `json:"has_more"`     // Whether there are more pages (useful for infinite scroll)
}

type QueryOpts struct {
	Page     int               // 1-based page number (default: 1)
	PageSize int               // Items per page (default: from ModelConfig)
	Search   string            // Free-text search across SearchFields
	Filters  map[string]string // Exact-match filters: column -> value
	OrderBy  string            // Sort clauses: comma-separated "<column> [asc|desc]" (e.g. "created_at desc, name asc"). Each column must be a known model column; invalid input is rejected with an error (not raw SQL).
	Fields   []string          // SELECT specific columns (empty = all)

	// Where holds the filters that need an operator — a range, a prefix, a
	// set, a null check. Filters stays what it always was (column → value,
	// equality), and the two are ANDed: a caller that never sets Where
	// behaves exactly as before.
	Where []Filter

	// ExactTotal asks for a real COUNT of the matching rows instead of the
	// cheap answer. FindAll never counted a FILTERED query: it answered
	// Total -1 with IsEstimated true, so no pager could say how many pages
	// there were. Counting is a second query, so it is the caller's choice —
	// a screen with a pager asks for it, a background sweep does not.
	ExactTotal bool
}

type Registry struct {
	// contains filtered or unexported fields
}

type SQLQueryEvent struct {
	ModelName string
	Operation string
	Query     string
	Args      []interface{}
	Duration  time.Duration
	Error     error
	// RowsAffected is the driver-reported row count for exec-style
	// operations (INSERT/UPDATE/DELETE). 0 means "not reported": SELECT
	// paths cannot know it without consuming the rows, and some drivers
	// do not support it.
	RowsAffected int64
}

type SQLQueryObserver func(ctx context.Context, event SQLQueryEvent)