crud

type Builder[T any] interface {
	// ResourceKind sets the resource kind (RPC or REST) for this endpoint.
	ResourceKind(kind api.Kind) T
	// Action sets the action name for this endpoint.
	Action(action string) T
	// EnableAudit enables audit logging for this endpoint.
	EnableAudit() T
	// Timeout sets the request timeout for this endpoint.
	Timeout(timeout time.Duration) T
	// Public marks this endpoint as publicly accessible without authentication.
	Public() T
	// PermToken sets the permission token required to access this endpoint.
	PermToken(token string) T
	// RateLimit configures rate limiting for this endpoint.
	RateLimit(maxRequests int, period time.Duration) T
	// Build creates an OperationSpec with the configured settings and the given handler.
	Build(handler any) api.OperationSpec
}

type Create[TModel, TParams any] interface {
	api.OperationsProvider
	Builder[Create[TModel, TParams]]

	// WithPreCreate registers a processor that is called before the model is saved to the database.
	WithPreCreate(processor PreCreateProcessor[TModel, TParams]) Create[TModel, TParams]
	// WithPostCreate registers a processor that is called after the model is saved within the same transaction.
	WithPostCreate(processor PostCreateProcessor[TModel, TParams]) Create[TModel, TParams]
}

type CreateMany[TModel, TParams any] interface {
	api.OperationsProvider
	Builder[CreateMany[TModel, TParams]]

	// WithPreCreateMany registers a processor that is called before the models are saved to the database.
	WithPreCreateMany(processor PreCreateManyProcessor[TModel, TParams]) CreateMany[TModel, TParams]
	// WithPostCreateMany registers a processor that is called after the models are saved within the same transaction.
	WithPostCreateMany(processor PostCreateManyProcessor[TModel, TParams]) CreateMany[TModel, TParams]
}

type CreateManyParams[TParams any] struct {
	api.P

	List []TParams `json:"list" validate:"required,min=1,dive" label_i18n:"batch_create_list"`
}

type DataOption struct {
	// Display text shown to users
	Label string `json:"label" bun:"label"`
	// Underlying value used in form submissions
	Value string `json:"value" bun:"value"`
	// Additional descriptive text (optional)
	Description string `json:"description,omitempty" bun:"description"`
	// Custom metadata for extended functionality (optional)
	Meta map[string]any `json:"meta,omitempty" bun:"meta"`
}

type DataOptionColumnMapping struct {
	// Column name for label (default: "name")
	LabelColumn string `json:"labelColumn"`
	// Column name for value (default: "id")
	ValueColumn string `json:"valueColumn"`
	// Column name for description
	DescriptionColumn string `json:"descriptionColumn"`
	// Additional columns to include in meta field
	// Supports simple column names or "column AS alias" format
	// Examples: ["status", "role_name as role"]
	MetaColumns []string `json:"metaColumns"`
}

type DataOptionConfig struct {
	api.M

	DataOptionColumnMapping
}

type Delete[TModel any] interface {
	api.OperationsProvider
	Builder[Delete[TModel]]

	// WithPreDelete registers a processor that is called before the model is deleted from the database.
	WithPreDelete(processor PreDeleteProcessor[TModel]) Delete[TModel]
	// WithPostDelete registers a processor that is called after the model is deleted within the same transaction.
	WithPostDelete(processor PostDeleteProcessor[TModel]) Delete[TModel]
	// DisableDataPerm disables automatic data permission filtering for delete queries.
	DisableDataPerm() Delete[TModel]
}

type DeleteMany[TModel any] interface {
	api.OperationsProvider
	Builder[DeleteMany[TModel]]

	// WithPreDeleteMany registers a processor that is called before the models are deleted from the database.
	WithPreDeleteMany(processor PreDeleteManyProcessor[TModel]) DeleteMany[TModel]
	// WithPostDeleteMany registers a processor that is called after the models are deleted within the same transaction.
	WithPostDeleteMany(processor PostDeleteManyProcessor[TModel]) DeleteMany[TModel]
	// DisableDataPerm disables automatic data permission filtering for batch delete queries.
	DisableDataPerm() DeleteMany[TModel]
}

