ihtml

type APISpec struct {
	Name        string `json:"name"`            // 标识, 如 player_search
	Title       string `json:"title,omitempty"` // 一句话名称
	Method      string `json:"method"`          // 目前探测工具只放行 GET
	Path        string `json:"path"`            // 页面同源绝对路径, 如 /capi/players
	Description string `json:"description"`     // 参数与返回结构说明(给 AI 看)
}

type Access struct {
	// ReadOnly 拒绝一切写操作(HTTP 写接口与 AI 工具写), 用于
	// 客服代查/演示账号/免费套餐只读等场景。
	ReadOnly bool
	// ChatDisabled 对该用户禁用 AI 对话(入口隐藏, WS 拒绝)。
	ChatDisabled bool
}

type AuditEvent struct {
	Time   time.Time       `json:"time"`
	User   string          `json:"user"`
	Action string          `json:"action"` // items.put/items.delete/items.replace/items.rollback/kv.set/kv.delete/page.set/page.delete/user.import/user.purge
	By     string          `json:"by"`     // api / chat / import ...
	Note   string          `json:"note,omitempty"`
	Detail json.RawMessage `json:"detail,omitempty"` // ids/key/page 等结构化明细
}

type Breakpoint struct {
	ID       string  `json:"id"`
	Name     string  `json:"name,omitempty"`
	MinWidth int     `json:"min_width,omitempty"`
	MaxWidth int     `json:"max_width,omitempty"`
	Columns  int     `json:"columns,omitempty"`
	Gap      float64 `json:"gap,omitempty"`
}

type Broadcaster interface {
	// Publish 向该用户的所有订阅者投递事件。实现应保证不阻塞调用方。
	// 若实现会丢弃积压事件，必须改为投递 Type="resync" 以显式
	// 告知订阅者，不得静默丢弃。
	Publish(user string, ev Event)
	// Subscribe 订阅该用户的事件流; cancel 幂等, 调用后通道会被关闭。
	Subscribe(user string) (ch <-chan Event, cancel func())
}

type ChatAgentStage struct {
	Mode         string `json:"mode"`  // fast / deep
	Agent        string `json:"agent"` // root / ui_inspector / ui_reviewer
	TaskID       string `json:"task_id,omitempty"`
	ParentTaskID string `json:"parent_task_id,omitempty"`
	Phase        string `json:"phase,omitempty"` // turn / plan / inspect / review / approval
	Status       string `json:"status"`          // running / completed / paused / error
	Summary      string `json:"summary,omitempty"`
	// ApprovalResume 明示确认后的恢复能力。当前 deep 使用 manual_tool_only：
	// 只执行确认卡，不会静默恢复或宣称整个计划完成。
	ApprovalResume string `json:"approval_resume,omitempty"`
}

type ChatBackend interface {
	NewSession(ctx context.Context, sctx *ChatSessionContext) (ChatSession, error)
}

type ChatClientContext struct {
	Viewport  ChatClientViewport `json:"viewport"`
	Page      ChatClientPage     `json:"page"`
	Locale    string             `json:"locale,omitempty"`
	TimeZone  string             `json:"time_zone,omitempty"`
	UserAgent string             `json:"user_agent,omitempty"`
}

type ChatClientEvent struct {
	Type     string        `json:"type"`
	Messages []ChatMessage `json:"messages,omitempty"`
	Model    string        `json:"model,omitempty"`
	// AgentMode 为空或 fast 时走低延迟单 Agent；deep 仅在服务端显式开启后可用。
	AgentMode     string            `json:"agent_mode,omitempty"`
	ToolsEnabled  *bool             `json:"tools_enabled,omitempty"`
	ClientContext ChatClientContext `json:"client_context"`
	ToolCall      *ProposedToolCall `json:"tool_call,omitempty"`
	// InspectID/Inspect 仅用于 inspect_result: 应答服务端的同 ID inspect_request。
	InspectID string                `json:"inspect_id,omitempty"`
	Inspect   *ChatClientInspection `json:"inspect,omitempty"`
}

