plugin

type Author struct {
	Name    string `yaml:"name" json:"name"`
	Website string `yaml:"website" json:"website"`
}

type Capabilities struct {
	// Content 是对站点内容的读写。
	Content ContentAccess `yaml:"content" json:"content"`
	// HTTP 是允许访问的外部域名：精确域名，或 *.example.com 形式的一级通配。
	HTTP []string `yaml:"http" json:"http"`
	// Mail 表示要经站点的 SMTP 发邮件。
	Mail bool `yaml:"mail" json:"mail"`
	// Cron 表示要定时运行任务。
	Cron bool `yaml:"cron" json:"cron"`
	// Frontend 表示要往前台页面里放东西（插槽、小组件、短代码、静态脚本与样式）。
	Frontend bool `yaml:"frontend" json:"frontend"`
}

type ContentAccess struct {
	// Read 表示读取文章、页面、分类、标签、评论与用户公开资料。
	Read bool `yaml:"read" json:"read"`
	// Write 是写操作要用的权限串，写入时按它判定；声明了写就隐含可读。
	Write []string `yaml:"write" json:"write"`
}

type CronJob struct {
	// Name 是任务名，对应 SDK 里 OnCron 登记的名字。
	Name string `yaml:"name" json:"name"`
	// Every 是运行间隔，Go 时长写法，如 10m、1h、24h。
	Every       string `yaml:"every" json:"every"`
	Description string `yaml:"description" json:"description"`
	// contains filtered or unexported fields
}

type DataCounts struct {
	Settings int `json:"settings" doc:"保存过的设置分组数"`
	KV       int `json:"kv" doc:"键值条数"`
	Records  int `json:"records" doc:"资源记录条数"`
}

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

type DepStatus struct {
	Dep Dependency
	// Installed 为真表示被依赖的插件已安装。
	Installed bool
	// InstalledVersion 是已安装那个插件的版本；没装时为空串。
	InstalledVersion string
	// Enabled 为真表示已安装且已启用。
	Enabled bool
	// Satisfied 为真表示这条依赖已就绪：装了、启用了、版本也够。
	Satisfied bool
}

type Dependency struct {
	// Name 是被依赖插件的标识。
	Name string `yaml:"name" json:"name"`
	// Version 是版本范围，如 >=1.0.0、^1.2、~1.2.3、1.2.*；留空表示不限。写法见 version.go。
	Version string `yaml:"version" json:"version"`
	// contains filtered or unexported fields
}

type FrontendDecl struct {
	// Styles 是放进页头的样式表，包里 static/ 下的 .css。
	Styles []string `yaml:"styles" json:"styles"`
	// Scripts 是放在页尾的脚本，包里 static/ 下的 .js，defer 加载。
	Scripts []string `yaml:"scripts" json:"scripts"`
	// Slots 是由后端代码渲染内容的插槽，取值见 hooks.Slots。
	Slots []string `yaml:"slots" json:"slots"`
	// Widgets 是插件提供的侧栏小组件，站长在主题的侧边栏设置里选用。
	Widgets []WidgetDecl `yaml:"widgets" json:"widgets"`
	// Shortcodes 是插件提供的短代码：作者在正文里写 [名字 参数="值"]，前台展开成插件渲染的内容。
	Shortcodes []ShortcodeDecl `yaml:"shortcodes" json:"shortcodes"`
}

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

type Hooks struct {
	// Actions 是订阅的动作名，如 comment.created。
	Actions []string `yaml:"actions" json:"actions"`
	// Filters 是订阅的过滤器名，如 comment.judge。
	Filters []string `yaml:"filters" json:"filters"`
}

type KVItem struct {
	Key       string          `json:"key"`
	Value     json.RawMessage `json:"value"`
	ExpiresAt *time.Time      `json:"expiresAt,omitempty"`
}

type Loaded struct {
	Manifest *Manifest
	// Dir 是插件目录的绝对路径。
	Dir string
	// FS 是插件包的根文件系统。
	FS fs.FS
	// Groups 是插件声明的设置分组。
	Groups []SettingsGroup
	// Resources 是插件声明的资源。
	Resources []Resource
	// Enabled 是当前的启用状态。
	Enabled bool
	// Granted 是站长授予过的能力；nil 表示从没授予过。
	Granted *Capabilities
	// DisabledReason 是系统停用它的原因；站长手动停用时为空串。
	DisabledReason string
	// contains filtered or unexported fields
}