type DeleteManyParams struct {
	api.P

	PKs []any `json:"pks" validate:"required,min=1" label_i18n:"batch_delete_pks"`
}

type Export[TModel, TSearch any] interface {
	api.OperationsProvider
	Find[TModel, TSearch, []TModel, Export[TModel, TSearch]]

	// WithDefaultFormat sets the default export format (Excel or CSV) when not specified in the request.
	WithDefaultFormat(format TabularFormat) Export[TModel, TSearch]
	// WithExcelOptions configures Excel-specific export options (sheet name, styles, etc.).
	WithExcelOptions(opts ...excel.ExportOption) Export[TModel, TSearch]
	// WithCsvOptions configures CSV-specific export options (delimiter, encoding, etc.).
	WithCsvOptions(opts ...csv.ExportOption) Export[TModel, TSearch]
	// WithPreExport registers a processor for post-query data transformation before export.
	WithPreExport(processor PreExportProcessor[TModel, TSearch]) Export[TModel, TSearch]
	// WithFilenameBuilder sets a custom function to generate the export filename.
	WithFilenameBuilder(builder FilenameBuilder[TSearch]) Export[TModel, TSearch]
}

type FilenameBuilder[TSearch any] func(search TSearch, ctx fiber.Ctx) string

type Find[TModel, TSearch, TProcessorIn, TOperation any] interface {
	Builder[TOperation]

	// Setup initializes the find operation with framework-level options and validates configuration.
	// Must be called before query execution. Config specifies which QueryParts framework options apply to.
	Setup(db orm.DB, config *FindOperationConfig, opts ...*FindOperationOption) error
	// ConfigureQuery applies FindOperationOption for the specified QueryPart to the query.
	// Returns error if any option applier fails.
	ConfigureQuery(query orm.SelectQuery, search TSearch, meta api.Meta, ctx fiber.Ctx, part QueryPart) error
	// Process applies post-query processing to transform results.
	// Returns input unchanged if no Processor is configured.
	Process(input TProcessorIn, search TSearch, ctx fiber.Ctx) any

	// WithProcessor registers a post-query processor to transform or enrich results before returning.
	WithProcessor(processor Processor[TProcessorIn, TSearch]) TOperation
	// WithOptions appends custom FindOperationOption to the query configuration.
	WithOptions(opts ...*FindOperationOption) TOperation
	// WithSelect adds a column to the SELECT clause for specified query parts.
	WithSelect(column string, parts ...QueryPart) TOperation
	// WithSelectAs adds a column with an alias to the SELECT clause for specified query parts.
	WithSelectAs(column, alias string, parts ...QueryPart) TOperation
	// WithDefaultSort sets the default sort order when no dynamic sorting is provided in the request.
	WithDefaultSort(sort ...*sortx.OrderSpec) TOperation
	// WithCondition adds a WHERE condition using ConditionBuilder for specified query parts.
	WithCondition(fn func(cb orm.ConditionBuilder), parts ...QueryPart) TOperation
	// DisableDataPerm disables automatic data permission filtering for this endpoint.
	// IMPORTANT: Must be called before the API is registered (before Setup() is invoked).
	DisableDataPerm() TOperation
	// WithRelation adds a relation join to the query for specified query parts.
	WithRelation(relation *orm.RelationSpec, parts ...QueryPart) TOperation
	// WithAuditUserNames joins audit user model to populate creator/updater name fields.
	WithAuditUserNames(userModel any, nameColumn ...string) TOperation
	// WithQueryApplier adds a custom query modification function for specified query parts.
	WithQueryApplier(applier func(query orm.SelectQuery, search TSearch, ctx fiber.Ctx) error, parts ...QueryPart) TOperation
}

type FindAll[TModel, TSearch any] interface {
	api.OperationsProvider
	Find[TModel, TSearch, []TModel, FindAll[TModel, TSearch]]
}