type ChatClientInspection struct {
	Page        string                     `json:"page,omitempty"` // 当前页面名, 空 = 单页/根
	Viewport    ChatClientViewport         `json:"viewport"`
	ThemeMode   string                     `json:"theme_mode,omitempty"` // light / dark
	Total       int                        `json:"total,omitempty"`      // 过滤后的 Item 总数
	Offset      int                        `json:"offset,omitempty"`
	Limit       int                        `json:"limit,omitempty"`
	NextOffset  int                        `json:"next_offset,omitempty"`
	Truncated   bool                       `json:"truncated,omitempty"` // 仍有后续分页
	Items       []ChatClientInspectionItem `json:"items,omitempty"`
	Errors      []string                   `json:"errors,omitempty"`       // 最近页面错误摘要
	VisibleText string                     `json:"visible_text,omitempty"` // 全页可见文本(截断)
}

type ChatClientInspectionItem struct {
	ID      string `json:"id"`
	Type    string `json:"type,omitempty"`
	Page    string `json:"page,omitempty"`
	Slot    string `json:"slot,omitempty"`
	Present bool   `json:"present"`           // 是否有已连接的 DOM 节点
	Visible bool   `json:"visible,omitempty"` // 是否实际占据可见空间
	Width   int    `json:"width,omitempty"`
	Height  int    `json:"height,omitempty"`
	Text    string `json:"text,omitempty"`  // 渲染文本摘要(截断)
	Error   string `json:"error,omitempty"` // 该 Item 最近一条运行错误
}

type ChatClientPage struct {
	Path        string `json:"path,omitempty"`
	Title       string `json:"title,omitempty"`
	VisibleText string `json:"visible_text,omitempty"`
}

type ChatClientViewport struct {
	Width            int    `json:"width,omitempty"`
	Height           int    `json:"height,omitempty"`
	DevicePixelRatio any    `json:"device_pixel_ratio,omitempty"`
	Mode             string `json:"mode,omitempty"` // pc / mobile
}

type ChatMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type ChatModels struct {
	ProtocolVersion int    `json:"protocol_version"`
	Provider        string `json:"provider,omitempty"`
	ModelReady      bool   `json:"model_ready"`
	// PreviewOnly 表示后端只提供确定性的界面预览，不代表真实模型已连接。
	// 客户端可继续开放输入以演示交互，但必须向用户说明回答并非来自 AI。
	PreviewOnly  bool     `json:"preview_only,omitempty"`
	CurrentModel string   `json:"current_model"`
	Models       []string `json:"models"`
	AgentModes   []string `json:"agent_modes,omitempty"`
	// DeepApprovalResume 当前为 manual_tool_only；未来安全接入 ADK checkpoint
	// 后可升级为 checkpoint，而无需客户端猜测。
	DeepApprovalResume string `json:"deep_approval_resume,omitempty"`
	RequestTimeoutMS   int64  `json:"request_timeout_ms"`
	// ModelSelect 为 true 时前端展示模型选择器(默认隐藏——
	// 模型是运维概念, 不该暴露给终端用户)。
	ModelSelect bool `json:"model_select,omitempty"`
}

type ChatPlanItem struct {
	ID      string `json:"id"`
	Content string `json:"content"`
	Status  string `json:"status"` // pending / in_progress / completed
}

type ChatSession interface {
	HandleEvent(ctx context.Context, ev *ChatClientEvent)
	Close()
}

type ChatSessionContext struct {
	// User 是 UserResolver 解析出的用户。
	User string
	// Service 用于读改 UI 数据。为兼容已有 ChatBackend 保留；新实现应优先
	// 使用 ScopedService，避免意外传入其他用户标识。
	Service Service
	// ScopedService 已绑定并持续校验当前用户，不暴露跨租户 user 参数。
	ScopedService ScopedService
	// Emit 向前端推流式事件, 并发安全; 连接断开后返回错误。
	Emit func(ChatStreamEvent) error
	// Request 是发起 WS 的原始请求, 供后端取额外参数/推导同源地址。
	Request *http.Request
	// APIs 是 WithAPIs 声明的业务 API 目录。
	APIs []APISpec
	// Access 是建立会话时的访问策略快照(只读时后端应隐藏/
	// 拒绝写工具)。Service 还会在每次调用时动态重验，防止撤权空窗。
	Access Access
}

