app

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

type Closer interface {
	Close(ctx context.Context) error
}

type Events interface {
	// Emit 通知一个动作。实现须异步执行，不拖慢调用方，也不向调用方报错。
	Emit(ctx context.Context, action string, data any)
	// Subscribed 判断有没有插件订阅了某个过滤器；没有时调用方可以连编码都省掉。
	Subscribed(filter string) bool
	// Filter 把值依次交给订阅了过滤器的插件，返回最终的值；任何一环失败都跳过那一环。
	Filter(ctx context.Context, filter string, value json.RawMessage) json.RawMessage
}

type Frontend interface {
	// Slot 返回插件放进某个插槽的内容。
	Slot(ctx context.Context, slot string, page *hooks.Page) template.HTML
	// Widget 渲染一个插件小组件，id 形如 <插件>/<小组件>；插件没启用或没产出内容时 ok 为假。
	Widget(ctx context.Context, id string, page *hooks.Page) (label string, html template.HTML, ok bool)
	// Shortcodes 展开正文里的短代码，返回新的正文；没有可展开的短代码时 changed 为假。
	Shortcodes(ctx context.Context, html string, page *hooks.Page) (out string, changed bool)
	// StripShortcodes 去掉纯文字里认得的短代码，摘要与页面描述里用。
	StripShortcodes(text string) string
}

type Hook struct {
	// Name 是钩子点标识。
	Name string
	// Priority 决定执行顺序，数值小者先执行。
	Priority int
	// Handler 是钩子实现。
	Handler HookFunc
}

type HookFunc func(http.Handler) http.Handler

type HookProvider interface {
	Hooks() []Hook
}

type Migrator interface {
	Migrations() fs.FS
}

type Module interface {
	// Name 返回模块的唯一标识，用于日志、迁移版本表名与依赖诊断。
	// 须为小写字母开头的短标识（字母、数字、下划线、连字符）。
	Name() string
	// Register 把模块的能力挂载到应用上。
	//
	// 只做装配，不得访问数据库：migrate 命令也会走同一条注册链，而那时业务表
	// 可能尚不存在。需要读写库的启动逻辑放到 Starter.Start。
	Register(app *App) error
}

type NamedFS struct {
	Module string
	FS     fs.FS
}

type NavGroup struct {
	// Name 是分组标识（DNS-1123），菜单项用它指认自己属于哪一组。
	Name string
	// Label 是分组显示名。
	Label string
	// Order 决定分组顺序，数值小者在前。
	Order int
}

type NavItem struct {
	// Key 是菜单项的稳定标识，同一分组内唯一。供前端做 key 与诊断用。
	Key string
	// Label 是菜单项显示名。
	Label string
	// Path 是 Console 内的绝对路径，如 /posts。
	//
	// 必须是绝对路径：前端以 basename=/console 挂载 SPA，
	// 相对路径会被解析到当前页之下。
	Path string
	// Icon 是图标名，取值来自 console/src/lib/icons.ts 的登记表。
	//
	// 后端只能给出名字，而两侧之间没有编译期约束：写了登记表里没有的名字，
	// 前端只会画一个默认图标，界面上不会有任何提示。故由 cmd/lumo 的契约测试盯着。
	Icon string
	// Group 是所属分组的 Name。
	Group string
	// Order 决定同组内的顺序，数值小者在前。
	Order int
	// Permission 是显示所需的权限串；留空表示所有已登录用户可见。
	//
	// 这是**显示条件而非安全边界**：没有权限就不显示入口，真正的拦截在服务端。
	// 前端隐藏按钮只是少让人白跑一趟。
	Permission string
	// Keywords 是命令面板的检索关键词（含拼音），便于中文输入习惯。
	Keywords string
	// Description 是一句话说明，供命令面板与悬停提示使用；可留空。
	Description string
	// End 为真时只在路径完全相等时高亮，用于「概览」这类根路径项。
	End bool
	// Hidden 为真时不进侧边栏，但仍参与命令面板与标题映射（如个人中心）。
	Hidden bool
}