type Manifest struct {
	APIVersion string `yaml:"apiVersion" json:"apiVersion"`
	Kind       string `yaml:"kind" json:"kind"`
	Metadata   Meta   `yaml:"metadata" json:"metadata"`
	Spec       Spec   `yaml:"spec" json:"spec"`
}

type Meta struct {
	// Name 是插件标识（DNS-1123），同时是安装目录名，必须与目录名一致。
	Name string `yaml:"name" json:"name"`
}

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

type PageDecl struct {
	// Path 是地址里的一段，后台地址为 /plugins/<插件>/p/<path>。
	Path        string `yaml:"path" json:"path"`
	Label       string `yaml:"label" json:"label"`
	Description string `yaml:"description" json:"description"`
	// Icon 是侧栏图标名，留空用拼图。
	Icon string `yaml:"icon" json:"icon"`
	// File 是包里 static/ 下的 .html 文件。
	File string `yaml:"file" json:"file"`
	// Menu 为 false 时不在侧栏出入口。缺省为 true。
	Menu *bool `yaml:"menu" json:"menu"`
	// Permission 是打开它要的权限串，缺省 plugins:manage。
	Permission string `yaml:"permission" json:"permission"`
	// contains filtered or unexported fields
}

type Record struct {
	bun.BaseModel `bun:"table:plugins,alias:p"`

	Name        string `bun:"name,pk"`
	Version     string `bun:"version,notnull"`
	DisplayName string `bun:"display_name,notnull"`
	Description string `bun:"description,notnull"`
	Author      string `bun:"author,notnull"`
	Enabled     bool   `bun:"enabled,notnull"`
	Manifest    []byte `bun:"manifest,type:jsonb,notnull"`
	// Granted 是站长授予过的能力；nil 表示从没授予过。
	Granted *Capabilities `bun:"granted,type:jsonb,nullzero"`
	// DisabledReason 是系统停用插件的原因，手动停用时为空串。
	DisabledReason string    `bun:"disabled_reason,notnull"`
	InstalledAt    time.Time `bun:"installed_at,nullzero,notnull,default:now()"`
	UpdatedAt      time.Time `bun:"updated_at,nullzero,notnull,default:now()"`
}

type RecordQuery struct {
	// Match 是字段相等条件（jsonb 包含匹配，走 GIN 索引）。
	Match map[string]any
	// Search 在标题字段里模糊查找。
	Search string
	// Sort 是排序字段，须是资源的顶层字段；留空按创建先后倒序。
	Sort string
	// Desc 为真时倒序。
	Desc   bool
	Limit  int
	Offset int
}

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

type RegistryOptions struct {
	// Root 是插件安装目录，通常是 data/plugins。
	Root  string
	Store *Store
	// Data 是插件自己的数据（设置、键值、资源记录）；卸载时按站长的选择清除或保留。
	Data   *DataStore
	Logger *slog.Logger
	// LumoVersion 是本站 Lumo 的版本号，用来核对 spec.requires；空串表示不核对。
	LumoVersion string
}

type Resource struct {
	Kind string
	// Path 是 URL 里的复数段，由 Kind 推导，如 visits。
	Path        string
	Label       string
	Description string
	Icon        string
	Columns     []string
	Title       string
	Editable    bool
	Menu        bool
	Permission  perm.Permission
	Form        *form.Form
	// contains filtered or unexported fields
}

type ResourceDecl struct {
	// Kind 是资源种类，单数 PascalCase，如 Visit。
	Kind string `yaml:"kind" json:"kind"`
	// Label 是显示名，如「访问记录」。
	Label       string `yaml:"label" json:"label"`
	Description string `yaml:"description" json:"description"`
	// Icon 是侧栏图标名（Console 的图标登记表），留空用拼图。
	Icon string `yaml:"icon" json:"icon"`
	// Schema 是字段声明，JSON Schema 子集，与设置分组相同。
	Schema map[string]any `yaml:"schema" json:"schema"`
	// Defaults 是新建记录时的缺省值。
	Defaults map[string]any `yaml:"defaults" json:"defaults"`
	// Columns 是列表页显示的字段，留空取前三个。
	Columns []string `yaml:"columns" json:"columns"`
	// Title 是用作记录标题的字段，留空取第一个文本字段。
	Title string `yaml:"title" json:"title"`
	// Editable 为 false 时后台只能查看，数据只由插件自己写。缺省为 true。
	Editable *bool `yaml:"editable" json:"editable"`
	// Menu 为 false 时不在侧栏出入口。缺省为 true。
	Menu *bool `yaml:"menu" json:"menu"`
	// Permission 是后台查看与编辑它要的权限串，缺省 plugins:manage。
	Permission string `yaml:"permission" json:"permission"`
}