type ChatStreamEvent struct {
	Type   string `json:"type"`
	RunID  string `json:"run_id,omitempty"`
	TurnID string `json:"turn_id,omitempty"`
	Seq    int64  `json:"seq,omitempty"`
	Delta  string `json:"delta,omitempty"`
	// ContentFormat applies only to assistant_delta.delta and
	// assistant_done.message. Empty preserves the legacy auto-detected format;
	// clients must render unknown values as plain text. HTML is always untrusted
	// model output: third-party clients must parse it inertly and rebuild it
	// through a strict element/attribute/URL allowlist before attaching to DOM.
	ContentFormat string `json:"content_format,omitempty"`
	Thinking      string `json:"thinking,omitempty"`
	// ThinkingID groups the incremental reasoning events produced by one model
	// output. Legacy servers and clients may omit or ignore it.
	ThinkingID string `json:"thinking_id,omitempty"`
	// ThinkingDone marks the last event in a reasoning segment. A non-streamed
	// reasoning response can carry both Thinking and ThinkingDone in one event.
	ThinkingDone bool               `json:"thinking_done,omitempty"`
	Status       string             `json:"status,omitempty"`
	Message      string             `json:"message,omitempty"`
	ModelReady   bool               `json:"model_ready,omitempty"`
	ToolCalls    []ProposedToolCall `json:"tool_calls,omitempty"`
	ToolCall     *ProposedToolCall  `json:"tool_call,omitempty"`
	// ToolID/ConfirmationNonce are used by cancel_tool_result. They deliberately
	// expose only the identifiers the client already sent, never the signed card.
	ToolID            string          `json:"tool_id,omitempty"`
	ConfirmationNonce string          `json:"confirmation_nonce,omitempty"`
	ToolResult        json.RawMessage `json:"tool_result,omitempty"`
	ToolName          string          `json:"tool_name,omitempty"`
	ToolTitle         string          `json:"tool_title,omitempty"`
	ToolStatus        string          `json:"tool_status,omitempty"`
	ToolInput         string          `json:"tool_input,omitempty"`
	ToolSummary       string          `json:"tool_summary,omitempty"`
	ToolDebug         json.RawMessage `json:"tool_debug,omitempty"`
	Plan              []ChatPlanItem  `json:"plan,omitempty"`
	Agent             *ChatAgentStage `json:"agent,omitempty"`
	Budget            *ChatTurnBudget `json:"budget,omitempty"`
	// FinishReason and Usage are populated on assistant_done when the provider
	// exposes them. FinishReason is provider-defined; clients should display it
	// only as diagnostic metadata and must tolerate unknown values.
	FinishReason string     `json:"finish_reason,omitempty"`
	Usage        *ChatUsage `json:"usage,omitempty"`
	// Repaired reports that the visible answer was safely regenerated from
	// already-completed tool evidence after the original final answer was empty
	// or truncated. No tool is re-executed during this repair.
	Repaired bool   `json:"repaired,omitempty"`
	Error    string `json:"error,omitempty"`
	// InspectID 仅用于 inspect_request: 内核应答 inspect_result 时原样带回。
	InspectID     string   `json:"inspect_id,omitempty"`
	InspectOffset int      `json:"inspect_offset,omitempty"`
	InspectLimit  int      `json:"inspect_limit,omitempty"`
	InspectIDs    []string `json:"inspect_ids,omitempty"`
}