type Navigation struct {
	Groups []NavGroup
	Items  []NavItem
}

type NavigationProvider interface {
	Navigation() Navigation
}

type Options struct {
	Config config.Config
	// DB 可为 nil：不需要数据库的命令（如仅渲染帮助）也应能构造 App。
	DB     *database.DB
	Logger *slog.Logger
	// Router 可为 nil：migrate 等非 HTTP 场景不注册接口。
	Router Router
}

type Permission struct {
	// Key 是权限串，如 posts:write。
	Key string
	// Label 是显示名，走 i18n key。
	Label string
	// Description 是权限说明。
	Description string
}

type PermissionProvider interface {
	Permissions() []Permission
}

type RouteProvider interface {
	Routes(r Router)
}

type Router interface {
	// Console 挂载 /api/v1/console/** ：已解析凭据、CSRF 校验、强制已认证；
	// 细粒度权限由各操作用 auth.RequirePermission 或 Principal.Allows 声明。
	Console() huma.API
	// ConsolePublic 挂载 Console 平面下**免认证**的端点，仅供登录一类极少数场景。
	ConsolePublic() huma.API
	// Public 挂载 /api/v1/public/** ：解析凭据但不强制，匿名可读已发布内容。
	Public() huma.API
	// Extension 挂载 /apis/{group}/{version}/{kind} ：强制已认证。
	Extension() huma.API
	// Raw 在站点根路径上挂一个直接写响应的处理器，供 robots.txt、sitemap.xml、
	// 订阅源一类**非 JSON 且必须位于根路径**的资源使用。
	//
	// 这是三平面之外唯一的注册口子，刻意开得很窄：它不经过任何鉴权与内容协商，
	// 挂上去的处理器对匿名请求可见。业务接口一律走上面四个注册面。
	Raw(method, path string, handler http.HandlerFunc)
}

type SettingGroup struct {
	// Name 是分组标识（DNS-1123），如 site、seo、mail。
	Name string
	// Label 是分组显示名。
	Label string
	// Description 是分组说明。
	Description string
	// Order 决定 Console 中的显示顺序，数值小者在前。
	Order int
	// Icon 是该分组的图标名，取值来自 console/src/lib/icons.ts 的登记表。
	//
	// 分组自己声明图标，设置页的区块标题与命令面板入口因此都从分组列表推导——
	// 少一处需要手工同步的清单，也就不会再出现「后端有这一组、界面上没有入口」。
	Icon string
	// Toggle 是本组主开关的字段名，可留空。
	//
	// 设置页把所有分组铺在一页上，各组默认收起；声明了主开关的组，
	// 那个开关会提到区块标题栏上——「开放评论」「启用邮件发送」「开放注册」
	// 这类决定「这一整块要不要生效」的开关，是站长最常动的东西，
	// 让它需要先展开一层才够得着，就是把最常用的动作放到最深的地方。
	//
	// 字段必须存在于 Form 中且为布尔，否则注册时报错：写错一个名字的代价
	// 是标题栏上少个开关，而那在界面上没有任何提示。
	Toggle string
	// Form 是表单声明。模块用 internal/form 的 DSL 构建；
	// 主题包从 settings.yaml 读入后经 form.Build 得到。
	//
	// 值 = Form 的缺省值被已保存值按顶层键覆盖；Schema、缺省值与条件依赖
	// 三者同出一处，不再有「stuct 改了 Schema 忘了改」这种缝。
	Form *form.Form
	// Public 列出可经 Public 平面读取的字段名（如站点标题）；其余字段仅 Console 可见。
	Public []string
	// Check 是 Schema 之外的 Go 侧校验（如时区名是否真实存在），入参为合并默认值后的有效值；可为 nil。
	Check func(values map[string]any) error
}

type SettingsProvider interface {
	Settings() []SettingGroup
}

type Starter interface {
	Start(ctx context.Context) error
}