type ResourceRecord struct {
	ID        int64          `json:"id"`
	Data      map[string]any `json:"data"`
	CreatedAt time.Time      `json:"createdAt"`
	UpdatedAt time.Time      `json:"updatedAt"`
}

type Retained struct {
	Name        string     `bun:"name" json:"name"`
	DisplayName string     `bun:"display_name" json:"displayName"`
	Version     string     `bun:"version" json:"version"`
	RetainedAt  time.Time  `bun:"retained_at" json:"retainedAt"`
	Counts      DataCounts `bun:"-" json:"counts"`
}

type Route struct {
	// Name 是处理函数名，对应 SDK 里 OnRoute 登记的名字。
	Name string `yaml:"name" json:"name"`
	// Method 是请求方法，缺省 GET。
	Method string `yaml:"method" json:"method"`
	// Path 是插件前缀之后的路径，如 /hit、/items/{id}。
	Path string `yaml:"path" json:"path"`
	// Public 为真时谁都能调；否则要登录并持有 Permission。
	Public bool `yaml:"public" json:"public"`
	// Permission 是非公开接口要的权限串，缺省 plugins:manage。
	Permission  string `yaml:"permission" json:"permission"`
	Description string `yaml:"description" json:"description"`
	// contains filtered or unexported fields
}

type SettingsGroup struct {
	Name        string
	Label       string
	Description string
	Order       int
	Icon        string
	Form        *form.Form
	// contains filtered or unexported fields
}

type ShortcodeDecl struct {
	Name        string `yaml:"name" json:"name"`
	Description string `yaml:"description" json:"description"`
}

type Spec struct {
	// DisplayName 是显示名。
	DisplayName string `yaml:"displayName" json:"displayName"`
	// Version 是插件版本。
	Version string `yaml:"version" json:"version"`
	// Description 是一句话说明。
	Description string `yaml:"description" json:"description"`
	// Author 是作者信息。
	Author Author `yaml:"author" json:"author"`
	// Homepage 是插件主页。
	Homepage string `yaml:"homepage" json:"homepage"`
	// Repo 是源码仓库地址。
	Repo string `yaml:"repo" json:"repo"`
	// License 是许可证标识。
	License string `yaml:"license" json:"license"`
	// Requires 声明所需的 Lumo 版本范围，写法同依赖的 version；留空表示不限制。
	// 不满足时装不上，也启用不了（站点回滚到旧版之后）；源码构建的本站版本不比，见 runningVersion。
	Requires string `yaml:"requires" json:"requires"`
	// Dependencies 声明本插件要用到的别的插件与版本范围，如 name: comment-guard、version: ">=1.0.0"。
	// 依赖没就绪（没装、没启用、版本不够）时插件启用不了；被依赖的插件停用或卸载会连带停用本插件。
	Dependencies []Dependency `yaml:"dependencies" json:"dependencies"`
	// Runtime 是后端的运行方式：留空表示纯声明式插件，wasm 表示包里带 plugin.wasm。
	Runtime string `yaml:"runtime" json:"runtime"`
	// Capabilities 是插件要用的宿主能力，启用时由站长逐项确认。
	Capabilities Capabilities `yaml:"capabilities" json:"capabilities"`
	// Hooks 是插件订阅的动作与过滤器。
	Hooks Hooks `yaml:"hooks" json:"hooks"`
	// Resources 是插件自己的数据类型：宿主替它存，后台替它出列表页与编辑页。
	Resources []ResourceDecl `yaml:"resources" json:"resources"`
	// Cron 是按固定间隔在后台运行的任务。
	Cron []CronJob `yaml:"cron" json:"cron"`
	// Routes 是插件自己的 HTTP 接口，挂在 /api/v1/plugins/<插件>/ 之下。
	Routes []Route `yaml:"routes" json:"routes"`
	// Frontend 是插件往前台页面里放的东西：样式、脚本、插槽、小组件与短代码。
	Frontend FrontendDecl `yaml:"frontend" json:"frontend"`
	// Pages 是后台的自定义页面，放在隔离的 iframe 里。
	Pages []PageDecl `yaml:"pages" json:"pages"`
}

type State struct {
	Enabled bool
	// Reason 是系统停用的原因，手动启停时为空串。
	Reason string
	// Granted 是授予过的能力；nil 表示不改动库里已有的值。
	Granted *Capabilities
}

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

type WidgetDecl struct {
	Name        string `yaml:"name" json:"name"`
	Label       string `yaml:"label" json:"label"`
	Description string `yaml:"description" json:"description"`
}