type ChatTurnBudget struct {
	ModelCalls           int64 `json:"model_calls"`
	MaxModelCalls        int64 `json:"max_model_calls,omitempty"`
	Subtasks             int64 `json:"subtasks"`
	MaxSubtasks          int64 `json:"max_subtasks,omitempty"`
	ToolCalls            int64 `json:"tool_calls"`
	MaxToolCalls         int64 `json:"max_tool_calls,omitempty"`
	MaxToolCallsPerTool  int64 `json:"max_tool_calls_per_tool,omitempty"`
	MaxRepeatedToolCalls int64 `json:"max_repeated_tool_calls,omitempty"`
	// ToolBudgetCode/Limit/Tool 仅在语义工具预算已锁存耗尽时设置。
	ToolBudgetCode  string `json:"tool_budget_code,omitempty"`
	ToolBudgetLimit string `json:"tool_budget_limit,omitempty"`
	ToolBudgetTool  string `json:"tool_budget_tool,omitempty"`
	DeadlineUnixMS  int64  `json:"deadline_unix_ms,omitempty"`
}

type ChatUsage struct {
	InputTokens       int64 `json:"input_tokens,omitempty"`
	OutputTokens      int64 `json:"output_tokens,omitempty"`
	TotalTokens       int64 `json:"total_tokens,omitempty"`
	CachedInputTokens int64 `json:"cached_input_tokens,omitempty"`
	ReasoningTokens   int64 `json:"reasoning_tokens,omitempty"`
}

type CurrentTemplate struct {
	Template  Template `json:"template"`
	Persisted bool     `json:"persisted"`
	Migrated  bool     `json:"migrated,omitempty"`
}

type ErrorService interface {
	// PageErrors 返回内核上报的最近页面错误(新的在前)。
	PageErrors(ctx context.Context, user string) ([]PageError, error)
	// ReportErrors 追加页面错误记录。
	ReportErrors(ctx context.Context, user string, errs []PageError) error
}

type Event struct {
	// Type: "items" 表示 Item 集合变化; "templates" 表示模板变化;
	// "kv" 表示某个 KV 键变化; "pages" 表示页面注册表变化;
	// "resync" 表示客户端必须全量刷新。
	Type string `json:"type"`
	// Op 是 items/templates 事件的操作: put / publish / delete / replace /
	// rollback / import / purge。
	Op string `json:"op,omitempty"`
	// Items 携带 put 的新内容, 内核原地应用。
	Items []Item `json:"items,omitempty"`
	// Templates 携带模板 put/publish 的最新完整值。
	Templates []Template `json:"templates,omitempty"`
	// IDs 携带 delete 的目标。
	IDs []string `json:"ids,omitempty"`
	// Key 是 kv 事件变化的键名。
	Key string `json:"key,omitempty"`
	// By 是变更来源(api / chat / import 等), 供宿主联动与前端展示。
	By string `json:"by,omitempty"`
	// Version 是某用户事件流的单调版本。默认 hub 总会填充；
	// 外部 Broadcaster 若能提供全局单调版本也应填充。
	Version uint64 `json:"version,omitempty"`
	// Reason 说明 resync 原因: subscribe / overflow / periodic / external。
	Reason string `json:"reason,omitempty"`
}

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

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

type HandlerConfigError struct {
	Field   string
	Problem string
}

type Item struct {
	ID    string   `json:"id"`
	Type  ItemType `json:"type"`
	Title string   `json:"title,omitempty"` // 人类/AI 可读的用途说明
	Order int      `json:"order"`           // 应用顺序, 小的先执行
	// Page 是所属页面名。空 = 全局 Item(菜单/顶栏/全局样式, 始终加载);
	// 非空 = 仅在内核路由切到该页时加载执行, 离开时 teardown。
	Page string `json:"page,omitempty"`
	// Content 是片段源码。html 类型可内嵌 <script>/<style>。
	Content string `json:"content"`
	// Meta 是附加元数据。约定:
	//   - js 类型 meta["module"]=="true" 时以 <script type="module"> 执行;
	//   - html 类型 meta["slot"] 是 Item 对当前 Template Slot.id 的规范绑定;
	//     sidebar/header/footer/main 是旧内核兼容名称。绑定缺失或 Slot 已删除时,
	//     模板运行时必须把 Item 放到 Root 末尾的未分配区，而不是丢弃内容。
	Meta      map[string]string `json:"meta,omitempty"`
	UpdatedAt time.Time         `json:"updated_at"`
}