type FindOne[TModel, TSearch any] interface {
	api.OperationsProvider
	Find[TModel, TSearch, TModel, FindOne[TModel, TSearch]]
}

type FindOperationConfig struct {
	// QueryParts defines which query operations (condition, sort, audit relations) apply to different query contexts
	QueryParts *QueryPartsConfig
}

type FindOperationOption struct {
	Parts   []QueryPart
	Applier func(query orm.SelectQuery, search any, meta api.Meta, ctx fiber.Ctx) error
}

type FindOptions[TModel, TSearch any] interface {
	api.OperationsProvider
	Find[TModel, TSearch, []DataOption, FindOptions[TModel, TSearch]]

	// WithDefaultColumnMapping sets fallback column mapping for value, label, and description columns.
	WithDefaultColumnMapping(mapping *DataOptionColumnMapping) FindOptions[TModel, TSearch]
}

type FindPage[TModel, TSearch any] interface {
	api.OperationsProvider
	Find[TModel, TSearch, []TModel, FindPage[TModel, TSearch]]

	// WithDefaultPageSize sets the fallback page size when the request's page size is zero or invalid.
	WithDefaultPageSize(size int) FindPage[TModel, TSearch]
}

type FindTree[TModel, TSearch any] interface {
	api.OperationsProvider
	Find[TModel, TSearch, []TModel, FindTree[TModel, TSearch]]

	// WithIDColumn sets the column used to identify individual tree nodes.
	WithIDColumn(name string) FindTree[TModel, TSearch]
	// WithParentIDColumn sets the column that establishes parent-child relationships between nodes.
	WithParentIDColumn(name string) FindTree[TModel, TSearch]
}

type FindTreeOptions[TModel, TSearch any] interface {
	api.OperationsProvider
	Find[TModel, TSearch, []TreeDataOption, FindTreeOptions[TModel, TSearch]]

	// WithDefaultColumnMapping sets fallback column mapping for label, value, description, and sort columns.
	WithDefaultColumnMapping(mapping *DataOptionColumnMapping) FindTreeOptions[TModel, TSearch]
	// WithIDColumn sets the column used to identify individual tree nodes.
	WithIDColumn(name string) FindTreeOptions[TModel, TSearch]
	// WithParentIDColumn sets the column that establishes parent-child relationships between nodes.
	WithParentIDColumn(name string) FindTreeOptions[TModel, TSearch]
}

type Import[TModel any] interface {
	api.OperationsProvider
	Builder[Import[TModel]]

	// WithDefaultFormat sets the default import format (Excel or CSV) when not specified in the request.
	WithDefaultFormat(format TabularFormat) Import[TModel]
	// WithExcelOptions configures Excel-specific import options (sheet index, header row, etc.).
	WithExcelOptions(opts ...excel.ImportOption) Import[TModel]
	// WithCsvOptions configures CSV-specific import options (delimiter, encoding, etc.).
	WithCsvOptions(opts ...csv.ImportOption) Import[TModel]
	// WithPreImport registers a processor that is called before parsed models are inserted into the database.
	WithPreImport(processor PreImportProcessor[TModel]) Import[TModel]
	// WithPostImport registers a processor that is called after models are inserted within the same transaction.
	WithPostImport(processor PostImportProcessor[TModel]) Import[TModel]
}

type PostCreateManyProcessor[TModel, TParams any] func(models []TModel, paramsList []TParams, ctx fiber.Ctx, tx orm.DB) error

type PostCreateProcessor[TModel, TParams any] func(model *TModel, params *TParams, ctx fiber.Ctx, tx orm.DB) error

type PostDeleteManyProcessor[TModel any] func(models []TModel, ctx fiber.Ctx, tx orm.DB) error

type PostDeleteProcessor[TModel any] func(model *TModel, ctx fiber.Ctx, tx orm.DB) error

type PostImportProcessor[TModel any] func(models []TModel, ctx fiber.Ctx, tx orm.DB) error

