spider/internal/plugin/interface.go

package plugin

import "context"

// MerchantData is the standard output format for all collector plugins.
// Every plugin must produce data in this shape via the callback.
type MerchantData struct {
	TgUsername   string `json:"tg_username"`   // required — no tg_username, no insert
	TgLink       string `json:"tg_link"`
	MerchantName string `json:"merchant_name"`
	Website      string `json:"website"`
	Email        string `json:"email"`
	Phone        string `json:"phone"`
	SourceType   string `json:"source_type"`   // web / tg_channel / github
	SourceName   string `json:"source_name"`   // specific source (page title / channel name)
	SourceURL    string `json:"source_url"`    // source URL
	OriginalText string `json:"original_text"` // raw text for audit
	IndustryTag  string `json:"industry_tag"`
}

// Collector is the interface every collection plugin must implement.
type Collector interface {
	// Name returns the plugin name, e.g. "web_collector".
	Name() string
	// Run starts collection. For every merchant found, call callback.
	// cfg carries plugin-specific configuration (keywords, limits, etc.).
	// The function should respect ctx cancellation for graceful shutdown.
	Run(ctx context.Context, cfg map[string]any, callback func(MerchantData)) error
	// Stop requests graceful shutdown from outside.
	Stop() error
}