type ItemService interface {
	// ListItems 返回按 Order 升序(同序按 ID)排好的 Item 全集。
	ListItems(ctx context.Context, user string) ([]Item, error)
	// PutItems 按 ID 增改 Item(变更前自动快照), note/by 记入快照说明。
	PutItems(ctx context.Context, user string, items []Item, by, note string) error
	// DeleteItems 删除指定 Item, 返回实际删除的 ID。
	DeleteItems(ctx context.Context, user string, ids []string, by, note string) ([]string, error)
	// ReplaceItems 整体替换 Item 全集。
	ReplaceItems(ctx context.Context, user string, items []Item, by, note string) error
}

type ItemType string

type KVConflictError struct {
	Key      string
	Expected string
	Actual   string
	Current  json.RawMessage
	Exists   bool
}

type KVService interface {
	// KVGet 读取用户级 KV, 不存在返回 ErrNotFound。ReservedKVPrefix 下的
	// 内核键不属于公共 KV 能力，返回 ErrReservedKVKey。
	KVGet(ctx context.Context, user, key string) (json.RawMessage, error)
	// KVSet 写入用户级 KV 并广播变更事件；保留键返回 ErrReservedKVKey。
	KVSet(ctx context.Context, user, key string, value json.RawMessage) error
	// KVDelete 删除用户级 KV 并广播变更事件；保留键返回 ErrReservedKVKey。
	KVDelete(ctx context.Context, user, key string) error
}

type LayoutMode string

type Limits struct {
	MaxSSEPerUser      int // 每用户 SSE 连接数, 默认 8
	MaxWSPerUser       int // 每用户对话 WebSocket 连接数, 默认 4
	ChatTurnsPerMinute int // 每用户每分钟对话轮次(模型调用是真金白银), 默认 20
	WritesPerMinute    int // 每用户每分钟写操作次数, 默认 240
	MaxKVKeysPerUser   int // 每用户 KV 键数量(排除内核保留键), 默认 256
}

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

type Metrics interface {
	Add(name string, delta float64)
	Observe(name string, value float64)
}

type ModelLister interface {
	Models(ctx context.Context) (ChatModels, error)
}

type Option func(*options)

type Page struct {
	Name       string `json:"name"`                  // 路由名, 如 bills; 出现在 #/bills
	Title      string `json:"title"`                 // 菜单显示名
	Icon       string `json:"icon,omitempty"`        // 菜单图标(emoji 或短文本)
	Order      int    `json:"order,omitempty"`       // 菜单排序
	TemplateID string `json:"template_id,omitempty"` // 稳定引用的布局模板
}

type PageError struct {
	ItemID  string    `json:"item_id,omitempty"` // 归属的 Item, 无法归属时为空
	Message string    `json:"message"`
	Stack   string    `json:"stack,omitempty"`
	URL     string    `json:"url,omitempty"`
	Time    time.Time `json:"time"`
}

type PageService interface {
	// ListPages 返回页面注册表(按 Order 排序), 即侧边菜单的数据源。
	ListPages(ctx context.Context, user string) ([]Page, error)
	// SetPage 新建或更新页面(按 Name 合并)。
	SetPage(ctx context.Context, user string, page Page) error
	// DeletePage 删除页面及其名下全部 Item, 返回连带删除的 Item ID。
	DeletePage(ctx context.Context, user, name, by string) ([]string, error)
}