type PostUpdateManyProcessor[TModel, TParams any] func(oldModels, models []TModel, paramsList []TParams, ctx fiber.Ctx, tx orm.DB) error

type PostUpdateProcessor[TModel, TParams any] func(oldModel, model *TModel, params *TParams, ctx fiber.Ctx, tx orm.DB) error

type PreCreateManyProcessor[TModel, TParams any] func(models []TModel, paramsList []TParams, query orm.InsertQuery, ctx fiber.Ctx, tx orm.DB) error

type PreCreateProcessor[TModel, TParams any] func(model *TModel, params *TParams, query orm.InsertQuery, ctx fiber.Ctx, tx orm.DB) error

type PreDeleteManyProcessor[TModel any] func(models []TModel, query orm.DeleteQuery, ctx fiber.Ctx, tx orm.DB) error

type PreDeleteProcessor[TModel any] func(model *TModel, query orm.DeleteQuery, ctx fiber.Ctx, tx orm.DB) error

type PreExportProcessor[TModel, TSearch any] func(models []TModel, search TSearch, ctx fiber.Ctx, db orm.DB) error

type PreImportProcessor[TModel any] func(models []TModel, query orm.InsertQuery, ctx fiber.Ctx, tx orm.DB) error

type PreUpdateManyProcessor[TModel, TParams any] func(oldModels, models []TModel, paramsList []TParams, query orm.UpdateQuery, ctx fiber.Ctx, tx orm.DB) error

type PreUpdateProcessor[TModel, TParams any] func(oldModel, model *TModel, params *TParams, query orm.UpdateQuery, ctx fiber.Ctx, tx orm.DB) error

type Processor[TIn, TSearch any] func(input TIn, search TSearch, ctx fiber.Ctx) any

type QueryPart int

type QueryPartsConfig struct {
	// Condition specifies which queries apply WHERE clause filtering
	Condition []QueryPart
	// Sort specifies which queries apply ORDER BY sorting
	Sort []QueryPart
	// AuditUserRelation specifies which queries auto-join audit user relations (created_by, updated_by)
	AuditUserRelation []QueryPart
}

type Sortable struct {
	api.M

	Sort []sortx.OrderSpec `json:"sort"`
}

type TabularFormat string

type TreeDataOption struct {
	DataOption

	// Unique identifier for the tree node
	ID string `json:"-" bun:"id"`
	// Parent node identifier (null for root nodes)
	ParentID null.String `json:"-" bun:"parent_id"`
	// Nested child options forming the tree structure
	Children []TreeDataOption `json:"children,omitempty" bun:"-"`
}

type Update[TModel, TParams any] interface {
	api.OperationsProvider
	Builder[Update[TModel, TParams]]

	// WithPreUpdate registers a processor that is called before the model is updated in the database.
	WithPreUpdate(processor PreUpdateProcessor[TModel, TParams]) Update[TModel, TParams]
	// WithPostUpdate registers a processor that is called after the model is updated within the same transaction.
	WithPostUpdate(processor PostUpdateProcessor[TModel, TParams]) Update[TModel, TParams]
	// DisableDataPerm disables automatic data permission filtering for update queries.
	DisableDataPerm() Update[TModel, TParams]
}

type UpdateMany[TModel, TParams any] interface {
	api.OperationsProvider
	Builder[UpdateMany[TModel, TParams]]

	// WithPreUpdateMany registers a processor that is called before the models are updated in the database.
	WithPreUpdateMany(processor PreUpdateManyProcessor[TModel, TParams]) UpdateMany[TModel, TParams]
	// WithPostUpdateMany registers a processor that is called after the models are updated within the same transaction.
	WithPostUpdateMany(processor PostUpdateManyProcessor[TModel, TParams]) UpdateMany[TModel, TParams]
	// DisableDataPerm disables automatic data permission filtering for batch update queries.
	DisableDataPerm() UpdateMany[TModel, TParams]
}

type UpdateManyParams[TParams any] struct {
	api.P

	List []TParams `json:"list" validate:"required,min=1,dive" label_i18n:"batch_update_list"`
}