@djvlc/contracts-types 1.0.0

package/dist/index.d.mts

@@ -0,0 +1,1958 @@
+/**
+ * 协议版本常量
+ * 用于标识当前 schema 版本，支持版本迁移
+ */
+/** 当前页面 Schema 版本 */
+declare const PAGE_SCHEMA_VERSION = "1.0.0";
+/** 当前组件 Meta Schema 版本 */
+declare const COMPONENT_META_SCHEMA_VERSION = "1.0.0";
+/** 当前 Action 规范版本 */
+declare const ACTION_SPEC_VERSION = "1.0.0";
+/** 当前 Data Query 规范版本 */
+declare const DATA_QUERY_SPEC_VERSION = "1.0.0";
+/** 协议版本信息 */
+interface ContractsVersion {
+    pageSchema: string;
+    componentMeta: string;
+    actionSpec: string;
+    dataQuerySpec: string;
+}
+/** 获取当前协议版本 */
+declare function getContractsVersion(): ContractsVersion;
+/**
+ * 检查版本兼容性
+ * @param required 要求的版本
+ * @param current 当前版本
+ * @returns 是否兼容
+ */
+declare function isVersionCompatible(required: string, current: string): boolean;
+
+/**
+ * 错误码规范
+ * 统一的错误码定义，用于 Action Gateway / Data Proxy / Runtime
+ */
+/** 错误码枚举 */
+declare enum ErrorCode {
+    UNKNOWN = 1000,
+    INVALID_REQUEST = 1001,
+    UNAUTHORIZED = 1002,
+    FORBIDDEN = 1003,
+    NOT_FOUND = 1004,
+    RATE_LIMITED = 1005,
+    VALIDATION_ERROR = 1006,
+    INTERNAL_ERROR = 1007,
+    SERVICE_UNAVAILABLE = 1008,
+    TIMEOUT = 1009,
+    ACTION_NOT_FOUND = 2001,
+    ACTION_INVALID_PARAMS = 2002,
+    ACTION_EXECUTION_FAILED = 2003,
+    ACTION_IDEMPOTENCY_CONFLICT = 2004,
+    ACTION_BLOCKED = 2005,
+    ACTION_RISK_REJECTED = 2006,
+    ACTION_EXPIRED = 2007,
+    ACTION_QUOTA_EXCEEDED = 2008,
+    QUERY_NOT_FOUND = 3001,
+    QUERY_INVALID_PARAMS = 3002,
+    QUERY_EXECUTION_FAILED = 3003,
+    QUERY_FIELD_NOT_ALLOWED = 3004,
+    QUERY_TIMEOUT = 3005,
+    QUERY_DISABLED = 3006,
+    COMPONENT_NOT_FOUND = 4001,
+    COMPONENT_VERSION_NOT_FOUND = 4002,
+    COMPONENT_BLOCKED = 4003,
+    COMPONENT_INTEGRITY_MISMATCH = 4004,
+    COMPONENT_INCOMPATIBLE = 4005,
+    COMPONENT_LOAD_FAILED = 4006,
+    COMPONENT_RENDER_ERROR = 4007,
+    PAGE_NOT_FOUND = 5001,
+    PAGE_VERSION_NOT_FOUND = 5002,
+    PAGE_SCHEMA_INVALID = 5003,
+    PAGE_MANIFEST_INVALID = 5004,
+    PAGE_PUBLISH_FAILED = 5005,
+    PAGE_ROLLBACK_FAILED = 5006,
+    ACTIVITY_NOT_FOUND = 6001,
+    ACTIVITY_NOT_STARTED = 6002,
+    ACTIVITY_ENDED = 6003,
+    ACTIVITY_ALREADY_CLAIMED = 6004,
+    ACTIVITY_ALREADY_SIGNED = 6005,
+    ACTIVITY_LIMIT_EXCEEDED = 6006,
+    ACTIVITY_DISABLED = 6007,
+    EXPRESSION_SYNTAX_ERROR = 7001,
+    EXPRESSION_UNKNOWN_FUNCTION = 7002,
+    EXPRESSION_INVALID_ARGUMENT = 7003,
+    EXPRESSION_UNKNOWN_VARIABLE = 7004,
+    EXPRESSION_TYPE_MISMATCH = 7005,
+    EXPRESSION_ACCESS_DENIED = 7006,
+    SCHEMA_VERSION_MISMATCH = 8001,
+    MIGRATION_FAILED = 8002,
+    MIGRATION_NOT_FOUND = 8003,
+    VERSION_INCOMPATIBLE = 8004
+}
+/** 错误码分类 */
+declare const ErrorCodeCategory: {
+    GENERAL: readonly [1000, 1999];
+    ACTION: readonly [2000, 2999];
+    QUERY: readonly [3000, 3999];
+    COMPONENT: readonly [4000, 4999];
+    PAGE: readonly [5000, 5999];
+    ACTIVITY: readonly [6000, 6999];
+    EXPRESSION: readonly [7000, 7999];
+    VERSION: readonly [8000, 8999];
+};
+/** 错误信息映射 */
+declare const ErrorMessages: Record<ErrorCode, string>;
+/** DJV 错误对象 */
+interface DjvlcError {
+    code: ErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+    traceId?: string;
+    timestamp?: number;
+}
+/** 创建 DJV 错误 */
+declare function createDjvlcError(code: ErrorCode, details?: Record<string, unknown>, traceId?: string): DjvlcError;
+/** 根据错误码获取 HTTP 状态码 */
+declare function getHttpStatusFromErrorCode(code: ErrorCode): number;
+/** 检查是否为可重试错误 */
+declare function isRetryableError(code: ErrorCode): boolean;
+
+/**
+ * 通用类型定义
+ * 跨模块使用的基础类型
+ */
+/**
+ * 低代码操作类型
+ * 用于审计日志记录
+ */
+type LowcodeAction = 'CREATE' | 'UPDATE' | 'DELETE' | 'PUBLISH' | 'UNPUBLISH' | 'DUPLICATE' | 'RESTORE' | 'ARCHIVE' | 'UNARCHIVE' | 'SAVE_VERSION' | 'ROLLBACK_VERSION' | 'USE_TEMPLATE' | 'BLOCK' | 'UNBLOCK';
+/**
+ * 操作用户信息
+ * 用于记录谁执行了操作
+ */
+interface OperatorInfo {
+    uid: string;
+    username: string;
+    role?: string;
+}
+/**
+ * 排序方向
+ */
+type SortOrder = 'ASC' | 'DESC' | 'asc' | 'desc';
+/**
+ * 通用排序配置
+ */
+interface SortConfig<T extends string = string> {
+    /** 排序字段 */
+    field: T;
+    /** 排序方向 */
+    order: SortOrder;
+}
+/**
+ * 分页查询参数
+ */
+interface PaginationParams {
+    /** 页码（从 1 开始） */
+    page?: number;
+    /** 每页数量 */
+    pageSize?: number;
+    /** 偏移量（与 page 二选一） */
+    offset?: number;
+    /** 限制数量 */
+    limit?: number;
+}
+/**
+ * 分页结果元数据
+ */
+interface PaginationMeta {
+    /** 当前页码 */
+    page: number;
+    /** 每页数量 */
+    pageSize: number;
+    /** 总数量 */
+    total: number;
+    /** 总页数 */
+    totalPages: number;
+    /** 是否有下一页 */
+    hasNext: boolean;
+    /** 是否有上一页 */
+    hasPrev: boolean;
+}
+/**
+ * 分页结果
+ */
+interface PaginatedResult<T> {
+    /** 数据列表 */
+    items: T[];
+    /** 分页元数据 */
+    meta: PaginationMeta;
+}
+/**
+ * 时间范围
+ */
+interface TimeRange {
+    /** 开始时间 */
+    startTime?: string;
+    /** 结束时间 */
+    endTime?: string;
+}
+/**
+ * 通用键值对
+ */
+interface KeyValuePair<T = unknown> {
+    key: string;
+    value: T;
+    label?: string;
+}
+/** 页面 UID */
+type PageUid = string;
+/** 页面版本 ID */
+type PageVersionId = string;
+/** 组件版本 ID */
+type ComponentVersionId = string;
+/** Action Definition 版本 ID */
+type ActionDefVersionId = string;
+/** Data Query 版本 ID */
+type DataQueryVersionId = string;
+/** 追踪 ID */
+type TraceId = string;
+/**
+ * 通用状态
+ */
+type GenericStatus = 'active' | 'inactive' | 'pending' | 'archived';
+/**
+ * 审计状态
+ */
+type AuditStatus = 'pending' | 'approved' | 'rejected';
+/**
+ * 深度只读类型
+ */
+type DeepReadonly<T> = {
+    readonly [P in keyof T]: T[P] extends object ? DeepReadonly<T[P]> : T[P];
+};
+/**
+ * 可选属性类型
+ */
+type PartialBy<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+/**
+ * 必需属性类型
+ */
+type RequiredBy<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+/**
+ * 提取非空属性
+ */
+type NonNullableProperties<T> = {
+    [P in keyof T]: NonNullable<T[P]>;
+};
+
+/**
+ * 页面 Schema 类型定义
+ * 与 djvlc-platform @libs/contracts 保持一致
+ */
+/** 页面状态 */
+type PageStatus = 'draft' | 'published';
+/** 画布类型 */
+type CanvasType = 'h5' | 'tablet' | 'pc';
+/**
+ * 页面排序字段
+ */
+type PageSortField = 'id' | 'createdAt' | 'updatedAt' | 'publishedAt' | 'title' | 'viewCount' | 'sortOrder';
+/** 发布渠道 */
+type PublishChannel = 'preview' | 'prod' | 'gray';
+/** 发布状态 */
+declare enum PublishStatus {
+    PENDING = "pending",
+    PUBLISHING = "publishing",
+    SUCCESS = "success",
+    FAILED = "failed",
+    ROLLBACK = "rollback"
+}
+/**
+ * 模板分类
+ */
+type TemplateCategory = 'all' | 'ecommerce' | 'marketing' | 'corporate' | 'other';
+/**
+ * 模板排序字段
+ */
+type TemplateSortField = 'id' | 'createdAt' | 'usageCount' | 'sortOrder';
+/**
+ * 页面 Schema（核心）
+ * 存储在 Page 的 schema 字段中的完整结构
+ */
+interface PageSchema {
+    /** Schema 版本号 */
+    schemaVersion: string;
+    /** 页面配置 */
+    page: PageConfig;
+    /** 组件列表 */
+    components: ComponentInstance[];
+    /** 绑定的 ActionDefinition 版本 ID */
+    actionDefVersionIds?: string[];
+    /** 绑定的 DataQuery 版本 ID */
+    dataQueryVersionIds?: string[];
+}
+/** 页面配置 */
+interface PageConfig {
+    id: string;
+    title: string;
+    description?: string;
+    canvas: CanvasConfig;
+    meta?: PageMeta;
+    variables?: Record<string, unknown>;
+    apis?: ApiConfig[];
+}
+/** 画布配置 */
+interface CanvasConfig {
+    type: CanvasType;
+    width: number;
+    height?: number;
+    background?: string;
+    gridSize?: number;
+    showGrid?: boolean;
+    showRuler?: boolean;
+    guides?: Guide[];
+}
+/** 参考线 */
+interface Guide {
+    id: string;
+    type: 'horizontal' | 'vertical';
+    position: number;
+}
+/** 页面元数据 */
+interface PageMeta {
+    createTime?: string;
+    updateTime?: string;
+    author?: string;
+    version?: string;
+    tags?: string[];
+    status?: PageStatus;
+}
+/** API 配置 */
+interface ApiConfig {
+    id: string;
+    name: string;
+    url: string;
+    method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+    headers?: Record<string, string>;
+    params?: Record<string, unknown>;
+    body?: Record<string, unknown>;
+    timeout?: number;
+    autoRun?: boolean;
+    dependencies?: string[];
+}
+/** 组件实例（运行时数据） */
+interface ComponentInstance {
+    id: string;
+    type: string;
+    name?: string;
+    props: Record<string, unknown>;
+    style: ComponentStyle;
+    layout?: ComponentLayout;
+    events?: ComponentEvent[];
+    visible?: boolean;
+    locked?: boolean;
+    children?: ComponentInstance[];
+}
+/** 组件样式 */
+interface ComponentStyle {
+    width?: string | number;
+    height?: string | number;
+    minWidth?: string | number;
+    minHeight?: string | number;
+    maxWidth?: string | number;
+    maxHeight?: string | number;
+    margin?: string;
+    padding?: string;
+    color?: string;
+    backgroundColor?: string;
+    borderColor?: string;
+    border?: string;
+    borderWidth?: string | number;
+    borderStyle?: string;
+    borderRadius?: string | number;
+    fontSize?: string | number;
+    fontWeight?: string | number;
+    fontFamily?: string;
+    lineHeight?: string | number;
+    textAlign?: string;
+    position?: string;
+    top?: string | number;
+    right?: string | number;
+    bottom?: string | number;
+    left?: string | number;
+    zIndex?: number;
+    display?: string;
+    opacity?: number;
+    overflow?: string;
+    visibility?: string;
+    flexDirection?: string;
+    justifyContent?: string;
+    alignItems?: string;
+    flexWrap?: string;
+    flex?: string | number;
+    gap?: string | number;
+    gridTemplateColumns?: string;
+    gridTemplateRows?: string;
+    gridGap?: string | number;
+    transform?: string;
+    transformOrigin?: string;
+    transition?: string;
+    [key: string]: unknown;
+}
+/** 组件布局 */
+interface ComponentLayout {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    rotation?: number;
+}
+/** 组件事件 */
+interface ComponentEvent {
+    id: string;
+    trigger: string;
+    actions: EventAction[];
+    enabled?: boolean;
+    condition?: string;
+    debounce?: number;
+    throttle?: number;
+}
+/** 事件动作 */
+interface EventAction {
+    id: string;
+    type: string;
+    params: Record<string, unknown>;
+    enabled?: boolean;
+    delay?: number;
+}
+/**
+ * 灰度规则
+ */
+interface GrayRule {
+    /** 规则名称 */
+    name: string;
+    /** 规则类型 */
+    type: 'user' | 'ip' | 'header' | 'cookie' | 'custom';
+    /** 匹配条件 */
+    condition: string;
+    /** 是否启用 */
+    enabled: boolean;
+}
+/**
+ * 灰度发布配置
+ */
+interface GrayPublishConfig {
+    /** 灰度比例 (0-100) */
+    percentage?: number;
+    /** 白名单用户 UID */
+    whitelistUsers?: string[];
+    /** 白名单 IP */
+    whitelistIps?: string[];
+    /** 自定义规则 */
+    rules?: GrayRule[];
+}
+/**
+ * 发布配置
+ */
+interface PublishConfig {
+    /** 发布渠道 */
+    channel: PublishChannel;
+    /** 发布描述 */
+    description?: string;
+    /** 灰度配置（仅 gray 渠道） */
+    grayConfig?: GrayPublishConfig;
+    /** 是否自动发布（跳过审核） */
+    autoPublish?: boolean;
+    /** 定时发布时间 */
+    scheduledAt?: string;
+}
+/**
+ * 版本信息
+ */
+interface VersionInfo {
+    uid: string;
+    versionNumber: number;
+    versionLabel?: string;
+    description?: string;
+    isAutoSave: boolean;
+    isPublished: boolean;
+    createdAt: string;
+    createdBy: string;
+    createdByUsername: string;
+}
+/**
+ * 版本对比结果
+ */
+interface VersionDiff {
+    added: string[];
+    removed: string[];
+    modified: string[];
+    changeLog: Record<string, ChangeLogItem>;
+}
+/**
+ * 变更日志项
+ */
+interface ChangeLogItem {
+    /** 旧值 */
+    old: unknown;
+    /** 新值 */
+    new: unknown;
+    /** 摘要描述 */
+    summary?: string;
+}
+/**
+ * 变更日志
+ */
+type ChangeLog = Record<string, ChangeLogItem>;
+
+/**
+ * 组件 Meta Schema 类型定义
+ * 定义每个组件版本必须包含的元数据
+ */
+/** JSON Schema 类型定义 */
+interface JsonSchema {
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array' | 'null';
+    title?: string;
+    description?: string;
+    default?: unknown;
+    enum?: unknown[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+    required?: string[];
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: string;
+    $ref?: string;
+}
+/** Props Schema - 组件属性定义 */
+interface PropsSchema {
+    $schema?: string;
+    type: 'object';
+    title: string;
+    description?: string;
+    properties: Record<string, JsonSchema & {
+        /** 属性分组 */
+        group?: string;
+        /** 编辑器中的控件类型 */
+        'x-editor-widget'?: string;
+        /** 是否支持表达式绑定 */
+        'x-expression-enabled'?: boolean;
+    }>;
+    required?: string[];
+}
+/** 事件定义 */
+interface EventDefinition {
+    /** 事件名称 */
+    name: string;
+    /** 事件显示名 */
+    label: string;
+    /** 事件描述 */
+    description?: string;
+    /** 事件参数 Schema */
+    payload?: JsonSchema;
+}
+/** 组件事件列表 */
+interface EventsDefinition {
+    /** 事件版本 */
+    version: string;
+    /** 事件列表 */
+    events: EventDefinition[];
+}
+/** 组件能力声明 */
+interface CapabilitiesDefinition {
+    /** 能力版本 */
+    version: string;
+    /** 是否需要用户登录态 */
+    requiresAuth?: boolean;
+    /** 是否需要执行 Action */
+    requiresAction?: boolean;
+    /** 需要的 Action 类型 */
+    actionTypes?: string[];
+    /** 是否需要 Data Query */
+    requiresDataQuery?: boolean;
+    /** 需要的 Query 类型 */
+    queryTypes?: string[];
+    /** 是否需要导航能力 */
+    requiresNavigation?: boolean;
+    /** 是否需要埋点能力 */
+    requiresTrack?: boolean;
+    /** 是否需要对话框能力 */
+    requiresDialog?: boolean;
+    /** 是否需要剪贴板能力 */
+    requiresClipboard?: boolean;
+    /** 自定义能力 */
+    custom?: string[];
+}
+/** 兼容性定义 */
+interface CompatDefinition {
+    /** 兼容版本 */
+    version: string;
+    /** 最低运行时版本 */
+    minRuntime: string;
+    /** 最高运行时版本（可选） */
+    maxRuntime?: string;
+    /** 是否有破坏性变更 */
+    breaking?: boolean;
+    /** 破坏性变更说明 */
+    breakingChanges?: string[];
+    /** 从哪个版本可以无缝升级 */
+    upgradeFrom?: string[];
+}
+/** 组件分类 */
+type ComponentCategory = 'basic' | 'form' | 'layout' | 'navigation' | 'feedback' | 'display' | 'data' | 'business' | 'chart' | 'other';
+/** 组件分类列表（用于校验和 UI） */
+declare const COMPONENT_CATEGORIES: ComponentCategory[];
+/** SRI 完整性校验 */
+interface IntegrityDefinition {
+    /** 完整性版本 */
+    version: string;
+    /** 主入口文件哈希 */
+    main: string;
+    /** 所有文件哈希 */
+    files: Record<string, string>;
+    /** 生成时间 */
+    generatedAt: string;
+    /** 哈希算法 */
+    algorithm: 'sha256' | 'sha384' | 'sha512';
+}
+/** 组件状态 */
+type ComponentStatus = 'draft' | 'canary' | 'stable' | 'deprecated' | 'blocked';
+/** 组件版本元数据（完整） */
+interface ComponentMeta {
+    /** 组件名称 */
+    name: string;
+    /** 组件版本 */
+    version: string;
+    /** 显示名称 */
+    label: string;
+    /** 组件描述 */
+    description?: string;
+    /** 组件图标 */
+    icon?: string;
+    /** 组件分类 */
+    category: ComponentCategory;
+    /** 组件标签 */
+    tags?: string[];
+    /** 组件作者 */
+    author?: string;
+    /** 属性定义 */
+    props: PropsSchema;
+    /** 事件定义 */
+    events: EventsDefinition;
+    /** 能力声明 */
+    capabilities: CapabilitiesDefinition;
+    /** 兼容性 */
+    compat: CompatDefinition;
+    /** 完整性校验 */
+    integrity: IntegrityDefinition;
+    /** 组件状态 */
+    status: ComponentStatus;
+    /** 预览图 */
+    preview?: string;
+    /** 入口文件（相对路径） */
+    entry: string;
+    /** 样式文件（相对路径） */
+    styles?: string[];
+}
+/** Registry 中的组件版本记录 */
+interface ComponentVersionRecord {
+    /** 组件 ID */
+    componentId: string;
+    /** 组件名称 */
+    name: string;
+    /** 版本号 */
+    version: string;
+    /** CDN 入口 URL */
+    entryUrl: string;
+    /** 元数据 */
+    meta: ComponentMeta;
+    /** 状态 */
+    status: ComponentStatus;
+    /** 发布时间 */
+    publishedAt: string;
+    /** 发布者 */
+    publishedBy: string;
+    /** 阻断信息（如果被阻断） */
+    blockInfo?: {
+        reason: string;
+        blockedAt: string;
+        blockedBy: string;
+    };
+}
+/** Manifest 中的组件引用 */
+interface ManifestItem {
+    /** 组件名称 */
+    name: string;
+    /** 组件版本 */
+    version: string;
+    /** 入口 URL */
+    entryUrl: string;
+    /** SRI 哈希 */
+    integrity: string;
+    /** 是否必须成功加载 */
+    critical?: boolean;
+}
+/** 页面 Manifest */
+interface PageManifest {
+    /** Manifest 版本 */
+    manifestVersion: string;
+    /** 内容哈希 */
+    contentHash: string;
+    /** 运行时版本 */
+    runtimeVersion: string;
+    /** 组件清单 */
+    components: ManifestItem[];
+    /** 生成时间 */
+    generatedAt: string;
+}
+
+/**
+ * Action 规范类型定义
+ * 用于 Action Gateway 的动作执行
+ */
+/** 内置动作类型 */
+type BuiltinActionType = 'claim' | 'signin' | 'lottery' | 'reserve' | 'share' | 'navigate' | 'track' | 'custom';
+/** 动作执行请求 */
+interface ActionExecuteRequest {
+    /** 动作类型 */
+    actionType: string;
+    /** 动作参数 */
+    params: Record<string, unknown>;
+    /** 上下文 */
+    context: ActionContext;
+    /** 幂等键 */
+    idempotencyKey?: string;
+}
+/** 动作上下文 */
+interface ActionContext {
+    /** 页面版本 ID */
+    pageVersionId?: string;
+    /** 组件版本 */
+    componentVersion?: string;
+    /** 用户 ID */
+    uid?: string;
+    /** 设备 ID */
+    deviceId?: string;
+    /** 渠道 */
+    channel?: string;
+    /** 追踪 ID */
+    traceId?: string;
+    /** 扩展数据 */
+    extra?: Record<string, unknown>;
+}
+/** 动作执行响应 */
+interface ActionExecuteResponse<T = unknown> {
+    /** 是否成功 */
+    success: boolean;
+    /** 响应数据 */
+    data?: T;
+    /** 错误码 */
+    code?: number;
+    /** 错误信息 */
+    message?: string;
+    /** 追踪 ID */
+    traceId?: string;
+}
+/** 动作定义状态 */
+type ActionDefinitionStatus = 'active' | 'deprecated' | 'disabled';
+/** 动作定义 */
+interface ActionDefinition {
+    /** 动作 ID */
+    id: string;
+    /** 动作名称 */
+    name: string;
+    /** 动作类型 */
+    actionType: string;
+    /** 描述 */
+    description?: string;
+    /** 参数 Schema */
+    paramsSchema: Record<string, unknown>;
+    /** 响应 Schema */
+    responseSchema?: Record<string, unknown>;
+    /** 是否需要认证 */
+    requiresAuth: boolean;
+    /** 幂等规则 */
+    idempotencyRule?: IdempotencyRule;
+    /** 频控规则 */
+    rateLimitRule?: RateLimitRule;
+    /** 版本 */
+    version: string;
+    /** 状态 */
+    status: ActionDefinitionStatus;
+}
+/** 动作定义版本（不可变） */
+interface ActionDefinitionVersion {
+    /** 版本 ID */
+    id: string;
+    /** 所属定义 ID */
+    definitionId: string;
+    /** 版本号 */
+    version: string;
+    /** 定义快照 */
+    spec: ActionDefinition;
+    /** 状态 */
+    status: ActionDefinitionStatus;
+    /** 创建时间 */
+    createdAt: string;
+    /** 创建者 */
+    createdBy: string;
+}
+/** 幂等规则 */
+interface IdempotencyRule {
+    /** 是否启用 */
+    enabled: boolean;
+    /** 幂等键字段 */
+    keyFields: string[];
+    /** 幂等有效期（秒） */
+    ttl: number;
+}
+/** 频控规则 */
+interface RateLimitRule {
+    /** 是否启用 */
+    enabled: boolean;
+    /** 时间窗口（秒） */
+    window: number;
+    /** 最大次数 */
+    limit: number;
+    /** 频控维度 */
+    dimension: 'user' | 'ip' | 'device' | 'global';
+}
+/** 风控检查请求 */
+interface RiskCheckRequest {
+    /** 动作类型 */
+    actionType: string;
+    /** 用户 ID */
+    uid?: string;
+    /** 设备 ID */
+    deviceId?: string;
+    /** IP 地址 */
+    ip?: string;
+    /** 追踪 ID */
+    traceId?: string;
+}
+/** 风控检查结果 */
+interface RiskCheckResult {
+    /** 是否通过 */
+    passed: boolean;
+    /** 风险等级 */
+    riskLevel: 'low' | 'medium' | 'high' | 'critical';
+    /** 需要的验证类型 */
+    requiredVerification?: 'captcha' | 'sms' | 'none';
+    /** 拒绝原因 */
+    rejectReason?: string;
+}
+/** 动作审计日志 */
+interface ActionAuditLog {
+    /** 日志 ID */
+    id: string;
+    /** 动作类型 */
+    actionType: string;
+    /** 请求参数 */
+    params: Record<string, unknown>;
+    /** 上下文 */
+    context: ActionContext;
+    /** 是否成功 */
+    success: boolean;
+    /** 错误码 */
+    code?: number;
+    /** 错误信息 */
+    message?: string;
+    /** 耗时（ms） */
+    duration: number;
+    /** 追踪 ID */
+    traceId: string;
+    /** 创建时间 */
+    createdAt: string;
+}
+
+/**
+ * Data Query 规范类型定义
+ * 用于 Data Proxy 的数据查询
+ */
+/** 数据查询请求 */
+interface DataQueryRequest {
+    /** 查询版本 ID */
+    queryVersionId: string;
+    /** 查询参数 */
+    params: Record<string, unknown>;
+    /** 上下文 */
+    context?: DataQueryContext;
+}
+/** 查询上下文 */
+interface DataQueryContext {
+    /** 页面版本 ID */
+    pageVersionId?: string;
+    /** 用户 ID */
+    uid?: string;
+    /** 追踪 ID */
+    traceId?: string;
+}
+/** 数据查询响应 */
+interface DataQueryResponse<T = unknown> {
+    /** 是否成功 */
+    success: boolean;
+    /** 响应数据 */
+    data?: T;
+    /** 是否来自缓存 */
+    fromCache?: boolean;
+    /** 缓存时间（秒） */
+    cacheTime?: number;
+    /** 错误码 */
+    code?: number;
+    /** 错误信息 */
+    message?: string;
+}
+/** 数据源类型 */
+type DataSourceType = 'api' | 'database' | 'cache' | 'custom';
+/** 数据查询定义状态 */
+type DataQueryDefinitionStatus = 'active' | 'deprecated' | 'disabled';
+/** 数据查询定义 */
+interface DataQueryDefinition {
+    /** 查询 ID */
+    id: string;
+    /** 查询名称 */
+    name: string;
+    /** 描述 */
+    description?: string;
+    /** 数据源类型 */
+    sourceType: DataSourceType;
+    /** 数据源配置 */
+    sourceConfig: DataSourceConfig;
+    /** 参数 Schema */
+    paramsSchema: Record<string, unknown>;
+    /** 响应 Schema */
+    responseSchema: Record<string, unknown>;
+    /** 字段白名单 */
+    allowedFields?: string[];
+    /** 脱敏规则 */
+    maskRules?: MaskRule[];
+    /** 缓存配置 */
+    cacheConfig?: CacheConfig;
+    /** 版本 */
+    version: string;
+    /** 状态 */
+    status: DataQueryDefinitionStatus;
+}
+/** 数据查询定义版本（不可变） */
+interface DataQueryDefinitionVersion {
+    /** 版本 ID */
+    id: string;
+    /** 所属定义 ID */
+    definitionId: string;
+    /** 版本号 */
+    version: string;
+    /** 定义快照 */
+    spec: DataQueryDefinition;
+    /** 状态 */
+    status: DataQueryDefinitionStatus;
+    /** 创建时间 */
+    createdAt: string;
+    /** 创建者 */
+    createdBy: string;
+}
+/** 数据源配置 */
+interface DataSourceConfig {
+    /** API URL（api 类型） */
+    url?: string;
+    /** HTTP 方法 */
+    method?: 'GET' | 'POST';
+    /** 请求头 */
+    headers?: Record<string, string>;
+    /** 数据库连接（database 类型） */
+    connection?: string;
+    /** SQL 查询 */
+    query?: string;
+    /** 自定义处理器 */
+    handler?: string;
+}
+/** 脱敏规则 */
+interface MaskRule {
+    /** 字段路径 */
+    field: string;
+    /** 脱敏类型 */
+    type: 'phone' | 'email' | 'idcard' | 'name' | 'custom';
+    /** 自定义脱敏规则 */
+    pattern?: string;
+    /** 替换字符 */
+    replacement?: string;
+}
+/** 缓存配置 */
+interface CacheConfig {
+    /** 是否启用 */
+    enabled: boolean;
+    /** TTL（秒） */
+    ttl: number;
+    /** 缓存键字段 */
+    keyFields?: string[];
+    /** 是否支持刷新 */
+    allowRefresh?: boolean;
+}
+/** 字段权限规则 */
+interface FieldPermission {
+    /** 字段路径 */
+    field: string;
+    /** 允许的角色 */
+    allowedRoles?: string[];
+    /** 是否需要认证 */
+    requiresAuth?: boolean;
+    /** 是否需要脱敏 */
+    requiresMask?: boolean;
+}
+/** 查询权限配置 */
+interface QueryPermissionConfig {
+    /** 是否需要认证 */
+    requiresAuth: boolean;
+    /** 允许的角色 */
+    allowedRoles?: string[];
+    /** 字段权限 */
+    fieldPermissions?: FieldPermission[];
+}
+/** 查询审计日志 */
+interface QueryAuditLog {
+    /** 日志 ID */
+    id: string;
+    /** 查询版本 ID */
+    queryVersionId: string;
+    /** 请求参数 */
+    params: Record<string, unknown>;
+    /** 上下文 */
+    context?: DataQueryContext;
+    /** 是否成功 */
+    success: boolean;
+    /** 是否命中缓存 */
+    fromCache?: boolean;
+    /** 错误码 */
+    code?: number;
+    /** 耗时（ms） */
+    duration: number;
+    /** 追踪 ID */
+    traceId: string;
+    /** 创建时间 */
+    createdAt: string;
+}
+
+/**
+ * HostAPI 类型定义
+ * 运行时注入给组件的安全 API
+ *
+ * 组件只能通过 hostApi 与外部交互，禁止直接调用：
+ * - window.fetch（绕过 Data Proxy）
+ * - location.href（绕过权限/埋点）
+ * - localStorage（乱写）
+ */
+
+/** 导航选项 */
+interface NavigateOptions {
+    /** 目标 URL */
+    url: string;
+    /** 是否新窗口 */
+    newTab?: boolean;
+    /** 是否替换当前页 */
+    replace?: boolean;
+    /** 附加参数 */
+    params?: Record<string, string>;
+}
+/** 对话框选项 */
+interface DialogOptions {
+    /** 对话框类型 */
+    type: 'alert' | 'confirm' | 'prompt' | 'custom';
+    /** 标题 */
+    title?: string;
+    /** 内容 */
+    content?: string;
+    /** 自定义组件 */
+    component?: string;
+    /** 组件属性 */
+    componentProps?: Record<string, unknown>;
+    /** 确认按钮文案 */
+    confirmText?: string;
+    /** 取消按钮文案 */
+    cancelText?: string;
+}
+/** Toast 选项 */
+interface ToastOptions {
+    /** 消息内容 */
+    message: string;
+    /** 类型 */
+    type?: 'success' | 'error' | 'warning' | 'info';
+    /** 持续时间（毫秒） */
+    duration?: number;
+    /** 位置 */
+    position?: 'top' | 'center' | 'bottom';
+}
+/** 埋点事件 */
+interface TrackEvent {
+    /** 事件名称 */
+    eventName: string;
+    /** 事件参数 */
+    params?: Record<string, unknown>;
+    /** 时间戳 */
+    timestamp?: number;
+}
+/** 剪贴板操作结果 */
+interface ClipboardResult {
+    success: boolean;
+    content?: string;
+    error?: string;
+}
+/** 存储选项 */
+interface StorageOptions {
+    /** 命名空间 */
+    namespace?: string;
+    /** 过期时间（秒） */
+    ttl?: number;
+}
+/**
+ * HostAPI 接口
+ * 运行时提供给组件的安全 API
+ */
+interface HostAPI {
+    /**
+     * 请求数据（走 Data Proxy）
+     */
+    requestData<T = unknown>(queryId: string, params?: Record<string, unknown>): Promise<DataQueryResponse<T>>;
+    /**
+     * 执行动作（走 Action Gateway）
+     */
+    executeAction<T = unknown>(actionType: string, params?: Record<string, unknown>): Promise<ActionExecuteResponse<T>>;
+    /**
+     * 页面导航
+     */
+    navigate(options: NavigateOptions): void;
+    /**
+     * 返回上一页
+     */
+    goBack(): void;
+    /**
+     * 刷新页面
+     */
+    refresh(): void;
+    /**
+     * 打开对话框
+     */
+    openDialog(options: DialogOptions): Promise<boolean | string>;
+    /**
+     * 关闭对话框
+     */
+    closeDialog(): void;
+    /**
+     * 显示 Toast
+     */
+    showToast(options: ToastOptions): void;
+    /**
+     * 上报埋点
+     */
+    track(event: TrackEvent): void;
+    /**
+     * 复制到剪贴板
+     */
+    copyToClipboard(text: string): Promise<ClipboardResult>;
+    /**
+     * 从剪贴板读取
+     */
+    readFromClipboard(): Promise<ClipboardResult>;
+    /**
+     * 获取页面状态
+     */
+    getState<T = unknown>(key: string): T | undefined;
+    /**
+     * 设置页面状态
+     */
+    setState(key: string, value: unknown): void;
+    /**
+     * 获取全局变量
+     */
+    getVariable<T = unknown>(name: string): T | undefined;
+    /**
+     * 发送消息给其他组件
+     */
+    postMessage(componentId: string, message: unknown): void;
+    /**
+     * 广播消息
+     */
+    broadcast(channel: string, message: unknown): void;
+    /**
+     * 安全存储（有命名空间隔离）
+     */
+    storage: {
+        get<T = unknown>(key: string, options?: StorageOptions): T | undefined;
+        set(key: string, value: unknown, options?: StorageOptions): void;
+        remove(key: string, options?: StorageOptions): void;
+    };
+    /**
+     * 获取运行时上下文
+     */
+    getContext(): RuntimeContext;
+}
+/** 运行时上下文 */
+interface RuntimeContext {
+    /** 页面 UID */
+    pageUid: string;
+    /** 页面版本 ID */
+    pageVersionId: string;
+    /** 运行时版本 */
+    runtimeVersion: string;
+    /** 用户 ID */
+    userId?: string;
+    /** 设备 ID */
+    deviceId?: string;
+    /** 渠道 */
+    channel?: string;
+    /** 是否编辑模式 */
+    isEditMode: boolean;
+    /** 是否预览模式 */
+    isPreviewMode: boolean;
+}
+
+/**
+ * 资源相关类型定义
+ * 用于管理图片、视频、文档等资源
+ */
+/**
+ * 资源状态
+ * - active: 活跃
+ * - archived: 已归档
+ */
+type AssetStatus = 'active' | 'archived';
+/**
+ * 资源类型
+ * - image: 图片
+ * - video: 视频
+ * - audio: 音频
+ * - document: 文档
+ * - other: 其他
+ */
+type AssetType = 'image' | 'video' | 'audio' | 'document' | 'other';
+/**
+ * 资源排序字段
+ */
+type AssetSortField = 'id' | 'createdAt' | 'size' | 'filename';
+/**
+ * 资源元数据
+ */
+interface AssetMeta {
+    /** 原始文件名 */
+    originalName: string;
+    /** MIME 类型 */
+    mimeType: string;
+    /** 文件大小（字节） */
+    size: number;
+    /** 宽度（仅图片/视频） */
+    width?: number;
+    /** 高度（仅图片/视频） */
+    height?: number;
+    /** 时长（仅音频/视频，秒） */
+    duration?: number;
+    /** 扩展信息 */
+    extra?: Record<string, unknown>;
+}
+/**
+ * 资源信息
+ */
+interface Asset {
+    /** 资源 ID */
+    id: string;
+    /** 资源名称 */
+    name: string;
+    /** 资源类型 */
+    type: AssetType;
+    /** 资源状态 */
+    status: AssetStatus;
+    /** 存储路径/URL */
+    url: string;
+    /** 缩略图 URL */
+    thumbnailUrl?: string;
+    /** 元数据 */
+    meta: AssetMeta;
+    /** 标签 */
+    tags?: string[];
+    /** 所属目录 */
+    folderId?: string;
+    /** 创建时间 */
+    createdAt: string;
+    /** 创建者 */
+    createdBy: string;
+    /** 更新时间 */
+    updatedAt?: string;
+}
+
+/**
+ * 运行时相关类型定义
+ * 包括页面解析结果、运行时配置、Manifest 等
+ */
+
+/**
+ * 运行时配置
+ * 控制运行时行为的动态配置
+ */
+interface RuntimeConfig {
+    /** Kill Switch 列表（紧急禁用的 actionType） */
+    killSwitches?: string[];
+    /** 被阻断的组件版本列表 */
+    blockedComponents?: BlockedComponent[];
+    /** 功能开关 */
+    features?: Record<string, boolean>;
+    /** 灰度配置 */
+    rollout?: RolloutConfig;
+    /** 调试模式 */
+    debug?: boolean;
+}
+/**
+ * 被阻断的组件信息
+ */
+interface BlockedComponent {
+    /** 组件名称 */
+    name: string;
+    /** 被阻断的版本（支持 semver range） */
+    version: string;
+    /** 阻断原因 */
+    reason: string;
+    /** 阻断时间 */
+    blockedAt: string;
+}
+/**
+ * 灰度配置
+ */
+interface RolloutConfig {
+    /** 是否启用 */
+    enabled: boolean;
+    /** 灰度百分比 (0-100) */
+    percentage?: number;
+    /** 白名单用户 */
+    whitelistUsers?: string[];
+    /** 黑名单用户 */
+    blacklistUsers?: string[];
+}
+/**
+ * 页面解析请求
+ * GET /page/resolve
+ */
+interface PageResolveRequest {
+    /** 页面 UID */
+    pageUid: string;
+    /** 渠道 */
+    channel?: string;
+    /** 用户 ID（用于灰度） */
+    uid?: string;
+    /** 设备 ID */
+    deviceId?: string;
+    /** 预览 Token */
+    previewToken?: string;
+}
+/**
+ * 页面解析结果
+ * GET /page/resolve 的响应数据
+ */
+interface PageResolveResult {
+    /** 页面 UID */
+    pageUid: string;
+    /** 页面版本 ID */
+    pageVersionId: string;
+    /** 页面 JSON */
+    pageJson: PageSchema;
+    /** 组件清单 */
+    manifest: PageManifest;
+    /** 运行时配置 */
+    runtimeConfig: RuntimeConfig;
+    /** 运行时版本要求 */
+    runtimeVersion: string;
+    /** 是否预览模式 */
+    isPreview?: boolean;
+}
+/**
+ * 组件加载状态
+ */
+type ComponentLoadStatus = 'pending' | 'loading' | 'loaded' | 'failed' | 'blocked';
+/**
+ * 组件加载结果
+ */
+interface ComponentLoadResult {
+    /** 组件名称 */
+    name: string;
+    /** 组件版本 */
+    version: string;
+    /** 加载状态 */
+    status: ComponentLoadStatus;
+    /** 组件类/构造函数 */
+    component?: unknown;
+    /** 错误信息 */
+    error?: string;
+    /** 加载耗时（ms） */
+    loadTime?: number;
+}
+/**
+ * 组件注册表
+ */
+interface ComponentRegistry {
+    /** 已注册的组件 */
+    components: Map<string, ComponentLoadResult>;
+    /** 注册组件 */
+    register(name: string, component: unknown): void;
+    /** 获取组件 */
+    get(name: string): ComponentLoadResult | undefined;
+    /** 检查组件是否已加载 */
+    has(name: string): boolean;
+}
+/**
+ * 运行时错误类型
+ */
+type RuntimeErrorType = 'LOAD_ERROR' | 'RENDER_ERROR' | 'ACTION_ERROR' | 'QUERY_ERROR' | 'EXPRESSION_ERROR' | 'INTEGRITY_ERROR' | 'BLOCKED_ERROR';
+/**
+ * 运行时错误
+ */
+interface RuntimeError {
+    /** 错误类型 */
+    type: RuntimeErrorType;
+    /** 错误消息 */
+    message: string;
+    /** 组件 ID */
+    componentId?: string;
+    /** 组件类型 */
+    componentType?: string;
+    /** 组件版本 */
+    componentVersion?: string;
+    /** 动作 ID */
+    actionId?: string;
+    /** 堆栈 */
+    stack?: string;
+    /** 追踪 ID */
+    traceId?: string;
+    /** 发生时间 */
+    timestamp: number;
+}
+/**
+ * 错误边界处理器
+ */
+interface ErrorBoundaryHandler {
+    /** 处理错误 */
+    handleError(error: RuntimeError): void;
+    /** 渲染 fallback */
+    renderFallback(error: RuntimeError): unknown;
+}
+/**
+ * 性能指标类型
+ */
+type PerformanceMetricType = 'page_resolve' | 'component_load' | 'first_render' | 'action_execute' | 'query_execute';
+/**
+ * 性能指标
+ */
+interface PerformanceMetric {
+    /** 指标类型 */
+    type: PerformanceMetricType;
+    /** 名称/标识 */
+    name: string;
+    /** 耗时（ms） */
+    duration: number;
+    /** 开始时间 */
+    startTime: number;
+    /** 额外数据 */
+    extra?: Record<string, unknown>;
+}
+/**
+ * 运行时事件类型
+ */
+type RuntimeEventType = 'page:loaded' | 'page:error' | 'component:mounted' | 'component:unmounted' | 'component:error' | 'action:start' | 'action:success' | 'action:error' | 'query:start' | 'query:success' | 'query:error';
+/**
+ * 运行时事件
+ */
+interface RuntimeEvent<T = unknown> {
+    /** 事件类型 */
+    type: RuntimeEventType;
+    /** 事件数据 */
+    data: T;
+    /** 时间戳 */
+    timestamp: number;
+    /** 追踪 ID */
+    traceId?: string;
+}
+/**
+ * 事件总线接口
+ */
+interface EventBus {
+    /** 发送事件 */
+    emit<T>(event: RuntimeEvent<T>): void;
+    /** 订阅事件 */
+    on<T>(type: RuntimeEventType, handler: (event: RuntimeEvent<T>) => void): () => void;
+    /** 取消订阅 */
+    off<T>(type: RuntimeEventType, handler: (event: RuntimeEvent<T>) => void): void;
+}
+
+/**
+ * 统一 API 响应类型定义
+ * 所有 API 响应遵循统一格式
+ */
+
+/**
+ * 统一 API 响应格式
+ */
+interface ApiResponse<T = unknown> {
+    /** 是否成功 */
+    success: boolean;
+    /** 响应数据 */
+    data?: T;
+    /** 错误码 */
+    code?: ErrorCode | number;
+    /** 错误信息 */
+    message?: string;
+    /** 追踪 ID */
+    traceId?: string;
+    /** 请求 ID */
+    requestId?: string;
+    /** 时间戳 */
+    timestamp?: number;
+}
+/**
+ * 分页 API 响应格式
+ */
+interface PaginatedApiResponse<T> extends ApiResponse<T[]> {
+    /** 分页信息 */
+    pagination?: {
+        /** 当前页码 */
+        page: number;
+        /** 每页数量 */
+        pageSize: number;
+        /** 总数量 */
+        total: number;
+        /** 总页数 */
+        totalPages: number;
+    };
+}
+/**
+ * 标准请求头
+ */
+interface StandardRequestHeaders {
+    /** 追踪 ID */
+    'x-trace-id'?: string;
+    /** 请求 ID */
+    'x-request-id'?: string;
+    /** 页面版本 ID */
+    'x-page-version-id'?: string;
+    /** 组件版本 */
+    'x-component-version'?: string;
+    /** 用户 ID */
+    'x-user-id'?: string;
+    /** 设备 ID */
+    'x-device-id'?: string;
+    /** 渠道 */
+    'x-channel'?: string;
+    /** 应用 ID */
+    'x-app-id'?: string;
+}
+/**
+ * 标准响应头
+ */
+interface StandardResponseHeaders {
+    /** 追踪 ID */
+    'x-trace-id'?: string;
+    /** 请求 ID */
+    'x-request-id'?: string;
+    /** 服务器时间戳 */
+    'x-server-time'?: string;
+    /** 缓存状态 */
+    'x-cache-status'?: 'HIT' | 'MISS' | 'BYPASS';
+}
+/**
+ * 健康检查响应
+ */
+interface HealthCheckResponse {
+    /** 状态 */
+    status: 'healthy' | 'degraded' | 'unhealthy';
+    /** 版本 */
+    version: string;
+    /** 服务名 */
+    service: string;
+    /** 依赖服务状态 */
+    dependencies?: Record<string, DependencyHealth>;
+    /** 时间戳 */
+    timestamp: number;
+}
+/**
+ * 依赖服务健康状态
+ */
+interface DependencyHealth {
+    /** 状态 */
+    status: 'up' | 'down';
+    /** 延迟（ms） */
+    latency?: number;
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 批量操作请求
+ */
+interface BatchRequest<T> {
+    /** 操作列表 */
+    items: T[];
+    /** 是否原子操作（全部成功或全部失败） */
+    atomic?: boolean;
+}
+/**
+ * 批量操作结果
+ */
+interface BatchResult<T> {
+    /** 成功数量 */
+    successCount: number;
+    /** 失败数量 */
+    failedCount: number;
+    /** 结果列表 */
+    results: BatchItemResult<T>[];
+}
+/**
+ * 单个批量操作项结果
+ */
+interface BatchItemResult<T> {
+    /** 索引 */
+    index: number;
+    /** 是否成功 */
+    success: boolean;
+    /** 数据 */
+    data?: T;
+    /** 错误码 */
+    code?: number;
+    /** 错误信息 */
+    message?: string;
+}
+/**
+ * 上传凭证请求
+ */
+interface UploadCredentialRequest {
+    /** 文件名 */
+    filename: string;
+    /** 文件类型 */
+    contentType: string;
+    /** 文件大小 */
+    size: number;
+    /** 目录 */
+    directory?: string;
+}
+/**
+ * 上传凭证响应
+ */
+interface UploadCredentialResponse {
+    /** 上传 URL */
+    uploadUrl: string;
+    /** 上传方法 */
+    method: 'PUT' | 'POST';
+    /** 需要的请求头 */
+    headers: Record<string, string>;
+    /** 表单字段（POST multipart 时） */
+    formFields?: Record<string, string>;
+    /** 最终文件 URL */
+    fileUrl: string;
+    /** 凭证过期时间 */
+    expiresAt: string;
+}
+/**
+ * WebSocket 消息类型
+ */
+type WsMessageType = 'ping' | 'pong' | 'subscribe' | 'unsubscribe' | 'publish' | 'error';
+/**
+ * WebSocket 消息
+ */
+interface WsMessage<T = unknown> {
+    /** 消息类型 */
+    type: WsMessageType;
+    /** 频道 */
+    channel?: string;
+    /** 消息数据 */
+    data?: T;
+    /** 消息 ID */
+    id?: string;
+    /** 时间戳 */
+    timestamp: number;
+}
+
+/**
+ * 表达式引擎类型定义
+ * 无 eval 的安全 DSL，支持发布期校验
+ */
+/**
+ * 表达式类型
+ */
+type ExpressionType = 'literal' | 'identifier' | 'member' | 'index' | 'call' | 'binary' | 'unary' | 'conditional' | 'array' | 'object';
+/**
+ * 表达式 AST 节点基类
+ */
+interface ExpressionNode {
+    /** 节点类型 */
+    type: ExpressionType;
+    /** 原始表达式 */
+    raw?: string;
+    /** 起始位置 */
+    start?: number;
+    /** 结束位置 */
+    end?: number;
+}
+/**
+ * 字面量节点
+ */
+interface LiteralNode extends ExpressionNode {
+    type: 'literal';
+    value: string | number | boolean | null;
+}
+/**
+ * 标识符节点
+ */
+interface IdentifierNode extends ExpressionNode {
+    type: 'identifier';
+    name: string;
+}
+/**
+ * 成员访问节点
+ */
+interface MemberNode extends ExpressionNode {
+    type: 'member';
+    object: ExpressionNode;
+    property: string;
+}
+/**
+ * 函数调用节点
+ */
+interface CallNode extends ExpressionNode {
+    type: 'call';
+    callee: string;
+    arguments: ExpressionNode[];
+}
+/**
+ * 二元运算节点
+ */
+interface BinaryNode extends ExpressionNode {
+    type: 'binary';
+    operator: BinaryOperator;
+    left: ExpressionNode;
+    right: ExpressionNode;
+}
+/**
+ * 二元运算符
+ */
+type BinaryOperator = '+' | '-' | '*' | '/' | '%' | '==' | '!=' | '>' | '<' | '>=' | '<=' | '&&' | '||' | '??';
+/**
+ * 一元运算符
+ */
+type UnaryOperator = '!' | '-' | '+';
+/**
+ * 内置函数定义
+ */
+interface BuiltinFunction {
+    /** 函数名 */
+    name: string;
+    /** 描述 */
+    description: string;
+    /** 参数定义 */
+    params: FunctionParam[];
+    /** 返回类型 */
+    returnType: ValueType;
+    /** 示例 */
+    examples?: string[];
+}
+/**
+ * 函数参数定义
+ */
+interface FunctionParam {
+    /** 参数名 */
+    name: string;
+    /** 参数类型 */
+    type: ValueType;
+    /** 是否必填 */
+    required: boolean;
+    /** 默认值 */
+    defaultValue?: unknown;
+    /** 描述 */
+    description?: string;
+}
+/**
+ * 值类型
+ */
+type ValueType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'null' | 'any' | 'void';
+/**
+ * 内置函数白名单
+ * 表达式中只能调用这些函数
+ */
+declare const BUILTIN_FUNCTIONS: BuiltinFunction[];
+/**
+ * 内置函数名称集合（用于快速校验）
+ */
+declare const BUILTIN_FUNCTION_NAMES: Set<string>;
+/**
+ * 表达式上下文
+ * 表达式执行时可访问的变量
+ */
+interface ExpressionContext {
+    /** 页面状态 */
+    state: Record<string, unknown>;
+    /** 查询结果 */
+    query: Record<string, unknown>;
+    /** 运行时上下文 */
+    context: {
+        userId?: string;
+        deviceId?: string;
+        channel?: string;
+        pageVersionId?: string;
+        [key: string]: unknown;
+    };
+    /** 事件参数 */
+    event?: Record<string, unknown>;
+    /** 循环变量 */
+    item?: unknown;
+    /** 循环索引 */
+    index?: number;
+}
+/**
+ * 表达式允许访问的根变量
+ */
+declare const ALLOWED_ROOT_VARIABLES: readonly ["state", "query", "context", "event", "item", "index"];
+/**
+ * 表达式校验结果
+ */
+interface ExpressionValidationResult {
+    /** 是否有效 */
+    valid: boolean;
+    /** 错误列表 */
+    errors: ExpressionError[];
+    /** 警告列表 */
+    warnings: ExpressionWarning[];
+    /** 引用的变量路径 */
+    referencedPaths: string[];
+    /** 调用的函数 */
+    calledFunctions: string[];
+}
+/**
+ * 表达式错误
+ */
+interface ExpressionError {
+    /** 错误类型 */
+    type: ExpressionErrorType;
+    /** 错误消息 */
+    message: string;
+    /** 位置 */
+    position?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * 表达式错误类型
+ */
+type ExpressionErrorType = 'SYNTAX_ERROR' | 'UNKNOWN_FUNCTION' | 'INVALID_ARGUMENT' | 'UNKNOWN_VARIABLE' | 'TYPE_MISMATCH' | 'ACCESS_DENIED';
+/**
+ * 表达式警告
+ */
+interface ExpressionWarning {
+    /** 警告类型 */
+    type: 'DEPRECATED' | 'PERFORMANCE' | 'NULLABLE';
+    /** 警告消息 */
+    message: string;
+    /** 位置 */
+    position?: {
+        start: number;
+        end: number;
+    };
+}
+/**
+ * 表达式绑定
+ * 用于属性值的动态绑定
+ */
+interface ExpressionBinding {
+    /** 是否为表达式 */
+    __isExpression: true;
+    /** 表达式字符串 */
+    expression: string;
+    /** 默认值（表达式失败时使用） */
+    fallback?: unknown;
+}
+/**
+ * 检查是否为表达式绑定
+ */
+declare function isExpressionBinding(value: unknown): value is ExpressionBinding;
+/**
+ * 创建表达式绑定
+ */
+declare function createExpressionBinding(expression: string, fallback?: unknown): ExpressionBinding;
+
+/**
+ * Schema 迁移脚本
+ * 用于 Editor/Platform 在读取草稿/发布版本时做迁移
+ *
+ * 原则：
+ * 1. 不可变版本：发布后永不修改
+ * 2. 向前迁移：从旧版本迁移到新版本
+ * 3. 草稿迁移：Editor 打开草稿时执行
+ * 4. 发布固化：发布时固化迁移后的 Schema
+ */
+
+declare const SCHEMA_VERSIONS: readonly ["1.0.0", "1.1.0", "2.0.0"];
+type SchemaVersion = (typeof SCHEMA_VERSIONS)[number];
+declare const CURRENT_SCHEMA_VERSION: SchemaVersion;
+/**
+ * 迁移函数类型
+ */
+type MigrationFn<T = PageSchema> = (data: T) => T;
+/**
+ * 迁移定义
+ */
+interface Migration {
+    /** 源版本 */
+    from: string;
+    /** 目标版本 */
+    to: string;
+    /** 迁移描述 */
+    description: string;
+    /** 迁移函数 */
+    migrate: MigrationFn;
+    /** 是否破坏性变更 */
+    breaking?: boolean;
+}
+/**
+ * 迁移结果
+ */
+interface MigrationResult<T = PageSchema> {
+    /** 是否成功 */
+    success: boolean;
+    /** 迁移后的数据 */
+    data?: T;
+    /** 原始版本 */
+    fromVersion: string;
+    /** 目标版本 */
+    toVersion: string;
+    /** 应用的迁移列表 */
+    appliedMigrations: string[];
+    /** 错误信息 */
+    error?: string;
+}
+/**
+ * 注册迁移
+ */
+declare function registerMigration(migration: Migration): void;
+/**
+ * 获取所有迁移
+ */
+declare function getAllMigrations(): Migration[];
+/**
+ * 查找从源版本到目标版本的迁移路径
+ */
+declare function findMigrationPath(from: string, to: string): Migration[];
+/**
+ * 执行 PageSchema 迁移
+ */
+declare function migratePageSchema(data: PageSchema, targetVersion?: string): MigrationResult<PageSchema>;
+/**
+ * 检查是否需要迁移
+ */
+declare function needsMigration(data: PageSchema, targetVersion?: string): boolean;
+/**
+ * 获取版本信息
+ */
+declare function getVersionInfo(version: string): {
+    major: number;
+    minor: number;
+    patch: number;
+};
+/**
+ * 比较版本
+ * @returns -1 if a < b, 0 if a === b, 1 if a > b
+ */
+declare function compareVersions(a: string, b: string): number;
+
+export { ACTION_SPEC_VERSION, ALLOWED_ROOT_VARIABLES, type ActionAuditLog, type ActionContext, type ActionDefVersionId, type ActionDefinition, type ActionDefinitionStatus, type ActionDefinitionVersion, type ActionExecuteRequest, type ActionExecuteResponse, type ApiConfig, type ApiResponse, type Asset, type AssetMeta, type AssetSortField, type AssetStatus, type AssetType, type AuditStatus, BUILTIN_FUNCTIONS, BUILTIN_FUNCTION_NAMES, type BatchItemResult, type BatchRequest, type BatchResult, type BinaryNode, type BinaryOperator, type BlockedComponent, type BuiltinActionType, type BuiltinFunction, COMPONENT_CATEGORIES, COMPONENT_META_SCHEMA_VERSION, CURRENT_SCHEMA_VERSION, type CacheConfig, type CallNode, type CanvasConfig, type CanvasType, type CapabilitiesDefinition, type ChangeLog, type ChangeLogItem, type ClipboardResult, type CompatDefinition, type ComponentCategory, type ComponentEvent, type ComponentInstance, type ComponentLayout, type ComponentLoadResult, type ComponentLoadStatus, type ComponentMeta, type ComponentRegistry, type ComponentStatus, type ComponentStyle, type ComponentVersionId, type ComponentVersionRecord, type ContractsVersion, DATA_QUERY_SPEC_VERSION, type DataQueryContext, type DataQueryDefinition, type DataQueryDefinitionStatus, type DataQueryDefinitionVersion, type DataQueryRequest, type DataQueryResponse, type DataQueryVersionId, type DataSourceConfig, type DataSourceType, type DeepReadonly, type DependencyHealth, type DialogOptions, type DjvlcError, type ErrorBoundaryHandler, ErrorCode, ErrorCodeCategory, ErrorMessages, type EventAction, type EventBus, type EventDefinition, type EventsDefinition, type ExpressionBinding, type ExpressionContext, type ExpressionError, type ExpressionErrorType, type ExpressionNode, type ExpressionType, type ExpressionValidationResult, type ExpressionWarning, type FieldPermission, type FunctionParam, type GenericStatus, type GrayPublishConfig, type GrayRule, type Guide, type HealthCheckResponse, type HostAPI, type IdempotencyRule, type IdentifierNode, type IntegrityDefinition, type JsonSchema, type KeyValuePair, type LiteralNode, type LowcodeAction, type ManifestItem, type MaskRule, type MemberNode, type Migration, type MigrationFn, type MigrationResult, type NavigateOptions, type NonNullableProperties, type OperatorInfo, PAGE_SCHEMA_VERSION, type PageConfig, type PageManifest, type PageMeta, type PageResolveRequest, type PageResolveResult, type PageSchema, type PageSortField, type PageStatus, type PageUid, type PageVersionId, type PaginatedApiResponse, type PaginatedResult, type PaginationMeta, type PaginationParams, type PartialBy, type PerformanceMetric, type PerformanceMetricType, type PropsSchema, type PublishChannel, type PublishConfig, PublishStatus, type QueryAuditLog, type QueryPermissionConfig, type RateLimitRule, type RequiredBy, type RiskCheckRequest, type RiskCheckResult, type RolloutConfig, type RuntimeConfig, type RuntimeContext, type RuntimeError, type RuntimeErrorType, type RuntimeEvent, type RuntimeEventType, SCHEMA_VERSIONS, type SchemaVersion, type SortConfig, type SortOrder, type StandardRequestHeaders, type StandardResponseHeaders, type StorageOptions, type TemplateCategory, type TemplateSortField, type TimeRange, type ToastOptions, type TraceId, type TrackEvent, type UnaryOperator, type UploadCredentialRequest, type UploadCredentialResponse, type ValueType, type VersionDiff, type VersionInfo, type WsMessage, type WsMessageType, compareVersions, createDjvlcError, createExpressionBinding, findMigrationPath, getAllMigrations, getContractsVersion, getHttpStatusFromErrorCode, getVersionInfo, isExpressionBinding, isRetryableError, isVersionCompatible, migratePageSchema, needsMigration, registerMigration };