type Placement struct {
	ItemID     string     `json:"item_id"`
	SlotID     string     `json:"slot_id,omitempty"`
	Unassigned bool       `json:"unassigned,omitempty"`
	Breakpoint string     `json:"breakpoint,omitempty"`
	Mode       LayoutMode `json:"mode"`
	Order      int        `json:"order,omitempty"`
	Column     int        `json:"column,omitempty"`
	ColumnSpan int        `json:"column_span,omitempty"`
	Row        int        `json:"row,omitempty"`
	RowSpan    int        `json:"row_span,omitempty"`
	X          float64    `json:"x,omitempty"`
	Y          float64    `json:"y,omitempty"`
	Width      float64    `json:"width,omitempty"`
	Height     float64    `json:"height,omitempty"`
	ZIndex     int        `json:"z_index,omitempty"`
	Locked     bool       `json:"locked,omitempty"`
	Hidden     bool       `json:"hidden,omitempty"`
}

type ProposedToolCall struct {
	ID                   string         `json:"id,omitempty"`
	Name                 string         `json:"name,omitempty"`
	Title                string         `json:"title,omitempty"`
	Method               string         `json:"method"`
	Path                 string         `json:"path"`
	Query                map[string]any `json:"query,omitempty"`
	Body                 any            `json:"body,omitempty"`
	Risk                 string         `json:"risk"` // low / medium / high / blocked
	RequiresConfirmation bool           `json:"requires_confirmation"`
	Reason               string         `json:"reason"`
	AgentMode            string         `json:"agent_mode,omitempty"`
	ApprovalResume       string         `json:"approval_resume,omitempty"`
	ConfirmationToken    string         `json:"confirmation_token,omitempty"`
	ConfirmationNonce    string         `json:"confirmation_nonce,omitempty"`
	ConfirmationExpires  int64          `json:"confirmation_expires,omitempty"`
}

type Revision struct {
	Version               int        `json:"version,omitempty"`
	ID                    string     `json:"id"`
	Note                  string     `json:"note,omitempty"` // 变更说明, 如 "put 2 items"
	By                    string     `json:"by,omitempty"`   // 变更来源: api / chat
	CreatedAt             time.Time  `json:"created_at"`
	Items                 []Item     `json:"items"`
	Pages                 []Page     `json:"pages,omitempty"`
	Templates             []Template `json:"templates,omitempty"`
	RootTemplateID        string     `json:"root_template_id,omitempty"`
	TemplateRevisionClock uint64     `json:"template_revision_clock,omitempty"`
}

type RevisionInfo struct {
	ID            string    `json:"id"`
	Note          string    `json:"note,omitempty"`
	By            string    `json:"by,omitempty"`
	CreatedAt     time.Time `json:"created_at"`
	ItemCount     int       `json:"item_count"`
	TemplateCount int       `json:"template_count,omitempty"`
}

type RevisionService interface {
	// ListRevisions 返回快照列表(新的在前)。
	ListRevisions(ctx context.Context, user string) ([]RevisionInfo, error)
	// RevisionItems 返回某快照的 Item 全集。
	RevisionItems(ctx context.Context, user, id string) ([]Item, error)
	// Rollback 把 Item 全集回滚到指定快照(回滚前同样自动快照)。
	Rollback(ctx context.Context, user, revisionID, by string) error
}

type RevisionStore interface {
	Revision(ctx context.Context, user, id string) (Revision, error)
}

type ScopedErrorService interface {
	PageErrors(context.Context) ([]PageError, error)
	ReportErrors(context.Context, []PageError) error
}

type ScopedItemService interface {
	ListItems(context.Context) ([]Item, error)
	PutItems(context.Context, []Item, string, string) error
	DeleteItems(context.Context, []string, string, string) ([]string, error)
	ReplaceItems(context.Context, []Item, string, string) error
}

type ScopedKVService interface {
	KVGet(context.Context, string) (json.RawMessage, error)
	KVSet(context.Context, string, json.RawMessage) error
	KVDelete(context.Context, string) error
}

type ScopedPageService interface {
	ListPages(context.Context) ([]Page, error)
	SetPage(context.Context, Page) error
	DeletePage(context.Context, string, string) ([]string, error)
}

type ScopedRevisionService interface {
	ListRevisions(context.Context) ([]RevisionInfo, error)
	RevisionItems(context.Context, string) ([]Item, error)
	Rollback(context.Context, string, string) error
}

type ScopedService interface {
	ScopedItemService
	ScopedRevisionService
	ScopedKVService
	ScopedErrorService
	ScopedPageService
	ScopedTemplateService
}

type ScopedTemplateService interface {
	ListTemplates(context.Context) ([]Template, error)
	GetTemplate(context.Context, string) (Template, error)
	GetCurrentTemplate(context.Context, string) (CurrentTemplate, error)
	PutTemplate(context.Context, Template, uint64, string) (Template, error)
	PutCurrentTemplate(context.Context, string, Template, uint64, string) (Template, error)
	PublishTemplate(context.Context, string, uint64, string) (Template, error)
	DeleteTemplateSlot(context.Context, string, string, uint64, string) (Template, error)
	DeleteTemplate(context.Context, string, uint64, string) error
}

type ScopedVersionedKVService interface {
	KVGetWithRevision(context.Context, string) (json.RawMessage, string, error)
	KVCompareAndSet(context.Context, string, json.RawMessage, string) (string, error)
}

type Service interface {
	ItemService
	RevisionService
	KVService
	ErrorService
	PageService
	TemplateService
}

type Slot struct {
	ID      string     `json:"id"`
	NodeID  string     `json:"node_id"`
	Name    string     `json:"name,omitempty"`
	Accepts []ItemType `json:"accepts,omitempty"`
	Locked  bool       `json:"locked,omitempty"`
}

type Store interface {
	// Items 返回该用户的全部 Item(顺序不限, 上层会按 Order 排序)。
	// 用户不存在时返回空切片而不是错误。
	Items(ctx context.Context, user string) ([]Item, error)
	// ReplaceItems 用 items 整体替换该用户的 Item 全集。
	ReplaceItems(ctx context.Context, user string, items []Item) error

	// KVGet 读取用户级键值, 键不存在时返回 ErrNotFound。KVSet/KVGet
	// 必须逐字节保留有效 JSON（包括无意义空白与 HTML 字符），不得规范化、
	// compact 或重新编码 RawMessage。
	KVGet(ctx context.Context, user, key string) (json.RawMessage, error)
	KVSet(ctx context.Context, user, key string, value json.RawMessage) error
	// KVDelete 删除键, 键不存在时不报错。
	KVDelete(ctx context.Context, user, key string) error

	// KVKeys 返回该用户的全部 KV 键(含保留键), 顺序不限。
	KVKeys(ctx context.Context, user string) ([]string, error)

	// Revisions 返回该用户的快照元信息, 新的在前。
	Revisions(ctx context.Context, user string) ([]RevisionInfo, error)
	// RevisionItems 返回指定快照的 Item 全集, 不存在时返回 ErrNotFound。
	RevisionItems(ctx context.Context, user, id string) ([]Item, error)
	// AddRevision 追加一条快照。keep 是保留上限, 实现应删除最旧的超额快照。
	AddRevision(ctx context.Context, user string, rev Revision, keep int) error

	// EraseUser 清空该用户的业务数据(Item/KV/快照), 用于注销与导入前清场。
	// VersionedUserStateStore 必须额外保留一个不可见的递增版本墓碑。
	EraseUser(ctx context.Context, user string) error
}

type Template struct {
	ID          string           `json:"id"`
	Name        string           `json:"name"`
	Revision    uint64           `json:"revision"`
	Draft       TemplateVersion  `json:"draft"`
	Published   *TemplateVersion `json:"published,omitempty"`
	CreatedAt   time.Time        `json:"created_at"`
	UpdatedAt   time.Time        `json:"updated_at"`
	PublishedAt *time.Time       `json:"published_at,omitempty"`
}

type TemplateConflictError struct {
	ID       string
	Expected uint64
	Actual   uint64
	Current  *Template
}

type TemplateNode struct {
	ID       string                     `json:"id"`
	ParentID string                     `json:"parent_id,omitempty"`
	Kind     TemplateNodeKind           `json:"kind"`
	Name     string                     `json:"name,omitempty"`
	Order    int                        `json:"order,omitempty"`
	Props    map[string]json.RawMessage `json:"props,omitempty"`
}

type TemplateNodeKind string

type TemplateService interface {
	// ListTemplates 返回一等布局模板；模板内容与动态页面 Item 分离。
	ListTemplates(ctx context.Context, user string) ([]Template, error)
	GetTemplate(ctx context.Context, user, id string) (Template, error)
	GetCurrentTemplate(ctx context.Context, user, page string) (CurrentTemplate, error)
	PutTemplate(ctx context.Context, user string, template Template, expectedRevision uint64, by string) (Template, error)
	PutCurrentTemplate(ctx context.Context, user, page string, template Template, expectedRevision uint64, by string) (Template, error)
	PublishTemplate(ctx context.Context, user, id string, expectedRevision uint64, by string) (Template, error)
	DeleteTemplateSlot(ctx context.Context, user, id, slotID string, expectedRevision uint64, by string) (Template, error)
	DeleteTemplate(ctx context.Context, user, id string, expectedRevision uint64, by string) error
}

type TemplateVersion struct {
	Version     uint64         `json:"version"`
	RootID      string         `json:"root_id,omitempty"`
	Nodes       []TemplateNode `json:"nodes"`
	Slots       []Slot         `json:"slots"`
	Placements  []Placement    `json:"placements"`
	Breakpoints []Breakpoint   `json:"breakpoints"`
}

type UserExport struct {
	Version               int                        `json:"version,omitempty"`
	Items                 []Item                     `json:"items"`
	Pages                 []Page                     `json:"pages,omitempty"`
	Templates             []Template                 `json:"templates,omitempty"`
	RootTemplateID        string                     `json:"root_template_id,omitempty"`
	TemplateRevisionClock uint64                     `json:"template_revision_clock,omitempty"`
	KV                    map[string]json.RawMessage `json:"kv,omitempty"`
	Revisions             []Revision                 `json:"revisions,omitempty"`
}

type UserResolver func(r *http.Request) (string, error)

type UserState struct {
	Items     []Item
	KV        map[string]json.RawMessage
	Revisions []Revision // 新的在前

	// Version 是整个用户状态的乐观并发令牌，由实现 VersionedUserStateStore 的
	// Store 在 UserState() 时填充；不支持版本的 Store 保持为 0。调用方应视为
	// 不透明值：读到什么，条件写时就传什么。
	Version uint64
}

type UserStateStore interface {
	UserState(ctx context.Context, user string) (UserState, error)
	ReplaceUserState(ctx context.Context, user string, state UserState) error
}

type VersionedBroadcaster interface {
	Broadcaster
	CurrentVersion(user string) uint64
}

type VersionedKVService interface {
	// KVGetWithRevision 返回值及其不透明版本令牌；键不存在仍返回 ErrNotFound。
	KVGetWithRevision(ctx context.Context, user, key string) (json.RawMessage, string, error)
	// KVCompareAndSet 仅在当前版本等于 expectedRevision 时原子写入，并返回
	// 新版本。读取时不存在的键使用 MissingKVRevision 作为 expectedRevision。
	KVCompareAndSet(ctx context.Context, user, key string, value json.RawMessage, expectedRevision string) (string, error)
}

type VersionedUserStateStore interface {
	UserStateStore
	// ReplaceUserStateVersioned 仅当该用户当前版本等于 expected 时原子替换完整
	// 状态并推进版本；否则返回 ErrVersionConflict 且不产生任何修改。
	ReplaceUserStateVersioned(ctx context.Context, user string, state UserState, expected uint64) error
}